Math Lab: MCP + OpenAI Agents SDK

Este proyecto usa una misma lógica matemática desde dos adaptadores:

Un servidor MCP para Codex, el MCP Inspector, o cualquier cliente compatible.
Un agente construido con el OpenAI Agents SDK para conversar en lenguaje natural.

Empaquetado como paquete Python instalable (pip install -e .), con layout src/ y arquitectura limpia por capas.

Estructura

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

La dependencia siempre apunta hacia adentro:

CLI / MCP / OpenAI SDK  →  application  →  domain

El dominio no conoce FastMCP, OpenAI, una API key, ni print. Por eso puede probarse rápido y sin red.

Instalación

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

Copia tu OPENAI_API_KEY en un archivo .env en la raíz (nunca se sube a git).

Ejecutar la interfaz amigable

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

El menú permite:

Hablar con el agente de OpenAI (usa OPENAI_API_KEY de .env).
Probar suma, resta, multiplicación y división localmente, sin costo de API.
Ver las herramientas que el servidor MCP publica.

Ejecutar el servidor MCP

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

Para inspeccionarlo con MCP Inspector:

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

Usa rutas absolutas: el Inspector no siempre respeta el directorio de trabajo actual.

No agregues print() dentro de run_mcp.py ni del adaptador MCP: el canal estándar de salida (stdout) se reserva para los mensajes JSON-RPC del protocolo. La interfaz amigable vive en run_cli.py por esa razón.

Integración con Codex

.codex/config.toml (no versionado, es config local de máquina) apunta Codex al servidor MCP. Si usas Codex CLI, crea el tuyo:

[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"

Pruebas

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

Cómo añadir una herramienta matemática

Crea la función pura y su docstring en src/math_assistant/domain/operations.py.
Agrégala a MATH_OPERATIONS en src/math_assistant/application/tool_catalog.py.
Ejecuta las pruebas.

Los dos adaptadores la expondrán automáticamente: FastMCP la convierte en una herramienta MCP y el Agents SDK en una function tool.