duke-book

Expose Duke Bookmark notes, categories, and knowledge search to MCP clients such as Cursor, Claude Code, and VS Code.

Configuration

Create an API token in Duke Bookmark: API Docs / Token (/api-docs?tab=tokens).

DUKE_API_BASE_URL=http://localhost:3001
DUKE_API_TOKEN=your_api_token

DUKE_API_BASE_URL defaults to http://localhost:3001. DUKE_API_TOKEN is required for note/category operations. duke_health_check can run without a token.

DUKE_API_TOKEN may be configured as either the raw token or Bearer <token>; the server normalizes it before calling Duke Bookmark.

Local Usage

npm install
npm run build
$env:DUKE_API_BASE_URL="http://localhost:3001"
$env:DUKE_API_TOKEN="your_api_token"
npm start

After publishing to npm, clients can also run this server with npx -y duke-book.

Local Verification

Start Duke Bookmark first, then run:

npm run smoke

The smoke test verifies that the MCP server starts, exposes all expected tools, and can reach /api/health. If DUKE_API_TOKEN is set, it also validates token-scoped access through duke_validate_token.

To require a token during verification:

npm run smoke:token

Cursor

The project includes .cursor/mcp.json. Set DUKE_API_TOKEN in your local shell/user environment before starting Cursor:

{
  "mcpServers": {
    "duke-book": {
      "command": "node",
      "args": ["${workspaceFolder}/mcp-server/dist/index.js"],
      "env": {
        "DUKE_API_BASE_URL": "http://localhost:3001",
        "DUKE_API_TOKEN": "${env:DUKE_API_TOKEN}"
      }
    }
  }
}

Claude Code

claude mcp add duke-book -e DUKE_API_BASE_URL=http://localhost:3001 -e DUKE_API_TOKEN=your_api_token -- node D:/duke/mcp-server/dist/index.js

VS Code

The project includes .vscode/mcp.json. VS Code prompts for the token the first time the MCP server starts:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "duke-api-token",
      "description": "Duke Bookmark API Token",
      "password": true
    }
  ],
  "servers": {
    "dukeBook": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/mcp-server/dist/index.js"],
      "env": {
        "DUKE_API_BASE_URL": "http://localhost:3001",
        "DUKE_API_TOKEN": "${input:duke-api-token}"
      }
    }
  }
}

Tools

• duke_list_categories
• duke_search_notes
• duke_get_note
• duke_create_note
• duke_update_note
• duke_delete_note
• duke_create_category
• duke_search_knowledge
• duke_validate_token
• duke_health_check

Publishing Checklist

1. Run npm run smoke and npm run smoke:token.
2. Publish the package with npm publish --access public.
3. Publish server.json to the MCP Registry or the target marketplace.

Full release notes are documented in docs/MCP发布流程.md.