devbook-mcp

Official TypeScript-based Model Context Protocol (MCP) server for Devbook, the distraction-free desktop prompt engineering workbench and studio.

This server enables AI assistants and agents (Claude Desktop, Antigravity, Cursor, and custom MCP clients) to seamlessly query, author, manage, and execute prompt templates, inspect projects, upload file attachments, and render GitHub Flavored Markdown directly through the Devbook REST API.

Features

• Full MCP Capabilities Suite:

  • 17 Comprehensive Tools: Full CRUD, full-text search, pin management, attachments, and markdown rendering.

  • MCP Resources: Direct URI inspection via devbook://stats, devbook://projects, devbook://prompts, and parameterized templates.

  • Dynamic MCP Prompts: Exposes Devbook prompt templates as native MCP prompt commands with automatic parsing and dynamic substitution of {{variable}} placeholders.

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

• Resilient Attachment Handling: Upload prompt 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 Devbook's OpenAPI 3.1.0 specification with runtime Zod validation.

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

Related MCP server: Paperclip MCP server

Architecture Overview

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

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

Quickstart

Prerequisites

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

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

Installation & Build

# Clone repository
git clone https://github.com/leouofa/devbook-mcp.git
cd devbook-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. Claude Desktop

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

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

2. Antigravity IDE

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

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

3. Cursor

Add to your .cursor/mcp.json:

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

Available MCP Primitives

MCP Tools

MCP Resources

MCP Prompts (Prompt Templates)

• devbook_execute_prompt: Dynamically loads any Devbook prompt by ID and populates {{variable}} placeholders from a variables JSON dictionary.

• devbook_author_prompt: Interactive guide that assists agents and users in authoring structured prompts with dynamic placeholders.

• Dynamic Prompts (devbook_<id>_<slug>): On startup, saved Devbook prompts are automatically discovered, variables are extracted from the template body, and exposed as first-class typed MCP prompts (e.g., devbook_5_project_bootstrap).

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