mcpforge

Erstelle einen MCP-Server in 5 Zeilen Python.

Before                              After
──────                              ─────
~200 lines of                       @serve
JSON-RPC stdio                      class MarketTools:
boilerplate, schema                     @tool
generation, error                       def latest_price(self, symbol: str) -> float: ...
handling, lifecycle                     @tool
management.                             def search(self, query: str) -> list[dict]: ...

                                    $ python -m mcpforge run market:MarketTools
                                    ✓ MCP server running on stdio

Warum mcpforge

Das Model Context Protocol (MCP) ist der offene Standard, den Claude, Cursor und ein explodierendes Ökosystem von KI-Tools verwenden, um externe Funktionen aufzurufen. Es ist mächtig — und das Schreiben eines Servers ist derzeit mühsam.

Du schreibst bei jedem Projekt dasselbe JSON-RPC-Framing, die Schema-Generierung, die Dispatch-Schleife und die Fehlerbehandlung. mcpforge löscht das alles. Annotiere deine Klasse. Gib deinen Methoden Typ-Hinweise. Fertig.

from mcpforge import serve, tool

@serve(name="market_tools", version="0.1.0")
class MarketTools:
    """Market data tools for AI agents."""

    @tool(description="Get the latest price for a symbol")
    def latest_price(self, symbol: str) -> float:
        return fetch_price(symbol)

    @tool
    def search(self, query: str, limit: int = 10) -> list[dict]:
        """Search ticker symbols matching `query`."""
        return run_search(query, limit)

Das ist ein vollständiger, spezifikationskonformer MCP-Server. Typ-Hinweise werden zu JSON-Schemas. Docstrings werden zu Tool-Beschreibungen. Rückgabewerte werden automatisch serialisiert.

60-Sekunden-Schnellstart

pip install mcpforge

# hello.py
from mcpforge import serve, tool

@serve(name="hello", version="0.1.0")
class HelloTools:
    @tool
    def greet(self, name: str = "world") -> str:
        """Say hello to someone."""
        return f"Hello, {name}!"

python -m mcpforge run hello:HelloTools

Du hast jetzt einen funktionierenden MCP-Server, der JSON-RPC 2.0 über stdio spricht.

Wie es funktioniert

1. @serve markiert eine Klasse als MCP-Server (Name, Version, Fähigkeiten).

2. @tool registriert Methoden als MCP-Tools.

3. @resource(uri=...) registriert Methoden als MCP-Ressourcen.

4. mcpforge untersucht die Signatur jeder Methode und erstellt ein JSON-Schema — Primitive, list[T], dict[str, T], Literal[...], Optional[T], Dataclasses und Pydantic-Modelle funktionieren einfach.

5. python -m mcpforge run mod:Class startet die stdio-Schleife, verarbeitet initialize / tools/list / tools/call / resources/list / resources/read, und meldet JSON-RPC-Fehler mit den korrekten Codes.

Kein externes MCP-SDK. Nur Standardbibliothek json + pydantic für Schema-Annehmlichkeiten.

Integrierte Server

Zwei "Batteries-included"-Server, die du heute sofort einsetzen kannst:

# Filesystem tools (sandboxed to a root directory)
python -m mcpforge run mcpforge.builtin.filesystem:FilesystemTools

# HTTP fetch tools
python -m mcpforge run mcpforge.builtin.http:HttpTools

FilesystemTools stellt list_dir, read_file, search bereit — in einer Sandbox mit Pfad-Traversal-Prüfungen. HttpTools stellt fetch_url mit Größenbeschränkungen bereit.

Einbindung in Claude Desktop

Füge dies zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"],
      "cwd": "/path/to/your/project"
    }
  }
}

Starte Claude Desktop neu. Deine Tools erscheinen im Chat.

Einbindung in Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "market": {
      "command": "python",
      "args": ["-m", "mcpforge", "run", "market:MarketTools"]
    }
  }
}

Vergleich

Überprüfung des Wire-Formats

python -m mcpforge inspect market:MarketTools

Gibt die exakte tools/list-Payload aus, die deine Clients sehen werden.

Roadmap

• [x] Tools (call, list)

• [x] Ressourcen (read, list)

• [x] Typ-Hinweis -> JSON Schema (Pydantic v2, dataclasses, Literal, Optional)

• [x] Integrierte Dateisystem- und HTTP-Server

• [ ] Ressourcen-Abonnements

• [ ] Prompts-Fähigkeit

• [ ] Sampling-Fähigkeit

• [ ] WebSocket / HTTP-SSE Transport (optional [http] extra)

• [ ] Asynchrone Tools (async def)

• [ ] OTel Tracing-Hooks

Lizenz

MIT — siehe LICENSE.

Autor: thechifura. Geschwisterprojekt von quantflow und strategos.