Math Lab: MCP + OpenAI Agents SDK

Dieses Projekt verwendet dieselbe mathematische Logik über zwei Adapter:

• Einen MCP-Server für Codex, den MCP Inspector oder jeden kompatiblen Client.

• Einen Agenten, der mit dem OpenAI Agents SDK erstellt wurde, um in natürlicher Sprache zu kommunizieren.

Verpackt als installierbares Python-Paket (pip install -e .), mit src/-Layout und sauberer Schichtenarchitektur.

Struktur

pyproject.toml       # Metadata, dependencias y entry points del paquete
src/
└── math_assistant/
    ├── domain/          # Reglas matemáticas puras (sin dependencias externas)
    ├── application/     # Catálogo de capacidades públicas
    ├── infrastructure/  # Adaptadores para MCP (FastMCP) y OpenAI Agents SDK
    └── presentation/    # Interfaz de terminal
tests/
├── unit/            # Prueban dominio y catálogo
└── integration/     # Comprueban que los adaptadores se construyen
run_cli.py           # Entry point: interfaz amigable para aprender y probar
run_mcp.py           # Entry point: STDIO exclusivo para el cliente MCP

Die Abhängigkeit zeigt immer nach innen:

CLI / MCP / OpenAI SDK  →  application  →  domain

Die Domäne kennt weder FastMCP, OpenAI, einen API-Key noch print. Deshalb lässt sie sich schnell und ohne Netzwerk testen.

Related MCP server: Explore MCP

Installation

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Kopiere deinen OPENAI_API_KEY in eine .env-Datei im Stammverzeichnis (sie wird nie in git hochgeladen).

Die benutzerfreundliche Oberfläche ausführen

.\.venv\Scripts\python.exe .\run_cli.py

Das Menü ermöglicht:

1. Mit dem OpenAI-Agenten sprechen (verwendet OPENAI_API_KEY aus .env).

2. Addition, Subtraktion, Multiplikation und Division lokal testen, ohne API-Kosten.

3. Die Tools anzeigen, die der MCP-Server veröffentlicht.

Den MCP-Server ausführen

.\.venv\Scripts\python.exe .\run_mcp.py

Um ihn mit MCP Inspector zu inspizieren:

npx @modelcontextprotocol/inspector "C:\ruta\completa\a\math-mcp-lab\.venv\Scripts\python.exe" "C:\ruta\completa\a\math-mcp-lab\run_mcp.py"

Verwende absolute Pfade: Der Inspector respektiert nicht immer das aktuelle Arbeitsverzeichnis.

Füge kein print() in run_mcp.py oder im MCP-Adapter hinzu: Der Standardausgabekanal (stdout) ist für die JSON-RPC-Nachrichten des Protokolls reserviert. Aus diesem Grund befindet sich die benutzerfreundliche Oberfläche in run_cli.py.

Integration mit Codex

.codex/config.toml (nicht versioniert, es ist eine lokale Maschinenkonfiguration) verweist Codex auf den MCP-Server. Wenn du Codex CLI verwendest, erstelle deine eigene:

[mcp_servers.math]
command = "C:\\ruta\\completa\\a\\math-mcp-lab\\.venv\\Scripts\\python.exe"
args = ["C:\\ruta\\completa\\a\\math-mcp-lab\\run_mcp.py"]
cwd = "C:\\ruta\\completa\\a\\math-mcp-lab"

Tests

.\.venv\Scripts\python.exe -m unittest discover -s tests -v

So fügst du ein mathematisches Tool hinzu

1. Erstelle die reine Funktion und ihren Docstring in src/math_assistant/domain/operations.py.

2. Füge sie zu MATH_OPERATIONS in src/math_assistant/application/tool_catalog.py hinzu.

3. Führe die Tests aus.

Beide Adapter stellen sie automatisch bereit: FastMCP wandelt sie in ein MCP-Tool um und das Agents SDK in eine Function Tool.