Developer Knowledge MCP 三工具解析：google-cloud-developer 插件的官方文档检索机制与实践

Developer Knowledge MCP 三工具解析google-cloud-developer 插件的官方文档检索机制与实践【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文基于google-cloud-developer插件中retrieving-developer-knowledge技能的参考文档 mcp-usage.md详解 Developer Knowledge Remote MCP 服务器的端点配置、三个核心工具search_documents、answer_query、get_documents的参数与返回结构以及资源名的构造规则。读完本文你将能够正确配置 MCP 端点、按问题类型选择合适工具并理解 MCP 与 REST API 两套传输层之间的对应关系从而让编码 Agent 稳定地基于官方文档作答。1. MCP 服务器定位与端点配置Developer Knowledge 技能的检索能力来自一个远程 MCP 服务器其入口地址为https://developerknowledge.googleapis.com/mcp这个端点在插件仓库中以三处配置互相印证mcp.json面向 Agent 插件规范的声明指定type为streamable-httpurl指向上述端点mcp_config.jsonserverUrl字段的简式声明指向同一地址gemini-extension.json面向 Gemini 扩展场景除httpUrl外还声明了authProviderType: google_credentials即使用 Google 凭证完成鉴权。插件元信息见 plugin.jsongoogle-cloud-developer当前版本 1.1.1其描述明确指出插件包含 Google Developer Knowledge MCP 服务器用于提供有据可依、保持更新的 Google Cloud 文档。也就是说这个 MCP 服务器的定位不是通用知识源而是面向 Google 开发者文档语料的 RAG 检索服务。从 SKILL.md 的 Workflow 部分可以进一步看出一个工程上的重要细节声明了服务器不等于连接上了服务器。部分客户端无法与该服务器完成 MCP 握手即使插件声明了服务器环境中也不会暴露answer_query、search_documents或get_documents工具。因此 SKILL.md 要求把这种情况视为常态转而使用 REST API 回退路径见第 6 节。2. 三个可用工具参数、返回与适用场景参考文档 mcp-usage.md 定义了 MCP 服务器暴露的三个工具。下面逐一拆解并结合 SKILL.md 的选型建议补充使用约束。2.1search_documents细粒度文档块检索输入一个搜索查询字符串输出相关的文档文本块chunks其中包含匹配到的语法、代码块或命令行标志flags返回项结构每条结果包含两个关键字段content命中文档块的正文内容parentURI该块所属文档页面的完整 URI可作为后续get_documents取全文的输入。SKILL.md 进一步给出了使用纪律适用场景细粒度的 CLI 标志、精确语法、参数名、IAM 权限串service.resource.verb形式查询写法使用 25 个聚焦关键词例如cloud run filestore nfs mount gcloud而不是整句对话式描述调用形态search_documents(query..., page_size5)即支持page_size参数控制返回块数。2.2answer_query服务端 RAG 综合问答输入一个自然语言问题行为由服务器端执行 RAG检索增强生成输出带来源引用的综合回答synthesized response with source citations。SKILL.md 建议将answer_query(query...)用于概念性指南、架构对比、产品选型概览和多步骤工作流这类需要跨文档综合的问题。它与search_documents的分工是前者回答为什么/怎么选/怎么规划后者回答具体标志和参数长什么样。2.3get_documents按资源名取全文行为拉取完整文档内容参数接收一个names数组元素格式为documents/{uri_without_scheme}——即把文档 URI 去掉协议头https://后拼在documents/前缀之后示例原文档给出对于 parent URIhttps://cloud.google.com/run/docs/deploying应传names: [documents/cloud.google.com/run/docs/deploying]这一URI 去 scheme 转资源名的规则是三个工具中唯一的硬编码格式约束。它意味着search_documents返回结果里的parent字段与get_documents的names参数可以直接串联使用先用搜索定位文档块取出parentURI去掉https://后作为资源名请求全文。SKILL.md 中给出的另一个示例是names: [documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run]对应文档页https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run。2.4 选型速查表问题类型首选工具调用要点概念指南、架构对比、产品选型、多步骤流程answer_query自然语言提问结果自带引用CLI 标志、精确语法、参数名、IAM 权限串search_documents25 个聚焦关键词page_size5已知文档 URI需要完整页面get_documentsnames数组格式documents/{uri_without_scheme}3. 检索结果的消费纪律插件对取到结果之后怎么用有明确的输出规范这些规范决定了 MCP 检索的工程价值直接检索不委派回答问题时应在当前会话上下文中直接执行一次文档查询不派发给子 Agent确认检索成功后再使用PERMISSION_DENIED、UNAUTHENTICATED、HTTP 401/403、空结果集或任何错误负载即使工具本身未报错也属于失败的检索。失败时不应假装成功作答而应先尝试另一条传输路径仍失败则明确告知用户未能访问 Developer Knowledge回答不基于文档检索。SKILL.md 特别强调把凭记忆回忆的文档伪装成检索结果是最差的可用结果因为回复中没有任何东西能把它与真实检索区分开立即输出完整方案拿到文档响应后应直接输出完整、自包含、可执行的技术方案带全部必需标志与占位符的命令、YAML/JSON 配置或代码片段而不是给出指向文档的引用官方文档优先所有方案以检索到的官方文档为唯一依据官方文档约定绝对优先于模型记忆中的默认值CLI 标志、复合键如locationIP:PATH、IAM 权限串须按 Google 官方规范原样呈现。4. 检索语料范围支持哪些域get_documents与search_documents能覆盖什么取决于该服务的文档语料。从 supported-domains.md 可以看到语料横跨五大类官方域名Google Cloud 与基础设施docs.cloud.google.com、cloud.google.com、docs.apigee.com、firebase.google.comAI 与机器学习ai.google.dev、adk.dev、antigravity.google、geminicli.com、www.tensorflow.org移动、Web 与客户端developer.android.com、docs.flutter.dev、dart.dev、developer.chrome.com、web.dev语言、工具与生态go.dev、developers.google.com、developers.home.google.com、mapsplatform.google.com、fuchsia.dev。这解释了 SKILL.md frontmatter 中的边界声明该技能适用于 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台不适用于本地文件系统查找或非 Google 文档——检索不到时不要硬答而应如实说明。5. 与 REST API 的对应关系MCP 三个工具在 REST 层各有对应端点详见 api-fallback.mdbase URL 同为https://developerknowledge.googleapis.comMCP 工具REST 端点方法与路径answer_queryanswerQueryPOST /v1:answerQuerysearch_documentssearchDocumentChunksGET /v1/documents:searchDocumentChunksget_documentsget/batchGetGET /v1/documents/{URI_WITHOUT_SCHEME}/POST /v1/documents:batchGet值得注意的是get_documents对应的 REST 资源名格式与 MCP 完全一致documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-runURI 去掉https://两套传输层可以无缝互切。REST 端点还有两个 MCP 未暴露的细节searchDocumentChunks支持可选的filter参数按域名过滤例如data_source docs.cloud.google.com以及pageSize参数默认 10输出统一为 JSON文档内容以 Markdown 块形式承载对应 MCP 返回项的content字段。6. MCP 不可用时的 REST 回退当运行环境没有暴露 MCP 工具时SKILL.md 规定使用curl直接请求https://developerknowledge.googleapis.com/v1并按优先级尝试两种凭证。方式一复用已存在的 Google 凭证优先。若gcloud已完成认证直接取其访问令牌与配额项目无需额外安装配置curl -s -X POST https://developerknowledge.googleapis.com/v1:answerQuery \ -H Authorization: Bearer $(gcloud auth print-access-token) \ -H X-Goog-User-Project: $(gcloud config get-value project 2/dev/null) \ -H Content-Type: application/json \ -d {\query\: \How do I configure public read access on Cloud Storage?\}如果该方式遇到 401/403 或其他凭证错误说明账号持有的是 API 不接受的令牌——此时应把gcloud auth print-access-token替换为gcloud auth application-default print-access-token重试。API 接受哪种凭证取决于环境的认证方式因此凭证错误是换凭证再试的信号而不是检索失败的终局。方式二API Key。若环境中配置了DEVELOPERKNOWLEDGE_API_KEY则改为key查询参数传参四个操作分别如下# Answer Query curl -s -X POST https://developerknowledge.googleapis.com/v1:answerQuery?key${DEVELOPERKNOWLEDGE_API_KEY} \ -H Content-Type: application/json \ -d {query: How do I configure public read access on Cloud Storage?} # Search Document Chunks25 个聚焦关键词 curl -s https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?querygcloudloggingmetricscreatekey${DEVELOPERKNOWLEDGE_API_KEY} # Get Document curl -s https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key${DEVELOPERKNOWLEDGE_API_KEY} # Batch Get Documents curl -s -X POST https://developerknowledge.googleapis.com/v1/documents:batchGet?key${DEVELOPERKNOWLEDGE_API_KEY} \ -H Content-Type: application/json \ -d {names: [documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run]}api-fallback.md 补充了两个 API 版本v1GA 与v1alpha以及 API Key 也可通过X-Goog-Api-Key请求头传递的替代方式。7. 小结与使用边界本文的核心内容可以归纳为四件事端点Developer Knowledge Remote MCP 服务器位于https://developerknowledge.googleapis.com/mcp以streamable-http类型声明仓库内 mcp.json、mcp_config.json 与 gemini-extension.json 三处配置一致工具search_documents返回带content与parent字段的文档块answer_query做服务端 RAG 综合问答get_documents按documents/{uri_without_scheme}资源名取全文三者覆盖找块—问综合—取全文的完整链路纪律检索失败401/403、错误负载、空结果必须如实上报禁止把记忆内容伪装成检索结果官方文档约定优先于模型记忆边界检索语料限于 Google 官方开发者文档域名见 supported-domains.md非 Google 文档与本地文件查找不在其职责范围内声明了 MCP 服务器不代表已连接缺失工具时应走 REST 回退。相关文档入口SKILL.md 工作流与选型规范、MCP 工具详情、REST API 回退指南、支持域名清单。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考