noteking-mcp

Official TypeScript-based Model Context Protocol (MCP) server for NoteKing, the local-first Markdown note-taking studio and developer workspace.

This server enables AI assistants and agents (Antigravity, Claude Desktop, Cursor, and custom MCP clients) to seamlessly search, author, append, organize, and pin developer notes, Architecture Decision Records (ADRs), and project workspaces, manage ActiveStorage file attachments, and render GitHub Flavored Markdown directly through the NoteKing REST API.

Features

• Full MCP Capabilities Suite:

  • 18 Comprehensive Tools: Full CRUD for projects and notes, safe Markdown appending (noteking_append_to_note), full-text search, pin & reorder management, file attachments, and GFM Markdown rendering.

  • 5 MCP Resources: Direct URI inspection via noteking://stats, noteking://projects, noteking://projects/{id}, noteking://notes, and noteking://notes/{id} (Markdown with YAML frontmatter).

  • Developer Note & ADR Prompts + Dynamic Sync: Built-in prompts for authoring structured notes/ADRs (noteking_author_note), synthesizing project workspaces (noteking_summarize_project), and executing {{variable}} note templates (noteking_use_note_template), plus automatic startup registration of saved NoteKing notes.

• Stdio Transport: Ultra-fast JSON-RPC 2.0 communication over standard input/output.

• Resilient Attachment Handling: Upload context files via local filesystem paths or base64-encoded strings streamed as multipart/form-data.

• OpenAPI 3.1 Contract: Strongly typed client generated directly against NoteKing's OpenAPI 3.1.0 specification with runtime Zod validation.

• Zero Friction Setup: Works out of the box with your local NoteKing Rails server.

Related MCP server: API MCP Server

Architecture Overview

flowchart LR
    Client["AI Agent / Desktop Client<br/>(Antigravity, Claude, Cursor)"]
    Stdio["Stdio Transport<br/>(JSON-RPC 2.0)"]
    MCPServer["NoteKing MCP Server<br/>(@modelcontextprotocol/sdk)"]
    APIClient["Typed NotekingClient<br/>(Node native fetch)"]
    NotekingAPI["NoteKing Rails API<br/>(http://localhost:3000/api/v1)"]

    Client <-->|MCP Protocol| Stdio
    Stdio <--> MCPServer
    MCPServer -->|18 Tools / 5 Resources / Prompts| APIClient
    APIClient <-->|REST JSON & Multipart| NotekingAPI

Quickstart

Prerequisites

• Node.js: v18.0.0 or higher (recommended: Node 20+)

• NoteKing: Running locally (default: http://localhost:3000)

Installation & Build

# Clone repository
git clone https://github.com/leouofa/noteking-mcp.git
cd noteking-mcp

# Install dependencies
npm install

# Build the TypeScript distribution
npm run build

Configuration

The server can be configured via environment variables or command-line arguments:

Client Integration Guides

1. Antigravity IDE

Add to your local MCP server configuration in Antigravity (~/.gemini/antigravity/mcp_config.json or project settings):

{
  "mcpServers": {
    "noteking": {
      "command": "node",
      "args": ["/Users/leonid/src/noteking-mcp/dist/index.js"],
      "env": {
        "NOTEKING_API_URL": "http://localhost:3000"
      }
    }
  }
}

2. Claude Desktop

Add noteking to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "noteking": {
      "command": "node",
      "args": ["/absolute/path/to/noteking-mcp/dist/index.js"],
      "env": {
        "NOTEKING_API_URL": "http://localhost:3000"
      }
    }
  }
}

3. Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "noteking": {
      "command": "node",
      "args": ["/absolute/path/to/noteking-mcp/dist/index.js"],
      "env": {
        "NOTEKING_API_URL": "http://localhost:3000"
      }
    }
  }
}

Available MCP Primitives

MCP Tools (18)

MCP Resources (5)

MCP Prompts

• noteking_use_note_template: Dynamically loads any NoteKing note by ID and populates {{variable}} placeholders from a variables JSON dictionary.

• noteking_author_note: Interactive engineering guide that assists agents and users in drafting structured ADRs, design docs, runbooks, meeting notes, or scratchpads and saving them to NoteKing.

• noteking_summarize_project: Loads a NoteKing project and all its associated notes to synthesize an executive project summary, key architectural decisions, and open action items.

• Dynamic Note Prompts (noteking_<id>_<slug>): On startup, saved NoteKing notes are automatically discovered, {{variable}} placeholders are extracted from the body, and each note is exposed as a typed MCP prompt.

Development & Testing

# Regenerate TypeScript types from openapi.json
npm run typegen

# Typecheck with TypeScript
npm run typecheck

# Run unit and integration tests (Vitest)
npm test

# Build production bundle
npm run build

License

MIT © Leonid Medovyy