OpenPlan MCP Server

Waze for AI agents — plan, track, and learn from software projects.

An MCP server that helps AI agents decompose goals into costed execution plans, checkpoint progress with deviation tracking, and learn from past project data.

Quick Start

npx @openplan/mcp

The server auto-creates its config and SQLite database on first run — no setup needed.

Add it to your MCP client:

opencode.json:

{
  "mcp": {
    "openplan": {
      "type": "local",
      "command": ["npx", "-y", "@openplan/mcp"]
    }
  }
}

claude_desktop_config.json:

{
  "mcpServers": {
    "openplan": {
      "command": "npx",
      "args": ["-y", "@openplan/mcp"]
    }
  }
}

Or run openplan install to auto-detect and configure both.

Tools (3)

| Tool | Description | |------|-------------| | plan(goal, context?, replan?, project?) | Decompose a goal into costed phases with estimates | | checkpoint(phase?, actual_cost?, correct?, route_id?, project?) | Record phase cost, correct data, or check status | | review(route_id?, project?) | Session retrospective with deviations, accuracy, learning |

Resources (3)

| URI | Description | |-----|-------------| | openplan://{project}/route | Current route state and phase progress | | openplan://profiles | Personal bias and accuracy by action | | openplan://sync-status | Mesh sync health and pending checkpoints |

CLI

openplan                 # Start MCP server (stdio mode)
openplan install         # Auto-detect and install in MCP clients
openplan auth            # Authenticate with Mesh via GitHub OAuth
openplan subscribe       # Subscribe to Pro (Stripe Checkout)
openplan portal          # Manage subscription (Stripe Customer Portal)
openplan account         # Show identity, API key, subscription
openplan config          # View current configuration
openplan mesh [on|off]   # Show or toggle Mesh sync
openplan status          # List routes for a project
openplan log             # Show checkpoint trail
openplan export          # Export calibration data (Pro)
openplan completion      # Generate shell completion script
openplan doctor          # Check system health and diagnose issues

Use --json on account, config, status, log, mesh for structured output. Auth supports --no-browser, --clipboard, --with-token <key>, and --debug.

Architecture

core/      Domain types, pure logic, typed ports
handlers/  MCP tool handlers — validation, wiring
adapters/  Mesh sync, cost probes, config loaders
db/        Drizzle schema, SQLite, DataStore implementation

One rule: Core never imports adapters or handlers. The DataStore port insulates core from Drizzle.

Development

npm install
npm run dev        # tsx watch
npm test           # vitest (config at vitest.config.ts)
npm run test:e2e   # end-to-end against compiled dist/
npm run build      # tsc
npm run lint       # biome check

CI/CD

GitHub Actions runs lint, test, build on every push/PR. Publish to npm happens automatically on version tags (v*).

Stack

• FastMCP — MCP framework with Zod schemas for input validation
• SQLite via better-sqlite3 / Drizzle ORM — 7 tables, local-first
• Mesh API (proprietary, at github.com/vncsleal/openplan-api) — cross-session cost learning
• Structured logging — createLogger(module) with [openplan:module] prefix
• Coverage — Vitest with 60% branch / 65% line thresholds

License: MIT