# ab-platform-mcp-local

一个本地 MCP（Model Context Protocol）server，作为上游实验平台 MCP 的**本地扩展层**：透传上游已有的工具，并在其上新增几个面向「用 AI Agent 做实验分析、并调试分析 skill」的工具。纯接口调用，可在 Claude Code 等 MCP 客户端中使用。

> 本仓库为**脱敏公开版**：所有服务地址、账号、密钥都通过环境变量注入（见 `.env.example`），代码本身不含任何内部地址或凭据。

## 能力

启动后对客户端暴露两类工具：

- **透传工具**：把上游 MCP（通过 SSE transport 连接）的工具原样转发，客户端可直接调用。
- **本地新增工具**：
  - `start_agent_analysis(message, experiment_id, ...)` — 向后端 Agent 发起一次分析对话（异步），返回 `thread_id` / `chat_url`。
  - `get_run_details(thread_id, diagnose?)` — 读取某次对话的完整执行详情（执行统计、思考过程、最终报告；`diagnose=true` 给每个工具的入参/结果/报错）。数据从 Agent 的 checkpoint 读，运行中和完成后都能用。
  - `list_exp_conversations(experiment_id?)` — 列对话历史，拿 `thread_id`。
  - `sync_skill(skill_name, skill_md_path?/content?)` — 上传/覆盖一个个人 skill（幂等）。
  - `list_skills()` — 列出当前账号的个人 skill。

## 结构

```
server.py          # MCP server 入口（低层 Server API：动态合并远端清单 + 本地工具，分发调用）
relay.py           # 透传层：sse_client 连上游 MCP，拉清单 / 转发 tools/call
agent_http.py      # Agent 服务的共享 HTTP 客户端（按 X-Username 认证）
agent_chat.py      # 对话流（SSE 解析 + 异常处理）
tools/             # 本地新增工具实现
  agent_analysis.py、run_details.py、sync_skill.py、conversations.py
run_one.py         # 单任务执行器：上传 skill → 发起 → 体检/重发 → 轮询 → 分类（供批量/并行调用）
```

## 使用

1. Python 3.10+，装依赖：
   ```bash
   python -m venv .venv && ./.venv/bin/pip install -r requirements.txt
   ```
2. 复制 `.env.example` 为 `.env`，填上你自己的服务地址 / 账号 / 密钥。
3. 在 MCP 客户端（如 Claude Code）的配置里注册：
   ```json
   {
     "ab-platform-local": {
       "type": "stdio",
       "command": "/abs/path/.venv/bin/python",
       "args": ["/abs/path/server.py"]
     }
   }
   ```

## 说明

- `.env` 含真实凭据，已被 `.gitignore` 忽略，不要提交。
- 工具的服务地址、鉴权全部来自环境变量；本仓库代码不含任何内部信息。

## License

MIT