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 命令执行、文件读写、目录浏览、补丁应用、图片查看、网络搜索、MCP 服务器管理等能力。
• Codex Agent 集成 —— 内置 codex 工具，可直接将复杂编码任务委托给 Codex Agent 执行，支持超时控制和自定义模型。
• 外部 MCP 服务器代理 —— 通过 mcp_servers.json 配置，可将第三方 MCP 服务器（如 Excel、SSH、高德地图等）统一代理并集成进工具列表。
• 图形化控制界面 —— 提供 PyQt5 构建的 GUI 程序，可配置项目目录、权限模式、主机端口、模型参数，并实时查看服务日志与 AI 交互记录。
• 轻量级测试客户端 —— 内置纯标准库实现的 mcp_client_test.py，无需第三方依赖即可验证服务可用性。

🚀 快速开始

启动服务端

# 启动 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"
    }
  }
}

📦 可用工具

工具名称	描述
shell	在项目目录中执行 shell 命令（受权限模式约束）
codex	启动 Codex Agent 完成编码任务（嵌套 Agent）
read_file	读取项目内文本文件
write_file	写入项目内文本文件（只读模式下禁用）
list_dir	列出项目内目录内容
apply_patch	应用 git 风格 unified diff 补丁
view_image	查看 base64 编码或项目路径下的图片
web_search	联网搜索（走 DuckDuckGo 网页接口）
harness_context	返回当前注入的完整上下文（流程规则 + 技能索引）
list_skills	列出项目可用的技能
get_skill	按需加载指定技能的完整 SKILL.md 说明
memory_save / update / delete	长期记忆管理（用户偏好、行为纠正、讨论要点等）
skill_draft_create	创建待审阅的自定义 Skill 草稿
memory_import_preview	预览并导入外部记忆数据

🧩 技能系统（Skills）

技能是项目级别的可复用能力单元，存放于 .a_harness_mcp/skills/<技能名>/SKILL.md。

每个技能文件使用 frontmatter 声明元数据：

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

# PDF 分析技能

## 使用场景
...

外部 AI 初始化时只会加载技能的 name 和 description 作为索引，完整正文通过 get_skill 按需获取，大幅压缩上下文窗口占用。

🎛️ 权限模式

模式	说明
workspace-read	只读模式，禁止任何写入操作
workspace-write	允许在工作区内读写和执行命令
workspace-write-all	无额外限制的完整工作区权限

权限模式可通过 GUI 下拉菜单或服务启动参数切换。

📁 分层上下文装配机制

服务启动时自动装配以下上下文，注入给外部 AI 作为初始 instructions：

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。在提交代码前，请确保：

• 遵循现有代码风格
• 新增功能附带对应的测试用例
• 更新相关文档

---

Made with ❤️ for local AI Agent development.