Architecture

System Overview

Here's how your AI development team works under the hood:

┌─────────────────┐         ┌────────────────────────────────┐
│   Your Client   │         │    Agile Project MCP Server    │
│                 │         │                                │
│  - Chat UI      │──API──▶│  ┌─────────────────────────┐   │
│  - CLI Tool     │         │  │   FastAPI Endpoints     │   │
│  - Custom App   │◀───────│  │  • /v1/chat/completions │   │
└─────────────────┘         │  │  • /tools/*             │   │
                            │  └────────────┬────────────┘   │
                            │               │                │
                            │  ┌────────────▼────────────┐   │
                            │  │   Request Router &      │   │
                            │  │   Agent Orchestrator    │   │
                            │  └────────────┬────────────┘   │
                            │               │                │
                            │  ┌────────────▼────────────┐   │
                            │  │     AI Agent Roles      │   │
                            │  │ 👔 Product Owner        │   │
                            │  │ 💻 Developers           │   │
                            │  │ 🧪 QA Engineer          │   │
                            │  │ 📋 Project Manager      │   │
                            │  │ 🏃 Scrum Master         │   │
                            │  └────────────┬────────────┘   │
                            │               │                │
                            │  ┌────────────▼────────────┐   │
                            │  │    State Management     │   │
                            │  │  • Stories (YAML/JSON)  │   │
                            │  │  • Kanban Board         │   │
                            │  │  • Project Artifacts    │   │
                            │  └─────────────────────────┘   │
                            └────────────────────────────────┘
                                           │
                                           ▼
                            ┌─────────────────────────────────┐
                            │    External Services (via MCP)  │
                            │  • Code Repositories            │
                            │  • Web Search                   │
                            │  • Code Execution Environments  │
                            └─────────────────────────────────┘

Core Components

🚀 FastAPI Server

The brain of the operation - handles all incoming requests and routes them to the right place.

Key features:

Async request handling for speedy responses
OpenAPI documentation auto-generated at /docs
Two main interfaces: chat completions and direct tools

🎭 Agent Orchestrator

This is where the magic happens! When you send a request:

Natural language? → Routes to the right agent based on context
Direct tool call? → Executes immediately and returns results
Complex task? → Breaks it down and coordinates multiple agents

🤖 AI Agent Roles

Each agent is a specialized LLM instance with:

Custom system prompt - Defines their personality and expertise
Role-specific tools - Only gets access to what they need
Focused context - Sees only relevant project information

💾 State Management

Everything is stored in simple, human-readable files:

store/
├── project-123/
│   ├── project.yaml      # Project metadata
│   ├── stories/          # User stories as YAML files
│   │   ├── STORY-001.yaml
│   │   └── STORY-002.yaml
│   ├── board.json        # Current Kanban board state
│   └── artifacts/        # Generated code, test results, etc.
│       ├── STORY-001/
│       └── STORY-002/

How Requests Flow

Chat Request Example

When you say "Build me a todo app":

1. Client sends: POST /v1/chat/completions
   {"messages": [{"role": "user", "content": "Build me a todo app"}]}

2. Server identifies: This is a new feature request
   → Routes to Product Owner agent

3. Product Owner agent:
   → Creates user stories
   → Prioritizes them
   → Updates backlog

4. Server responds with Product Owner's message:
   "I've created 5 user stories for your todo app..."

Tool Call Flow

When an agent needs to use a tool:

1. Agent requests tool use (e.g., "create_story")
2. Server intercepts the tool call
3. Executes tool internally:
   - Validates parameters
   - Updates state files
   - Returns results
4. Agent continues with tool results

External Tool Access

Some agents need to work with external resources:

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Developer  │────▶│  MCP Client  │────▶│ Git Repository  │
│    Agent    │     │              │     │ Web APIs        │
│             │◀────│  (Built-in)  │◀────│ Code Runners    │
└─────────────┘     └──────────────┘     └─────────────────┘

The server includes an OpenAPI MCP client that lets certain roles:

Developers: Access code repositories, run tests
Researchers: Search the web, read documentation
QA Engineers: Execute test suites, validate deployments

Configuration

All customisable via simple config files:

pyproject.toml - Server settings, dependencies .env - API keys, endpoints agents.yaml - Agent personalities, tool access

Example agent config:

developer:
  model: "gpt-4"
  system_prompt: "You are a senior developer..."
  tools:
    - read_story
    - update_story_status
    - create_artifact
    - mcp_repository_access

Why This Architecture?

✅ Modular - Easy to add new agent roles or tools ✅ Auditable - All decisions and changes tracked in files ✅ Scalable - Async design handles multiple projects smoothly ✅ Flexible - Swap AI providers, customise agents, extend tools ✅ Simple - No complex databases, just files you can inspect

7.2 KiB Raw Permalink Blame History