A Harness MCP — Servicio de agente de programación autónoma estilo Codex

A Harness MCP es un programa de servidor local basado en el Model Context Protocol (MCP) que expone el contexto jerárquico, el sistema de habilidades y las capacidades de agente autónomo de Codex Harness a clientes de IA externos (como Claude Desktop, DeepSeek, etc.) en forma de herramientas MCP. A través de este servicio, la IA externa puede ejecutar código, leer y escribir archivos, invocar herramientas externas en su proyecto local y completar tareas de programación complejas de forma estructurada.

✨ Características principales

• Ensamblaje de contexto jerárquico — Inspirado en el diseño de Codex Harness, superpone capas de reglas de comportamiento base, AGENTS.md de nivel de usuario, AGENTS.md de nivel de proyecto e índice de habilidades. Las convenciones de flujo de trabajo son editables libremente por el usuario y no están codificadas de forma fija en el programa.

• Sistema de habilidades (Skills) — Admite la definición de habilidades independientes en el directorio .a_harness_mcp/skills/ del proyecto, cargando las instrucciones completas bajo demanda mediante la herramienta get_skill, lo que reduce la redundancia de contexto.

• Conjunto de herramientas integrado — Proporciona ejecución de comandos shell, lectura/escritura de archivos, navegación de directorios, aplicación de parches, visualización de imágenes, búsqueda web, gestión de servidores MCP y más.

• Integración con Codex Agent — Incluye la herramienta integrada codex, que permite delegar tareas de codificación complejas directamente a Codex Agent, con control de tiempo de espera y modelos personalizados.

• Proxy de servidores MCP externos — Mediante el archivo de configuración mcp_servers.json, se pueden integrar y agrupar servidores MCP de terceros (como Excel, SSH, mapas de Amap, etc.) en la lista de herramientas.

• Interfaz de control gráfica — Proporciona un programa GUI construido con PyQt5 para configurar el directorio del proyecto, el modo de permisos, el puerto del host, los parámetros del modelo y ver en tiempo real los registros del servicio y el historial de interacciones con la IA.

• Cliente de prueba ligero — Incluye mcp_client_test.py, implementado únicamente con la biblioteca estándar, que permite verificar la disponibilidad del servicio sin dependencias de terceros.

Related MCP server: MCP Server

🚀 Inicio rápido

Iniciar el servidor

# 启动 GUI 控制界面
python codex_mcp_gui.py

# 或直接启动 HTTP 服务（无 GUI）
python codex_mcp_server.py

Conectar un cliente MCP

El servicio proporciona por defecto un endpoint MCP Streamable HTTP en http://127.0.0.1:9999/mcp, compatible con cualquier cliente MCP.

Verificar con el cliente de prueba de humo

# 握手并列出所有可用工具
python mcp_client_test.py

# 调用 shell 工具执行 dir 命令
python mcp_client_test.py --tool shell --args '{"command":"dir"}'

# 调用 codex 工具执行编程任务
python mcp_client_test.py --tool codex --args '{"prompt":"读取当前目录所有 Python 文件并统计总行数"}'

Configurar en Claude Desktop

Añada lo siguiente al archivo de configuración de Claude Desktop:

{
  "mcpServers": {
    "a-harness-mcp": {
      "url": "http://127.0.0.1:9999/mcp"
    }
  }
}

📦 Herramientas disponibles

🧩 Sistema de habilidades (Skills)

Las habilidades son unidades de capacidad reutilizables a nivel de proyecto, almacenadas en .a_harness_mcp/skills/<nombre-de-habilidad>/SKILL.md.

Cada archivo de habilidad declara metadatos mediante frontmatter:

---
name: pdf-analyzer
description: 提取 PDF 文档中的表格和关键信息，适用于财务报告分析
---

# PDF 分析技能

## 使用场景
...

Al inicializarse, la IA externa solo carga el name y la description de la habilidad como índice; el cuerpo completo se obtiene bajo demanda mediante get_skill, lo que reduce considerablemente el uso del contexto.

🎛️ Modos de permisos

El modo de permisos se puede cambiar mediante el menú desplegable de la GUI o los parámetros de inicio del servicio.

📁 Mecanismo de ensamblaje de contexto jerárquico

Al iniciarse, el servicio ensambla automáticamente el siguiente contexto y lo inyecta a la IA externa como instrucciones iniciales:

1. Reglas de comportamiento base — Reglas integradas de estilo Codex (especificaciones de herramientas, autonomía, requisitos de calidad)

2. Convenciones de flujo de nivel de usuario — ~/.a_harness_mcp/AGENTS.md (se genera automáticamente una plantilla predeterminada en la primera ejecución, editable libremente)

3. Convenciones de flujo de nivel de proyecto — <proyecto>/AGENTS.md o <proyecto>/.a_harness_mcp/AGENTS.md (con prioridad sobre el nivel de usuario)

4. Índice de habilidades — Escanea el directorio .a_harness_mcp/skills/ y resume los nombres y descripciones de todas las habilidades

🔌 Proxy de servidores MCP externos

Mediante el archivo de configuración mcp_servers.json, se pueden integrar servidores MCP de terceros en este servicio:

[
  {
    "name": "excel",
    "enabled": true,
    "config": {
      "mcpServers": {
        "excel": {
          "command": "npx",
          "args": ["-y", "@zhiweixu/excel-mcp-server"],
          "env": { "CACHE_MAX_AGE": "1" },
          "type": "stdio"
        }
      }
    }
  }
]

Las herramientas proxy se registran de forma unificada en la lista de herramientas y la IA externa puede invocarlas directamente.

🧪 Desarrollo y pruebas

Instalación de dependencias

pip install PyQt5

Ejecutar pruebas

# 启动服务（GUI 或非 GUI 模式）
python codex_mcp_gui.py

# 另开终端执行冒烟测试
python mcp_client_test.py

🗂️ Estructura del proyecto

.
├── A Harness MCP.exe       # PyInstaller 打包的可执行文件
├── codex_mcp_gui.py        # PyQt5 GUI 控制界面
├── codex_mcp_server.py     # MCP HTTP 服务核心实现
├── context.py              # 分层上下文装配器
├── mcp_plugins.py          # 外部 MCP 服务器代理与插件管理
├── mcp_client_test.py      # 纯标准库 MCP 客户端冒烟测试
├── mcp_servers.json        # 外部 MCP 服务器配置
└── codex_mcp_gui_config.json # GUI 配置文件（项目目录、端口、权限模式等）

📄 Licencia

MIT

🤝 Contribuciones

Las Issues y Pull Requests son bienvenidas. Antes de enviar código, asegúrese de:

• Seguir el estilo de código existente

• Incluir casos de prueba correspondientes para las nuevas funcionalidades

• Actualizar la documentación relevante

Hecho con ❤️ para el desarrollo de agentes de IA locales.