Engenharia MCP Zero-Boilerplate: Compilando Funções Python Tipadas em Servidores JSON-RPC 2.0 Blindados com mcp-forge

Por que JSON Schemas escritos à mão, loops STDIO frágeis e ferramentas Python sem proteção quebram em produção—e como o Benni-OS/mcp-forge, o Benni-OS/benni-operator-gateway e o BenniAlencar/agent-code-sandbox compilam funções tipadas em servidores JSON-RPC 2.0 blindados com circuit breaker e política Default-Deny.

Engenharia MCP Zero-Boilerplate: Compilando Funções Python Tipadas em Servidores JSON-RPC 2.0 Blindados com mcp-forge

1. A Armadilha do Boilerplate MCP e a Fragilidade no Fio

Todo time que coloca integrações do Model Context Protocol (MCP) em produção esbarra no mesmo muro em menos de quarenta e oito horas. Escrever uma função de domínio de duas linhas leva trinta segundos; empacotá-la em um servidor MCP compatível exige trezentas linhas de encanamento frágil. Engenheiros copiam dicionários JSON Schema manualmente, escrevem loops asyncio em stdin/stdout para enquadramento JSON-RPC 2.0, implementam handshakes initialize e notifications/initialized e convertem exceções manualmente em payloads de erro.

Pior do que o imposto de boilerplate é o que falha silenciosamente quando servidores artesanais enfrentam tráfego real de agentes:

Doutrina Central: O schema é derivado, nunca escrito à mão; o transporte é uma decisão de runtime, nunca regra de negócio; e nenhuma ferramenta entra em produção sem circuit breakers orientados a orçamento de latência, gates Default-Deny e isolamento por inspeção estática AST.

2. Arquitetura de Síntese Determinística: Dos Type Hints ao Default-Deny

A infraestrutura de ferramentas do Benni OS resolve ergonomia e blindagem em três camadas open-source componíveis. O Benni-OS/mcp-forge atua como o compilador estilo FastAPI e runtime multi-transporte; o Benni-OS/benni-operator-gateway impõe roteamento de capacidades Default-Deny e aprovação humana; e o BenniAlencar/agent-code-sandbox isola avaliação dinâmica de código atrás de um scanner AST sub-milissegundo.

flowchart LR A["Função Python Tipada\n(@app.tool + Type Hints + BaseModel)"] -->|"Inspeção de Assinatura e AST"| B["Compilador mcp-forge\n(build_schema -> Schema Draft-07)"] B -->|"validate_input / validate_output"| C["Camada de Resiliência e Telemetria\n(Circuit Breaker + P50/P90/P99)"] C -->|"STDIO stderr-safe / HTTP / SSE"| D["Canal JSON-RPC 2.0\n(MCP 2024-11-05)"] D -->|"Perfil de Risco e Gate de Política"| E["benni-operator-gateway\n(Default-Deny + Webhook de Aprovação)"] E -->|"Caminho de Execução Dinâmica"| F["agent-code-sandbox\n(< 0.2ms AST Guard + VFS Efêmero)"]

Repare na separação nítida de responsabilidades: engenheiros escrevem funções Python puras e tipadas, o mcp-forge garante fidelidade de protocolo e schema nos três transportes, a malha de circuit breaker evita timeouts em cascata e o perímetro gateway/sandbox impõe autorização e segurança de host antes de qualquer efeito colateral.


3. Por Dentro do Compilador Tipo-para-Schema e da Inspeção AST Pré-Execução

No momento do registro, o decorator @app.tool() em mcp_forge/core/forge.py invoca build_schema(fn) de mcp_forge/core/schema.py e devolve a função original intacta. Em vez de exigir manifestos JSON ou YAML paralelos, build_schema() combina typing.get_type_hints(fn) com inspect.signature(fn):

Combinando Síntese de Assinatura com Inspeção AST Pré-Execução

Quando uma ferramenta MCP recebe código Python ou expressões geradas pelo LLM, validar apenas o tipo str no JSON Schema não basta—um argumento perfeitamente válido para o schema ainda pode conter import os; os.system(...) ou escapes reflexivos como ().__class__.__base__.__subclasses__(). É exatamente aqui que entra o ASTSecurityScanner do BenniAlencar/agent-code-sandbox.

Usando ast.parse() e um ast.NodeVisitor nativo, o método ASTSecurityScanner.scan() percorre a árvore sintática em < 0,2 ms (média observada de 0,18 ms em 1.000 ciclos de benchmark) e bloqueia imports proibidos (os, sys, subprocess, ctypes, importlib, socket), chamadas perigosas (eval, exec, compile, open, __import__) e travessias reflexivas (__subclasses__, __mro__, __globals__, __closure__) antes que qualquer subprocesso seja criado.


4. Wire Protocol JSON-RPC 2.0 Blindado, Multi-Transporte e Testes Sem Sockets

Com os schemas compilados, a classe Forge expõe os mesmos contratos por três transportes desacoplados, alternáveis via app.run(transport=...) ou pela flag mcp-forge run --transport:

Na chamada, Forge.call_tool() executa validate_input() para verificar campos obrigatórios e realizar coerção determinística, resolve transparentemente handlers síncronos (def) e assíncronos (async def) e submete o retorno a validate_output()—disparando ValidationError se uma função não-nulável retornar None silenciosamente.

Para evitar estado mutável compartilhado entre serviços, app.include(router) realiza cópia rasa dos metadados de routers contrib opt-in (memory, filesystem, web), enquanto o ForgeTestClient executa chamadas diretamente em memória (client.call() ou await client.acall()) sem abrir sockets, portas ou mocks pesados no pytest.


5. Circuit Breakers, Orçamentos de Latência e Telemetria P50/P90/P99

Sintetizar endpoints JSON-RPC válidos elimina a deriva de schema, mas enxames em produção enfrentam outra classe de falha: latência de cauda em cascata e tempestades de retry. Quando uma API externa degrada ou um scraper trava, um loop de agente sem limite de tempo queima tokens e bloqueia workers paralelos.

No runtime do Benni OS, mcp_forge.serve.telemetry.TelemetryEngine registra janelas móveis de execução (max_history=500), calculando contagem por ferramenta (tool_distribution), taxa de erro e percentis latency_p50_ms, latency_p90_ms e latency_p99_ms em conjunto com o BenchMatrixRunner. Acoplar essa telemetria à máquina de estados do MCPMeshSynthesizer e do MCPToolContract traz isolamento determinístico de falhas:


6. Implementação de Referência: Servidor MCP Blindado com Circuit Breaker e Sandbox AST

O módulo Python abaixo demonstra como o decorator declarativo @app.tool() do mcp-forge, a derivação de schema Pydantic v2, a telemetria de percentis do TelemetryEngine, o orçamento de latência com circuit breaker e a execução verificada por AST do agent-code-sandbox se integram sem boilerplate:

import asyncio
import time
from dataclasses import dataclass
from typing import Any
from pydantic import BaseModel, Field

from mcp_forge import Forge, ForgeConfig
from mcp_forge.serve import TelemetryEngine
from mcp_forge.testing import ForgeTestClient
from agent_code_sandbox import SandboxEngine

app = Forge(
    name="hardened-operator-tools",
    version="1.0.0",
    config=ForgeConfig(transport="stdio", max_tool_timeout=15),
)
telemetry = TelemetryEngine(max_history=500)
sandbox = SandboxEngine()


@dataclass
class CircuitBreaker:
    failure_threshold: int = 3
    cooldown_seconds: float = 15.0
    consecutive_failures: int = 0
    state: str = "closed"  # closed | open | half_open
    opened_at: float = 0.0

    def allow_request(self) -> bool:
        if self.state == "closed":
            return True
        if self.state == "open" and (time.monotonic() - self.opened_at) >= self.cooldown_seconds:
            self.state = "half_open"
            return True
        return self.state == "half_open"

    def record_success(self) -> None:
        self.consecutive_failures = 0
        self.state = "closed"

    def record_failure(self) -> None:
        self.consecutive_failures += 1
        if self.consecutive_failures >= self.failure_threshold:
            self.state = "open"
            self.opened_at = time.monotonic()


_breakers: dict[str, CircuitBreaker] = {}


class SandboxAuditInput(BaseModel):
    code: str = Field(..., min_length=1, description="Snippet Python para verificar e executar")
    timeout_s: float = Field(default=3.0, ge=0.2, le=10.0)


@app.tool(description="Executa Python não confiável em sandbox efêmero protegido por AST")
def run_sandboxed_python(payload: SandboxAuditInput) -> dict[str, Any]:
    t0 = time.perf_counter()
    res = sandbox.execute_python(code=payload.code, timeout=payload.timeout_s)
    elapsed_ms = (time.perf_counter() - t0) * 1000.0
    telemetry.record_call("run_sandboxed_python", elapsed_ms, success=res.is_safe and res.exit_code == 0)
    return res.to_dict()


@app.tool(description="Consulta telemetria externa com circuit breaker e orçamento de latência")
async def query_upstream_signal(endpoint: str, budget_ms: int = 1500) -> dict[str, Any]:
    breaker = _breakers.setdefault("query_upstream_signal", CircuitBreaker(failure_threshold=3))
    if not breaker.allow_request():
        telemetry.record_call("query_upstream_signal", 0.1, success=False)
        return {"status": "circuit_open", "endpoint": endpoint, "error": "Falha rápida pelo circuit breaker"}

    t0 = time.perf_counter()
    try:
        # Impõe orçamento determinístico de latência por ferramenta
        async with asyncio.timeout(budget_ms / 1000.0):
            await asyncio.sleep(0.01)  # Substitua por chamada httpx/DB assíncrona
            data = {"endpoint": endpoint, "signal": "nominal"}
        breaker.record_success()
        telemetry.record_call("query_upstream_signal", (time.perf_counter() - t0) * 1000.0, success=True)
        return {"status": "ok", "data": data}
    except Exception as exc:
        breaker.record_failure()
        telemetry.record_call("query_upstream_signal", (time.perf_counter() - t0) * 1000.0, success=False)
        return {"status": "error", "circuit_state": breaker.state, "error": str(exc)}


if __name__ == "__main__":
    # Verificação sem sockets antes de acoplar em STDIO / HTTP / SSE
    client = ForgeTestClient(app)
    safe_out = client.call("run_sandboxed_python", {"payload": {"code": "print(6 * 7)"}})
    assert safe_out["is_safe"] is True and "42" in safe_out["stdout"]

    blocked = client.call("run_sandboxed_python", {"payload": {"code": "import os; os.system('id')"}})
    assert blocked["is_safe"] is False

    app.run()  # Emite JSON-RPC 2.0 no stdout; logs fixados estritamente em stderr

7. Governança Default-Deny com benni-operator-gateway

Derivação automática de schema e coerção de entradas garantem que parâmetros respeitem seus tipos Python—mas validade de schema não é autorização. Um agente autônomo comprometido por prompt injection indireto ou deriva de raciocínio ainda pode enviar um JSON perfeitamente válido solicitando um force push, deploy em produção ou exfiltração de credenciais.

Por isso, o Benni OS posiciona o Benni-OS/benni-operator-gateway à frente das malhas MCP críticas como um Gateway MCP HTTP Default-Deny:

// Trecho da política de aprovação Default-Deny do benni-operator-gateway
export function requiresApproval(job: CreateJobInput): boolean {
  if (job.riskLevel === 'approval_required' || job.riskLevel === 'execute') return true;
  const typeLower = job.type.toLowerCase();
  if (!KNOWN_SAFE_TYPES.includes(typeLower)) return true;

  const inputJson = JSON.stringify(job.input || {}).toLowerCase();
  for (const keyword of HIGH_RISK_KEYWORDS) {
    if (inputJson.includes(keyword)) {
      if (job.type === 'repository_summary_preview' && job.riskLevel === 'read' && !inputJson.includes('merge pr')) {
        continue;
      }
      return true;
    }
  }
  return !(job.type === 'repository_summary_preview' && job.riskLevel === 'read');
}

8. Comparação Arquitetural: Scripts JSON-RPC Manuais vs. Wrappers Genéricos vs. Stack Benni OS

Dimensão de Engenharia Scripts JSON-RPC Manuais Wrappers de Decorator Genéricos mcp-forge + Gateway + Sandbox
Compilação de Schema Dicionários JSON manuais (alta deriva) Apenas anotações básicas Draft-07 Derivado + Pydantic v2 + Gate CLI
Integridade do Fio STDIO Vulnerável a print() em stdout Risco de logs misturados ao canal Logs Fixados em stderr + Pipe Binário
Portabilidade de Transporte Preso a um único loop de transporte Geralmente apenas STDIO STDIO, HTTP REST e SSE Sem Alterar Código
Controle de Falhas e Latência Travamentos sem limite em APIs lentas Timeouts ad-hoc por função Circuit Breakers + Orçamento + Telemetria P99
Governança de Efeitos Colaterais Execução implícita allow-all Sem checkpoint de aprovação humana Gateway Default-Deny + Webhook de Aprovação
Segurança de Código Dinâmico exec() cru ou containers de 3s+ Sem inspeção AST pré-execução AST Guard < 0,2 ms + VFS Efêmero + TokenShield

Implante Infraestrutura MCP Blindada e Zero-Boilerplate

Compile ferramentas Python tipadas com o Benni-OS/mcp-forge, imponha gates Default-Deny com aprovação humana via Benni-OS/benni-operator-gateway e isole execuções dinâmicas em sub-milissegundo com o BenniAlencar/agent-code-sandbox.

Benni-OS/mcp-forge → Benni-OS/benni-operator-gateway → BenniAlencar/agent-code-sandbox →

Perguntas Frequentes

Como o mcp-forge gera JSON Schema sem arquivos manuais de schema?
Ao decorar uma função com @app.tool(), o mcp-forge inspeciona o callable usando inspect.signature() e typing.get_type_hints(). Seu compilador build_schema() mapeia recursivamente tipos primitivos Python, list[T], dict[str, T], Optional[T] / Union e classes Pydantic v2 BaseModel para um JSON Schema Draft-07 validado, separando automaticamente parâmetros obrigatórios daqueles com valor padrão.
Por que o StdioTransport direciona todos os logs para stderr em vez de stdout?
No transporte MCP via STDIO, o stdout é o canal exclusivo do protocolo JSON-RPC 2.0 delimitado por quebra de linha entre o servidor e clientes como Claude Desktop ou Cursor. Qualquer texto fora do padrão JSON escrito em stdout corrompe o parser de frames. O mcp-forge fixa logging.basicConfig em sys.stderr e grava respostas JSON serializadas diretamente em sys.stdout.buffer.
Como circuit breakers e orçamentos de latência evitam falhas em cascata na malha MCP?
Cada contrato de ferramenta sintetizado acompanha um orçamento de latência (timeout_ms), telemetria contínua P50/P90/P99 via TelemetryEngine e contagem de falhas consecutivas. Quando as falhas atingem o limite configurado, o circuit breaker muda de closed para open, devolvendo imediatamente um erro estruturado circuit_open em vez de travar o loop do agente.
Como o benni-operator-gateway e o agent-code-sandbox blindam ferramentas criadas no mcp-forge?
O benni-operator-gateway atua como um broker MCP HTTP Default-Deny que bloqueia capacidades não registradas e ferramentas external_effect, inspeciona palavras-chave de risco no payload, pausa ações sensíveis em pending_approval aguardando webhooks de aprovação humana e grava trilhas de auditoria com redação de segredos. Para ferramentas que executam código dinâmico, o agent-code-sandbox adiciona um scanner AST em menos de 0,2ms, diff SHA-256 em workspace efêmero e TokenShield no stdout.