Composio Granola MCP Toolkit 指南：上游元数据镜像机制与工具 schema 不一致排查方法-编程实验室

Composio Granola MCP Toolkit 指南：上游元数据镜像机制与工具 schema 不一致排查方法

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

Granola 是一款会议笔记应用，负责捕获会议转录内容，并帮助团队检索与共享对话，把会议上下文转化为行动项和后续跟进。Composio 通过granola_mcptoolkit 将 Granola 官方 MCP server 的能力接入 AI Agent，本文围绕该 toolkit 的元数据来源机制展开：Composio 为什么无法保证工具元数据与 Granola 上游完全同步、空输出 schema 为什么不能作为 catalog 过期的证据，以及遇到工具缺失或字段不一致时如何正确排查与上报。读完本文，你将掌握 Granola MCP toolkit 的真实能力清单、其元数据边界背后的源码原理，以及一套可复用的 MCP 元数据差异诊断流程。

Granola MCP toolkit 在 Composio 中的真实形态

在 Composio 的工具目录（toolkit catalog）中，Granola 以granola_mcp为 slug 注册，其公开元数据记录在 docs/public/data/toolkits.json：

属性	值
slug	`granola_mcp`
名称	Granola MCP
分类	productivity & project management
认证方式	`DCR_OAUTH`（动态客户端注册 OAuth）
工具数量	6
触发器数量	0
catalog 版本	`20260805_00`

从分类与认证方式可以看出两点重要信息：其一，该 toolkit 属于生产力 / 项目管理类，聚焦会议笔记的读写与检索；其二，它只通过 DCR OAuth 连接 Granola 账户，没有额外的触发器等事件能力。

值得留意的是，catalog 中该 toolkit 的版本号（20260805_00）是 Composio 侧对上游 server 元数据做快照的版本标记。由于下游能力完全取决于上游暴露内容（下文详解），版本号只能反映"Composio 最近一次同步到的上游元数据状态"，而不代表工具本身由 Composio 实现。

六个工具：Composio 可暴露的全部能力

根据 docs/public/data/toolkits.json，granola_mcp当前暴露 6 个工具。注意一个关键事实：catalog 中这些工具条目只包含 slug、名称与描述，没有声明任何input_parameters或输出 schema 字段——这正是本文核心论点的最直观例证（见下一节）。

工具 slug	名称	能力说明
`GRANOLA_MCP_GET_ACCOUNT_INFO`	Get account info	返回当前连接账户的邮箱、活跃工作区与有效笔记访问范围（`mcp_note_access.scopes`，如`personal`、`public`）
`GRANOLA_MCP_GET_MEETINGS`	Get meetings	按会议 ID 获取详细会议信息：私人笔记、AI 生成的摘要、与会者与元数据
`GRANOLA_MCP_GET_MEETING_TRANSCRIPT`	Get meeting transcript	按会议 ID 获取逐字转录全文，`Me`代表记录者，`Them`代表其他未命名参与者
`GRANOLA_MCP_LIST_MEETING_FOLDERS`	List meeting folders	列出用户的会议文件夹（含嵌套），返回 folder ID、标题、描述与笔记数，可用于配合`list_meetings`的`folder_id`过滤
`GRANOLA_MCP_LIST_MEETINGS`	List meetings	在时间范围内列出会议笔记，支持`workspace_only`、`involvement`、`captured_by_me`、`listed_as_participant`等过滤组合
`GRANOLA_MCP_QUERY_GRANOLA_MEETINGS`	Query granola meetings	用自然语言查询会议内容，返回带编号内联引用链接（如`[[0]](url)`）的答案，引用必须原样保留给用户以保持可溯源

从工具描述中可以提炼出 Granola 上游设计的使用准则，Agent 集成时应当遵循：

短期的会议内容问题优先使用query_granola_meetings（自然语言检索 + 引用溯源），而不是list_meetings/get_meetings；
已有明确会议 ID时使用get_meetings获取详情、get_meeting_transcript获取逐字转录；
需要浏览/分目录时用list_meetings（支持folder_id）与list_meeting_folders；
需要确认身份与权限（如怀疑连错账户、会议结果不完整）时先调用get_account_info核对当前账户与访问范围。

这些描述文本均由 Granola 官方 MCP server 提供，Composio 原样镜像，具体内容以你实际连接到的上游 server 为准。

元数据边界：Composio 镜像上游，而非自研工具

核心文档 docs/kb/articles/toolkits-granola-mcp.md 明确声明：Granola MCP toolkit 使用 Granola 官方 MCP server，工具名称、描述、输入定义与响应元数据，都受限于该上游 server 实际暴露的内容。

这条边界带来两个直接推论：

上游给什么，Composio 才能暴露什么。如果 Granola 只提供一个工具名和一句描述，那么这就是 Composio 能镜像到的全部元数据，Composio 不会（也无法）凭空补充更丰富的输入定义。
上游没声明的东西，Composio 不会编造。如果 Granola 没有为某工具声明响应/输出 schema，Composio 不可能自行发明一个输出 schema，因此空的输出 schema 本身并不能作为"Composio catalog 过期"的证据。

对应的源文档 docs/kb/source/toolkits/granola_mcp/public.md 将该文档标记为visibility: public、category: toolkits-and-providers，即这是一份面向公众的参考文档；而 MDX 版本 docs/content/kb/guide/toolkits-granola-mcp.mdx 将其元数据标注为freshness: "evergreen"（常青内容），并登记了lastVerifiedAt（2026-08-17）与reviewAfter（2026-11-15）两个复核时间点，说明这份"镜像机制"说明在 Composio 知识库中被视为长期有效的稳定性指南，而非一次性公告。

源码印证：为什么"空输出 schema"是正常现象

上面关于空输出 schema 的论断并非仅是文档表述，它还有对应的 SDK 源码级实现证据。

在 ts/packages/core/src/models/Tools.ts 中，Composio TypeScript SDK 定义了normalizeRawToolParameters函数，其注释明确写道：

MCP-backed toolkits (granola_mcp, apify_mcp, tavily_mcp, …) have no declared output schema and the API serializes that as{}, which would otherwise tripParametersSchema.

该函数将 API 返回的input_parameters/output_parameters中的null、undefined与空对象{}——三者语义相同，都表示"未声明 schema"——统一归一化为undefined，从而让严格的 ZodParametersSchema校验器不会误判。从源码结构可以推断：

MCP 类 toolkit 没有声明输出 schema 是系统性的、被 SDK 显式处理的预期行为，不是 catalog 数据损坏；
当你在 SDK 中看到 Granola 工具的输出参数为空时，这正是上游 server 未声明响应 schema 被镜像后的正常形态；
SDK 之所以专门为这一情形写归一化逻辑（并关联到上游 issue 跟踪），恰恰证明此类 toolkit 在真实调用链路中广泛存在，空 schema 属于必须兼容的正常状态，而非异常信号。

因此，判断"catalog 是否过期"绝不能只看输出 schema 是否为空，必须回到上游 server 的实际情况去核对。

元数据不一致排查流程：从发现到上报

当你在使用granola_mcp时发现某个工具缺失、或某个工具缺少预期字段（如输入参数、描述、输出 schema），请按 docs/kb/articles/toolkits-granola-mcp.md 给出的流程处理，避免把上游的天然限制误判为 Composio 侧缺陷：

第一步：先核对上游，再下结论。任何差异都必须先与 Granola 官方 MCP server 的当前行为对照。只有确认"官方 server 现在确实暴露了该工具或该 schema 字段，而 Composio 里却没有"时，差异才成立。

第二步：记录精确信息。记下确切的工具名与缺失字段。模糊的描述（"Granola 的工具不完整"）无法用于定位，精确到工具 slug 和字段名（如GRANOLA_MCP_LIST_MEETINGS缺少某个输入参数）才有排查价值。

第三步：区分两种情形。

官方 server 也没暴露 → 差异是上游限制，Composio 镜像机制的正常体现，无需处理；
官方 server 已暴露但 Composio 缺失 → 这才是真正需要上报的 catalog 同步缺口。

第四步：联系 Composio 支持并附上对比信息。将第二步记录的精确工具名/字段名、以及"官方 server 当前行为 vs Composio catalog 现状"的对比细节一并提供给 Composio 支持团队，才能让 catalog 的同步问题被准确定位和修复。

整个流程的核心原则可以概括为一句话：不要凭 Composio 侧的元数据表象判断对错，一切以 Granola 官方 MCP server 的实际暴露内容为准。

延伸：在 Composio 中使用 MCP 类 toolkit 的注意点

granola_mcp属于 MCP 承载型 toolkit，其使用方式与 Composio 的 MCP 机制紧密相关。仓库中的 MCP 排查文档 docs/kb/articles/mcp-mcp-hermes.md 提供了若干与 MCP 连接相关的通用提示，可作为使用此类 toolkit 时的背景参考：

MCP 生产环境 API 路径形如https://backend.composio.dev/api/v3.1/mcp/servers与https://backend.composio.dev/api/v3.1/mcp/<mcp_server_id>，需在x-api-key中传递 Project API key；
无认证的 server 也应显式传auth_config_ids: []（配合no_auth_apps），避免因缺省配置导致连接失败；
直接测试返回的 MCP transport 时，需要携带 Project API key、user_id或connected_account_id以及Accept: application/json, text/event-stream头。

另外，从 SDK 的使用方式看，ts/packages/core/src/models/MCP.ts 显示 Composio 官方推荐通过会话级 MCP endpoint 使用 MCP 能力（composio.create(userId, { mcp: true })后访问session.mcp.url/session.mcp.headers），granola_mcp这类 MCP 镜像 toolkit 的元数据也遵循与 MCP server 一致的镜像边界。

总结

Composio 的granola_mcptoolkit 是一面"镜子"：它忠实反射 Granola 官方 MCP server 暴露的工具名称、描述、输入定义与响应元数据，自身不增不减。理解这层镜像关系，是正确使用与排查该 toolkit 的前提：

能力边界：当前 catalog 中可镜像 6 个工具（账户信息、会议详情、转录、文件夹、会议列表、自然语言查询），认证方式为 DCR OAuth；
schema 真相：MCP 类 toolkit 无输出 schema 属正常现象，SDK 在 Tools.ts 中专门为此做归一化处理；
排查原则：一切差异以上游 Granola 官方 server 为准，确认上游已暴露而 Composio 缺失后，携带精确的工具名、缺失字段与对比细节联系 Composio 支持。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考