内容
AdaptOrch 中间件（MCP）
<p align="center">
<a href="https://adaptorch.ai.kr"><img src="assets/readme-hero.png" alt="AdaptOrch 中间件（MCP）— 路由、运行和从 Claude Code 检索证据" width="100%"></a>
</p>
<p align="center">
<a href="https://adaptorch.ai.kr"><strong>adaptorch.ai.kr</strong></a>
·
<a href="docs/configuration.md">配置</a>
·
<a href="docs/tools.md">工具</a>
·
<a href="docs/claude-code-b2c.md">Claude Code 指南</a>
·
<a href="docs/publishing.md">发布</a>
·
<a href="https://arxiv.org/abs/2602.16873">论文</a>
</p>
<p align="center">
<img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white">
<img alt="MCP" src="https://img.shields.io/badge/MCP-stdio%20%7C%20HTTP-22d3ee?style=flat-square">
<img alt="License Proprietary" src="https://img.shields.io/badge/license-Proprietary-94a3b8?style=flat-square">
<img alt="Public ready" src="https://img.shields.io/badge/public--ready-yes-86efac?style=flat-square <a href="https.org/abs/2602.16873"><img alt="arXiv 2602.16873" src="https://img.shields.io/badge/arXiv-2602.16873-b31b?style=flat-square&logo&logoColor=white"></a>
>
**AdaptOrch 中间件（MCP）** 是 [AdaptOrch](https://adaptorch.ai.kr) 的公共 MCP 包装器：一个可靠性内核，允许 Claude Code 路由任务，启动有编排的运行，并将证据工件拉回聊天中。
在以下情况下使用它：编码任务太大、太模糊或太昂贵，无法信任单个通道响应。
```text
Claude Code → AdaptOrch MCP → 路由拓扑 → 运行并合成 → 检索工件
```
## 获取您的 API 密钥
AdaptOrch 需要身份验证。分两步获取您的令牌：
1. **注册** → [adaptorch.ai.kr/app/signup](https://adaptorch.ai.kr/app/signup)
2. **创建 API 密钥** → 仪表盘 → API 密钥管理 → 生成密钥（以 `ado_` 开头）
将该密钥用作 `ADAPTORCH_CONTROL_PLANE_TOKEN`：
```bash
export ADAPTORCH_CONTROL_PLANE_TOKEN="ado_..."
```
| 令牌 | 用途 | 获取位置 |
| --- | --- | --- |
| `ADAPTORCH_CONTROL_PLANE_TOKEN` | 所有 AdaptOrch API 调用（运行、状态、工件） | 注册后在仪表盘上 |
| `ADAPTORCH_MCP_HTTP_AUTH_TOKEN` | 保护您的本地 HTTP MCP 端点 | 您定义（任何安全字符串） |
免费层（Starter `$0`）包括 API 密钥访问。有关 Pro/Team 计划，请adaptorch.ai.kr](https://adaptorch.ai.kr)。
### 精确度配置文件（可选）
AdaptOrch MCP 委托给 AdaptOrch 引擎，因此精度特征仅通过环境变量激活（无需更改代码）。所有功能关闭**（当前在每个部署中激活一个证明的配置文件：
| 变量 | 用途 | 值 |
| --- | --- |
| `ADAPTORCH_ACCURACY_PROFILE` | 命名精度预设（基准） | `off`（默认）\| `balanced` \| `max_accuracy` |
| `ADAPTORCH_PARTIAL_CREDIT_PREFER_CONFIDENCE` | 每个字段覆盖：优先选择置信度更高的部分信用候选 | 真值 |
| `ADAPTORCH_JUDGE_OVERRIDE_MARGIN` | 每个字段覆盖：置信度边缘门控裁判覆盖 | 浮点数 |
| `ADAPTORCH_VERIFICATION_CRITICAL_COMMANDS` | 每个字段覆盖：视为验证关键的命令 | 逗号列表 |
| `ADAPTORCH_VERIFICATION_CRITICAL_WEIGHT` | 每个字段覆盖：应用于验证关键命令的权重 | 整数或浮点数 |
配置文件是可选的，仅在测量更好的情况下采用；每个字段的变量胜过配置文件。包装器本身不实现算法；它将环境激活转发到 AdaptOrch 引擎的 P11–P19 行。
## 研究论文
AdaptOrch MCP 遵循 AdaptOrch 研究线路。 在 arXiv 上阅读论文：
- 摘要页面：[arxiv.org/abs/2602.16873](https://arxiv.org/abs/2602.16873)
- HTML 论文：[arxiv.org/html/2602.16873v1](https://arxiv.org/html/2602.16873v1)
<p align="center">
<a href="https://arxiv.org/html/2602.16873v1">
<img src="https://arxiv.org/html/2602.16873v1/x1.png" alt="AdaptOrch arXiv HTML中的图表" width="88%">
</a>
</p>
<p align="center"><sub预览源自 arXiv HTML 版本。</sub></p>
## 安装
### pip
```bash
pip install adaptorch-mcp
```
Orch 核心尚未在 PyPI 上，请先从 Git：
```bash install "adaptorch[api] @ git+https://github.com/dmae97orch.git"
pip install-mcp
```
### uv一次性，无需安装）
```bash
uvorch-mcp --```
使用 GitHub 上的 依赖项：
```bash
uvx --with "adaptorch[ @ git+https:///dmae97/ad.git" adaptorch-mcp
```
## 为什么 Claude Code 用户快速感受到它的| 首选优势 | 工具 | 聊天中的变化 |
| --- | --- | --- |
| 减少规划不确定性 | `adaptorch_route_topology` |在花费运行预算之前解释任务应该是单例、管道、DAG 还是集成。 减少大型任务失败 | `adaptorch_run` | 大目标通过 AdaptOrch、合成和遥测，而不是一次脆弱的通道。 |
| 无需上下文切换的证据 | `adaptorch_get_artifacts` | 输出、跟踪和运行证明返回到 Claude Code 对话中。 |
| 更安全的设置支持 | `adaptorch-mcp-doctor` | 用户可以粘贴删减的诊断信息，而不会泄露令牌。 |
| 快速安装循环 | `adaptorch-mcp-smoke` | 使用 `initialize` + `tools/list` 验证本地 MCP 连线。 |
## 架构
<p align="center">
<img src="assets/mcp-flow.png" alt="AdaptOrch MCP 路由-运行-证据流程" width="100%">
</p>
## 软件包
| 路径 | 软件包 | 用途 |
| --- | --- | --- |
| `packages/adaptorch-mcp` | `adaptorch-mcp` | 围绕 `adaptorch.mcp_server` 的 Python CLI 包装器 |
包装器故意将运行时给 `adaptorch.mcp_server`。这使得 MCP 工具、资源、提示、安全检查和传输与最新的 AdaptOrch 核心版本保持一致。
## 快速入门
### 本地开发
```bash
git clone git@github.com:dmae97/Adaptorch-MCP.git
git clone git@github.com:dmae97/adaptorch.git # 与 Adaptorch-MCP 并列
cd Adaptorch-MCP
uv sync --all-packages --extra dev
uv run adaptorch-mcp --help
```
## stdio 中间件（MCP）
对于 Claude Code 或桌面 MCP 主机等本地客户端，请使用 stdio：
```bash
export ADAPTORCH_CONTROL_PLANE_TOKEN="<your-token>"
adaptorch-mcp --transport stdio --base-url https://adaptorch.ai.kr
```
## HTTP 中间件（MCP）
对于本地网关、反向代理或远程 MCP 客户端，请使用 HTTP：
```bash
export ADAPTORCH_CONTROL_PLANE_TOKEN="<upstream-adaptorch-token>"
export ADAPTORCH_MCP_HTTP_AUTH_TOKEN="<client-facing-mcp-token>"
adaptorch-mcp \
--transport http \
--base-url https://adaptorch.ai.kr \
--http-host 127.0.0.1 \
--http-port 8765
```
健康检查：
```bash
python - <<'PY'
import httpx
print(httpx.get('http://127.0.0.1:8765/mcp/health').json())
PY
```
## CLI 和环境参考
| 命令 | 用途 | 重要选项 |
| --- | --- | --- |
| `adaptorch-mcp` | 启动 stdio 或 HTTP MCP 服务器。 | `--transport stdio|http`， `--base-url`， `--api-token`， `--timeout-seconds`， `--stdio-framing`， `--http-host`， `--http-port`， `--http-auth-token` |
| `adaptorch-mcp-doctor` | 打印删减的本地诊断信息。 | `--json`， `--strict` |
| `adaptorch-mcp-smoke` | 验证 stdio `initialize` + `tools/list`。 | `--command`， `--base-url`， `--api-token`， `--timeout-seconds`， 可重复的 `--expected-tool` |
对于 `adaptorch-mcp`，公共包装器按以下顺序解析控制平面 URL：显式 `--base-url`，然后修剪/验证的 `ADAPTORCH_CONTROL_PLANE_BASE_URL`，然后托管的备用 `https://adaptorch.ai.kr`。`adaptorch-mcp-smoke` 在未配置基 URL 时保留 `http://127.0.0.1:8000` 的本地开发备用。 在已检查的 MCP 客户端配置中显式传递 `--base-url` 以实现可复制的行为。
| 变量 | 用途 | 备注 |
| --- | --- | --- |
| `ADAPTORCH_CONTROL_PLANE_TOKEN` | 上游 AdaptOrch 令牌。 | 除非传递 `--api-token`，否则必填。 |
| `ADAPTORCH_CONTROL_PLANE_BASE_URL` | 在省略 `--base-url` 时使用的基准 URL。 | 修剪并验证为 HTTP(S)；不要嵌入凭证。 |
| `ADAPTORCH_MCP_HTTP_AUTH_TOKEN` | HTTP/SSE MCP 的客户端承载令牌。 | 与上游控制平面令牌分开。 |
| `ADAPTORCH_MCP_ALLOWED_ORIGINS` | 以逗号分隔的 HTTP 源允许列表。 | 与浏览器或远程 HTTP 客户端一起使用。 |
| `ADAPTORCH_MCP_MAX_PAYLOAD_SIZE_BYTES` | 接受的 HTTP 请求正文大小上限。 | 为公共部署保留限定。 |
| `ADAPTORCH_MCP_REQUEST_TIMEOUT_SECONDS` | HTTP 请求超时预算。 | 适用于 HTTP 服务器请求处理。 |
| `ADAPTORCH_MCP_MAX_SSE_SUBSCRIBERS` | 最大并发 SSE 订阅者。 | 默认值由 `adaptorch.mcp_server` 提供。 |
| `ADAPTORCH_MCP_TIMEOUT_SECONDS` | 用于应用程序工厂用例的控制平面客户端超时。 | 在嵌入 ASGI 应用程序时很有用。 |
| `ADAPTORCH_ACCURACY_PROFILE` | 可选的 P11–P19 精确度预设。 | 默认情况下为 `off`；`balanced`/`max_accuracy` 是可选的。 |
## Claude Code 中间件（MCP）配置
```json
{
"mcpServers": {
"adaptorch": {
"command": "adaptorch-mcp",
"args": [
"--transport",
"stdio",
"--base-url",
"https://adaptorch.ai.kr"
],
"env": {
"ADAPTORCH_CONTROL_PLANE_TOKEN": "${ADAPTORCH_CONTROL_PLANE_TOKEN}"
}
}
}
}
```
更多模板：
- `examples/claude_desktop_config.json`
- `examples/omk.mcp.json`
- `examples/mcp-http.env.example`
已检查的示例使用占位符或环境插值。仅在本地的、未提交的配置文件中填写真实的 URL 和令牌。
## 诊断
打印删减的本地诊断信息：
```bash
adaptorch-mcp-doctor
adaptorch-mcp-doctor --json
adaptorch-mcp-doctor --strict
```
运行一个 stdio 烟雾测试。令牌通过子环境传递，而不是进程参数。如果未提供基准烟雾测试将http://127.0.1: 进行本地开发bash
export ADAPTORCH_CONTROL_PLANE_TOKEN="<your-token>"
adaptorch-mcp-smoke --base-url https://adaptorch.ai.kr
```
预期的 JSON 包括 `"ok": true`，`adaptorch_plan_catalog` 和预期的核心工具子集。医生 JSON 还包括已解析基准 URL 源的删减 `` 元数据。添加可重复的 `--expected-tool <name>` 标志以验证特定的托管/。
## 工具表面
| 工具 | 用途 |
| --- | --- |
| `adaptorch_run` | 提交 AdaptOrch 任务有效载荷并可选地等待。 |
| `adaptorch_get_run` | 按 `run_id` 读取运行摘要。 |
| `adaptorch_get_artifacts` | 读取运行的工件元数据。 |
| `adaptorch_list_runs 列出最近的运行。 |
| `adapt_traces` | 读取执行跟踪。 |
adaptorch_cancel_run 请求运行取消。 `adaptorch_route_topology` | 通过 Adapt拓扑路由器本地路由 DAG。 |
| `_server_metrics` | 读取删减的 MCP 服务器指标。 |
| `adaptorch_capabilities` | 读取合成模式、连接器和服务器功能。 |
| `adaptorch_plan_catalog` | 读取托管计划目录：Starter `$0`，Pro `$39`，Team `$149`。 |
对于受信任的本地客户端，请仅自动该客户端安全的输出。保持 `adaptorch_run` 和 `adaptorch_cancel_run` 需要手动批准。对于共享或生产客户端，请在未净有效载荷的情况下，避免自动批准运行、工件和跟踪读取器。
## 品牌资产
- GitHub 英雄assets/readme-hero- GitHub图：`assets/m.png`
- GPT-image-2.0 栅格提示简介：`docs/brand/gpt-image-2-brief.md`
## 公共发布检查清单
发布前：bash
uv run ruff check packages/adaptorch-mcp
uv run mypy packages/ad-mcp/src
pytest packages/ad-mcp/tests -uv run python -m build packages/adaptorch --outdir dist publish --dry-run dist/*
```
然后按照 `ublishing.md`PI 信任发布或基于令牌的 ``。
## 安全不要提交`、API 密钥、承载令牌、私钥 客户端令牌。参见 `SECURITY.md`。
## 许可证
专有 — 版GG。保留所有权利。参见 `LICENSE`。
