接入数据与服务

​

选择接入方式

​

先验证，再开发

​

统一工具入口

{
  "toolAccess": ["call"]
}

// 在服务激活后的请求处理里调用；名称、参数和返回结构先用真实查询验证
async function callVerifiedTool(context, args) {
  const { tools } = await context.tool.list();
  const tool = tools.find(
    (item) => item.kind === 'mcp' && item.server === VERIFIED_SERVER && item.tool === VERIFIED_TOOL_NAME,
  );
  if (!tool || tool.permission === 'deny') throw new Error('tool_unavailable');
  return context.tool.call(tool.name, args);
}

• 从 list() 的结果取 name，按 kind、server / provider 和 tool 匹配，不拼接工具名。list() 返回 { tools, partial }；partial: true 表示清单不完整，可能有来源不可用或部分工具因元数据问题被省略；已列出的工具仍按当前权限调用。
• permission 是当时的 allow、ask 或 deny；每次调用都会重新判定。规则采用用户的全局工具权限和权限模式，不继承某个 Agent 或会话的规则；宿主内置工具沿用原有放行行为，这条调用链不会执行 Agent 的工具 Hook。
• 需要确认时，由宿主弹框提供「允许一次」「始终允许」「拒绝」。只有用户在宿主框中选择「始终允许」才会写入全局规则，Mini App 不能代答。无人可确认时返回 TOOL_APPROVAL_REQUIRED。
• MCP 结果包含 kind: 'mcp'、isError 和 content；isError: true 是工具报告业务失败，Promise 仍正常返回。Connector 结果包含 kind: 'connector' 和原始 value。写操作遇到 unknown_after_dispatch 时，先核对业务状态，不要盲目重试。
• Node 的 context.tool.request(names) 和页面的 window.mcode.miniapp.tool.request(names) 可提前请求授权；需探测 tool.request 能力。页面调用必须来自用户手势、每次最多 10 个工具，并要求 Node 服务正在运行。页面只请求授权，工具的列出和调用仍在 Node；把 Node 获取的运行时工具名通过业务接口传给页面。

​

Host Connector

{
  "hostConnectorAccess": { "providers": ["notion"] }
}

• 只声明运行时真正需要、并且已经验证过的 provider。
• list() 随时可用，返回允许的工具清单和输入 schema。call() 只在服务激活后、在请求处理里调用，不要在 start 里调。
• 不要自己构造或保存 toolRef，也不要发给页面。进程重启或遇到过期引用时，重新 list()。
• 用户退出登录时，工具清单和授权引用会被撤销；同一账号重新登录后再 list() 即可恢复，不用重新发布。换成其他账号后，旧引用永久失效。

// 在请求处理里调用；工具名和参数以验证时观察到的清单和 schema 为准
async function readRecords(context, args) {
  const { tools } = await context.hostConnector.list();
  const tool = tools.find((t) => t.provider === 'notion' && t.name === VERIFIED_TOOL_NAME);
  if (!tool) throw new Error('connector_tool_unavailable');
  const result = await context.hostConnector.call(tool.toolRef, args);
  return parseRecords(decodeHostConnectorValue(result.value));
}

​

错误处理

​

解析返回值

​

状态与持久化

• 运行时数据写在 context.dataDir，不要写进工作区或载荷。
• 页面、MCP 调用和 Agent 操作的所有写入都走同一个 Node 业务服务。先将状态写入磁盘，再推送 SSE 或 WebSocket 事件，这样每个打开的页面都能刷新到最新数据。