# Orchestrator MCP Server

MCP server that exposes workflows and agents information to Claude Code.

## Tools Available

### 1. `list_workflows`

List all available workflows in `.ai/workflows/`

**Example:**
```
Use list_workflows MCP tool
```

**Response:**
```json
{
  "workflows": [
    {
      "name": "feature-complete",
      "description": "Complete feature development workflow (Architect → Developer → Tester → Reviewer)"
    },
    {
      "name": "bug-fix",
      "description": "Bug fix workflow (Developer → Tester → Reviewer)"
    },
    {
      "name": "refactor",
      "description": "Code refactoring workflow (Architect → Developer → Reviewer)"
    }
  ],
  "total": 3
}
```

---

### 2. `get_workflow_info`

Get detailed information about a specific workflow.

**Input:**
- `workflowName` (string) - Name without .yaml extension

**Example:**
```
Use get_workflow_info for "feature-complete"
```

**Response:**
```json
{
  "name": "feature-complete",
  "description": "Architect → Developer → Tester → Reviewer",
  "steps": 4,
  "stepDetails": [
    {
      "name": "design",
      "agent": "architect",
      "onError": "fail",
      "retries": 0
    },
    {
      "name": "implement",
      "agent": "developer",
      "onError": "fail",
      "retries": 0
    },
    {
      "name": "test",
      "agent": "tester",
      "onError": "retry",
      "retries": 1
    },
    {
      "name": "review",
      "agent": "reviewer",
      "onError": "fail",
      "retries": 0
    }
  ],
  "variables": {
    "level": "balanced",
    "platform": "web"
  }
}
```

---

### 3. `execute_workflow` (Simulated)

Shows how to execute a workflow (returns simulation info).

**Input:**
- `workflowName` (string) - Name of workflow
- `variables` (object) - Variables to pass

**Example:**
```
Use execute_workflow with:
{
  "workflowName": "feature-complete",
  "variables": {
    "featureName": "user-authentication",
    "requirements": "Users can login with email/password",
    "level": "balanced",
    "platform": "web"
  }
}
```

**Response:**
```json
{
  "status": "simulated",
  "message": "Workflow execution is simulated in this MCP server",
  "workflow": {
    "name": "feature-complete",
    "description": "Complete feature development...",
    "steps": 4
  },
  "variables": { ... },
  "note": "To execute workflows with real agents, use the Orchestrator TypeScript API directly",
  "example": "import { WorkflowEngine } from '.ai/orchestrator'..."
}
```

**Note:** Real workflow execution requires the TypeScript API (not available via MCP yet).

---

### 4. `list_agents`

List all available specialized agents.

**Example:**
```
Use list_agents MCP tool
```

**Response:**
```json
{
  "agents": [
    {
      "name": "architect",
      "description": "System architect - Designs architecture, creates ADRs, defines interfaces",
      "tools": ["crafted-context", "filesystem", "architecture-guard"]
    },
    {
      "name": "developer",
      "description": "Software developer - Implements features, writes clean code, respects patterns",
      "tools": ["crafted-context", "filesystem", "git", "typescript", "crafted-cli"]
    },
    {
      "name": "tester",
      "description": "QA Engineer - Writes comprehensive tests, ensures coverage requirements",
      "tools": ["crafted-context", "filesystem", "vitest"]
    },
    {
      "name": "reviewer",
      "description": "Code Reviewer - Reviews code quality, validates rules, approves or rejects",
      "tools": ["git", "rules-validator", "architecture-guard", "vitest", "typescript"]
    }
  ],
  "total": 4
}
```

---

### 5. `get_agent_info`

Get detailed information about a specific agent.

**Input:**
- `agentName` (string) - architect, developer, tester, or reviewer

**Example:**
```
Use get_agent_info for "architect"
```

**Response:**
```json
{
  "name": "architect",
  "description": "System architect - Designs architecture, creates ADRs, defines interfaces",
  "tools": ["crafted-context", "filesystem", "architecture-guard"],
  "outputFormat": "json",
  "systemPromptLength": 2845,
  "systemPromptPreview": "# System Architect Agent\n\nYou are a **System Architect** for Crafted SaaS projects..."
}
```

---

## Usage in Claude Code

### Example 1: Explore Workflows

```
You: What workflows are available?

Claude: *Uses list_workflows*
You have 3 workflows available:
1. feature-complete - Full feature development
2. bug-fix - Bug fixing with tests
3. refactor - Code refactoring

You: Tell me more about feature-complete

Claude: *Uses get_workflow_info*
The feature-complete workflow has 4 steps:
1. Architect designs architecture
2. Developer implements
3. Tester writes tests (with retry on failure)
4. Reviewer validates

Default variables: level=balanced, platform=web
```

### Example 2: Understand Agents

```
You: What agents do we have?

Claude: *Uses list_agents*
We have 4 specialized agents:
- Architect (design)
- Developer (implement)
- Tester (test)
- Reviewer (validate)

You: What does the Architect agent do?

Claude: *Uses get_agent_info for architect*
The Architect agent designs architecture, creates ADRs, and defines interfaces.

Tools available:
- crafted-context (project understanding)
- filesystem (read existing code)
- architecture-guard (validate boundaries)

Output format: JSON with architecture, files, interfaces, ADRs, and risks.
```

### Example 3: Plan Workflow Execution

```
You: I want to implement user authentication using the workflow

Claude: *Uses get_workflow_info for feature-complete*
Here's how the feature-complete workflow would run:

Variables you need to provide:
- featureName: "user-authentication"
- requirements: "Users can login/register with email/password"
- level: "balanced" (or rapid/crafted)
- platform: "web" (or web-mobile)

Workflow steps:
1. Architect will design a 3-layer architecture (Balanced level)
2. Developer will implement auth.router, auth.service, user.repository
3. Tester will write tests ensuring 70% coverage
4. Reviewer will validate code quality and approve

To execute this workflow, you would use the TypeScript API directly in your code.
```

---

## Limitations

**Current MCP Implementation:**
- ✅ List and inspect workflows
- ✅ List and inspect agents
- ❌ Execute workflows with real agents (requires TypeScript API)

**Why no execution?**
MCP servers are stateless and cannot maintain long-running processes. Real workflow execution with agents requires the TypeScript orchestrator API.

---

## Real Workflow Execution

For actual workflow execution, use the TypeScript API:

```typescript
import { WorkflowEngine } from '.ai/orchestrator';

// Setup
const stepExecutor = async (agent, input, context) => {
  // Your agent execution logic
  // This would call the actual AI with the agent's system prompt
};

const engine = new WorkflowEngine('.ai/workflows', stepExecutor);

// Execute
const result = await engine.executeWorkflow('feature-complete', {
  featureName: 'user-authentication',
  requirements: 'Users can login/register',
  level: 'balanced',
  platform: 'web',
});

console.log(result.success); // true/false
console.log(result.outputs); // All agent outputs
```

---

## Future Enhancements

Planned for future versions:

1. **Real workflow execution via MCP**
   - Long-running process support
   - Progress streaming
   - Cancellation support

2. **Workflow creation**
   - `create_workflow` tool
   - YAML validation
   - Template workflows

3. **Custom agents**
   - `create_agent` tool
   - Custom system prompts
   - Tool configuration

---

For now, use this MCP server to **explore and understand** workflows and agents. For **execution**, use the TypeScript API directly.
