Skip to main content
Glama
README.md
<p align="center">
  <img src="assets/logo.jpg" alt="Doer MCP" width="400" />
</p>

# doer-mcp

[![Version](https://img.shields.io/badge/version-1.0.0-emerald.svg)](https://github.com/leouofa/doer-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)
[![Doer Engine](https://img.shields.io/badge/Doer-Rails_8-D30001?logo=rubyonrails&logoColor=white)](https://github.com/leouofa/doer)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Official TypeScript-based [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Doer](https://github.com/leouofa/doer), the local-first Markdown todoing tool and checklist workbench for developers.

This server enables AI assistants and agents (Antigravity, Claude Desktop, Cursor, and custom MCP clients) to seamlessly search, author, append, toggle checklist items, organize, and pin developer todo lists and sprint goals, manage ActiveStorage file attachments, and render GitHub Flavored Markdown directly through the Doer REST API.

---

## Features

- **Full MCP Capabilities Suite**:
  - **19 Comprehensive Tools**: Full CRUD for projects and todo lists, specialized checklist manipulation (`doer_append_to_todo_list`, `doer_toggle_todo_item`), full-text search, pin & reorder management, file attachments, and GFM Markdown rendering.
  - **5 MCP Resources**: Direct URI inspection via `doer://stats`, `doer://projects`, `doer://projects/{id}`, `doer://todo_lists`, and `doer://todo_lists/{id}` (Markdown with YAML frontmatter).
  - **Task Breakdown & Sprint Prompts + Dynamic Sync**: Built-in prompts for deconstructing objectives (`doer_breakdown_task`), synthesizing project workspaces and planning sprints (`doer_plan_project_sprint`), and executing `{{variable}}` checklist templates (`doer_use_list_template`), plus automatic startup registration of saved Doer todo lists.
- **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 Doer's OpenAPI 3.1.0 specification with runtime `Zod` validation.
- **Zero Friction Setup**: Works out of the box with your local Doer 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["Doer MCP Server<br/>(@modelcontextprotocol/sdk)"]
    APIClient["Typed DoerClient<br/>(Node native fetch)"]
    DoerAPI["Doer Rails API<br/>(http://localhost:3000/api/v1)"]

    Client <-->|MCP Protocol| Stdio
    Stdio <--> MCPServer
    MCPServer -->|19 Tools / 5 Resources / Prompts| APIClient
    APIClient <-->|REST JSON & Multipart| DoerAPI
```

---

## Quickstart

### Prerequisites

- **Node.js**: `v18.0.0` or higher (recommended: Node 20+)
- **Doer**: Running locally (default: `http://localhost:3000`)

### Installation & Build

```bash
# Clone repository
git clone https://github.com/leouofa/doer-mcp.git
cd doer-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** | `DOER_API_URL` | `-u, --url <url>` | `http://localhost:3000` | Doer API base URL |
| **API Key** | `DOER_API_KEY` | `-k, --api-key <key>` | *(none)* | Optional Bearer token for authentication |
| **Timeout** | `DOER_TIMEOUT_MS` | `-t, --timeout <ms>` | `30000` | HTTP request timeout in milliseconds |
| **Template Sync** | — | `--no-sync` | `true` | Eagerly register saved Doer checklists at startup |

---

## Client Integration Guides

### 1. Antigravity IDE

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

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

### 2. Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "doer": {
      "command": "node",
      "args": ["/path/to/doer-mcp/dist/index.js"],
      "env": {
        "DOER_API_URL": "http://localhost:3000"
      }
    }
  }
}
```

### 3. Cursor

Add to your project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "doer": {
      "command": "node",
      "args": ["/path/to/doer-mcp/dist/index.js"],
      "env": {
        "DOER_API_URL": "http://localhost:3000"
      }
    }
  }
}
```

---

## MCP Primitives Reference

### Tools (19)

#### Project Management
| Tool Name | Description | Key Parameters |
| :--- | :--- | :--- |
| `doer_list_projects` | Search and list project workspaces with list counts | `q`, `limit`, `offset` |
| `doer_get_project` | Get project details and all associated todo lists | `id` |
| `doer_create_project` | Create a new project workspace | `name`, `description` |
| `doer_update_project` | Update project name or description | `id`, `name`, `description` |
| `doer_delete_project` | Delete a project workspace | `id` |

#### Todo Lists & Checklists
| Tool Name | Description | Key Parameters |
| :--- | :--- | :--- |
| `doer_list_todo_lists` | Search and list todo lists across projects or standalone | `q`, `project_id`, `scope`, `pinned`, `limit`, `offset` |
| `doer_get_todo_list` | Retrieve full todo list markdown, pin position, attachments | `id`, `render_markdown` |
| `doer_create_todo_list` | Create a new markdown todo list or checklist | `title`, `body`, `project_id`, `pinned`, `pinned_position` |
| `doer_update_todo_list` | Update title, body, project assignment, or pin position | `id`, `title`, `body`, `project_id`, `pinned`, `pinned_position` |
| `doer_delete_todo_list` | Delete a todo list permanently | `id` |
| `doer_toggle_pin` | Quick toggle pinning of a list to the sidebar | `id` |
| `doer_reorder_pinned` | Update ordered position of pinned todo lists | `todo_list_ids` |

#### Checklist Task Manipulation Helpers
| Tool Name | Description | Key Parameters |
| :--- | :--- | :--- |
| `doer_append_to_todo_list` | Append new task items or sections to an existing list | `id`, `items`, `section_header`, `render_markdown` |
| `doer_toggle_todo_item` | Toggle or set task checkbox (`- [ ]` / `- [x]`) by index, line, or text | `id`, `index`, `line_number`, `match_text`, `complete` |

#### File Attachments
| Tool Name | Description | Key Parameters |
| :--- | :--- | :--- |
| `doer_list_attachments` | List context files attached to a todo list | `todo_list_id` |
| `doer_upload_attachment` | Attach files from local filesystem paths or base64 data | `todo_list_id`, `files` (`path`, `filename`, `content_base64`) |
| `doer_delete_attachment` | Remove an attachment by ID | `todo_list_id`, `attachment_id` |

#### Markdown & System
| Tool Name | Description | Key Parameters |
| :--- | :--- | :--- |
| `doer_render_markdown` | Render Markdown to sanitized HTML via Redcarpet | `text` |
| `doer_get_stats` | Retrieve platform aggregate metrics | *(none)* |

---

### Resources (5)

| Resource URI | MIME Type | Description |
| :--- | :--- | :--- |
| `doer://stats` | `application/json` | Aggregated metrics: total lists, standalone lists, pinned lists, projects, attachments |
| `doer://projects` | `application/json` | Index of all project workspaces |
| `doer://projects/{id}` | `application/json` | Detailed view of a project and its associated todo lists |
| `doer://todo_lists` | `application/json` | Index of all active todo lists |
| `doer://todo_lists/{id}` | `text/markdown` | Full todo list Markdown body with YAML frontmatter metadata |

---

### Prompts (3 + Dynamic Sync)

| Prompt Name | Arguments | Description |
| :--- | :--- | :--- |
| `doer_breakdown_task` | `goal`, `project_id` | Interactive workflow decomposing an objective into milestone markdown checklists |
| `doer_plan_project_sprint` | `project_id` | Synthesizes open vs completed checklist items and drafts a sprint plan |
| `doer_use_list_template` | `todo_list_id`, `variables` | Hydrates any saved checklist template substituting `{{variables}}` |
| Dynamic Sync (`doer_{id}_{slug}`) | Variable inputs | Automatically generates native prompts for saved lists containing `{{variables}}` |

---

## Development

```bash
# Generate types from OpenAPI specification
npm run typegen

# Run TypeScript typecheck
npm run typecheck

# Run Vitest test suite
npm test

# Build distribution bundle
npm run build
```

---

## License

MIT © [Leonid Medovyy](https://github.com/leouofa)

TDQS

B3.4/5.0

Scored across 19 tools

Disambiguation4/5

Most tools map cleanly to a distinct resource+action (project/list CRUD, attachments, pinning, rendering, stats). Minor overlap exists: doer_update_todo_list can change pin state and markdown body, which partially shadows doer_toggle_pin and doer_append_to_todo_list, but descriptions make the preferred path clear.

Naming Consistency5/5

All 19 tools use a uniform doer_ prefix with a verb_noun pattern (doer_list_projects, doer_create_todo_list, doer_delete_attachment). The few variations (doer_toggle_pin, doer_reorder_pinned, doer_append_to_todo_list) still follow predictable verb-first phrasing and target the same resource family.

Tool Count4/5

19 tools is on the heavy side of the ideal 3-15 band, but the count is driven by genuine sub-resources: two full CRUD entities (projects, todo lists) plus items, attachments, pinning, and utilities. Each tool covers a distinct operation rather than duplicating another.

Completeness4/5

Projects and todo lists have full CRUD, attachments have create/read/delete, and utilities (stats, markdown render) round out the surface. Gaps remain around individual task items: you can append and toggle them but there is no delete/remove-item or edit-item tool, and attachments cannot be fetched or renamed.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues