mcp-forger

<p align="center"> <img src="https://raw.githubusercontent.com/coderXcode/mcp-forge/main/images/mcp_forge.jpg" alt="MCP Forger" width="200" /> </p> <h1 align="center">🔨 MCP Forger</h1> <p align="center"> ## Your software becomes an AI coworker. MCP Forger turns any app, API, repo, or codebase into an AI coworker that Claude, Codex, and other MCP clients can use directly. Give it your backend. It analyzes it, generates an MCP server, tests it, and lets Claude operate your software through natural language. Convert <strong>any application</strong> into an MCP (Model Context Protocol) server — with AI assistance. </p> <p align="center"> <img src="https://img.shields.io/badge/docker-ready-blue?logo=docker" /> <img src="https://img.shields.io/badge/claude-plugin-blueviolet?logo=anthropic" /> <img src="https://img.shields.io/badge/python-3.12+-green?logo=python" /> <img src="https://img.shields.io/badge/license-MIT-lightgrey" /> <img src="https://img.shields.io/pypi/v/mcp-forger?label=pypi" /> </p> ## ✨ Features | Category | Highlights | |---|---| | **Source ingestion** | Local folder (`mnt/`) · OpenAPI/Swagger URL *(under testing)* · GitHub repo *(under testing)* · Live URL probing *(under testing)* · File upload *(under testing)* · Manual description *(under testing)* | | **AI agent** | Multi-LLM (Gemini · Anthropic · OpenAI · local HuggingFace) · per-project chat · clarification Q&A loop | | **Code generation** | **Python FastMCP** (stable) · Node.js / Go / Generic *(under development & testing)* · LLM polish pass · security audit · auto-generated `.env`, `configure_claude.sh` & `configure_claude.ps1` | | **Versioning** | Snapshot on every generation · one-click rollback · optional git commits | | **Testing** | AI-generated pytest cases · in-container runner · full test history | | **Dashboard** | Real-time logs · 6-tab project view · editable `.env` config from the browser | | **Integrations** | Claude Desktop · Claude Code · Codex · `forge` CLI | --- ## 🗺️ Two Ways to Use MCP Forger | Method | Best for | |---|---| | **Web Dashboard** | Visual workflow — point & click, no code | | **`forge` CLI + Claude Desktop** | AI-driven workflow from your terminal or Claude chat | Both require MCP Forger running in Docker first — see [Step 1](#step-1--run-mcp-forge-docker) below. --- ## Step 1 — Run MCP Forger (Docker) > **Required for everything** — the dashboard, CLI, and Claude Desktop all connect to this Docker instance. ### Prerequisites - [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running - At least one LLM API key **or** an NVIDIA GPU for local mode ### 1.1 — Clone & configure ```bash git clone https://github.com/coderXcode/mcp-forge.git cd mcp-forge cp .env.example .env ``` Open `.env` and set at minimum: ```env LLM_PROVIDER=gemini # or: anthropic | openai | local GEMINI_API_KEY=your-key-here # This token authenticates the CLI and Claude Desktop — change it to something secret MCP_AUTH_TOKEN=change-me-to-something-secret ``` > **Free option:** Gemini has a free tier at [aistudio.google.com](https://aistudio.google.com) — no credit card needed. > **No API key? Run locally instead:** Set `LLM_PROVIDER=local` and leave the API key fields empty. On **macOS** run `bash scripts/start_model_server.sh` after Docker starts. On **Linux with NVIDIA GPU** the model loads inside Docker automatically. See [Local Model](#️-local-model-no-api-key) for details. ### 1.2 — macOS / Linux — disable the NVIDIA GPU block first > **Skip this if you are on Windows with an NVIDIA GPU.** The default `docker-compose.yml` includes an NVIDIA GPU reservation that causes Docker to fail on macOS (and any machine without an NVIDIA GPU). Open `docker-compose.yml` and comment out the `deploy:` block under the `app:` service: ```yaml # ── GPU (NVIDIA) — uncomment if on Linux with NVIDIA GPU ──────────────── # deploy: # resources: # reservations: # devices: # - driver: nvidia # count: all # capabilities: [gpu] ``` It should already be commented out if you cloned the latest version. If you see it **uncommented**, add `#` in front of each of those lines. > If you also want to change the MCP server port (e.g. port 8001 is already in use), edit `MCP_SERVER_PORT` in `.env` before starting: > ```env > MCP_SERVER_PORT=8002 # change to any free port > ``` ### 1.3 — Start ```bash docker compose up -d ``` | Service | URL | Purpose | |---|---|---| | 🌐 Dashboard | http://localhost:8000 | Web UI — full visual workflow | | 🔌 MCP endpoint | http://localhost:8002/sse | Used by Claude Desktop / Claude Code (default port) | ### 1.4 — Verify it's running ```bash # Should return [] (empty list — that's fine) curl http://localhost:8000/api/projects/ ``` ✅ MCP Forger is now online. Keep Docker running whenever you use the CLI or Claude Desktop. --- ## Step 2A — Use the Web Dashboard Visit **http://localhost:8000** → click **+ New Project** → follow the UI. No further setup needed. --- ## Step 2B — Use the `forge` CLI ### Install ```bash pip install mcp-forger # or: pipx install mcp-forger (isolated, recommended) ``` ### Connect the CLI to your running MCP Forger instance > Do this once — it saves your connection details locally. ```bash forge connect --url http://localhost:8000 --token YOUR_MCP_AUTH_TOKEN ``` Get your token with: ```bash # macOS / Linux grep -m1 '^MCP_AUTH_TOKEN=' .env | cut -d= -f2 # Windows (PowerShell) (Get-Content .env | Where-Object { $_ -match '^MCP_AUTH_TOKEN=' }) -replace '^MCP_AUTH_TOKEN=','' ``` ### Verify ```bash forge status # Should list your projects (empty at first — that's fine) ``` ### Create and convert your first project ```bash # Recommended: from a local folder # 1. Copy your project into mnt/ (e.g. mnt/my-api/) # 2. Create the project on the dashboard or via Claude Desktop # 3. Trigger analysis forge analyze 1 # Check what's happening forge logs 1 --tail 20 # Generate the MCP server (Python FastMCP is the stable option) forge generate 1 --lang python_fastmcp # Run AI-generated tests forge test 1 # Chat with the AI agent forge chat 1 "review all endpoints and ask me anything unclear" ``` ### Install the Claude Desktop plugin (one command) ```bash forge plugin install # Then fully quit + reopen Claude Desktop ``` This writes `claude_desktop_config.json` automatically — no manual editing. ### All CLI commands ```bash forge connect --url <url> --token <token> # save connection (run once) forge status # list all projects forge analyze <project_id> # trigger analysis forge generate <project_id> --lang <lang> # generate MCP server forge chat <project_id> "<message>" # chat with AI agent forge logs <project_id> --tail 50 # stream live logs forge test <project_id> # run AI-generated tests forge plugin install # write claude_desktop_config.json forge plugin status # verify Claude Desktop config ``` --- ## Step 2C — Use Claude Desktop Claude Desktop lets you control MCP Forger entirely through natural language. ### Install the plugin **Windows (PowerShell):** ```powershell .\scripts\install_claude_plugin.ps1 ``` **macOS / Linux:** ```bash bash scripts/install_claude_plugin.sh ``` Or if you have the CLI installed: ```bash forge plugin install ``` Then **fully quit and reopen Claude Desktop** (right-click system tray → Quit). Go to **Settings → Developer** — you should see **mcp-forge** with a 🟢 green dot. ### Example prompts **Recommended — local folder (most reliable):** ``` Create a new MCP Forge project called "my-api", source type local_folder, path /mnt/my-api ``` **OpenAPI/Swagger URL** *(under testing)*: ``` Create a new MCP Forge project called "petstore" from https://petstore3.swagger.io/api/v3/openapi.json ``` ``` Generate the MCP server for project 1 in Python FastMCP ``` ``` Run tests for project 1 and show me the results ``` ``` Chat with the forge agent for project 1: "Add rate limiting to all tools" ``` > **Language note:** Only **Python FastMCP** is stable. Node.js, Go, and other language targets are under development and testing. --- ## Step 2D — Use Claude Code ``` /plugin marketplace add coderXcode/mcp-forge /plugin install mcp-forge@coderXcode-mcp-forge ``` Skills available: ``` /forge:analyze <project_id> /forge:generate <project_id> /forge:chat <project_id> <message> /forge:status /forge:test <project_id> /forge:rollback <project_id> <version> ``` --- ## Step 3 — Connect Your Generated MCP Server to Claude Desktop ### Understanding the two plugins After this step you will have **two separate plugins** in Claude Desktop — they do different things: | Plugin | What it does | Installed by | |---|---|---| | `mcp-forge` | Lets Claude *operate MCP Forge itself* — create projects, generate code, run tests | `forge plugin install` (Step 2C) | | `your-project-name` | Lets Claude call *your actual app* directly — the converted product | `bash configure_claude.sh` (this step) | They are completely independent. You can use either or both. The generated plugin (`your-project-name`) is the end product — it talks directly to your running app, with no dependency on MCP Forge once it's set up. > **Important:** The generated plugin needs your original app to be running. It doesn't start your app for you — it just gives Claude a way to talk to it. Make sure your app is running at the `BASE_URL` set in `.env` before asking Claude to use it. ### Run the setup script Open a terminal in the **generated project folder** and run: **macOS / Linux** ```bash bash configure_claude.sh ``` **Windows (PowerShell)** ```powershell .\configure_claude.ps1 ``` The script does everything in one step: 1. Creates a Python virtual environment (`.venv/`) 2. Installs dependencies from `requirements.txt` 3. Finds the right `claude_desktop_config.json` for your OS 4. Safely merges a new `mcpServers` entry — existing entries are preserved 5. Prints restart instructions Then **fully quit and reopen Claude Desktop** (system tray → Quit, not just close window). Your converted API appears as a new tool with a 🟢 green dot. > **Non-standard port?** Pass `--base-url` to override the default: > ```bash > bash configure_claude.sh --base-url http://localhost:9000 > ``` > The generated `.env` file also lets you set `BASE_URL` and `API_TOKEN` before running the script. --- ## 🖥️ Local Model (No API Key) Run entirely offline with any HuggingFace model — no API key needed. ### Linux with NVIDIA GPU Set in `.env` (or via the dashboard **Config** page → select **Local**): ```env LLM_PROVIDER=local LOCAL_MODEL=Qwen/Qwen2.5-Coder-14B-Instruct LOCAL_MODEL_DEVICE=auto LOCAL_MODEL_LOAD_IN_4BIT=true ``` ```bash docker compose up -d ``` ### macOS (Apple Silicon or Intel) Docker cannot access the Mac GPU, so the model runs natively on the host instead. One command does everything (installs deps, creates a venv, starts the server): ```bash bash scripts/start_model_server.sh ``` Wait until the terminal shows `Listening on 0.0.0.0:8005`, then go to the dashboard **Config** page and select **Local** — the app will proxy inference requests to the native server automatically. Model weights download once to `./cache/huggingface/` and are reused on every subsequent start. > The script auto-selects the best model for your RAM (7B for 16–32 GB, 14B for 36 GB+). | Model | RAM (unified) | Notes | |---|---|---| | `Qwen/Qwen2.5-Coder-7B-Instruct` | ~16 GB | Recommended for most Macs | | `Qwen/Qwen2.5-Coder-14B-Instruct` | ~36 GB | Better quality, needs more RAM | | `Qwen/Qwen2.5-Coder-32B-Instruct` | ~64 GB | Best quality | > **Linux / NVIDIA — CPU-only fallback:** set `LOCAL_MODEL_LOAD_IN_4BIT=false` and `LOCAL_MODEL_DEVICE=cpu` — slower but works. --- ## ⚙️ Key Configuration All settings live in `.env` — also editable live from the dashboard **Config** page without restarting Docker. Switch LLM providers anytime: open **Config**, click **Gemini / Anthropic / OpenAI / Local**, enter your key, and click **Save Changes**. | Variable | Default | Description | |---|---|---| | `LLM_PROVIDER` | `gemini` | `gemini` \| `anthropic` \| `openai` \| `local` | | `GEMINI_API_KEY` | — | Google Gemini API key | | `ANTHROPIC_API_KEY` | — | Anthropic Claude API key | | `OPENAI_API_KEY` | — | OpenAI API key | | `MCP_AUTH_TOKEN` | `change-me` | Auth token for CLI / Claude — **change this** | | `GITHUB_TOKEN` | — | PAT for private GitHub repos | | `LOCAL_MODEL` | `Qwen/Qwen2.5-Coder-14B-Instruct` | Any HuggingFace model ID | | `ENABLE_GIT_SNAPSHOTS` | `false` | Auto-commit each snapshot to git | | `DEBUG` | `false` | Verbose logs + uvicorn reload | --- ## 🐳 Useful Docker Commands ```bash docker compose up -d # start docker compose up -d --build # rebuild after code changes docker compose restart # restart after .env changes docker compose down -v # stop + wipe database docker logs mcp_forge_app -f # app logs docker logs mcp_forge_mcp -f # MCP server logs ``` --- ## 🔧 Troubleshooting **mcp-forge not showing in Claude Desktop (red dot / missing)** - Fully quit Claude Desktop (system tray → Quit, not just close) - Re-run: `forge plugin install` or `.\scripts\install_claude_plugin.ps1` - Validate JSON at [jsonlint.com](https://jsonlint.com) **"Connection refused" on port 8000 or 8001** ```bash docker ps # check containers are running docker compose up -d # start if not running docker logs mcp_forge_app --tail 30 ``` **Wrong / expired auth token** ```bash # macOS / Linux grep -m1 '^MCP_AUTH_TOKEN=' .env | cut -d= -f2 # Windows (PowerShell) (Get-Content .env | Where-Object { $_ -match '^MCP_AUTH_TOKEN=' }) -replace '^MCP_AUTH_TOKEN=','' ``` ```bash forge connect --url http://localhost:8000 --token <new-token> forge plugin install # updates claude_desktop_config.json too ``` **Reset the database** ```bash echo y | docker exec -i mcp_forge_app python clear_db.py ``` --- ## 📖 Full Documentation See **[user_manual.md](https://github.com/coderXcode/mcp-forge/blob/main/user_manual.md)** for advanced configuration, Codex integration, local folder setup, architecture details, and more. --- ## 📝 License MIT