A Harness MCP — автономный сервис программирования в стиле Codex

A Harness MCP — это локальный серверный сервис на основе Model Context Protocol (MCP), который предоставляет внешним AI-клиентам (таким как Claude Desktop, DeepSeek и др.) многоуровневый контекст, систему навыков и возможности автономного агента Codex Harness в виде MCP-инструментов. С помощью этого сервиса внешний AI может выполнять код, читать и записывать файлы, вызывать внешние инструменты в вашем локальном проекте и выполнять сложные задачи программирования структурированным образом.

✨ Ключевые возможности

• Многоуровневая сборка контекста — по образцу Codex Harness: базовые правила поведения, пользовательские AGENTS.md, проектные AGENTS.md и индекс навыков накладываются слоями; соглашения о рабочих процессах можно свободно редактировать, они не зашиты в код.

• Система навыков (Skills) — поддерживает определение отдельных навыков в каталоге .a_harness_mcp/skills/ проекта; полное описание загружается по требованию через инструмент get_skill, что снижает избыточность контекста.

• Встроенный богатый набор инструментов — выполнение shell-команд, чтение/запись файлов, просмотр каталогов, применение патчей, просмотр изображений, веб-поиск, управление MCP-серверами и многое другое.

• Интеграция Codex Agent — встроенный инструмент codex позволяет делегировать сложные задачи кодирования агенту Codex Agent с поддержкой контроля тайм-аута и настраиваемых моделей.

• Проксирование внешних MCP-серверов — через конфигурацию mcp_servers.json можно проксировать сторонние MCP-серверы (например, Excel, SSH, Amap и др.) и интегрировать их в список инструментов.

• Графический интерфейс управления — GUI-программа на PyQt5 для настройки каталога проекта, режима разрешений, порта хоста, параметров модели, а также просмотра журналов сервиса и записей взаимодействия с AI в реальном времени.

• Облегчённый тестовый клиент — встроенный mcp_client_test.py, реализованный только на стандартной библиотеке, позволяет проверить работоспособность сервиса без сторонних зависимостей.

Related MCP server: MCP Server

🚀 Быстрый старт

Запуск сервера

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

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

Подключение MCP-клиента

Сервис по умолчанию предоставляет конечную точку MCP Streamable HTTP по адресу http://127.0.0.1:9999/mcp и поддерживает подключение любого MCP-совместимого клиента.

Проверка с помощью смоук-тестового клиента

# 握手并列出所有可用工具
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 文件并统计总行数"}'

Настройка в Claude Desktop

Добавьте в конфигурационный файл Claude Desktop:

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

📦 Доступные инструменты

🧩 Система навыков (Skills)

Навыки — это переиспользуемые единицы возможностей на уровне проекта, хранящиеся в .a_harness_mcp/skills/<имя_навыка>/SKILL.md.

Каждый файл навыка объявляет метаданные с помощью frontmatter:

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

# PDF 分析技能

## 使用场景
...

При инициализации внешний AI загружает только name и description навыка в качестве индекса; полный текст получается по требованию через get_skill, что значительно сокращает занимаемое контекстное окно.

🎛️ Режимы разрешений

Режим разрешений можно переключать через выпадающее меню GUI или параметры запуска сервиса.

📁 Механизм многоуровневой сборки контекста

При запуске сервис автоматически собирает следующий контекст и внедряет его внешнему AI в качестве начальных инструкций:

1. Базовые правила поведения — встроенные правила в стиле Codex (спецификация инструментов, автономность, требования к качеству)

2. Пользовательские соглашения о процессах — ~/.a_harness_mcp/AGENTS.md (при первом запуске автоматически создаётся шаблон по умолчанию, который можно свободно редактировать)

3. Проектные соглашения о процессах — <проект>/AGENTS.md или <проект>/.a_harness_mcp/AGENTS.md (приоритет выше, чем у пользовательских)

4. Индекс навыков — сканирование каталога .a_harness_mcp/skills/ и сводка имён и описаний всех навыков

🔌 Проксирование внешних MCP-серверов

Через конфигурационный файл mcp_servers.json можно проксировать сторонние MCP-серверы в этот сервис:

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

Проксированные инструменты регистрируются в общем списке инструментов, и внешний AI может вызывать их напрямую.

🧪 Разработка и тестирование

Установка зависимостей

pip install PyQt5

Запуск тестов

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

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

🗂️ Структура проекта

.
├── 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 配置文件（项目目录、端口、权限模式等）

📄 Лицензия

MIT

🤝 Вклад

Приветствуются Issue и Pull Request. Перед отправкой кода убедитесь, что:

• Соблюдается существующий стиль кода

• Новые функции сопровождаются соответствующими тестовыми примерами

• Обновлена соответствующая документация

Сделано с ❤️ для разработки локальных AI-агентов.