Skip to main content
Glama
mcp-forge

mcp-forge

by benni-os
README.md
<div align="center">

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:0D0D0D,50:0066FF,100:00C853&height=200&section=header&text=mcp-forge&fontSize=72&fontColor=ffffff&fontAlignY=38&desc=The%20FastAPI-Style%20Framework%20for%20Building%20MCP%20Servers%20in%20Python&descAlignY=58&descSize=16&animation=fadeIn" width="100%"/>

<br/>

<img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=700&size=20&duration=3000&pause=800&color=0066FF&center=true&vCenter=true&multiline=true&repeat=true&width=800&height=80&lines=Declarative+Tools.+Auto-Schema.+Type-Safe.+Production-Ready.;%40app.tool()+%E2%80%94+Zero+Boilerplate%2C+Three+Transports;The+FastAPI+Moment+for+MCP+Servers+%F0%9F%90%8D" alt="Typing SVG" />

<br/><br/>

[![PyPI](https://img.shields.io/pypi/v/mcp-forge?style=for-the-badge&logo=pypi&logoColor=white&color=0066FF)](https://pypi.org/project/mcp-forge/)
[![Tests](https://img.shields.io/badge/Tests-29%20Passed-00C853?style=for-the-badge&logo=pytest&logoColor=white)](#-architecture)
[![Python](https://img.shields.io/badge/python-3.11_%7C_3.12_%7C_3.13-00C853?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org)
[![CI](https://img.shields.io/github/actions/workflow/status/benni-os/mcp-forge/ci.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&label=CI)](https://github.com/benni-os/mcp-forge/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-FF007A?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](LICENSE)
[![mypy strict](https://img.shields.io/badge/mypy-strict-7000FF?style=for-the-badge&logo=python&logoColor=white)](https://mypy.readthedocs.io)
[![Benni OS](https://img.shields.io/badge/Benni%20OS-benni--os.net-0D0D0D?style=for-the-badge)](https://benni-os.net)
[![Smithery](https://img.shields.io/badge/Smithery-Indexed-00F0FF?style=for-the-badge&logo=target&logoColor=black)](https://smithery.ai)
[![Author](https://img.shields.io/badge/Author-Benni%20Alencar-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/benni-alencar/)

<br/>

> **"The FastAPI moment for MCP servers."**

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" width="100%"/>

<br/>

<img src="assets/demo.gif" alt="mcp-forge Declarative Python Framework Demo" width="100%"/>

<br/>

</div>

<br/>

## ⭐ What Is mcp-forge?

**mcp-forge** eliminates MCP server boilerplate entirely. You write a typed Python function. The framework derives the JSON Schema from your type hints, validates inputs at runtime, and exposes the tool over STDIO, HTTP, or SSE — without changing a single line of your logic.

Every MCP server starts the same way: hand-craft JSON Schema, wire a transport loop, handle `notifications/initialized`, redirect stderr, copy-paste validation logic. **mcp-forge does all of that for you.**

```python
from mcp_forge import Forge

app = Forge(name="my-server", version="1.0.0")


@app.tool(description="Search the knowledge base")
async def search(query: str, limit: int = 10) -> list[dict]:
    """Returns ranked results for the given query."""
    ...  # your logic here


if __name__ == "__main__":
    app.run()  # STDIO — Claude Desktop / Cursor / VS Code ready
```

No JSON Schema by hand. No transport boilerplate. No config files.

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## ⚡ Core Doctrine

> These are not features. These are design laws.

| ☔ Principle | 🔧 Implementation |
|---|---|
| **Schema is Derived, Never Written** | Pydantic v2 generates full draft-07 JSON Schema from type hints — automatically |
| **Transport is a Runtime Concern** | STDIO · HTTP · SSE — switch with one flag, tool code never changes |
| **Contrib is Opt-In** | `app.include(memory)` adds tools; you stay in control, zero forced dependencies |
| **Strict by Default** | mypy strict + ruff + 100% typed public API — no surprises in production |
| **Testing Without a Server** | `ForgeTestClient` calls tools directly — no sockets, no mocking, no overhead |
| **Zero Boilerplate** | `@app.tool()` is the entire registration API — one decorator, full MCP compliance |

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## 🚀 Quick Start

```bash
# Install
pip install mcp-forge

# Scaffold + run
mcp-forge new my-server && cd my-server
mcp-forge run --reload
```

Connect to **Claude Desktop** in 30 seconds:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["-m", "my_server"]
    }
  }
}
```

Switch to **HTTP** transport with one flag:

```bash
mcp-forge run --transport http --port 8080
```

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## ✨ Features

| Feature | Description |
|---|---|
| 🏗️ **Declarative Tools** | `@app.tool()` — no schema files, no registration calls |
| 🧠 **Auto JSON Schema** | Pydantic v2 under the hood — full draft-07 generated from type hints |
| ✅ **Runtime Validation** | Inputs validated before execution — errors as proper MCP-spec responses |
| 🚀 **Multi-Transport** | STDIO · HTTP · SSE — switch at runtime, logic unchanged |
| ⏳ **Async-First** | `async def` and `def` tools work side by side — no event loop management |
| 🔌 **Contrib Routers** | `memory` · `filesystem` · `web` — one-line include |
| 🧪 **Testing Client** | `ForgeTestClient` — no server, no mocking, no sockets |
| 📦 **PEP 561 Typed** | Ships `py.typed` — full mypy strict + Pyright support |

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## 📚 Examples

### Minimal server

```python
from mcp_forge import Forge

app = Forge(name="calculator")


@app.tool()
def add(a: float, b: float) -> float:
    """Add two numbers."""
    return a + b


app.run()
```

### With contrib tools

```python
from mcp_forge import Forge
from mcp_forge.contrib import memory, filesystem, web

app = Forge(name="agent-tools")
app.include(memory)  # remember(), recall(), forget(), list_memory()
app.include(filesystem)  # read_file(), write_file(), list_dir(), delete_file()
app.include(web)  # fetch_url()

app.run()
```

### Unit testing — no server needed

```python
from mcp_forge.testing import ForgeTestClient

client = ForgeTestClient(app)


def test_add():
    result = client.call("add", {"a": 2, "b": 3})
    assert result == 5
```

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## 🏗️ Architecture

```text
  Claude Desktop / Cursor / VS Code / Custom LLM Agents
         │
         ├──► STDIO JSON-RPC 2.0 (mcp-forge run)
         └──► HTTP / SSE Transport (mcp-forge run --transport http|sse)
                       │
                       ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │                              mcp-forge                              │
  │                                                                     │
  │  ┌───────────────────┐  ┌───────────────────┐  ┌─────────────────┐  │
  │  │ Declarative @tool │  │  Pydantic v2      │  │ Runtime         │  │
  │  │ Registry          │─►│  Auto-Schema      │─►│ Validator       │  │
  │  │ • Sync & Async    │  │  • Draft-07 JSON  │  │ • Input Guard   │  │
  │  │ • Contrib Routers │  │  • Type Coercion  │  │ • Output Guard  │  │
  │  └───────────────────┘  └───────────────────┘  └─────────────────┘  │
  │                                                                     │
  │  ┌───────────────────┐  ┌───────────────────┐  ┌─────────────────┐  │
  │  │ Transport Layer   │  │  In-Process       │  │ Live Telemetry  │  │
  │  │ • STDIO / HTTP    │  │  ForgeTestClient  │  │ & Doctor /      │  │
  │  │ • SSE Streaming   │  │  • Zero-Socket    │  │ Bench Matrix    │  │
  │  └───────────────────┘  └───────────────────┘  └─────────────────┘  │
  └─────────────────────────────────────────────────────────────────────┘
         │                                         │
         ▼                                         ▼
   Typed Tool Execution                      MCP Spec 2024-11-05
   (memory / filesystem / web)               Structured Responses
```

---

## 📁 Project Structure

```text
mcp-forge/
├── mcp_forge/
│   ├── __init__.py                   # Public Forge, ForgeConfig & exception exports
│   ├── py.typed                      # PEP 561 strict typing marker
│   ├── core/
│   │   ├── config.py                 # ForgeConfig dataclass
│   │   ├── exceptions.py             # MCP-aligned exception hierarchy
│   │   ├── forge.py                  # Declarative Forge app & @app.tool() registry
│   │   ├── schema.py                 # Auto JSON Schema (draft-07) from Pydantic v2
│   │   └── validator.py              # Runtime input/output validation engine
│   ├── serve/
│   │   ├── __init__.py               # Serving & telemetry subpackage exports
│   │   └── telemetry.py              # P50/P90/P99 latency & tool call metrics
│   ├── tools/
│   │   ├── __init__.py               # Diagnostics & benchmark subpackage exports
│   │   ├── bench_matrix.py           # Multi-batch tool dispatch benchmark matrix
│   │   └── doctor.py                 # Runtime dependency & schema probe
│   ├── transports/
│   │   ├── __init__.py               # Transport exports
│   │   ├── http.py                   # FastAPI-based HTTP REST transport
│   │   ├── sse.py                    # Server-Sent Events streaming transport
│   │   └── stdio.py                  # STDIO JSON-RPC 2.0 transport
│   ├── cli/
│   │   ├── main.py                   # Typer CLI (new, run, validate, build)
│   │   └── validator.py              # CLI schema & manifest validator
│   ├── contrib/
│   │   ├── __init__.py               # Opt-in contrib router exports
│   │   ├── filesystem.py             # Sandboxed filesystem tools
│   │   ├── memory.py                 # Scoped in-process memory store
│   │   └── web.py                    # Resilient HTTP fetch tool
│   └── testing/
│       ├── __init__.py               # Testing client exports
│       └── client.py                 # Zero-socket in-process ForgeTestClient
├── docs/
│   └── ARCHITECTURE.md               # Framework & subpackage architecture spec
├── examples/
│   ├── contrib_router_demo.py        # Contrib memory router + TelemetryEngine demo
│   └── quickstart_server.py          # Minimal Forge app + ForgeTestClient example
├── scripts/
│   ├── benchmark_dispatch.py         # Tool dispatch throughput benchmark runner
│   └── gate_schema_validation.py     # Pydantic v2 strict validation gate script
└── tests/                            # Full pytest suite (29 tests)
```

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## 📦 Installation

```bash
# Core only (STDIO transport)
pip install mcp-forge

# With HTTP + SSE transports
pip install "mcp-forge[http]"

# Everything
pip install "mcp-forge[all]"
```

**Requires:** Python 3.11+ · pydantic>=2.0

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## 🌍 Ecosystem Compatibility

| Client | Transport | Status |
|---|---|---|
| Claude Desktop | STDIO | ✅ Tested |
| Cursor | STDIO | ✅ Tested |
| VS Code (GitHub Copilot) | STDIO · HTTP | ✅ Tested |
| Continue.dev | HTTP · SSE | ✅ Tested |
| Custom LLM agents | HTTP · SSE | ✅ Tested |

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## 🤝 Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.

```bash
git clone https://github.com/benni-os/mcp-forge
cd mcp-forge
pip install -e ".[dev]"
pytest
```

- 🐛 **Found a bug?** → [Open an issue](https://github.com/benni-os/mcp-forge/issues/new?template=bug_report.md)
- 💡 **Have an idea?** → [Start a discussion](https://github.com/benni-os/mcp-forge/discussions)
- 📜 **See what's planned** → [ROADMAP.md](ROADMAP.md)

<br/>

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/dark.png" width="100%"/>

## 🌐 The Benni OS Open-Source Ecosystem

`mcp-forge` is part of the coordinated **Benni Master OS v9.4** open-source infrastructure suite:

| Repository | Focus & Architecture | Stars |
| :--- | :--- | :---: |
| **[`conductor-sdd`](https://github.com/Benni-OS/conductor-sdd)** | Zero-Dependency Spec-Driven Development, Static AST Drift Detector & MCP Guardrail | [![GitHub Stars](https://img.shields.io/github/stars/Benni-OS/conductor-sdd?style=flat)](https://github.com/Benni-OS/conductor-sdd) |
| **[`benni-inference-engine`](https://github.com/Benni-OS/benni-inference-engine)** | High-Throughput Sovereign Local Inference for 8GB–16GB Consumer GPUs | [![GitHub Stars](https://img.shields.io/github/stars/Benni-OS/benni-inference-engine?style=flat)](https://github.com/Benni-OS/benni-inference-engine) |
| **[`agent-eval-harness`](https://github.com/BenniAlencar/agent-eval-harness)** | Deterministic Zero-Cloud Agent Evaluation, Red-Teaming & Benchmark Harness | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-eval-harness?style=flat)](https://github.com/BenniAlencar/agent-eval-harness) |
| **[`agent-code-sandbox`](https://github.com/BenniAlencar/agent-code-sandbox)** | Micro-Second Zero-Dependency Code Sandbox & Execution Shield for AI Agents | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-code-sandbox?style=flat)](https://github.com/BenniAlencar/agent-code-sandbox) |
| **[`agent-deep-research`](https://github.com/BenniAlencar/agent-deep-research)** | Autonomous Multi-Source Deep Research & Evidence Synthesis Engine | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-deep-research?style=flat)](https://github.com/BenniAlencar/agent-deep-research) |
| **[`agent-browser-mesh`](https://github.com/BenniAlencar/agent-browser-mesh)** | Token-Saving Resilient Headless Browser Automation & A11y DOM Compiler | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-browser-mesh?style=flat)](https://github.com/BenniAlencar/agent-browser-mesh) |
| **[`agent-intent-compiler`](https://github.com/BenniAlencar/agent-intent-compiler)** | Deterministic Intent Compiler & Typed DAG Execution Planner for AI Agents | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-intent-compiler?style=flat)](https://github.com/BenniAlencar/agent-intent-compiler) |
| **[`agent-token-optimizer`](https://github.com/BenniAlencar/agent-token-optimizer)** | Sub-Millisecond Context Compression & Semantic Deduplication Engine | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-token-optimizer?style=flat)](https://github.com/BenniAlencar/agent-token-optimizer) |
| **[`bio-sync-operator-os`](https://github.com/BenniAlencar/bio-sync-operator-os)** | Real-Time Biometric Swarm Governance & 120 FPS Resonant Kinetic Interface | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/bio-sync-operator-os?style=flat)](https://github.com/BenniAlencar/bio-sync-operator-os) |
| **[`agent-cyber-sentinel`](https://github.com/BenniAlencar/agent-cyber-sentinel)** | Zero-Trust Runtime Security, Prompt Injection Firewall & Secrets Redaction | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-cyber-sentinel?style=flat)](https://github.com/BenniAlencar/agent-cyber-sentinel) |
| **[`agent-run-ledger`](https://github.com/BenniAlencar/agent-run-ledger)** | Deterministic Multi-Step Task Execution Ledger & Anti-Looping Engine | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-run-ledger?style=flat)](https://github.com/BenniAlencar/agent-run-ledger) |
| **[`reality-lock`](https://github.com/BenniAlencar/reality-lock)** | Cryptographic State Verification & Invariant Proof Engine for Agents | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/reality-lock?style=flat)](https://github.com/BenniAlencar/reality-lock) |
| **[`agent-memory-mesh`](https://github.com/BenniAlencar/agent-memory-mesh)** | Hybrid Vector + BM25 Hierarchical Session Memory & Continuity Engine | [![GitHub Stars](https://img.shields.io/github/stars/BenniAlencar/agent-memory-mesh?style=flat)](https://github.com/BenniAlencar/agent-memory-mesh) |
| **[`benni-operator-gateway`](https://github.com/Benni-OS/benni-operator-gateway)** | Human-in-the-Loop Approval & Policy Enforcement Gateway | [![GitHub Stars](https://img.shields.io/github/stars/Benni-OS/benni-operator-gateway?style=flat)](https://github.com/Benni-OS/benni-operator-gateway) |
| **[`mcp-forge`](https://github.com/Benni-OS/mcp-forge)** | Rapid Model Context Protocol (MCP) Server Scaffolding & Dynamic Tooling | [![GitHub Stars](https://img.shields.io/github/stars/Benni-OS/mcp-forge?style=flat)](https://github.com/Benni-OS/mcp-forge) |
| **[`benni-nexus`](https://github.com/Benni-OS/benni-nexus)** | Autonomous Multi-Agent Intent Routing & Swarm Coordination Hub | [![GitHub Stars](https://img.shields.io/github/stars/Benni-OS/benni-nexus?style=flat)](https://github.com/Benni-OS/benni-nexus) |
| **[`community-autopilot`](https://github.com/Benni-OS/community-autopilot)** | Autonomous GitHub Community Triaging & PR Feedback Agent | [![GitHub Stars](https://img.shields.io/github/stars/Benni-OS/community-autopilot?style=flat)](https://github.com/Benni-OS/community-autopilot) |

---

## 🏛️ Commercial & Sovereign Architecture

Need autonomous multi-agent swarm orchestration, private datacenter infrastructure, or enterprise governance?

- **Official Website:** [https://benni-os.net](https://benni-os.net)
- **Operator Mode Playbook:** [https://benni-os.net/blog/academy.html](https://benni-os.net/blog/academy.html)
- **GitHub Organization:** [https://github.com/Benni-OS](https://github.com/Benni-OS)
- **Maintainer:** [Benni Alencar](https://github.com/BenniAlencar)

---

## 📄 License & Provenance

- **License:** [MIT License](LICENSE)
- **Author:** Benni Alencar (`bennialencar@benni-os.net`)
- **Architecture:** Benni Master OS v9.4 Tier-0 Governance Standard

<div align="center">

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:00C853,50:0066FF,100:0D0D0D&height=120&section=footer" width="100%"/>

**mcp-forge** — *Open-Source Python MCP Framework by [Benni OS](https://github.com/Benni-OS)* • [benni-os.net](https://benni-os.net) • `MIT License`

`ZERO_BOILERPLATE` • `AUTO_SCHEMA` • `MULTI_TRANSPORT` • `STRICT_TYPING` • `MIT_LICENSE`

Engineered by **Benni Alencar** and the Benni OS Core Engineering Group · *If mcp-forge saves you time, give it a ⭐*

</div>