Idea To Prod

You give it an idea. It gives you back working, tested code.

Idea-To-Prod is a multi-agent AI platform. You describe an application idea in one sentence, and 6 AI agents work together — one after another — to design it, write the code, test it, and (optionally) deploy it.

It is built as an MCP server, so any MCP-compatible AI assistant (Claude Desktop, GitHub Copilot, etc.) can use it as a tool.

---

📋 Table of Contents

• How it works
• The 6 agents
• Which AI models are used
• Setup
• How to run it
• What you get back
• Project structure
• Notes on a few design decisions

---

🔄 How it works

flowchart LR
    Idea(["💡 Your idea"]) --> A1

    A1["Agent 1
    High-Level Design"] -->|saves doc| Drive1[("Google Drive")]
    A1 --> A2

    A2["Agent 2
    Detailed Design"] -->|saves doc| Drive2[("Google Drive")]
    A2 -->|creates tasks| Jira[("Jira")]
    A2 --> A3

    A3["Agent 3
    Write Code"] -->|pushes code| GH1[("GitHub")]
    A3 --> A4

    A4["Agent 4
    Write Tests"] -->|pushes tests| GH2[("GitHub")]
    A4 --> A5

    A5{"Agent 5
    Run Tests"}
    A5 -->|❌ failed, try again| A4
    A5 -->|✅ passed| A6

    A6["Agent 6
    Deploy (optional)"] --> Done(["🎉 Done - code ready"])

Each agent does one job and then hands off to the next one. If the tests fail (Agent 5), the flow goes back to Agent 4 to fix the tests — up to 3 times — before giving up and reporting what went wrong.

---

🤖 The 6 agents

#	Agent	What it does	Saves to
1	High-Level Design	Reads your idea and writes a short design document: what the app does, who it's for, what technologies to use.	Google Drive
2	Detailed Design	Takes the design and breaks it into concrete, buildable development tasks.	Google Drive + Jira
3	Code Generation	Reads the tasks and writes the actual application code.	GitHub (new repository)
4	Unit Test Generation	Reads the code and writes tests for it. Uses a different AI model than Agent 3, so it's a genuine second opinion, not the same model checking its own work.	GitHub (same repository)
5	Test Execution	Actually runs the tests. If they fail, sends the failure details back to Agent 4. If they pass, the pipeline is done.	—
6	Deploy (optional)	Publishes the finished, tested app online. Only runs if you ask for it.	Hosting provider

---

🧠 Which AI models are used

Every agent uses an AI model to do its job, but not the same one for everything — this project specifically requires Agent 3 (writing code) and Agent 4 (writing tests) to use two different models, so Agent 4 is a real second opinion, not an echo of Agent 3.

Right now every agent runs on OpenAI, with two different models (gpt-4o for the heavier design/coding work, gpt-4o-mini for the lighter tasks). Swapping any single agent to a different provider (Gemini, Claude, etc.) is a one-line change — see src/idea_to_prod/config/models.py.

---

🧩 How the pieces connect (MCP)

This project speaks MCP in two directions:

• As a server — it exposes exactly one tool, ideaToProd(idea). This is what an AI assistant like Claude Desktop calls.
• As a client — internally, each agent connects out to other MCP servers (Google Drive, Jira, GitHub, Playwright) to actually save documents, create tasks, push code, and run tests.

   You / Claude Desktop
          │
          │  calls  ideaToProd("build me a calculator app")
          ▼
  ┌───────────────────┐
  │  Idea-To-Prod      │   ← this project
  │  MCP Server        │
  └─────────┬──────────┘
            │  the 6 agents call out to:
            ▼
  Google Drive · Jira · GitHub · Playwright   ← real services (or local mocks)

For testing without any real accounts, every one of those four services has a local mock (tests/mocks/) that behaves like the real thing — the GitHub mock creates a real local git repository, and the Playwright mock actually runs the generated tests with pytest. Each service can be switched from mock to real independently, one at a time, using its own USE_MOCK_<SERVICE> flag in .env (all default to true, meaning mocked).

---

⚙️ Setup

You'll need:

• Python 3.11 or newer
• uv (Python package manager)
• git (the GitHub mock uses it directly)
• Node.js (only needed once you connect real, non-mock services — they run via npx)
• An OpenAI API key

Install:

uv sync
cp .env.example .env

Then open .env and set OPENAI_API_KEY to your real key. Everything else can stay as-is (mocked) for your first run.

---

▶️ How to run it

There are three ways to use it — pick whichever fits what you're doing.

1. Smoke test — fastest way to see it work

uv run pytest tests/test_smoke.py -s

Runs all 6 agents against the local mocks with one sample idea, and prints each agent's progress as it happens. This makes real OpenAI API calls (small cost).

2. Our own CLI client — the interactive way

uv run idea-to-prod-client

Asks you for an idea, then runs the whole pipeline and shows live progress in your terminal.

3. Claude Desktop — the "real" MCP way

1. Copy claude_desktop_config.example.json into Claude Desktop's MCP settings, filling in this project's folder path and your API key.
2. Restart Claude Desktop.
3. Ask it something like: "Use ideaToProd to build a CLI todo list app."

---

📦 What you get back

If the tests pass: the generated application files, the generated test files, how many retries it needed, and links to the design documents and Jira tasks created along the way.

If the tests keep failing (after 3 retries): the best attempt it made, plus a clear report explaining what's still broken — instead of hanging forever or silently returning broken code.

---

📁 Project structure

idea-to-prod/
├── pyproject.toml
├── .env.example
├── claude_desktop_config.example.json
├── src/idea_to_prod/
│   ├── config/          # settings + which AI model each agent uses
│   ├── tools/            # connects each agent to its MCP service
│   ├── agents/            # the 6 agents
│   ├── flow.py            # ties all 6 agents together, including the retry loop
│   ├── server.py          # the MCP server (exposes ideaToProd)
│   └── client.py          # a simple CLI client for trying it out
└── tests/
    ├── mocks/              # local stand-ins for Drive/Jira/GitHub/Playwright
    └── test_smoke.py       # end-to-end test

---

📝 Notes on a few design decisions

A few choices here aren't obvious, so they're written down:

• The retry loop (Agent 5 → Agent 4) is a plain Python loop, not a CrewAI "Flow" cycle. Two attempts at building it as a native Flow cycle didn't reliably repeat on a second try during testing, so it was rebuilt as a simple, predictable while loop instead. Details in flow.py.
• The GitHub repository name is decided by code, not by the AI. Early testing showed the AI could invent a repository name in its final summary that didn't match the one it actually used — a classic AI "hallucination" that broke every step after it. Now the name is computed once, in plain code, and passed to every agent that needs it.
• Real MCP servers don't all use the same tool names. The tool names this project calls (e.g. create_document) are its own internal agreement, matched exactly by the local mocks. Connecting a real service may need a one-line name adjustment — see the note at the top of tools/mcp_connection.py.

---

📄 License

MIT — see LICENSE.