mcp-code-execution: Instructions file for Codex

AGENTS.md — MCE Development Guide for AI Agents

This file governs how AI agents develop, maintain, and extend the MCE (MCP Code Execution) codebase. Read it in full before making any change.

1. Project Overview

MCE is a production-grade MCP server built with Python 3.13 and FastMCP. It exposes 4 meta-tools + 1 prompt to LLMs instead of bloating the context with N per-endpoint tools:

Key invariant: credentials are never embedded in generated code or logs. They are injected exclusively as Docker environment variables at runtime.

2. Repository Layout

/home/ob1/aai/mcp-code-execution/      ← project root
├── pyproject.toml                      ← single source of truth for deps & tools
├── .env.example                        ← template; never commit .env
├── config/swaggers.yaml                ← swagger source definitions
├── sandbox/
│   ├── Dockerfile                      ← python:3.13-slim sandbox image
│   ├── entrypoint.py                   ← code receiver inside sandbox
│   └── requirements.txt                ← httpx, pydantic, orjson only
├── src/mce/
│   ├── __init__.py                     ← version only
│   ├── __main__.py                     ← CLI: clean | compile | serve | run
│   ├── server.py                       ← FastMCP tool registration (4 tools + 1 prompt)
│   ├── config.py                       ← MCEConfig (pydantic-settings)
│   ├── errors.py                       ← full exception hierarchy
│   ├── models/__init__.py              ← ALL pydantic models (single file)
│   ├── compiler/
│   │   ├── swagger_parser.py           ← OpenAPI 3.x / Swagger 2.0 parser
│   │   ├── codegen.py                  ← Jinja2 Python function generator
│   │   ├── orchestrator.py             ← compile pipeline coordinator
│   │   ├── llm_enhancer.py             ← optional Claude improvement pass
│   │   └── templates/function.py.j2   ← Jinja2 template for functions.py
│   ├── runtime/
│   │   ├── registry.py                 ← loads manifests, provides lookups
│   │   ├── executor.py                 ← Docker sandbox execution pipeline
│   │   └── cache.py                    ← async SQLite cache (aiosqlite)
│   ├── security/
│   │   ├── ast_guard.py                ← AST static analysis (runs before exec)
│   │   ├── policies.py                 ← read-only + domain allowlist enforcement
│   │   └── vault.py                    ← credential → Docker env var injection
│   └── utils/
│       ├── logging.py                  ← structlog setup
│       └── hashing.py                  ← SHA256 helpers for cache keys
├── tests/
│   ├── conftest.py                     ← shared fixtures (mce_config, specs, sources)
│   ├── fixtures/                       ← YAML swagger test fixtures
│   │   ├── weather_api.yaml            ← read-only, simple GET endpoints
│   │   ├── hotel_api.yaml              ← read-write, path + body params
│   │   └── petstore.yaml               ← standard petstore with $ref schemas
│   ├── unit/                           ← isolated, no Docker, no network
│   │   ├── test_swagger_parser.py
│   │   ├── test_codegen.py
│   │   ├── test_ast_guard.py
│   │   └── test_cache.py
│   └── integration/                    ← requires compiled output on disk
│       └── test_compiler.py