# Backend Architect MCP Server

An expert MCP toolchain designed to act as a **Backend Architect** for AI agents. This server enforces a strict "Atomic Development" workflow for building Python FastAPI + Supabase backends.

## 🚀 Overview

The Backend Architect server guides an agent through a **Plan -> Prompt -> Write** loop, ensuring that database models, API routes, and tests are built in the correct dependency order.

### Key Features
- **Atomic Development**: Focuses on one component at a time.
- **Workflow Enforcement**: Models → Routes → Tests (respects model dependencies).
- **Auto-Imports**: Automatically updates `__init__.py` files for models and routes.
- **State Persistence**: Maintains `.mcp_state.json` to track building progress.
- **Contextual Prompts**: Generates specialized system prompts for each component.

## 🛠️ Tech Stack
- **Python 3.12**
- **MCP SDK** (FastMCP)
- **UV** (Dependency Manager)
- **Pydantic** (State Validation)

## 📦 Installation

Ensure you have `uv` installed. Then, clone the repository and install dependencies:

```powershell
# Clone the repository
cd mcp_fastapi

# Install dependencies and run the server
uv run server.py
```

## 🛠️ Tools Reference

### 1. Initialization
- `initialize_project(root_path: str = ".")`: Scaffolds the FastAPI project structure and `pyproject.toml`. Defaults to the current working directory.

### 2. Planning
- `save_roles_plan(roles: list)`: Define user roles and permissions.
- `save_database_plan(models: list)`: Define SQLModel schemas and relationships.
- `save_route_plan(routes: list)`: Define API endpoints and methods.
- `save_test_plan(tests: list)`: Define simulation scenarios.

### 3. Execution
- `get_next_pending_task()`: The "Traffic Cop" that tells you exactly what to build next.
- `get_file_instruction(task_type: str, task_name: str)`: Returns a strict system prompt for the AI to follow.
- `write_component_file(type: str, name: str, content: str)`: Writes the code and marks the task as "done".

## 🔄 The Loop

1. **Initialize**: Set up your project root.
2. **Plan**: Feed the architect your schemas and endpoints.
3. **Draft**: Ask `get_next_pending_task()` for the current objective.
4. **Learn**: Get instructions via `get_file_instruction()`.
5. **Write**: Submit code via `write_component_file()`.
6. **Repeat**: Until the entire backend is architected.

## ⚙️ MCP Configuration

Add this to your MCP settings file (e.g., `mcp_config.json` or your IDE's MCP settings):

```json
{
  "mcpServers": {
    "backend-architect": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/server/directory",
        "python",
        "server.py"
      ]
    }
  }
}
```

> [!TIP]
> Use the absolute path to the directory where you cloned this repository for the `--project` argument. This ensures the server can find its dependencies regardless of where your AI agent is currently working.

---
*Built with ❤️ for the AI-First Developer.*