# Dev Team MCP — Autonomous AI Software Development Team

> **Submit a ticket → get production-ready code.**
>
> An autonomous MCP server that runs a full software development pipeline:
> **Planner → Coder → Tester → Reviewer → Delivery**
>
> Runs on port **8002** alongside:
> - DevOps MCP (`:8000`) — Docker, K8s, AWS, Git
> - Dev Agent MCP (`:8001`) — Code generation in 18 languages

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│  Claude Code / Copilot Chat                                         │
│                                                                     │
│  MCP Stdio Adapters:                                                │
│  ├── devops   → mcp-server      :8000  (DevOps — infra/git)        │
│  ├── dev      → mcp-dev-agent   :8001  (Code gen — 18 languages)   │
│  └── devteam  → dev-team-mcp    :8002  (Dev Team — full pipeline)  │
│                      │                                              │
│            ┌─────────▼─────────┐                                   │
│            │   ORCHESTRATOR    │                                    │
│            └─────────┬─────────┘                                   │
│                      │                                              │
│    ┌─────────────────┼─────────────────┐                           │
│    ▼                 ▼                 ▼                 ▼          │
│ PLANNER           CODER            TESTER           REVIEWER        │
│ Decompose         Generate         Write &          Security +      │
│ ticket into       production       run tests        perf + style    │
│ plan + stack      code files       fix failures     checklist       │
│    │                 │                 │                 │          │
│    └─────────────────┴─────────────────┴─────────────────┘         │
│                                │                                    │
│                      ┌─────────▼─────────┐                         │
│                      │  DELIVERY.md      │                         │
│                      │  git repo + tag   │                         │
│                      └───────────────────┘                         │
└─────────────────────────────────────────────────────────────────────┘
```

Each agent uses:
- **LLM** (Ollama / OpenAI / Anthropic) for reasoning
- **Dev Agent :8001** for high-quality code generation and reviews
- **DevOps MCP :8000** for git operations and deployments

---

## Quick Start

### 1. Install

```bash
cd ~/dev-team-mcp
make install
```

### 2. Configure

```bash
cp .env.example .env
# Edit .env — choose LLM_PROVIDER (default: ollama)
```

### 3. Run

```bash
# Start this server
make dev        # Dev server on :8002 with auto-reload

# Or start all three MCP servers at once
make start-all
```

### 4. Verify

```bash
curl http://localhost:8002/health | jq
```

---

## How to Use

### Submit a ticket (async)

```bash
curl -X POST http://localhost:8002/ticket \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add JWT authentication to FastAPI app",
    "description": "Add JWT-based auth with login endpoint, token refresh, and protected routes. Use python-jose.",
    "language": "python",
    "framework": "fastapi",
    "priority": "high",
    "labels": ["feature", "security"]
  }'
```

Response:
```json
{
  "ticket_id": "a1b2c3d4e5f6",
  "status": "pending",
  "message": "Ticket accepted. Pipeline started: Planner -> Coder -> Tester -> Reviewer. Poll GET /ticket/a1b2c3d4e5f6 for status."
}
```

### Poll for status

```bash
curl http://localhost:8002/ticket/a1b2c3d4e5f6 | jq
```

```json
{
  "ticket_id": "a1b2c3d4e5f6",
  "status": "done",
  "output_path": "/home/user/dev-team-mcp/workspace/add-jwt-auth-a1b2c3d4e5f6",
  "review_score": 88,
  "plan_summary": "Implement JWT authentication..."
}
```

### Get all generated files

```bash
curl http://localhost:8002/ticket/a1b2c3d4e5f6/artifacts | jq
```

### Get a specific file

```bash
curl http://localhost:8002/ticket/a1b2c3d4e5f6/artifacts/auth/jwt.py | jq .content
```

### Blocking / sync mode (for small tasks)

```bash
curl -X POST http://localhost:8002/ticket/sync \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello world script", "description": "Python script that prints hello world and current time"}'
```

---

## MCP Tools (for Claude Code)

Once registered in `~/.claude/settings.json`, you can use these tools directly in Claude:

| Tool | Description |
|------|-------------|
| `devteam_submit_ticket` | Submit a ticket for autonomous development |
| `devteam_submit_sync` | Submit and wait (blocking) |
| `devteam_ticket_status` | Check pipeline progress |
| `devteam_ticket_logs` | Stream agent log entries |
| `devteam_list_tickets` | List all tickets |
| `devteam_list_artifacts` | List generated files |
| `devteam_get_artifact` | Get a specific file content |
| `devteam_review_report` | Get code review score + checklist |
| `devteam_cancel_ticket` | Cancel a ticket |
| `devteam_health` | Health check |

---

## Pipeline Stages

### 1. Planner Agent
- Reads the ticket and produces a structured JSON plan
- Chooses the minimal viable tech stack
- Breaks work into numbered steps with file targets
- Flags security concerns (OWASP Top-10)
- Defines test strategy and CI/CD approach

### 2. Coder Agent
- Generates production-ready code for every file in the plan
- Uses Dev Agent :8001 when available (falls back to direct LLM)
- Applies OWASP mitigations (input validation, parameterised queries, no hardcoded secrets)
- Auto-retries with alternative approach on failure

### 3. Tester Agent
- Generates unit + integration tests for every source file
- Runs tests via the language's native test runner
- On failure: asks LLM to fix the implementation and re-runs (loop)
- Tracks coverage percentage

### 4. Reviewer Agent
- Full security audit (uses Dev Agent :8001 + LLM bundle review)
- Performance analysis
- Documentation completeness check
- Production readiness checklist (12 criteria)
- Auto-fixes medium/low issues
- Approves (score ≥ 75) or rejects with detailed feedback

### Delivery
- All files written to `workspace/<slug>-<ticket_id>/`
- Git repository initialised with commit history
- `DELIVERY.md` — full handover document
- `production-ready-<id>` git tag applied when approved

---

## Output Structure

```
workspace/add-jwt-auth-a1b2c3d4e5f6/
├── DELIVERY.md          ← Human-readable handover
├── auth/
│   ├── jwt.py           ← JWT implementation
│   ├── routes.py        ← Protected routes
│   └── test_jwt.py      ← Unit tests
├── main.py              ← FastAPI app
├── requirements.txt
└── .github/
    └── workflows/
        └── ci.yml       ← GitHub Actions CI
```

---

## Configuration

| Env var | Default | Description |
|---------|---------|-------------|
| `LLM_PROVIDER` | `ollama` | `ollama` / `openai` / `anthropic` |
| `OLLAMA_MODEL` | `mistral` | Any Ollama model (codestral, llama3.1, etc.) |
| `OPENAI_API_KEY` | — | Required when `LLM_PROVIDER=openai` |
| `ANTHROPIC_API_KEY` | — | Required when `LLM_PROVIDER=anthropic` |
| `DEVOPS_MCP_URL` | `http://localhost:8000` | DevOps MCP server URL |
| `DEV_AGENT_URL` | `http://localhost:8001` | Dev Agent MCP server URL |
| `DEV_TEAM_PORT` | `8002` | This server's port |
| `MAX_RETRIES` | `3` | Max LLM retries per step |
| `MAX_TEST_FAILURES` | `5` | Max test fix iterations |
| `WORKSPACE_DIR` | `./workspace` | Where generated repos land |

---

## Running Tests

```bash
make test
```

---

## Full 3-Server Stack

```bash
# Terminal 1: DevOps MCP (infrastructure)
cd ~/mcp && make dev

# Terminal 2: Dev Agent MCP (code gen)
cd ~/mcp-dev-agent && make dev

# Terminal 3: Dev Team MCP (autonomous pipeline)
cd ~/dev-team-mcp && make dev
```

Or use the convenience target:
```bash
cd ~/dev-team-mcp && make start-all
```

---

*Generated by Dev Team MCP — autonomous AI software development pipeline*