AI导哈

代理MCP规范

定义代理MCP提供商的规范，包括工具名称、输入输出模式及语义，以确保互操作性。

  • by AbhiShake1
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 AbhiShake1/agents-mcp

使用说明

特工mcp

代理MCP提供商的规范。定义任何Agent MCP实现必须遵循的工具名称、输入模式、输出模式和语义，以实现互操作性。

问题

存在多个具有重叠功能但工具名称和模式不同的代理MCP提供程序（cmux代理MCP、wezterm代理MCP和macp代理MCP）。消费者（Pulse、Storyrun、未来产品）被迫与特定的实现相结合。如果提供者更改了其接口，则下游的所有内容都会中断。

解决方案

此repo定义 能力概况 --提供者实现和消费者编程所依据的可组合合约。提供者通过声明它支持哪些功能 agents_capabilities，消费者使用规范名称发现+调用工具。

┌─────────────────────────────────────────────────────────┐
│                     Consumers                           │
│   Pulse  ·  Storyrun  ·  Custom orchestrators           │
│                         │                               │
│              calls canonical tool names                 │
│                         ▼                               │
│   ┌─────────────────────────────────────────────────┐   │
│   │            agents-mcp spec (this repo)          │   │
│   │                                                 │   │
│   │  terminal-environment  ·  agent-orchestration   │   │
│   │  coordination  ·  metadata (generic)            │   │
│   └─────────────────────────────────────────────────┘   │
│                         │                               │
│           providers implement these profiles            │
│                         ▼                               │
│   cmux-agent-mcp  ·  wezterm-agent-mcp  ·  macp-agent-mcp │
└─────────────────────────────────────────────────────────┘

能力概况

terminal-environment （终端提供商需要）

生命周期、窗格CRUD、文本I/O、导航和布局。

工具 说明
term_status 健康检查和环境信息
term_start 启动终端环境
term_shutdown 终止所有窗格和环境
term_spawn 创建新窗格
term_split 拆分现有窗格
term_kill_pane 关闭特定窗格
term_list 列出所有包含元数据的窗格
term_send_text 发送不带Enter键的文本
term_send_submit 发送文本并按Enter键
term_send_key 发送特殊密钥
term_read_output 读取窗格中的文本输出
term_focus_pane 聚焦/激活窗格
term_resize_pane 调整窗格大小
term_rename 重命名选项卡/工作区/窗口
term_screenshot 截图

agent-orchestration （代理感知终端需要）

启动AI CLI、批量I/O和会话持久性。 取决于 terminal-environment.

工具 说明
orch_launch 在网格中生成多个AI代理
orch_launch_grid 创建一个空的终端网格
orch_launch_mixed 启动异构AI CLIs
orch_broadcast 向所有窗格发送相同的文本
orch_send_each 向每个窗格发送不同的文本
orch_send_some 将文本发送到特定窗格
orch_read_all 读取所有窗格的输出
orch_read_deep 查询空闲代理的状态
orch_orchestrate 向窗格发送有针对性的提示
orch_session_save 持续的环境状态
orch_session_recover 从保存状态还原
orch_session_reconcile 比较已保存状态与实时状态

coordination （独立式——无需终端）

多代理消息传递、文件声明、共享内存、任务和目标。

工具 说明
coord_register 注册代理会话
coord_poll 检查收到的消息
coord_send_channel 广播到频道
coord_send_direct 发送给特定代理
coord_ack 确认交货
coord_deregister 注销会话
coord_list_agents 列出活动代理
coord_claim_files 创建咨询文件锁
coord_release_files 发布文件声明
coord_list_locks 列出活动文件索赔
coord_set_memory 存储范围值
coord_get_memory 检索值
coord_search_memory 全文搜索记忆
coord_list_memories 列出回忆
coord_delete_memory 存档存储器
coord_dispatch_task 创建任务
coord_claim_task 申请待处理任务
coord_start_task 过渡到进行中
coord_complete_task 完成结果
coord_block_task 有理由阻止
coord_cancel_task 取消任务
coord_get_task 获取任务详细信息
coord_list_tasks 列出任务
coord_create_goal 设定一个目标
coord_update_goal 更新目标
coord_list_goals 列出目标
coord_get_goal 获取目标详细信息

通用元数据

该规范没有为侧边栏UI、浏览器自动化或其他特定于提供商的功能提供专用的功能配置文件，而是提供了一个通用的 metadata 字段分为两个级别：

  • 按能力：每个 CapabilityDeclaration 有一个可选 metadata: Record<string, unknown> 功能特定扩展字段。
  • 提供商级别：The AgentsCapabilitiesOutput 有一个可选 metadata: Record<string, unknown> 提供程序范围扩展的字段（状态标记、UI提示、浏览器配置等）。

这使规范专注于可互操作的合同，同时为提供商提供了充分的灵活性来展示自定义功能。

{
  "ok": true,
  "spec_version": "0.1.0",
  "provider": "cmux",
  "provider_version": "1.2.3",
  "capabilities": [
    {
      "id": "terminal-environment",
      "version": "0.1.0",
      "metadata": { "supports_tabs": true, "sidebar": true }
    },
    { "id": "agent-orchestration", "version": "0.1.0" }
  ],
  "metadata": {
    "browser": { "engine": "playwright", "headless": true },
    "sidebar": { "status_badges": true, "progress_bars": true }
  }
}

发现

每个符合要求的提供商都必须公开 agents_capabilities:

{
  "ok": true,
  "spec_version": "0.1.0",
  "provider": "cmux",
  "provider_version": "1.2.3",
  "capabilities": [
    { "id": "terminal-environment", "version": "0.1.0" },
    { "id": "agent-orchestration", "version": "0.1.0" }
  ],
  "platform": "darwin"
}

消费者首先调用此功能，然后只使用声明功能中的工具。

用法

对于供应商（实施规范）

npm install @agents-mcp/spec

import {
  TERMINAL_ENVIRONMENT_TOOLS,
  AGENT_ORCHESTRATION_TOOLS,
  AgentsCapabilitiesOutput,
} from "@agents-mcp/spec";

// Register tools using the canonical names and schemas
for (const [name, { input, output }] of Object.entries(TERMINAL_ENVIRONMENT_TOOLS)) {
  server.tool(name, input, async (params) => {
    // Your implementation here
    return output.parse(result);
  });
}

对于消费者（呼叫提供商）

import {
  TermListOutput,
  OrchLaunchInput,
  OrchReadAllOutput,
} from "@agents-mcp/spec";

// Call canonical tool names — works with any conforming provider
const panes = TermListOutput.parse(await callTool("term_list", {}));
const launched = await callTool("orch_launch", OrchLaunchInput.parse({
  cli: "claude",
  count: 4,
  cwd: "/my/project",
}));

一致性测试

import { runConformance, printReport } from "@agents-mcp/spec/conformance";

const report = await runConformance(callTool, listTools);
printReport(report);
// ✓ term_status
// ✓ term_spawn
// ✗ term_split — Missing input fields: direction

版本控制

  • 规范如下： MAJOR.MINOR.PATCH
  • 重大：重大更改（删除工具、更改必填字段）
  • 次要的：附加更改（新的可选工具、新的可选字段）
  • 补丁：文件、澄清、一致性测试修复
  • 提供者声明他们符合哪个规范版本
  • 消费者应该检查 spec_version 并优雅地处理

设计原则

  1. 规范名称 --每个概念一个名称。没有泄漏提供程序标识的前缀。
  2. 可组合能力 --选择你实施的东西。无头协调？就 coordination.全终端？ terminal-environment + agent-orchestration.
  3. 架构优先 --每个工具都有Zod输入/输出模式。验证是免费的。
  4. 发现驱动 --消费者从不猜测。呼叫 agents_capabilities 第一。
  5. 提供者不可知 --规范不在乎你是cmux、wezterm还是还不存在的东西。
  6. 配置文件上的元数据 --特定于提供商的功能（侧边栏UI、浏览器自动化）属于通用功能 metadata 现场，而不是专用的能力配置文件。

提供商映射

现有供应商如何映射到规范功能：

提供者 终端环境 代理编排 协调
cmux代理mcp 是 是 --
wezterm特工mcp 是 是 --
macp代理mcp -- -- 是

许可证

Apache 2.0

相关 MCP