# 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

```text
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:

```text
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

```powershell
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

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

El menú permite:

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

## Ejecutar el servidor MCP

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

Para inspeccionarlo con [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```powershell
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:

```toml
[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

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

## Cómo añadir una herramienta matemática

1. Crea la función pura y su docstring en `src/math_assistant/domain/operations.py`.
2. Agrégala a `MATH_OPERATIONS` en `src/math_assistant/application/tool_catalog.py`.
3. 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.