AIConductor

An open-source Model Context Protocol (MCP) server that orchestrates multi-stakeholder feature refinement and development execution workflows for AI-assisted software teams.

Overview

AIConductor gives your AI coding agent a structured, auditable pipeline — from raw feature idea to merged code. It exposes 39 MCP tools that any MCP-compatible agent (Claude, Copilot, Cursor, Cline, etc.) can call to drive tasks through two workflows:

1. Feature Refinement — Break a feature into discrete tasks, then route each task through a sequential stakeholder approval chain before any code is written.
2. Development Execution — Drive approved tasks through a Developer → Code Reviewer → QA lifecycle with full audit history.

Features

Prerequisites

• Docker and Docker Compose
• An MCP-compatible AI agent (Claude Desktop, VS Code Copilot, Cursor, Cline, etc.)

Quick Start

git clone https://github.com/your-org/aiconductor.git
cd aiconductor
docker compose up -d

The MCP server and dashboard are now running. Connect your AI agent by adding the following to your MCP config:

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aiconductor": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "DISABLE_DASHBOARD=true", "aiconductor-mcp", "node", "dist/bundle.js"]
    }
  }
}

VS Code — .vscode/mcp.json or user settings

{
  "mcp.servers": {
    "aiconductor": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "DISABLE_DASHBOARD=true", "aiconductor-mcp", "node", "dist/bundle.js"]
    }
  }
}

Restart your agent. Open the dashboard at http://localhost:5111.

Workflows

Two slash-command workflows are included in .github/prompts/ and can be invoked directly from your agent.

/refine-feature — Feature Refinement

Turns a plain-text feature description into stakeholder-approved, implementation-ready tasks.

Feature Description
  │
  ├─ Scope determination & context gathering
  ├─ Attachment analysis (images, docs, spreadsheets)
  ├─ Clarification questions
  ├─ SMART acceptance criteria generation
  ├─ Test scenario generation
  ├─ Task breakdown (5–8 tasks)
  │
  └─ Batched stakeholder review cycle
       │
       ├─ Product Director  →  Architect  →  UI/UX Expert  →  Security Officer
       │        │                  │               │                  │
       │     reject             reject          reject             reject
       │        └──────────────────┴───────────────┴──────────────────┘
       │                                  ▼
       │                         NeedsRefinement → restart
       │
       └─ All tasks reach ReadyForDevelopment ✓

Tasks are processed in batches per role — a single role adoption covers all tasks in one pass, dramatically reducing context overhead.

/dev-workflow — Development Execution

Drives ReadyForDevelopment tasks through implementation to Done.

ReadyForDevelopment
  └─→ InProgress ─→ InReview ─→ InQA ─→ Done ✓
           │             │          │
           └─────────────┴──────────┘
                    NeedsChanges → back to InProgress

Each stage is handled by a distinct role: Developer (implements & tests), Code Reviewer (approves or requests changes), QA (verifies acceptance criteria).

Dashboard

Open http://localhost:5111 in your browser.

• Kanban board — Task cards arranged by workflow status; empty columns collapse to a slim strip so all columns fit on screen without horizontal scrolling
• Real-time updates — WebSocket connection pushes task state changes instantly to all open browser tabs
• Detail panel — Per-feature acceptance criteria, test scenarios, clarifications, and refinement step progress
• Multi-repo switcher — Switch between registered repositories from the sidebar
• Reviewer presence — See which reviewers are currently active on a feature

MCP Tools Reference

Orchestration

Stakeholder Reviews

Development Pipeline

Feature & Task Management

Refinement Tracking

Checkpoint Management

Repository Management

Stakeholder Roles

Project Structure

src/
├── index.ts                 # MCP server — tool definitions and request handling
├── AIConductor.ts     # Business logic for all workflow operations
├── WorkflowValidator.ts     # State machine — validates transitions and returns role prompts
├── DatabaseHandler.ts       # SQLite CRUD operations
├── rolePrompts.ts           # System prompts for each stakeholder role
├── websocket.ts             # WebSocket server — real-time event broadcasting
├── dashboard.ts             # Express web server (port 5111)
├── types.ts                 # TypeScript interfaces
└── client/                  # React SPA (Vite)

.github/prompts/
├── refine-feature.prompt.md # Feature refinement workflow
└── dev-workflow.prompt.md   # Development execution workflow

Database:

• Docker: /data/tasks.db (persistent volume task-review-data)
• Local: ./tasks.db in project root

Local Development

npm install
npm run dev          # Watch mode — recompiles on change
npm run build        # Production build (server + client)
npm test             # Run all tests with coverage
npm run lint         # TypeScript and code quality lint
npm run dashboard    # Start dashboard standalone (port 5111)

To rebuild the Docker image after code changes:

docker compose up -d --build

CI/CD Pipeline

All pull requests automatically run through our GitHub Actions CI workflow, which includes:

• Build — TypeScript compilation with npm run build
• Lint — Code quality checks with npm run lint
• Test — Jest tests with coverage tracking via npm test
• Coverage — Coverage metrics uploaded to Codecov

See CONTRIBUTING.md for details on running these checks locally, understanding failures, and our branch protection rules.

Configuration

To reset all data:

docker compose down -v && docker compose up -d

License

MIT