npm package: @orchestrator-claude/mcp-server
Description: MCP Thin Client for Orchestrator - delegates to REST API
Author: Orchestrator Team
Latest version: 3.30.2

# @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)

```bash
npm install -g @orchestrator/mcp-server
```

### Local Installation

```bash
npm install @orchestrator/mcp-server
```

## Configuration

### Prerequisites

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

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

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

   ```bash
   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):

```json
{
  "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

```bash
npm run build
```

### Testing

```bash
npm test
```

### Running Locally

```bash
# With debug logging
MCP_DEBUG=true npm start
```

## Troubleshooting

### "API server unavailable"

1. Check if REST API is running:
   ```bash
   curl http://localhost:3000/api/v1/health
   ```

2. Check if API key is configured:
   ```bash
   cat ~/.orchestrator/config.json
   ```

3. Regenerate API key if needed:
   ```bash
   orchestrator auth generate
   ```

### "API key not configured"

Run:
```bash
orchestrator auth generate
```

### MCP Server Not Found in Claude

1. Ensure global installation:
   ```bash
   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](https://docs.orchestrator.ai)
- [GitHub Issues](https://github.com/your-org/orchestrator/issues)
- [Discord Community](https://discord.gg/orchestrator)