@orchestrator/mcp-server

MCP server for Orchestrator - thin client forwarding to REST API

Overview

This package provides an MCP (Model Context Protocol) server that exposes Orchestrator functionality to Claude Code and other MCP-compatible clients.

Architecture: This is a thin client that forwards all requests to the Orchestrator REST API. It contains NO business logic, only request transformation and error handling.

Installation

Global Installation (Recommended)

npm install -g @orchestrator/mcp-server

Local Installation

npm install @orchestrator/mcp-server

Configuration

Prerequisites

1. REST API Server Running: The MCP server requires the Orchestrator REST API to be running.

   # Start API server (in main orchestrator project)
   docker-compose up -d
   # OR
   npm start

2. API Key: Generate an API key using the CLI:

   orchestrator auth generate

   This creates ~/.orchestrator/config.json with your API key.

Claude Code Integration

Add to your Claude Code config (.mcp.json or Claude settings):

{
  "mcpServers": {
    "orchestrator": {
      "command": "orchestrator-mcp-server"
    }
  }
}

Environment Variables

• MCP_DEBUG=true - Enable debug logging
• ORCHESTRATOR_API_URL - Override API URL (default: http://localhost:3000)

Available Tools

Workflow Management

• getStatus - Get workflow status
• advancePhase - Advance workflow to next phase
• approveAction - Approve pending action
• getContext (v2) - Get workflow context and available actions
• executeAction (v2) - Execute deterministic action

Project Management

• detectWorkflow - Detect workflow type from prompt
• validateArtifact - Validate generated artifacts
• createCheckpoint - Create git checkpoint

Ping-Pong Pattern (LIM-001 Solution)

• getNextAction - Get next pending action
• setPendingAction - Set pending action for agent invocation
• clearPendingAction - Clear pending action
• approveAction - Approve action requiring human approval

Architecture

Claude Code
    ↓
MCP Server (thin client)
    ↓
REST API (business logic)
    ↓
Domain/Application/Infrastructure Layers

Key Principles:

1. No Business Logic: All logic resides in REST API
2. Stateless: No state stored in MCP server
3. Simple Transformation: Request → API Call → Response
4. Error Forwarding: API errors forwarded to Claude

Development

Building

npm run build

Testing

npm test

Running Locally

# With debug logging
MCP_DEBUG=true npm start

Troubleshooting

"API server unavailable"

1. Check if REST API is running:

   curl http://localhost:3000/api/v1/health

2. Check if API key is configured:

   cat ~/.orchestrator/config.json

3. Regenerate API key if needed:

   orchestrator auth generate

"API key not configured"

Run:

orchestrator auth generate

MCP Server Not Found in Claude

1. Ensure global installation:

   npm list -g @orchestrator/mcp-server

2. Restart Claude Code after installing

3. Check Claude Code logs for MCP connection errors

Version Compatibility

| MCP Server | Orchestrator CLI | REST API | |------------|------------------|----------| | 0.9.x | >= 0.9.0 | >= 0.9.0 | | 1.0.x | >= 1.0.0 | >= 1.0.0 |

License

MIT

Support

• Documentation
• GitHub Issues
• Discord Community