io.github.vncsleal/openplan

Official

by vncsleal · TypeScript

Plan, track, and learn from software projects — three MCP tools for the AI agent lifecycle.

Track software projects and organize tasks across the AI agent lifecycle.

Topics

ai-agentcost-estimationdeveloper-toolsmcpmodel-context-protocolopen-sourceplanningproject-managementai-planningcost-trackingopencodesqlitetypescript

README.md3 KBView on GitHub

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

bash

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:

json

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

claude_desktop_config.json:

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

bash

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

code

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

bash

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

Install

claude_desktop_config.json

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