MCP任务中继
中文文档 |英语
MCP任务中继是一个生产就绪的模型上下文协议（MCP）服务器，它为自主代理提供了一个复杂的调度器/执行器工作流。它具有企业级可靠性，具有智能问答协议和加密上下文验证功能，可防止上下文漂移，同时将令牌使用率降低95%以上。
架构概述
┌─────────────┐ MCP Protocol ┌──────────────┐
│ MCP │ ◄──────────────────► │ Scheduler │
│ Clients │ (stdio/SSE) │ (Relay) │
│ (Claude/ │ │ │
│ Codex) │ │ ┌────────┐ │
└─────────────┘ │ │Answer │ │
│ │Runner │ │
│ │(LLM) │ │
│ └────────┘ │
│ ▲ │
│ │ Ask │
│ ▼ │
┌─────────────────────────────┤ ┌────────┐ │
│ Ask/Answer Protocol │ │Context │ │
│ (Context Envelope) │ │Envelope│ │
│ ┌──────────────┐ │ │+ Hash │ │
│ │ Executor SDK │ ◄────────┤ └────────┘ │
│ └──────────────┘ │ │
│ Job Execution └──────────────┘
│ Environment
└──────────────────────────────────────────────┘关键创新： 带有SHA-256验证的上下文包络协议确保了执行器和应答运行器之间的完美上下文对齐，消除了上下文漂移，同时最大限度地减少了令牌开销。
______________________________________________________________________
✨ 主要特点
🔐 上下文信封协议
通过显式、可验证的上下文快照防止上下文漂移：
- 密码验证：SHA-256哈希确保上下文完整性
- 令牌优化：约50个代币（最低）vs 10k-50k代币（完整历史）
- 零会话内存：每个Ask都独立处理，并进行完整的上下文重建
- 答案证明：使用的上下文/角色/模型/工具的加密证明
🤖 智能问答系统
- 四层提示架构：基地→ Role → 上下文→ Task
- 角色目录：基于YAML的可扩展角色定义
- LLM集成：具有自动重试和验证功能的拟人克劳德
- JSON模式验证：具有模式强制的类型安全响应
- 决策缓存：消除了对相同查询的冗余LLM调用
💾 企业级存储
- 带WAL模式的SQLite：高性能并发访问
- 自动架构管理：无需手动迁移
- 内存模式：非常适合测试和CI/CD
- 完整审计跟踪：完成所有状态转换的事件跟踪
📊 生产可观察性
- 结构化日志记录：通过Pino创建JSON日志
- 实时更新：作业/任务状态的服务器发送事件（SSE）
- 综合指标：请求延迟、缓存命中率、令牌使用情况
______________________________________________________________________
🚀 快速开始
先决条件
- Node.js ≥ 20
- npm 或 小圆面包 1.3+
- 无烟煤API密钥 （适用于答案跑者）
安装
# NPM (recommended for production)
npm install -g mcp-task-relay
# Or use npx for one-off execution
npx -y mcp-task-relay@latest serve --profile dev基本用法
# Start with in-memory storage (development)
mcp-task-relay serve \
--profile dev \
--storage memory \
--config-dir ./.mcp-task-relay
# Start with persistent storage (production)
export ANTHROPIC_API_KEY="sk-ant-..."
mcp-task-relay serve \
--profile prod \
--storage sqlite \
--sqlite ./data/relay.db \
--config-dir ./config______________________________________________________________________
📖 配置
CLI选项
| 标志 | 描述 | 环境变量 |
|---|---|---|
--profile | 环境配置文件（dev/stating/prod） | TASK_RELAY_PROFILE |
--config-dir | 配置目录路径 | TASK_RELAY_CONFIG_DIR |
--storage | 存储后端（内存/sqlite） | TASK_RELAY_STORAGE |
| `--sqlite | ||
| ` | SQLite数据库文件路径 | TASK_RELAY_SQLITE_URL |
--transport | 传输协议（仅限第2阶段的stdio） | TASK_RELAY_TRANSPORT |
环境变量
必修的：
ANTHROPIC_API_KEY-Answer Runner的Anthropic API密钥
可选：
TASK_RELAY_PROMPTS_DIR--自定义提示目录TASK_RELAY_SCHEMATA_DIR--自定义JSON模式目录TASK_RELAY_POLICY_FILE--自定义策略YAML文件TASK_RELAY_ANSWER_RUNNER_ENABLED--启用/禁用应答运行程序（默认值：true）
上下文信封（执行器侧）：
TASK_RELAY_JOB_ID--当前作业标识符TASK_RELAY_STEP_ID--当前执行步骤TASK_RELAY_REPO--存储库标识符TASK_RELAY_COMMIT_SHA--Git提交SHATASK_RELAY_POLICY_VERSION--策略版本TASK_RELAY_FACT_*--自定义事实（例如。，TASK_RELAY_FACT_branch=main)
配置目录结构
.mcp-task-relay/
├── config.yaml # Main configuration
├── policy.yaml # Security policy rules
├── prompts/ # Role definitions
│ ├── role.diff_planner@v1.yaml
│ ├── role.test_planner@v1.yaml
│ └── role.schema_summarizer@v1.yaml
└── schemata/ # JSON Schemas
├── ask.schema.json
├── answer.schema.json
└── artifacts/
├── diff_plan.schema.json
└── test_plan.schema.json示例 config.yaml:
askAnswer:
port: 3415
longPollTimeoutSec: 25
sseHeartbeatSec: 10
runner:
enabled: true
model: claude-3-5-sonnet-20241022
maxRetries: 1
defaultTimeout: 60______________________________________________________________________
🔧 MCP客户端集成
Codex CLI
# Add to Codex configuration
codex mcp add task-relay -- \
mcp-task-relay serve \
--profile prod \
--storage sqlite \
--sqlite ./relay.db克劳德代码（桌面）
添加到您的Claude Code MCP设置中(~/.claude-code/mcp.json):
{
"mcpServers": {
"task-relay": {
"command": "mcp-task-relay",
"args": [
"serve",
"--profile", "prod",
"--storage", "sqlite",
"--sqlite", "./relay.db"
],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}Gemini代码辅助
# Configure in Gemini workspace settings
gemini config mcp add task-relay \
--command "mcp-task-relay serve" \
--args "--profile prod --storage sqlite"______________________________________________________________________
🎯 上下文信封协议
概述
上下文包络协议通过显式、加密验证的上下文快照消除了上下文漂移。
问题： 传统方法需要传输完整的对话历史（10k-50k令牌），导致：
- 大量代币使用和成本
- 上下文窗口限制
- 执行器和应答运行器之间可能存在上下文不一致
解决方案： 具有SHA-256验证的结构化上下文快照（50-300个令牌）。
令牌使用情况比较
| 方法 | 令牌使用 | 上下文完整性 | 用例 |
|---|---|---|---|
| 无上下文 | ~50个令牌 | 无 | 答案运行者无视上下文❌ |
| 上下文信封 | 50-300个代币 | 密码学的 | 适用于95%以上的场景 ✅ |
| 历史 | 10k-50k代币 | 完成 | 需要完整上下文的复杂决策 |
上下文包络结构
最小（默认环境）：
{
"job_snapshot": {},
"role": "default"
}代币成本： 约50个代币
典型（定制事实生产）：
{
"job_snapshot": {
"repo": "github.com/user/repo",
"commit_sha": "abc123def456...",
"env_profile": "production",
"policy_version": "2.0"
},
"facts": {
"branch": "main",
"pr_number": "123"
},
"tool_caps": {
"database": {
"timeout_ms": 5000
}
},
"role": "code_reviewer"
}代币成本： ~150-200个代币
验证流程
1. Executor builds context_envelope
└─► Computes SHA-256 hash → context_hash
2. Ask sent with both context_envelope + context_hash
3. Scheduler stores Ask in database
4. Answer Runner retrieves Ask
├─► Verifies: computed_hash == stored_hash
└─► FAIL-FAST on mismatch (E_CONTEXT_MISMATCH)
5. Answer Runner generates response
└─► Creates attestation with context_hash
6. Answer sent back to Executor
7. Executor verifies attestation
└─► Ensures context_hash matches original错误代码
- E_CONTEXT_MISMATCH --上下文哈希验证失败
- E_CAPS_volation --违反了工具能力约束
- E_NO_CONTEXT_ENVELOPE --缺少所需的上下文信封
智能默认值（令牌优化）
SDK会自动省略默认值以尽量减少令牌使用：
repo：如果“未知”，则省略（默认）commit_sha：如果“未知”，则省略（默认）env_profile：如果为“dev”，则省略（默认）policy_version：如果为“1.0”，则省略（默认）facts：如果为空，则省略tool_caps：如果没有指定工具，则省略
结果： 在典型场景中，代币减少75-85%。
______________________________________________________________________
🛠️ 发展
从源代码构建
# Clone repository
git clone https://github.com/royisme/mcp-task-relay.git
cd mcp-task-relay
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Link for local development
npm link项目结构
src/
├── cli.ts # CLI entry point
├── server.ts # Runtime bootstrap
├── answer-runner/ # LLM-powered answering engine
│ ├── runner.ts # Core Answer Runner
│ ├── role-catalog.ts # YAML role loader
│ └── prompt-builder.ts # 4-layer prompt architecture
├── core/ # Business logic
│ └── job-manager.ts # Job orchestration
├── db/ # Data persistence
│ ├── connection.ts # SQLite setup
│ ├── asks-repository.ts # Ask/Answer storage
│ └── answers-repository.ts
├── models/ # Type definitions
│ ├── schemas.ts # Zod schemas
│ └── states.ts # State machine & error codes
├── sdk/ # Executor SDK
│ └── executor.ts # Context envelope auto-packing
├── services/ # HTTP/SSE services
│ └── ask-answer.ts # Ask/Answer API endpoints
└── utils/ # Shared utilities
├── hash.ts # Context hashing & verification
└── logger.ts # Structured logging
prompts/ # Built-in role catalog
schemata/ # JSON Schema definitions______________________________________________________________________
🤝 贡献
欢迎投稿！请阅读我们的 贡献指南 在提交PR之前。
开发工作流程
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
______________________________________________________________________
📄 许可证
麻省理工学院©2025罗伊。看 许可证 了解详情。
______________________________________________________________________
🙏 致谢
- Anthropic -对于Claude API和MCP规范
- 更好的SQLite3 --高性能SQLite绑定
- 黄道 --类型安全架构验证
______________________________________________________________________
📮 支持
- 问题:
- 讨论: