A Harness MCP — Codex 스타일의 자율 프로그래밍 에이전트 서비스

A Harness MCP는 Model Context Protocol (MCP) 기반의 로컬 서버 프로그램으로, Codex Harness의 계층형 컨텍스트, 스킬 시스템, 자율 에이전트 기능을 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, Amap 등)를 통합 프록시하여 도구 목록에 포함할 수 있습니다.

• 그래픽 제어 인터페이스 — 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 드롭다운 메뉴 또는 서비스 시작 매개변수로 전환할 수 있습니다.

📁 계층형 컨텍스트 조립 메커니즘

서비스 시작 시 다음 컨텍스트가 자동으로 조립되어 외부 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를 환영합니다. 코드를 제출하기 전에 다음을 확인해 주세요:

• 기존 코드 스타일 준수

• 새 기능에 해당하는 테스트 케이스 포함

• 관련 문서 업데이트

로컬 AI 에이전트 개발을 위해 ❤️로 제작되었습니다.