<p align="center">
  <img src="assets/logo.jpg" alt="NoteKing MCP" width="400" />
</p>

# noteking-mcp

[![Version](https://img.shields.io/badge/version-1.0.0-emerald.svg)](https://github.com/leouofa/noteking-mcp/releases/tag/v1.0.0)
[![MCP Server](https://img.shields.io/badge/MCP-Server-purple.svg)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![NoteKing Engine](https://img.shields.io/badge/NoteKing-Rails_8-D30001?logo=rubyonrails&logoColor=white)](https://github.com/leouofa/noteking)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Official TypeScript-based [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [NoteKing](https://github.com/leouofa/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.

---

## Architecture Overview

```mermaid
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

```bash
# 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:

| Option | Environment Variable | CLI Flag | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| **API URL** | `NOTEKING_API_URL` | `-u, --url <url>` | `http://localhost:3000` | NoteKing API base URL |
| **API Key** | `NOTEKING_API_KEY` | `-k, --api-key <key>` | *(none)* | Optional Bearer token for authentication |
| **Timeout** | `NOTEKING_TIMEOUT_MS` | `-t, --timeout <ms>` | `30000` | HTTP request timeout in milliseconds |
| **Note Sync** | — | `--no-sync` | `true` | Eagerly register saved NoteKing notes at startup |

---

## Client Integration Guides

### 1. Antigravity IDE

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

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

```json
{
  "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`:

```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)

| Tool | Description | Key Parameters |
| :--- | :--- | :--- |
| `noteking_list_projects` | Search and list project workspaces | `q` (query), `limit`, `offset` |
| `noteking_get_project` | Get project details and associated note index | `id` |
| `noteking_create_project` | Create a new project workspace | `name`, `description` |
| `noteking_update_project` | Update project name or description | `id`, `name`, `description` |
| `noteking_delete_project` | Delete a project (notes preserved as standalone) | `id` |
| `noteking_list_notes` | Search & filter notes across scopes | `q`, `project_id`, `scope` (`standalone`, `all`), `pinned`, `limit`, `offset` |
| `noteking_get_note` | Retrieve note Markdown body, attachments & HTML | `id`, `render_markdown` |
| `noteking_create_note` | Create a note (in a project or standalone) | `title`, `body`, `project_id`, `pinned`, `pinned_position` |
| `noteking_update_note` | Edit note content, project assignment, or pin | `id`, `title`, `body`, `project_id`, `pinned`, `pinned_position`, `render_markdown` |
| `noteking_append_to_note` | Safely append Markdown content to an existing note | `id`, `content`, `separator`, `render_markdown` |
| `noteking_delete_note` | Delete a note and its attachments permanently | `id` |
| `noteking_toggle_pin` | Toggle sidebar pin status for a note | `id` |
| `noteking_reorder_pinned` | Reorder sequential pinned notes | `note_ids` (array of numbers) |
| `noteking_list_attachments` | List files attached to a note | `note_id` |
| `noteking_upload_attachment` | Attach files (paths or base64) to a note | `note_id`, `files` (`path` or `content_base64` + `filename`) |
| `noteking_delete_attachment` | Purge an attachment from a note | `note_id`, `attachment_id` |
| `noteking_render_markdown` | Render GFM into sanitized HTML | `text` |
| `noteking_get_stats` | Inspect platform counts & metrics | *(none)* |

### MCP Resources (5)

| URI Pattern | MIME Type | Description |
| :--- | :--- | :--- |
| `noteking://stats` | `application/json` | Workbench metrics (total notes, standalone notes, pinned notes, projects, attachments) |
| `noteking://projects` | `application/json` | Index list of all project workspaces |
| `noteking://projects/{id}` | `application/json` | Project detail including its associated note list |
| `noteking://notes` | `application/json` | Index list of all notes and scratchpads |
| `noteking://notes/{id}` | `text/markdown` | Full note Markdown body with YAML metadata frontmatter |

### 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

```bash
# 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