Labsco
orchestratemcp logo

Orchestrate MCP

★ 1

from orchestratemcp

OrchestrateMCP is the planning brain for agentic workflows.

🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#crm#slack#payments#database#cloud#devops

OrchestrateMCP

An evidence-backed workflow-design advisor for AI agents. Connect it to ChatGPT, Claude (web), Cursor, or Claude Desktop and it plans safer, more grounded AI workflows — grounded in a registry of tested components, edges, and golden-path playbooks. Read-only, stateless, holds no secrets.

Status: registry of 47 components, 78 edges, 4 workers, 1 stack, 6 routes, 6 playbooks; 17 tools; available over stdio and as a free hosted endpoint (https://mcp.orchestratemcp.dev/mcp).

What it does

OrchestrateMCP 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 runs on stdio (Cursor, Claude Desktop) and over Streamable HTTP / a Cloudflare Worker (ChatGPT, claude.ai) — 17 registered tools.
  • health_check returns { name, version, registry: { component_count, edge_count, stack_count, route_count, playbook_count, untested_edge_pct } }.
  • Registry loaded from YAML: 47 components, 78 edges, 1 stack, 5 routes, 5 playbooks.
  • pnpm verify (typecheck + lint + tests) passes from a clean clone and install.

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"
    }
  }
}

Connect from ChatGPT or claude.ai (hosted)

No install, no terminal — point your AI client at the free hosted endpoint:

https://mcp.orchestratemcp.dev/mcp

Full walkthrough (ChatGPT Developer-Mode connector + claude.ai): docs/CHATGPT_USAGE.md.

Connecting your workflow's services

Connecting the MCP to your client takes no auth (it's a read-only advisor). But the workflows it plans need your credentials for Gmail, Slack, Stripe, your CRM, and so on. For how to provision those safely — least-privilege scopes, secret managers, and managed-auth brokers — see docs/CONNECTION_SETUP.md. OrchestrateMCP never holds a credential.

Scripts

ScriptDescription
pnpm devRun server directly with tsx (no build step)
pnpm buildCompile to dist/ with tsup
pnpm typecheckTypeScript type-check only (no emit)
pnpm testRun unit tests with vitest
pnpm verifyRun 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 (17 tools: health_check + 16 graph/advisor 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 (47 active)
    edges/                  edge/relation YAML files (78 active)
    stacks/                 stack YAML files
    routes/                 route YAML files (5 validated)
    playbooks/              golden-path playbook YAML files (5)

  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 (by design)

  • No first-party credential storage — it recommends secret managers / managed-auth brokers, never holds a secret
  • No auth / OAuth / accounts — the hosted endpoint is read-only and stateless, nothing to log into
  • 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
MAR-88  ✅  Domain-gated capability matcher — eliminates cross-domain false positives
MAR-92  ✅  Registry lint + untested_edge_pct in health_check
MAR-95  ✅  crm_note_write component + research→content bridge edge
MAR-96  ✅  Benchmark protocol v2 — rubric, prompts-v2.yaml, PROTOCOL.md
MAR-97  ✅  Docs truth pass — registry counts, tool count, verify path

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:

# v2 protocol — print session guide for all 7 prompts
pnpm tsx scripts/benchmark-template.ts --prompts benchmarks/prompts-v2.yaml --all

# v2 — single prompt
pnpm tsx scripts/benchmark-template.ts --prompts benchmarks/prompts-v2.yaml --prompt p6_email_lead_crm

# v1 (legacy)
pnpm tsx scripts/benchmark-template.ts

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