OrchestrateKit MCP

Local stdio MCP server that gives Cursor and Claude Desktop access to an opinionated, evidence-backed workflow graph for designing production-ready AI workflows.

Status: Scaffold with stub registry loader (MAR-35 graph-ready). Schemas, full registry data and graph tools are added in subsequent issues.

---

What it does

OrchestrateKit MCP exposes a structured registry of:

components  →  the building blocks of AI workflows
edges       →  tested relations between components (requires, safer_with, conflicts_with, …)
stacks      →  opinionated technology choices for different deployment contexts
routes      →  tested paths through the component graph
playbooks   →  golden-path routes with full implementation guidance

When a user describes a workflow goal, the MCP can:

1. Match the goal to required capabilities and components.
2. Traverse tested component relationships.
3. Reuse sections of known golden-path playbooks.
4. Compose a candidate route when no exact playbook exists.
5. Score route confidence (coverage, tested edges, stack fit, safety, simplicity).
6. Return the route as structured implementation context for Cursor or Claude.

---

What works right now

• MCP server starts on stdio and responds to the health_check tool.
• health_check returns { name, version, registry: { component_count, edge_count, stack_count, route_count, playbook_count } }.
• Registry loader stub returns zero counts — real data is added in MAR-38.
• pnpm verify (typecheck + tests) passes from a clean install.

---

Requirements

• Node.js ≥ 20
• pnpm

---

Local setup

cd orchestratekit-mcp
pnpm install
pnpm verify        # typecheck + tests — must pass before anything else
pnpm dev           # starts the MCP server on stdio

The server reads from stdin and writes JSON-RPC to stdout. All log output goes to stderr.

---

Connect from Cursor

Copy examples/cursor-mcp.json content into your Cursor workspace MCP config at .cursor/mcp.json. Replace the cwd value with the absolute path to this directory.

{
  "mcpServers": {
    "orchestratekit": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/absolute/path/to/orchestratekit-mcp"
    }
  }
}

---

Connect from Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "orchestratekit": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/absolute/path/to/orchestratekit-mcp"
    }
  }
}

---

Scripts

Script	Description
pnpm dev	Run server directly with tsx (no build step)
pnpm build	Compile to dist/ with tsup
pnpm typecheck	TypeScript type-check only (no emit)
pnpm test	Run unit tests with vitest
pnpm verify	Run typecheck then test

---

Project structure

orchestratekit-mcp/
  src/
    server.ts               Entry point — wires MCP server to stdio transport
    config.ts               Server name and version constants
    tools/
      index.ts              Tool registration (health_check + 8 graph tools)
      composeWorkflowRoute.ts
      listGraphComponents.ts / getGraphComponent.ts
      listGraphEdges.ts / getGraphEdge.ts
      getStackRecommendation.ts
      listKnownRoutes.ts / getRoute.ts
    registry/
      registryLoader.ts     YAML loader with validation, status filtering, cross-ref checks
      componentSchema.ts / edgeSchema.ts / stackSchema.ts / routeSchema.ts / playbookSchema.ts
      registryTypes.ts / registryValidation.ts
    graph/
      capabilityMatcher.ts  Keyword + token matching: goal text → components
      routeComposer.ts      Orchestrates all graph modules into a composed route
      routeScoring.ts       Deterministic 0-100 score with breakdown
      routeOrdering.ts      Topological sort via Kahn's algorithm
      safetyAugmenter.ts    Auto-adds approval gates and audit log
      playbookOverlap.ts    Detects overlap with known playbooks/routes
    docs-index/             Supplementary docs loader (future)
    lib/
      errors.ts             McpToolError class and toErrorResult helper
      logger.ts             Stderr-only logger (stdout reserved for transport)

  registry/
    components/             Component YAML files (added in MAR-38)
    edges/                  Edge/relation YAML files (added in MAR-38)
    stacks/                 Stack YAML files (added in MAR-38)
    routes/                 Route YAML files (added in MAR-38)
    playbooks/              Golden-path playbook YAML files (added in MAR-38)

  docs-index/               Supplementary context documents
  examples/
    cursor-mcp.json         Example Cursor MCP config
    claude-desktop-config.json  Example Claude Desktop config
  tests/
    health-check.test.ts

---

Non-goals (this phase)

• No remote hosting
• No auth / OAuth
• No vector database
• No graph database (Neo4j etc.)
• No automatic registry updates
• No LLM API calls inside MCP tools
• No SaaS dashboard
• No dependency on OrchestrateLab at runtime

---

Build order

MAR-35  ✅  Scaffold — done
MAR-37  ✅  Graph registry schemas: components, edges, stacks, routes, playbooks
MAR-38  ✅  Seed workflow graph: 30 components, 47 edges, 1 stack, 5 playbooks
MAR-77  ✅  Graph lookup tools: list/get components, edges, stacks, routes
MAR-78  ✅  compose_workflow_route — deterministic route composer
MAR-49  ✅  Benchmark setup — see docs/BENCHMARKING.md

---

Benchmarking

To validate that the workflow graph improves planning quality over vanilla Cursor/Claude, run the manual benchmark described in docs/BENCHMARKING.md.

Quick start:

# Print session guide with route previews for all 7 prompts
pnpm tsx scripts/benchmark-template.ts

# Single prompt
pnpm tsx scripts/benchmark-template.ts p6_email_lead_crm

Results go in benchmarks/results-YYYY-MM-DD.md.