mcp-server.mdc

---
description: Doughnut MCP server — structure, build, tests, Cursor/IDE configuration
alwaysApply: false
---

# doughnut-mcp-server MCP Server

A Model Context Protocol server for Doughnut.

Is in the `mcp-server` folder.

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

- Tools for getting instructions and updating note text content via the Doughnut backend API.

## 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 DoughnutApi
    api.ts                # DoughnutApi 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 comprehensive unit tests using Vitest. **Tests are located in the `tests/` folder**, not mixed with production code. Run tests with:

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

Or from the root directory:

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

### Test Organization

- **Production code**: Located in `src/` folder
- **Test files**: Located in `tests/` folder with `.test.ts` extension
- **Test configuration**: `vitest.config.ts` points to `tests/**/*.test.ts`
- **TypeScript config**: `tsconfig.json` includes both `src/` and `tests/` folders

This separation ensures:
- Clean, organized codebase structure
- Easy identification of production vs. test code
- Better maintainability and readability
- Standard practice followed by most TypeScript projects

### 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 "Frontend & MCP Unit Tests" job in GitHub Actions
- Formatting is included in the `pnpm format:all` command
- 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": {
    "doughnut": {
      "disabled": false,
      "timeout": 60,
      "transportType": "stdio",
      "command": "node",
      "args": [
        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
      ],
      "env": {
        "DOUGHNUT_API_BASE_URL": "http://localhost:9081",
        "DOUGHNUT_API_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}
```

For VS Code (you need to put the following content into `./.vscode/mcp.json`):
```json
{
  "servers": {
    "doughnut": {
      "command": "node",
      "args": [
        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
      ],
      "env": {
        "DOUGHNUT_API_BASE_URL": "http://localhost:9081",
        "DOUGHNUT_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": {
    "doughnut": {
      "disabled": false,
      "timeout": 60,
      "transportType": "stdio",
      "command": "node",
      "args": [
        "<doughnut root folder>/mcp-server/dist/mcp-server.bundle.mjs"
      ],
      "env": {
        "DOUGHNUT_API_BASE_URL": "http://localhost:9081",
        "DOUGHNUT_API_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

```

## Available Tools

- `update_note_text_content` - Update the title and/or details of a note by note ID
- `get_notebook_list` - Get list of user's notebooks
- `get_graph_with_note_id` - Get graph data for a specific note
- `add_note` - Add a note to a notebook
- `get_relevant_note` - Search for relevant notes based on a query