Estándar de código de módulos MCP

Por qué importa un estándar de código

Cada conector que entregamos se ve igual. Eso no es un accidente — es una disciplina. Cuando llega una segunda integración, las capacidades del agente son más fáciles de probar, auditar e intercambiar porque cada módulo MCP sigue la misma estructura, nomenclatura y contrato de errores.

Este documento define el estándar para todos los módulos MCP en la columna vertebral de orquestación de IdeaBosque. Cubre el diseño de directorios, el registro de herramientas, los esquemas de entrada/salida, el manejo de errores, los límites de tasa, el registro de auditoría y el manejo de PII en la frontera.

Estructura de directorios

Cada módulo MCP vive en su propio directorio bajo app/mcp_modules/ con un diseño consistente:

app/mcp_modules/<slug>/
  __init__.py
  module.py          # Registro de herramientas + handlers
  schemas.py         # Modelos Pydantic de entrada/salida
  tests/
    test_module.py
  README.md

Registro de herramientas

Cada módulo registra sus herramientas a través de una interfaz estándar. La columna vertebral de orquestación descubre las herramientas escaneando el punto de entrada register_tools() — sin cableado manual.

def register_tools(registrar):
    """Registrar todas las herramientas proporcionadas por este módulo."""
    registrar.tool(
        name="search_catalog",
        description="Buscar catálogo de proveedores por SKU o nombre",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # llamadas por minuto
    )

Manejo de errores

Los módulos deben lanzar excepciones tipadas, no strings sueltos. La columna vertebral captura subclases de MCPToolError y las convierte en respuestas estructuradas que el agente puede razonar:

• MCPAuthError — credenciales faltantes o expiradas
• MCPRateLimitError — límite de tasa del upstream alcanzado
• MCPTimeoutError — la llamada al upstream excedió el timeout configurado
• MCPValidationError — la entrada no pasó la validación del esquema
• MCPUpstreamError — el upstream devolvió un estado de error

Límites de tasa

Cada herramienta declara su propio límite de tasa en la llamada de registro. La columna vertebral los aplica por agente, por herramienta y por ventana. Cuando se alcanza un límite, el agente recibe una respuesta 429 con un header Retry-After — no se cuelga ni reintenta a ciegas.

Registro de auditoría

Cada llamada a herramientas se registra con: timestamp, ID del agente, nombre de la herramienta, hash de entrada (no entrada raw — frontera de PII), estado de salida, duración y sistema upstream. Los logs se escriben en JSON estructurado y se envían al pipeline de observabilidad.

"Cada llamada a herramientas se registra y es auditable" no es una característica que agregamos después. Es lo primero que el estándar exige.

Manejo de PII en la frontera

Los módulos deben declarar qué campos de entrada contienen PII. La columna vertebral hashea estos campos antes de registrarlos y nunca envía PII raw al pipeline de auditoría. Los campos PII se marcan en el esquema:

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

Cuando pii=True está activo, el logger de auditoría reemplaza el valor con un hash SHA-256. El handler de la herramienta sigue recibiendo el valor raw — el manejo de PII se aplica en la frontera de logging, no dentro de la lógica de negocio.