HTTP-based Model Context Protocol server for RiotPlan
@kjerneverk/riotplan-mcp-http
HTTP MCP server for RiotPlan.
This package is the network-facing surface of RiotPlan. It exposes every plan
operation as an MCP tool, resource, or prompt over HTTP using Hono and the
MCP SDK's StreamableHTTPTransport. Clients like Cursor, VS Code extensions,
and any MCP-compatible agent connect here.
What lives here
Server (`src/server-hono.ts`)
The Hono application that wires up MCP transport, session management, cloud
sync, RBAC authentication, plan download/upload routes, and the /health
endpoint. This is the main runtime entry point.
Tools (`src/tools/`)
Every riotplan_* MCP tool definition. Each file exports a tool object with
a name, Zod schema, description, and execute function. Tools cover the full
plan lifecycle:
- idea -- create plans, add notes/constraints/questions/evidence/narrative
- shaping -- start shaping, add approaches, compare, select
- build -- prepare caller-side generation instructions from plan artifacts
- build-write -- validate and persist generated plan artifacts and steps
- step -- start, complete, add, remove, move steps
- status -- read plan status
- transition -- move between lifecycle stages
- history -- checkpoints and timeline
- catalyst -- manage catalyst associations
- evidence -- structured evidence writer
- reflect -- step reflections
- retrospective -- generate plan retrospectives
- context -- read plan context for LLM consumption
- project -- bind plans to projects, resolve project context
- switch -- list plans, switch active plan, rename, delete
- generate -- server-side AI plan generation (legacy)
- validate -- plan validation
Resources (`src/resources/`)
MCP resource handlers for read-only access to plan data (plan metadata, status, steps, individual step content, idea, shaping, evidence, timeline, checkpoints, artifacts, prompts).
Prompts (`src/prompts/`)
MCP prompt templates for guided workflows (create plan, explore idea, shape approach, develop plan, execute step, execute plan, track progress, generate retrospective).
Session (`src/session/`)
Session management for multi-connection MCP server operation.
Other
rbac.ts-- role-based access control engine (API key auth, user/role lookup, route-level enforcement).bin-http.ts-- CLI entry point for starting the HTTP server.heartbeat.ts-- health/liveness utilities.types.ts-- MCP-specific type definitions (McpTool, ToolResult, ToolExecutionContext, resource types, prompt types).uri.ts--riotplan://URI parser.
Dependencies
| Package | Role |
|---|---|
@kjerneverk/riotplan |
Plan operations, types, AI artifact loading, config, status generation, step mutations, reflection writer, plan loader, plan categories |
@kjerneverk/riotplan-core |
Core service composition (lifecycle, status, idea, build helpers) -- used by a subset of tools |
@kjerneverk/riotplan-format |
SQLite provider for direct plan file/step/timeline access |
@kjerneverk/riotplan is a runtime dependency of this package (not a peer):
installing @kjerneverk/riotplan-mcp-http pulls the framework in automatically.
That dependency is currently broad — tools import from subpaths like
@kjerneverk/riotplan/ai/artifacts and @kjerneverk/riotplan/config. A future
goal is to narrow this so the MCP server depends only on well-defined service
interfaces rather than reaching into riotplan internals.
Development
During development, use npm link to resolve sibling packages:
cd ../riotplan && npm link
cd ../riotplan-core && npm link
cd ../riotplan-mcp-http && npm link @kjerneverk/riotplan @kjerneverk/riotplan-core @kjerneverk/riotplan-format
Status
Extraction in progress. Source code is real (copied from riotplan/src/mcp/
with imports rewritten to use package paths). The identical source still
exists in riotplan/src/mcp/ and is tested through the riotplan test
suite. Standalone build, tests, and npm publishing are not yet configured.
Tools (5)
ideaCreate plans and manage notes, constraints, questions, evidence, and narrative.shapingStart shaping, add approaches, compare, and select plan strategies.stepManage plan steps including starting, completing, adding, removing, and moving.retrospectiveGenerate plan retrospectives based on execution history.statusRead the current status of a plan.Environment Variables
RIOTPLAN_API_KEYrequiredAPI key for authentication and RBAC enforcement.Configuration
{"mcpServers": {"riotplan": {"command": "npx", "args": ["-y", "@kjerneverk/riotplan-mcp-http"], "env": {"RIOTPLAN_API_KEY": "your-api-key"}}}}