Math Lab: MCP + OpenAI Agents SDK

Этот проект использует одну и ту же математическую логику через два адаптера:

• Сервер MCP для Codex, MCP Inspector или любого совместимого клиента.

• Агент, построенный на OpenAI Agents SDK, для общения на естественном языке.

Упакован как устанавливаемый Python-пакет (pip install -e .), с layout src/ и чистой многослойной архитектурой.

Структура

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

Зависимость всегда направлена внутрь:

CLI / MCP / OpenAI SDK  →  application  →  domain

Домен не знает о FastMCP, OpenAI, API-ключе или print. Поэтому его можно быстро тестировать без сети.

Related MCP server: Explore MCP

Установка

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

Скопируй свой OPENAI_API_KEY в файл .env в корне (он никогда не попадает в git).

Запуск дружелюбного интерфейса

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

Меню позволяет:

1. Общаться с агентом OpenAI (использует OPENAI_API_KEY из .env).

2. Проверять сложение, вычитание, умножение и деление локально, без затрат на API.

3. Просматривать инструменты, которые публикует сервер MCP.

Запуск сервера MCP

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

Для проверки с помощью 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"

Используй абсолютные пути: Inspector не всегда уважает текущую рабочую директорию.

Не добавляй print() внутри run_mcp.py или в адаптере MCP: стандартный канал вывода (stdout) зарезервирован для JSON-RPC сообщений протокола. Дружелюбный интерфейс живёт в run_cli.py по этой причине.

Интеграция с Codex

.codex/config.toml (не версионируется, это локальная конфигурация машины) указывает Codex на сервер MCP. Если ты используешь Codex CLI, создай свой:

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

Тесты

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

Как добавить математический инструмент

1. Создай чистую функцию и её docstring в src/math_assistant/domain/operations.py.

2. Добавь её в MATH_OPERATIONS в src/math_assistant/application/tool_catalog.py.

3. Запусти тесты.

Оба адаптера автоматически её подхватят: FastMCP превратит её в инструмент MCP, а Agents SDK — в function tool.