A Harness MCP — Codex スタイルの自律プログラミング Agent サービス

A Harness MCP は、Model Context Protocol (MCP) に基づくローカルサーバープログラムで、Codex Harness の階層型コンテキスト、スキルシステム、自律 Agent 機能を MCP ツールの形で外部 AI クライアント（Claude Desktop、DeepSeek など）に公開します。このサービスを通じて、外部 AI はローカルプロジェクト内でコードの実行、ファイルの読み書き、外部ツールの呼び出しを行い、構造化された方法で複雑なプログラミングタスクを完了できます。

✨ コア機能

• 階層型コンテキストの組み立て —— Codex Harness の設計を参考に、基本行動規範、ユーザーレベルの AGENTS.md、プロジェクトレベルの AGENTS.md、スキルインデックスを階層的に重ね合わせます。プロセス規約はユーザーが自由に編集でき、コードにハードコードされません。

• スキル (Skill) システム —— プロジェクトの .a_harness_mcp/skills/ ディレクトリに独立したスキルを定義でき、get_skill ツールで完全な説明を必要に応じて読み込むことで、コンテキストの冗長性を削減します。

• 豊富な組み込みツールセット —— shell コマンド実行、ファイル読み書き、ディレクトリ参照、パッチ適用、画像表示、Web 検索、MCP サーバー管理などの機能を提供します。

• Codex Agent 統合 —— codex ツールを内蔵し、複雑なコーディングタスクを Codex Agent に直接委任して実行できます。タイムアウト制御とカスタムモデルをサポートします。

• 外部 MCP サーバープロキシ —— mcp_servers.json の設定により、サードパーティの MCP サーバー（Excel、SSH、高德地图など）を統一的にプロキシし、ツールリストに統合できます。

• グラフィカル制御インターフェース —— PyQt5 で構築された GUI プログラムを提供し、プロジェクトディレクトリ、権限モード、ホストポート、モデルパラメータを設定でき、サービスログと AI 対話記録をリアルタイムで確認できます。

• 軽量テストクライアント —— 純粋な標準ライブラリで実装された mcp_client_test.py を内蔵しており、サードパーティの依存関係なしでサービスの可用性を検証できます。

Related MCP server: MCP Server

🚀 クイックスタート

サーバーの起動

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

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

MCP クライアントへの接続

サービスはデフォルトで http://127.0.0.1:9999/mcp に MCP Streamable HTTP エンドポイントを提供し、任意の 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 のドロップダウンメニューまたはサービスの起動パラメータで切り替えられます。

📁 階層型コンテキスト組み立てメカニズム

サービス起動時に以下のコンテキストが自動的に組み立てられ、初期 instructions として外部 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 Agent 開発のために ❤️ を込めて作られました。