---
name: mcp-server
description: donut-mcp-server — structure, build, tests, Cursor/IDE configuration. Use when changing the Donut MCP server.
paths:
  - "mcp-server/**"
---
# donut-mcp-server MCP Server

A Model Context Protocol server for Donut.

Is in the `mcp-server` folder.

This is a TypeScript-based MCP server that demonstrates core MCP concepts by providing:

- Tools that read note context from the Donut backend API (search and graph).

## Structure (minimal)

```
mcp-server/
  src/                    # Production source code
    index.ts              # boot: create context, start stdio
    server.ts             # assemble server, list tools, route calls
    context.ts            # read env, create DonutApi
    api.ts                # DonutApi factory
    schemas.ts            # tool input schemas (shared)
    tools/index.ts        # tool registry + handlers
    types.ts              # shared types
    utils.ts              # error + validation helpers
  tests/                  # Unit tests (separate from production code)
    server.test.ts        # Server and tools tests
    utils.test.ts         # Utility functions tests
  vitest.config.ts        # Test configuration
  tsconfig.json           # TypeScript configuration
  package.json            # Dependencies and scripts
```

**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.

## Development

### Building the MCP Server

Run this command to build the mcp server:

```sh
CURSOR_DEV=true nix develop -c pnpm mcp-server:bundle
```

Note: Rebuild the bundle before running the e2e `mcp_services.feature`.

### Running Unit Tests

The MCP server has Vitest unit tests under `tests/` (not mixed with `src/`). **Style ("small test" practice — stable boundary, data over mocks, focused assertions, concise makeMe):** the `unit-testing` skill.

```sh
CURSOR_DEV=true nix develop -c pnpm mcp-server:test
```

For `dough-test-optimization`, measure that command as the ordinary feedback
path. Obtain per-test Vitest durations with
`CURSOR_DEV=true nix develop -c pnpm -C mcp-server exec vitest run --reporter=json`;
the JSON run is profiling evidence and does not replace normal verification.

### Test Organization

- **Production code**: `src/`
- **Test files**: `tests/**/*.test.ts` (see `vitest.config.ts`)
- Drive high-level tool/server entry points; cover lower layers with realistic `makeMe` data. Mock only backend HTTP responses (external dependency), with `makeMe` for API-shaped payloads.

### Formatting Code

Format the MCP server code with:

```sh
CURSOR_DEV=true nix develop -c pnpm mcp-server:format
```

### Test Coverage

The unit tests cover:
- Utility functions (error handling, parameter validation, environment configuration)
- Server configuration and tool definitions
- Tool schema validation
- Response format validation
- Behavior-focused assertions that are insensitive to internal structure

## CI/CD Integration

- Unit tests run as part of the "Other Unit Tests" job in GitHub Actions
- Formatting is included in the workspace format command; see `.agents/skills/linting_formating/SKILL.md`
- Tests are automatically executed on every push to main branch

## How to use this MCP Server

Add the below command to your AI MCP Server configuration.

For Cursor:
```json
{
  "mcpServers": {
    "donut": {
      "disabled": false,
      "timeout": 60,
      "transportType": "stdio",
      "command": "node",
      "args": [
        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
      ],
      "env": {
        "DONUT_API_BASE_URL": "http://localhost:9081",
        "DONUT_API_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}
```

For VS Code (you need to put the following content into `./.vscode/mcp.json`):
```json
{
  "servers": {
    "donut": {
      "command": "node",
      "args": [
        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
      ],
      "env": {
        "DONUT_API_BASE_URL": "http://localhost:9081",
        "DONUT_API_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

For IntelliJ IDE you need to go to the general settings/tools/GitHub Copilot/MCP and press configure:
```json
{
  "servers": {
    "donut": {
      "disabled": false,
      "timeout": 60,
      "transportType": "stdio",
      "command": "node",
      "args": [
        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
      ],
      "env": {
        "DONUT_API_BASE_URL": "http://localhost:9081",
        "DONUT_API_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

```

## Available Tools

- `find_most_relevant_note` - Search for the single most relevant note for a query
- `get_note_graph` - Fetch graph context for a note by ID and token limit