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