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:

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

Note: The E2E mcp_services.feature preparation task (bundleMcpServer) rebuilds the bundle from current source automatically before the client connects; the standalone build command above is for IDE/client use.

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.

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:

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:

{
  "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):

{
  "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

• list_note_candidates - List every note whose title or alias matches a query, with notebook and folder to tell candidates apart
• get_note_graph - Fetch graph context for a note by ID and token limit
• read_note - Read one note in full by ID: the user's note text (treated as evidence) with notebook, folder, and the whole notebook's accepted Git revision (null when none)