AuraBoot
免费开始
English简体中文

MCP 与 Tool

Aura Bot 知识库 — 已索引文档

AuraBoot 通过 Model Context Protocol（MCP）将其 Command 与命名查询暴露为 Tool。外部 MCP 客户端（例如桌面 AI 助手、IDE Agent 或其他 Agent 平台）可以连接到一个 AuraBoot 部署，并以与登录用户相同的 Permission、校验与审计保证调用其 Tool。

概念

MCP 是内部 Tool 选择的反向过程。在内部，AuraBoot Agent 运行时为自己的 LLM 挑选 Tool；在外部，MCP 让外部 Agent 看到 AuraBoot 的目录并按名调用 Tool。

让 MCP 在 AuraBoot 中行得通的两件事：

  1. 每个 Command 已经携带 input_schema、agent_hint、cmd_risk_level 与 execution_config（其中包含 permissions）。
  2. DSL Tool Provider 自动将这些 Command 定义转换为 Tool 描述符；外部客户端则通过 aura mcp serve CLI 连接。

你不需要手写 Tool 代码，只需编写 Command，并让 Provider 暴露它们。匹配某个模型的每个已发布 Command 都会自动成为 Tool，没有 exposeAsMcp 之类的开关需要逐个选择加入或排除。

何时使用

  • 外部助手（Claude Desktop、IDE Agent、其他平台 Agent）需要调用 AuraBoot 操作。
  • 内部团队构建独立 Agent 栈，但希望 AuraBoot 作为权威记录系统。
  • 长期集成希望使用带类型与 schema 描述的契约，而非定制 REST 胶水。

如果调用方本身就是 AuraBoot 部署，使用 ACP；MCP 面向外部客户端。

架构

+--------------------+
|  External MCP      |
|  client            |
|  (Claude Desktop,  |
|   IDE agent, etc.) |
+----------+---------+
           | tools/list
           | tools/call
           v
+----------+-----------+        +-----------------------+
|  aura mcp serve CLI  | <----  |  DSL Tool Provider    |
|  (per deployment)    |        |  reads commands +     |
+----------+-----------+        |  named queries +      |
           |                    |  agent_hints          |
           |                    +-----------------------+
           v
+----------+-----------+
|  Command pipeline    |
|  (auth, permission,  |
|   validation, audit) |
+----------------------+

MCP 服务器按调用无状态。aura mcp serve 启动时要求当前会话已固定（pin）租户（通过 aura login --tenant <name>），从而把外部客户端映射为 AuraBoot principal（携带 tenantId 的 JWT 主体）。从此处起，调用经过标准 Command 管道。

DSL Tool Provider

匹配某个模型的每个已发布 Command 都会成为一个 Tool（工具码形如 cmd:<commandCode>；命名查询为 nq:<queryCode>，并自动附带通用的 list:<modelCode> 与 get:<modelCode> 工具）：

{
  "code": "customer.query",
  "model_code": "crm_customer",
  "cmd_risk_level": "L0",
  "input_schema": {
    "type": "object",
    "properties": {
      "keyword": { "type": "string" },
      "status":  { "type": "string", "enum": ["active", "archived"] }
    }
  },
  "agent_hint": "Search customers by keyword and status.",
  "execution_config": {
    "permissions": ["crm.customer.read"]
  }
}

DSL Tool Provider 在发现时（ToolDiscoveryContext 提供 modelHint）查询数据库 ab_command_definition 表，筛选 tenant_id、model_code、deleted_flag = FALSE、is_current = TRUE 的命令；没有 exposeAsMcp 字段，所有匹配的命令都会被暴露。每个 Tool 的 schema 取自 Command 的 input_schema（缺省时由 execution_config.inputFields 与模型字段元数据推导）。

示例：外部客户端调用一个 Tool

外部 MCP 客户端基于 stdio 或 HTTP：

// tools/list 响应（节选）
{
  "tools": [
    {
      "name": "cmd:customer.query",
      "description": "Search customers by keyword and status.",
      "inputSchema": { "type": "object", "properties": { /* ... */ } }
    }
  ]
}

// tools/call 请求
{
  "name": "cmd:customer.query",
  "arguments": { "keyword": "acme", "status": "active" }
}

// tools/call 响应
{
  "content": [
    { "type": "text", "text": "Found 3 customers matching \"acme\" (active)." },
    { "type": "json", "json": { "rows": [ /* ... */ ], "total": 3 } }
  ]
}

Permission 与审计

MCP 不是 Permission 旁路：

  • 连接的客户端会映射为 AuraBoot principal（通过 aura login 获得的、携带 tenantId 的 JWT）。
  • 每次 Tool 调用都通过 <module>.<resource>.<action> Permission code 解析。
  • 每次调用都会经 POST /api/meta/audit/mcp-tool 写入 ab_command_audit_log，审计行的 command_code 为 mcp.<toolName>、phase_reached 为 mcp_tool，与普通 Command 共享同一套审计查询 UI；同时也会写入本地 ~/.aura/mcp-audit.log。
  • 风险等级策略仍然适用；破坏性 Tool 可能需要外部客户端带外解决的审批。

验证清单

  • 你希望暴露的 Command 已发布且 model_code 与目标模型匹配（匹配即自动暴露，无需开关）。
  • 每个暴露的 Command 都有严格的 input_schema 与精确的 agent_hint。
  • 外部客户端已 aura login --tenant <name> 并以拥有所需 Permission 的身份鉴权。
  • 审计日志针对外部 Tool 调用显示 command_code = mcp.<toolName>。
  • 客户端的 tools/list 仅返回该 principal 实际可运行的 Tool。

相关