# FastAPI Scaffolder

**FastAPI Scaffolder** is a developer tool and AI system agent that transforms human- and machine-readable YAML architecture specifications into production-ready FastAPI applications.

It provides both a **CLI interface for humans** and a **Model Context Protocol (MCP) server for AI agents** (Gemini, Claude Desktop, Cursor, Windsurf, LangChain) to generate modular APIs instantly.

---

## Capabilities

* **Dual Interface:** Native CLI for developers and a zero-dependency JSON-RPC 2.0 MCP server for AI models.
* **Declarative Schemas:** Define microservices, endpoints, HTTP methods, Pydantic request/response payloads, and service dependencies in single or split YAML files.
* **Modular Generation:** Renders complete project structures complete with typed Pydantic models, FastAPI routers, configuration, dependency wiring, and test suites.
* **Python 3.14 Ready:** Built natively without third-party wrapper bottlenecks or SDK version locks.

---

## Installation

### Prerequisites

* Python `>= 3.10` (Tested up to `3.14`)
* `uv` or `pip`

### Install Locally (Editable Mode)

```bash
# Clone and enter directory
cd fastapi-scaffolder

# Install with CLI and MCP entry points
pip install -e .

```

This registers two global commands in your active virtual environment:

* `scaffold` — Human-facing CLI tool
* `scaffold-mcp` — Executable stdio MCP server for AI clients

---

## Schema Specification (`architecture.yaml`)

Define your API architecture using standard YAML:

```yaml
system_name: PaymentInvoicingPlatform
version: 1.0.0

services:
  - name: AuthService
    description: Handles user authentication and tokens
    dependencies: []
    endpoints:
      - path: /auth/login
        method: POST
        summary: Authenticate user
        request_body:
          - name: email
            type: str
          - name: password
            type: str
        response_body:
          - name: access_token
            type: str

  - name: InvoiceService
    description: Manages client invoices
    dependencies:
      - AuthService
    endpoints:
      - path: /invoices
        method: POST
        summary: Create client invoice
        request_body:
          - name: client_email
            type: str
          - name: amount
            type: float
        response_body:
          - name: invoice_id
            type: str
          - name: status
            type: str

```

---

## Usage Guide

### 1. Human CLI Usage

Scaffold an app directly from the terminal using the `scaffold` command:

```bash
# Generate app from YAML spec
scaffold -i architecture.yaml -o ./my_fastapi_app

# Combine multiple service specs
scaffold -i auth_service.yaml billing_service.yaml -o ./monorepo_app

```

---

### 2. AI Setup with Model Context Protocol (MCP)

`scaffold-mcp` communicates over Standard Input/Output (stdio) via JSON-RPC 2.0.

#### Cursor / Claude Desktop / Windsurf Setup

Add `fastapi-scaffolder` to your MCP configuration file (`claude_desktop_config.json` or Cursor MCP settings):

```json
{
  "mcpServers": {
    "fastapi-scaffolder": {
      "command": "/path/to/your/venv/bin/scaffold-mcp",
      "args": []
    }
  }
}

```

*Replace `/path/to/your/venv/bin/scaffold-mcp` with the absolute path returned by `which scaffold-mcp`.*

#### System Prompt Directive for AI Agents

Add this instruction to your LLM system prompt so it outputs compliant YAML to invoke the tool:

> **FastAPI Scaffolder Schema Directive:**
> 
> When generating an API, output a YAML string structured as follows:
> 
> 
> ```yaml
> system_name: MySystem
> version: 1.0.0
> services:
>   - name: ServiceName
>     description: Summary of responsibility
>     dependencies: []
>     endpoints:
>       - path: /items/{id}
>         method: GET
>         summary: retrieve item
>         response_body:
>           - name: id
>             type: str
> 
> ```
> 
> 
> Pass this raw YAML string to the `build_fastapi_app` tool with `output_directory`.
> 
> 

---

### 3. Usage with Google Gemini SDK

To run `fastapi-scaffolder` inside Gemini agent workflows:

```python
from google import genai
from google.genai import types
from scaffolder.mcp_server import execute_scaffold

client = genai.Client()

# Pass the tool execution function to Gemini
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Design a user profile microservice in YAML and build the code in ./user_service",
    config=types.GenerateContentConfig(
        tools=[execute_scaffold]
    )
)

# Execute the returned function call
if response.function_calls:
    for call in response.function_calls:
        if call.name == "execute_scaffold":
            result = execute_scaffold(call.args)
            print(result)

```

---

## Testing the MCP Server Manually

Verify that the MCP server starts and receives messages via stdio:

```bash
# Run server executable
scaffold-mcp

```

Paste this test payload into stdout and press **Enter**:

```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

```

**Expected Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "build_fastapi_app",
        "description": "Scaffolds a complete FastAPI codebase from a YAML architecture definition.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "yaml_spec": {
              "type": "string",
              "description": "Raw YAML string matching the SystemArchitecture schema."
            },
            "output_directory": {
              "type": "string",
              "description": "Output directory path for generated files.",
              "default": "./generated_app"
            }
          },
          "required": ["yaml_spec"]
        }
      }
    ]
  }
}

```