# A Harness MCP — Codex 风格的自主编程 Agent 服务

[![Python](https://img.shields.io/badge/Python-3.7+-blue.svg)](https://www.python.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-2025--06--18-green.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**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`，无需第三方依赖即可验证服务可用性。

## 🚀 快速开始

### 启动服务端

```bash
# 启动 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 兼容客户端连接。

#### 使用冒烟测试客户端验证

```bash
# 握手并列出所有可用工具
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 配置文件中添加：

```json
{
  "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 声明元数据：

```markdown
---
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 服务器代理到本服务中：

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

代理后的工具会统一注册到工具列表，外部 AI 可直接调用。

## 🧪 开发与测试

### 依赖安装

```bash
pip install PyQt5
```

### 运行测试

```bash
# 启动服务（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](LICENSE)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request。在提交代码前，请确保：

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

---

**Made with ❤️ for local AI Agent development.**