# ai2dev-mcp

An [MCP](https://modelcontextprotocol.io) server that a frontend can talk to in
order to design software projects the same way AI2DEV does: draft a design
document with an LLM, refine it based on feedback, answer follow-up questions,
and finally hand the finished document to the AI2DEV API to create the
project.

## Tools exposed

| Tool | What it does |
| --- | --- |
| `generate_design_document` | Calls the LLM to draft a structured markdown design document from a project name, requirements, and optional audience/constraints. |
| `refine_design_document` | Calls the LLM to revise an existing design document based on feedback, keeping its structure. |
| `ask_question` | Calls the LLM to answer any question, optionally grounded in supplied context (e.g. the current design document). |
| `create_ai2dev_project` | Calls the AI2DEV API to create a project from a finalized design document. |

## Setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env  # fill in ANTHROPIC_API_KEY and AI2DEV_API_KEY
```

Required environment variables:

- `ANTHROPIC_API_KEY` — used by the LLM tools (design doc generation/refinement, Q&A).
- `ANTHROPIC_MODEL` — defaults to `claude-opus-4-8`.
- `AI2DEV_API_BASE_URL` — base URL of the AI2DEV API (defaults to a placeholder; set to your real endpoint).
- `AI2DEV_API_KEY` — bearer token for the AI2DEV API.

## Running

As a stdio MCP server (what most MCP clients/frontends expect):

```bash
python -m ai2dev_mcp.server
# or, after `pip install -e .`
ai2dev-mcp-server
```

For local interactive testing with the MCP Inspector:

```bash
mcp dev src/ai2dev_mcp/server.py
```

### Connecting a frontend / MCP client

Point your MCP client at the command above and pass the environment variables
through its `env` config, e.g. for a JSON-based MCP client config:

```json
{
  "mcpServers": {
    "ai2dev-design": {
      "command": "ai2dev-mcp-server",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "AI2DEV_API_BASE_URL": "https://api.ai2dev.example.com",
        "AI2DEV_API_KEY": "..."
      }
    }
  }
}
```

## Tests

```bash
pytest
```

## Project layout

```
src/ai2dev_mcp/
  config.py        # env-driven settings
  llm.py            # Anthropic-backed design doc generation/refinement/Q&A
  ai2dev_client.py  # HTTP client for the AI2DEV project-creation API
  server.py         # FastMCP server wiring the tools together
tests/
  test_server.py
```