@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

The dependency on @kjerneverk/riotplan 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.