Planner MCP Monorepo

A TypeScript monorepo for turning planning documents into structured SQLite data and exposing plan metadata to AI agents through MCP.

Repository Map

Path	Responsibility
packages/api	Markdown parser/formatter, domain types, SQLite repository, and REST API
packages/mcp	MCP stdio server and REST API client
skills/idea-planner	Phase-gated brain-dump planning skill and direct transfer scripts
docs/REPOSITORY_MAP.md	Detailed ownership, data flow, and extension map
AGENTS.md	Working rules and verification guidance for coding agents

Requirements

• Node.js 22.5 or newer; SQLite is provided by Node's built-in node:sqlite module
• npm 10 or newer
• curl for the skill's shell scripts

Setup

npm install
npm run check

Run

Start the API in one terminal:

PLANNER_DB_PATH=planner.sqlite npm run dev:api

The API defaults to http://127.0.0.1:3000.

Start the MCP stdio server from an MCP client configuration:

{
  "mcpServers": {
    "planner": {
      "command": "npm",
      "args": ["run", "dev:mcp"],
      "cwd": "/absolute/path/to/planner-mcp",
      "env": {
        "PLANNER_API_URL": "http://127.0.0.1:3000"
      }
    }
  }
}

Example local use in opencode.json/opencode.jsonc

"mcp": {
  "planner": {
    "type": "local",
    "enabled": true,
    "command": ["npm", "run", "dev:mcp"],
    "cwd": "/home/nhbody/git/planner-mcp",
    "environment": {
      "PLANNER_API_URL": "http://127.0.0.1:3000"
    }
  }
}

REST API

Method	Endpoint	Behavior
GET	/health	Readiness response
PUT	/plans	Parse and add/update a Markdown plan; returns { "reference": "..." }
GET	/plans	List plan frontmatter metadata
GET	/plans/:reference	Reconstruct canonical Markdown
DELETE	/plans/:reference	Delete a plan and all associated sections

PUT /plans requires Content-Type: text/markdown. A frontmatter reference of New creates a UUID-backed PLAN-... reference. Any other reference updates that plan transactionally.

Direct Plan Transfer

The scripts stream files directly to and from the API to avoid duplicating plan content in an agent context:

skills/idea-planner/scripts/upload-plan.sh path/to/plan.md
skills/idea-planner/scripts/download-plan.sh PLAN-id path/to/plan.md
skills/idea-planner/scripts/sync-plan.sh path/to/plan.md

Set PLANNER_API_URL to override the default API URL. sync-plan.sh uploads, captures the reference, and atomically replaces the local document with canonical Markdown containing that reference.

MCP Surface

The MCP server exposes list_plans, which returns saved plans and metadata, and delete_plan, which permanently deletes a plan and its associated sections. delete_plan is destructive and must only be invoked after an explicit user request to delete that plan. Use the shell scripts for bulk Markdown upload and download.

Verification

npm run typecheck
npm run test:unit
npm run test:integration
npm run test:e2e
npm run build
npm run check

Tests use in-memory or temporary SQLite databases and do not touch planner.sqlite.