duke-book

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 every tool, including duke_validate_token and duke_health_check. The token owner must have a current plan with API_ACCESS and MCP_ACCESS.

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

Create an explicit-scope token with: notes:read, notes:write, notes:delete, categories:read, categories:write, knowledge:read, and profile:read. Legacy compatibility tokens are deliberately rejected by MCP even if their owner has a paid plan. duke_search_knowledge additionally requires the plan capability AI_RAG.

Every tool performs a commercial preflight and the actual Duke API request independently revalidates the API token, API_ACCESS, MCP_ACCESS, any domain capability, and the method-aware scope. X-Duke-Client: duke-book-mcp is only a server-side tightening hint after token verification; it is never treated as identity.

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 always verifies that the MCP server starts and exposes all expected tools. If DUKE_API_TOKEN is set, it performs the authenticated commercial health check, reads /api/v1/token-info, and verifies the current plan, enabled features, and every scope required by MCP without performing a write.

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 (AI_RAG plus knowledge:read)
• duke_validate_token
• duke_health_check

Publishing Checklist

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

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