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

Related MCP server: Context Portal MCP (ConPort)

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

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.