Cursor rule

1---
2description: Doughnut MCP server — structure, build, tests, Cursor/IDE configuration
3alwaysApply: false
4---
5 
6# doughnut-mcp-server MCP Server
7 
8A Model Context Protocol server for Doughnut.
9 
10Is in the `mcp-server` folder.
11 
12This is a TypeScript-based MCP server that demonstrates core MCP concepts by providing:
13 
14- Tools that read note context from the Doughnut backend API (search and graph).
15 
16## Structure (minimal)
17 
18```
19mcp-server/
20  src/                    # Production source code
21    index.ts              # boot: create context, start stdio
22    server.ts             # assemble server, list tools, route calls
23    context.ts            # read env, create DoughnutApi
24    api.ts                # DoughnutApi factory
25    schemas.ts            # tool input schemas (shared)
26    tools/index.ts        # tool registry + handlers
27    types.ts              # shared types
28    utils.ts              # error + validation helpers
29  tests/                  # Unit tests (separate from production code)
30    server.test.ts        # Server and tools tests
31    utils.test.ts         # Utility functions tests
32  vitest.config.ts        # Test configuration
33  tsconfig.json           # TypeScript configuration
34  package.json            # Dependencies and scripts
35```
36 
37**Important**: Tests are kept in a separate `tests/` folder, not mixed with production code in the `src/` folder. This maintains clean separation between production and test code, making the codebase more organized and maintainable.
38 
39## Development
40 
41### Building the MCP Server
42 
43Run this command to build the mcp server:
44 
45```sh
46CURSOR_DEV=true nix develop -c pnpm mcp-server:bundle
47```
48 
49Note: Rebuild the bundle before running the e2e `mcp_services.feature`.
50 
51### Running Unit Tests
52 
53The MCP server has comprehensive unit tests using Vitest. **Tests are located in the `tests/` folder**, not mixed with production code. Run tests with:
54 
55```sh
56CURSOR_DEV=true nix develop -c pnpm mcp-server:test
57```
58 
59Or from the root directory:
60 
61```sh
62CURSOR_DEV=true nix develop -c pnpm mcp-server:test
63```
64 
65### Test Organization
66 
67- **Production code**: Located in `src/` folder
68- **Test files**: Located in `tests/` folder with `.test.ts` extension
69- **Test configuration**: `vitest.config.ts` points to `tests/**/*.test.ts`
70- **TypeScript config**: `tsconfig.json` includes both `src/` and `tests/` folders
71 
72This separation ensures:
73- Clean, organized codebase structure
74- Easy identification of production vs. test code
75- Better maintainability and readability
76- Standard practice followed by most TypeScript projects
77 
78### Formatting Code
79 
80Format the MCP server code with:
81 
82```sh
83CURSOR_DEV=true nix develop -c pnpm mcp-server:format
84```
85 
86### Test Coverage
87 
88The unit tests cover:
89- Utility functions (error handling, parameter validation, environment configuration)
90- Server configuration and tool definitions
91- Tool schema validation
92- Response format validation
93- Behavior-focused assertions that are insensitive to internal structure
94 
95## CI/CD Integration
96 
97- Unit tests run as part of the "Frontend & MCP Unit Tests" job in GitHub Actions
98- Formatting is included in the workspace format command; see `.cursor/rules/linting_formating.mdc`
99- Tests are automatically executed on every push to main branch
100 
101## How to use this MCP Server
102 
103Add the below command to your AI MCP Server configuration.
104 
105For Cursor:
106```json
107{
108  "mcpServers": {
109    "doughnut": {
110      "disabled": false,
111      "timeout": 60,
112      "transportType": "stdio",
113      "command": "node",
114      "args": [
115        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
116      ],
117      "env": {
118        "DOUGHNUT_API_BASE_URL": "http://localhost:9081",
119        "DOUGHNUT_API_AUTH_TOKEN": "your-token-here"
120      }
121    }
122  }
123}
124```
125 
126For VS Code (you need to put the following content into `./.vscode/mcp.json`):
127```json
128{
129  "servers": {
130    "doughnut": {
131      "command": "node",
132      "args": [
133        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
134      ],
135      "env": {
136        "DOUGHNUT_API_BASE_URL": "http://localhost:9081",
137        "DOUGHNUT_API_AUTH_TOKEN": "your-token-here"
138      }
139    }
140  }
141}
142 
143For IntelliJ IDE you need to go to the general settings/tools/GitHub Copilot/MCP and press configure:
144```json
145{
146  "servers": {
147    "doughnut": {
148      "disabled": false,
149      "timeout": 60,
150      "transportType": "stdio",
151      "command": "node",
152      "args": [
153        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
154      ],
155      "env": {
156        "DOUGHNUT_API_BASE_URL": "http://localhost:9081",
157        "DOUGHNUT_API_AUTH_TOKEN": "your-token-here"
158      }
159    }
160  }
161}
162 
163```
164 
165## Available Tools
166 
167- `find_most_relevant_note` - Search for the single most relevant note for a query
168- `get_note_graph` - Fetch graph context for a note by ID and token limit