A Harness MCP — Codex-Stil autonomer Programmier-Agent-Dienst

A Harness MCP ist ein lokaler Serverdienst, der auf dem Model Context Protocol (MCP) basiert. Er stellt die geschichteten Kontexte, das Skill-System und die autonomen Agent-Fähigkeiten des Codex Harness externen KI-Clients (wie Claude Desktop, DeepSeek usw.) in Form von MCP-Tools zur Verfügung. Über diesen Dienst können externe KI-Systeme in Ihren lokalen Projekten Code ausführen, Dateien lesen und schreiben, externe Tools aufrufen und komplexe Programmieraufgaben auf strukturierte Weise erledigen.

✨ Kernfunktionen

• Geschichtete Kontextassemblierung — Angelehnt an das Codex-Harness-Design werden grundlegende Verhaltensrichtlinien, benutzerbezogene AGENTS.md, projektspezifische AGENTS.md und ein Skill-Index schichtweise überlagert. Die Prozesskonventionen können vom Benutzer frei bearbeitet werden und sind nicht fest im Code verdrahtet.

• Skill-System — Unterstützt die Definition unabhängiger Skills im Verzeichnis .a_harness_mcp/skills/ des Projekts. Über das Tool get_skill werden die vollständigen Anweisungen bei Bedarf geladen, wodurch Kontextredundanz reduziert wird.

• Integrierter umfangreicher Tool-Satz — Bietet Shell-Befehlsausführung, Datei-Lesen/Schreiben, Verzeichnisdurchsuchung, Patch-Anwendung, Bildanzeige, Websuche, MCP-Serververwaltung und mehr.

• Codex-Agent-Integration — Integriertes codex-Tool, mit dem komplexe Codierungsaufgaben direkt an den Codex-Agent delegiert werden können, mit Timeout-Steuerung und benutzerdefinierten Modellen.

• Proxy für externe MCP-Server — Über die Konfigurationsdatei mcp_servers.json können Drittanbieter-MCP-Server (z. B. Excel, SSH, AMap usw.) einheitlich als Proxy bereitgestellt und in die Tool-Liste integriert werden.

• Grafische Steuerungsoberfläche — Bietet ein mit PyQt5 erstelltes GUI-Programm zur Konfiguration von Projektverzeichnis, Berechtigungsmodus, Host-Port und Modellparametern sowie zur Echtzeit-Anzeige von Dienstprotokollen und KI-Interaktionsaufzeichnungen.

• Leichtgewichtiger Testclient — Integrierter mcp_client_test.py, der nur die Standardbibliothek verwendet und ohne Drittanbieter-Abhängigkeiten die Verfügbarkeit des Dienstes verifizieren kann.

Related MCP server: MCP Server

🚀 Schnellstart

Server starten

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

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

MCP-Client verbinden

Der Dienst stellt standardmäßig einen MCP-Streamable-HTTP-Endpunkt unter http://127.0.0.1:9999/mcp bereit und unterstützt die Verbindung beliebiger MCP-kompatibler Clients.

Mit dem Smoke-Test-Client verifizieren

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

In Claude Desktop konfigurieren

Fügen Sie in der Claude-Desktop-Konfigurationsdatei Folgendes hinzu:

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

📦 Verfügbare Tools

🧩 Skill-System (Skills)

Skills sind projektebene, wiederverwendbare Fähigkeitseinheiten, die unter .a_harness_mcp/skills/<Skill-Name>/SKILL.md gespeichert werden.

Jede Skill-Datei deklariert Metadaten über Frontmatter:

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

# PDF 分析技能

## 使用场景
...

Beim Initialisieren lädt die externe KI nur name und description des Skills als Index. Der vollständige Text wird bei Bedarf über get_skill abgerufen, wodurch die Belegung des Kontextfensters erheblich reduziert wird.

🎛️ Berechtigungsmodi

Der Berechtigungsmodus kann über das GUI-Dropdown-Menü oder den Dienststartparameter umgeschaltet werden.

📁 Mechanismus der geschichteten Kontextassemblierung

Beim Dienststart werden automatisch die folgenden Kontexte assembliert und der externen KI als anfängliche Anweisungen injiziert:

1. Grundlegende Verhaltensrichtlinien — Integrierte Codex-Stil-Richtlinien (Tool-Spezifikationen, Autonomie, Qualitätsanforderungen)

2. Benutzerbezogene Prozesskonventionen — ~/.a_harness_mcp/AGENTS.md (Standardvorlage wird beim ersten Start automatisch generiert, frei bearbeitbar)

3. Projektspezifische Prozesskonventionen — <Projekt>/AGENTS.md oder <Projekt>/.a_harness_mcp/AGENTS.md (höhere Priorität als benutzerbezogene)

4. Skill-Index — Scannt das Verzeichnis .a_harness_mcp/skills/ und fasst Namen und Beschreibungen aller Skills zusammen

🔌 Proxy für externe MCP-Server

Über die Konfigurationsdatei mcp_servers.json können Drittanbieter-MCP-Server als Proxy in diesen Dienst integriert werden:

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

Die als Proxy bereitgestellten Tools werden einheitlich in der Tool-Liste registriert und können von der externen KI direkt aufgerufen werden.

🧪 Entwicklung und Tests

Abhängigkeiten installieren

pip install PyQt5

Tests ausführen

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

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

🗂️ Projektstruktur

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

📄 Lizenz

MIT

🤝 Beiträge

Issue- und Pull-Request-Einreichungen sind willkommen. Stellen Sie vor dem Einreichen von Code sicher, dass:

• Der vorhandene Codestil eingehalten wird

• Neue Funktionen mit entsprechenden Testfällen versehen sind

• Die zugehörige Dokumentation aktualisiert wird

Mit ❤️ erstellt für die lokale KI-Agent-Entwicklung.