oas-execute-mcp

Un servidor MCP que coloca una capa de seguridad entre un modelo de lenguaje y una orden de bróker.

Un modelo llama a order_submit. Antes de que nada llegue al bróker, la solicitud pasa por seis comprobaciones independientes, cualquiera de las cuales puede rechazarla — siete en las rutas de escritura, ya que la regla de stop-loss rige las modificaciones, no las aperturas. Cada intento — permitido o rechazado — se añade a un registro de auditoría con el motivo. El bróker en sí se encuentra detrás de un backend intercambiable, de modo que la misma superficie de herramientas funciona contra un simulador en disco o un terminal MetaTrader 5 en vivo sin que el modelo sepa cuál es.

Construido para un agente que, en su propio canal, envió órdenes contra una cuenta de evaluación de firma propietaria de $100k sin aprobación humana por operación, donde una orden con tamaño incorrecto no era una prueba fallida.

Por qué existe

La parte interesante de darle a un agente una herramienta que gasta dinero no es el camino feliz. Es:

• lo que la herramienta devuelve cuando tiene éxito a medias — la orden se ejecutó pero el stop no se adjuntó;

• dónde aterriza un timeout — el bróker nunca respondió, y no sabes si se ejecutó;

• cómo se impide que un fallo se reporte como éxito por la capa superior.

Así que la regla de diseño aquí es que el propio relato del modelo sobre lo que sucedió nunca se confía. El estado de la posición se vuelve a leer del bróker en cada llamada. Los rechazos son explícitos, pocos, y se sitúan directamente en la ruta de ejecución en lugar de al margen en un prompt.

Related MCP server: mt5-mcp

La capa de seguridad

Siete comprobaciones, cada una capaz de rechazar de forma independiente, todas registradas con un motivo legible por máquina. Seis de ellas se interponen entre order_submit y el bróker; check_sl_widen_block rige las modificaciones, por lo que nunca ve una apertura:

La adición a la auditoría se ejecuta después de las compuertas en cada ruta, permitida o rechazada — es el registro, no una comprobación: un rechazo que no deja rastro se trata como un fallo del sistema.

safety.py agrupa estas en run_entry_safety_gates, run_modify_safety_gates y run_close_safety_gates, de modo que un cierre nunca se bloquea por una regla que solo debería regir una apertura — el modo de fallo donde un sistema de seguridad te atrapa en una posición que se suponía que debía proteger.

Superficie de herramientas

Siete herramientas: order_submit · order_modify · order_close · close_all · position_list · account_info · health_check.

Arquitectura

    model tool call
          │
          ▼
   server.py  ── MCP stdio server, tool schemas + dispatch
          │
          ▼
   safety.py  ── 7 gates, audit log, kill switch     ◄── refuses here, before the broker
          │
          ▼
   backends/  ── swappable
      ├── stub.py      on-disk simulation, no broker, deterministic
      └── mt5_demo.py  file bridge → MetaTrader 5 (Wine/macOS) via an MQL5 EA
                       localhost HTTP listener, shared-secret token on the firing route

El asesor experto MQL5 (oas_execute_mcp/mql5/OAS_Bridge.mq5) consulta un endpoint de localhost y ejecuta en el lado del terminal. backends/base.py es la interfaz; añadir un bróker significa implementarla, y nada por encima del backend cambia.

Instalación

pip install -e ".[dev]"

Apunta tu cliente MCP a él:

{
  "mcpServers": {
    "oas-execute": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "oas_execute_mcp.server"],
      "cwd": "/path/to/parent-of-this-package"
    }
  }
}

La selección del backend y las rutas son variables de entorno:

Se distribuye con stub como predeterminado. Tienes que elegir apuntarlo a un bróker.

No hay credenciales en este repositorio, y no debería haberlas. El backend MT5 sigue al terminal que ya esté conectado; el registro de cuenta que lee es documental (login y nombre del servidor), no contiene contraseña y pertenece fuera del control de versiones.

Pruebas

PYTHONPATH=. python3 tests/test_smoke.py     # full submit → modify → close cycle + failure modes
for t in tests/test_*.py; do PYTHONPATH=. python3 "$t"; done   # the whole suite
python3 -m pytest tests/ -q                  # same suite, if you would rather type this

Nueve archivos de prueba, todos pasando en una copia limpia. Cada uno es un verificador autónomo: ejecuta sus aserciones en el ámbito del módulo y sale con código distinto de cero en caso de fallo, de modo que la suite solo necesita un intérprete. tests/suite_test.py ejecuta los mismos scripts como subprocesos, por lo que pytest también es un punto de entrada funcional — es un puente, no una segunda suite, y no hay versión de las pruebas que solo vea un ejecutor. Cubren el ciclo de enviar/modificar/cerrar contra el stub, el anclaje del stop-loss y su re-derivación tras una ejecución con comisión, el protocolo de enlace del puente en modo cliente, las rutas de cotizaciones y posiciones, y la compuerta que impide que una carga útil con forma de error se consuma como una lista de posiciones vacía — un incidente real, donde un timeout devolvió {"positions": []} y un lector posterior se lo creyó.

Dos pruebas se omiten en lugar de pasar cuando su sujeto está ausente. Ejercitan un consumidor de este servidor, por lo que necesitan el proyecto anfitrión (OAS_HOST_REPO, OAS_RECONCILE_CMD). Una comprobación que silenciosamente se vuelve verde cuando lo que comprueba falta es peor que ninguna comprobación.

Estado y limitaciones

• El backend stub está completo y es determinista. mt5_demo está en uso en producción contra un terminal MetaTrader 5 ejecutándose bajo Wine en macOS.

• check_rate_limit está implementado pero no lo ejercita el banco de pruebas — el banco simula timeouts del bróker y activación del interruptor de emergencia, no respuestas de límite de tasa. Se indica porque la distinción entre "implementado" y "probado" es el tema central de este repositorio.

• El puente MT5 tiene la forma de macOS/Wine. Una instalación nativa de Windows necesita OAS_MT5_COMMON_FILES configurado y no ha sido probada por mí.

• Un solo terminal por diseño: el listener es un singleton en un puerto, y un segundo proceso del servidor detecta al primero y reenvía a él en lugar de competir por el enlace.

Licencia

MIT — ver LICENSE.