Universal MCP Tool Framework

Eine wiederverwendbare Python-Grundlage für Model Context Protocol Tools. Das Framework bündelt Registrierung, Auffindbarkeit, Berechtigungen, die Trennung der Betriebsmodi, strukturiierte Fehler, Protokollierung, Konfuguration, Health-/Status-Ausgabe und Erweiterungskonventionen.

Design-Abgrenzung

Das Framework ist eine MCP-Server-Grundlage, keine allgeimeine Shell, keine Dateisy -Steuerung und keine Richtlien-Engine. Tools werden esplizit registriert and daufen über genau eine Berechtigungsgrenze.

Ein Tool muss beide Prüfungen bestehen: sein Betriebsmodus ist aktiviert und seine erforderlichen Scopes sind im Ausführungskontext vorhanden.

Related MCP server: achmadya-dev/mcp-core

Abgedeckter Funktionsumfang

Voraussetzungen

• Python 3.10+

• Das offizielle MCP-Python-SDK, gepine auf mcp==2.0.0

Schnellstart

python -m venv .venv
. .venv/bin/activate
pip install -e .
python -m unittest discover -s tests -p "test_*.py"

Starten Sie den Server über das MCP SDK:

mcp run server.py

Für die interaktive Entwicklung mit MCP Inspector:

mcp dev server.py

Konfiguration

Kopieren Sie, ändern Sie das Beispiel nur, nicht-leesende Operationen:

{
  "server_name": "Universal MCP Tool Framework",
  "enabled_modes": ["read"],
  "log_level": "INFO"
}

read ist der einzige Standardmodus. Um einem registrierten Schreib-Tool zu erlaubt, fügen Sie write hinzu; um einem registrierten Ausfühungstool zu erlauben, fügen Sie execute hinzu. Die Aktivierung eines Modus umgeht die erforderlichen Pro-Tool-Scopes nicht.

Starten Sie den Server mit einer ausgewählten Konfigurationsdatei:

UNIVERSAL_MCP_CONFIG=config.json mcp run server.py

Ein Tool hinzufügen

1. Wählen Sie einen Betriebsmodus.

2. Deklarieren Sie jeden erforderlichen Scope.

3. Registrieren Sie den Handler über ToolRegistry.

4. Fügen Sie einen Test für Discovery, erlaubte Ausführung und Ablehnungspfade hinzu.

5. Stellen Sie einen dünnen MCP-Handler nur dann bereit, wenn das Tool zur öffentlichen Server-Oberfläche gehört.

from universal_mcp.models import OperationMode
from universal_mcp.registry import ToolRegistry

registry = ToolRegistry()

@registry.register(
    name="inventory_get_item",
    description="Return one inventory item by stable identifier.",
    mode=OperationMode.READ,
    required_scopes={"inventory:read"},
)
def inventory_get_item(item_id: str) -> dict[str, str]:
    return {"item_id": item_id}

Rufen Sie es über ToolRuntime.execute() auf, damit der gemeinsame Berechtigungs-, Protokollierungs- und Fehlervertrag immer angewendet wird.

Ergebnisvertrag

Alle Laufzeit-Ausführungen erzeugen diese stabile Ergebnishülle:

{
  "ok": true,
  "data": {},
  "error": null
}

Abgelehne und fehlgeschlagene Anfragen verwenden ok: false und einen maschinenlesbaren Fehlercode wie tool_not_found, permission_denied oder tool_execution_failed.

Repository-Struktur

.
├── config.example.json
├── pyproject.toml
├── server.py
├── src/universal_mcp/
│   ├── config.py
│   ├── examples.py
│   ├── models.py
│   ├── registry.py
│   ├── runtime.py
│   └── server.py
└── tests/test_framework.py

Validierung

python -m unittest discover -s tests -p "test_*.py"

Die Test-Suite verifiziert Discovery, Standard-Lesezugriff, Ablehnung von Schreib-/Ausführzugriff standardgemäß, Scope-Durchsetzung, strukturierte Fehler, Status-Ausgabe und JSON-Konfiguration.

Universelles Projektgerüst-Werkzeug

Das Repository stellt außerdem umcp-scaffold bereit, einen kontrollierten Generator für wiederholbare Python-Projektanfänge.

Erstellen Sie ein vollständig initialisiertes Projekt. Standardmäßig erstellt der Generator ein lokales Git-Repository, eine isolierte .venv, installiert lokale Abhängigkeiten und validiert das generierte Projekt.

umcp-scaffold create "My Project" ./my-project --type mcp-tool

Mit einem späteren Zeitpunkt ein generiertes Projekt validier en:

umcp-scaffold validate ./my-project

Jedes generierte Projekt erhält eine .project-state.json mit Schema-Version, Namen, Paketnamen, Vorlagenart, Lebenszyklusstatus, Git-/Abhängigkeiten-Flags, Erstellungszeitpunkt und letztem Validierungsstatus. Der Generator lehnt nicht-leere Zielverzeichnisse ab, anstatt ein Projekt zu überschreiben.

Lokale Code-Analyse- und Test-Werkzeugsammlung

umcp-quality inspiziert ein lokales Python-Projekt und gibt einen maschinenlesbaren Qualitätsbericht mit PASS, FAIL und WARNING zurück.

umcp-quality ./my-project
umcp-quality ./my-project --format markdown

FAIL erzeugt einen Status ≠ null für den Befehl. Meanings WARNING zeigt einen unvollständigen, aber nicht fehlgeschlagenen Zustand – zumBeaßel fehlende virtuelle Umgebung, keine Tests, kein Konfigurations-verzeichnis oder nicht verfügare Git-Historie.