Skip to main content
Glama

doer-mcp

Version MCP Server TypeScript Node.js Doer Engine License: MIT

Official TypeScript-based Model Context Protocol (MCP) server for 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.


Related MCP server: Task MCP Server

Architecture Overview

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

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

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

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

{
  "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

# 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

Available Tools

19 tools
doer_append_to_todo_listB

Append one or more task items or markdown sections to a todo list (items are automatically formatted as '- [ ] ...')

Inputs: id (required), items (required), section_header, render_markdown.

doer_create_projectC

Create a new project workspace in Doer to organize related todo lists and checklists

Inputs: name (required), description.

doer_create_todo_listB

Create a new markdown todo list or checklist in Doer (assigned to a project or kept standalone)

Inputs: title (required), body, pinned, project_id, +1 more.

doer_delete_attachmentC

Purge and delete a file attachment from a todo list

Inputs: todo_list_id (required), attachment_id (required).

doer_delete_projectC

Delete a project workspace in Doer

Inputs: id (required).

doer_delete_todo_listB

Permanently delete a todo list and its context attachments from Doer

Inputs: id (required).

doer_get_projectB

Get full details of a Doer project workspace, including its associated todo lists and metadata

Inputs: id (required).

doer_get_statsA

Get system statistics from Doer (total todo lists, standalone lists, pinned lists, projects, and attachments)

Inputs: no named parameters.

doer_get_todo_listB

Get a todo list by ID, including its raw markdown body, task checkboxes, pinned position, and optional HTML preview

Inputs: id (required), render_markdown.

doer_list_attachmentsC

List file attachments associated with a todo list in Doer

Inputs: todo_list_id (required).

doer_list_projectsB

List and search todo list projects and workspaces in Doer with list counts and pagination

Inputs: q, limit, offset.

doer_list_todo_listsA

Search and list todo lists with filtering by project, standalone status, pinned status, or keyword

Inputs: q, limit, scope, offset, +2 more.

doer_render_markdownA

Render Markdown text to sanitized HTML using Doer's GitHub-flavored markdown Redcarpet pipeline

Inputs: text (required).

doer_reorder_pinnedC

Update the sequential ordering position of pinned todo lists in the Doer sidebar

Inputs: todo_list_ids (required).

doer_toggle_pinB

Toggle the pinned status of a todo list on the Doer persistent sidebar

Inputs: id (required).

doer_toggle_todo_itemA

Toggle or mark a specific task checklist item (- [ ] / - [x]) in a todo list by 0-based index, line number, or matching text

Inputs: id (required), index, complete, match_text, +2 more.

doer_update_projectC

Update an existing project's name or description in Doer

Inputs: id (required), name, description.

doer_update_todo_listC

Update an existing todo list's title, markdown body, project assignment, or pin state in Doer

Inputs: id (required), body, title, pinned, +3 more.

doer_upload_attachmentB

Upload one or more files to attach to a todo list in Doer (accepts local file paths or base64 data)

Inputs: files (required), todo_list_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    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

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI clients to manage todo tasks through Tools for adding, listing, completing, and searching, alongside Prompts for daily reviews and task breakdowns. Exposes task lists and statistics as Resources with local JSON file persistence.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to manage a local-first Kanban board with Azure DevOps-style workflow rules, including task creation, status updates, subtask breakdown, full-text search, daily summaries, and next-task suggestions.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to maintain a persistent developer logbook with notes, TODOs, reminders, code TODO scanning, and full-text search, while keeping all data local and optionally syncing with Obsidian.
      79 npm
      1
      MIT