Google Developer Knowledge MCP 集成实战三个检索工具、资源名规范与 REST 回退方案【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文基于仓库中 retrieving-developer-knowledge 技能的 MCP 工具文档系统讲解 Google Developer Knowledge 远程 MCP 服务器的接入配置、search_documents/answer_query/get_documents三个工具的参数与返回结构、documents/{uri_without_scheme}资源名转换规则并结合仓库内配套文档与插件配置补充 MCP 不可用时的 REST API 回退路径。读完后你可以让 Agent 通过 MCP 或curl稳定检索 Google Cloud、AI、Android、Flutter 等官方文档语料并正确区分检索成功与检索失败。一、Developer Knowledge 技能与 MCP 集成定位retrieving-developer-knowledge是仓库中面向开发者文档检索的技能其 SKILL.md 的元数据声明了它的职责边界能力范围跨 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台搜索、检索并综合synthesize官方开发者文档适用场景查找 gcloud CLI 命令、API 语法、IAM 权限、官方文档、架构对比、产品选型总览不适用场景本地文件系统查找、非 Google 文档。该技能有两条传输通道transport首选是Developer Knowledge 远程 MCP 服务器端点https://developerknowledge.googleapis.com/mcp次选是REST API 回退基址https://developerknowledge.googleapis.com/v1。MCP 工具文档 描述的正是首选通道中可用的三个工具是本文的主体。SKILL.md 中有一条值得牢记的经验性警告原文强调A declared server is not always a connected server.即声明了服务器不等于连接成功。部分客户端无法与该服务器完成 MCP 握手即使插件声明了该服务器环境中也可能完全没有answer_query、search_documents、get_documents三个工具。正确的处理方式是把工具缺失视为正常现象切换到 REST 回退而不是反复重试或臆测答案。二、MCP 服务器的接入配置仓库中的 google-cloud-developer 插件 声明了对该 MCP 服务器的接入。三处配置各自面向不同的宿主环境mcp.json 采用标准mcpServers结构声明了服务器类型与端点{ mcpServers: { developer-knowledge: { type: streamable-http, url: https://developerknowledge.googleapis.com/mcp } } }mcp_config.json 提供精简形式的serverUrl字段gemini-extension.json 则面向 Gemini 扩展场景额外声明了认证方式{ mcpServers: { developer-knowledge: { httpUrl: https://developerknowledge.googleapis.com/mcp, authProviderType: google_credentials } } }从源码结构看authProviderType: google_credentials表明该 MCP 端点走 Google 凭据认证这与下文 REST 回退中gcloud OAuth 令牌 / API Key两套凭据体系是一脉相承的。适用前提客户端需支持streamable-http类型的远程 MCP 服务器。若宿主环境如某些 IDE Agent不支持该握手三个工具将不会出现在工具列表中此时应直接使用第四节的 REST 回退。三、三个 MCP 工具详解以下三个工具的定义来自 MCP 工具文档选型策略来自 SKILL.md 的 Tool Selection 章节。1.search_documents面向精确语法与 CLI 标志输入一个搜索查询字符串输出包含匹配语法、代码块或标志flags的相关文档文本块text chunks返回项结构每个返回条目包含一个content字段文本块内容和一个parentURI 字段文本块所属的父级文档地址。使用要点来自 SKILL.md它适合查找细粒度的 CLI 标志、精确语法、参数名称、IAM 权限service.resource.verb格式。查询应使用2–5 个聚焦关键词例如cloud run filestore nfs mount gcloud而不是完整的对话式句子。返回结果中的parentURI 正是下一个工具get_documents的输入来源两个工具由此形成先检索、后取全文的调用链。2.answer_query面向概念性问答服务端 RAG输入一个自然语言问题处理服务器端执行 RAG检索增强生成输出综合synthesized后的回答并附带来源引用source citations。使用要点它适合概念指南、架构对比、产品选型总览、多步骤工作流这类需要跨文档综合的问题。对于单一事实某个标志怎么写、某个权限叫什么直接用search_documents更精确。3.get_documents按资源名取全文功能获取完整文档内容参数names数组元素格式为documents/{uri_without_scheme}——即去掉协议头后的文档 URI示例对于父级 URIhttps://cloud.google.com/run/docs/deploying应传入{ names: [documents/cloud.google.com/run/docs/deploying] }工具选型速查需求类型首选工具典型输入形态CLI 标志、精确语法、参数名、IAM 权限search_documents2–5 个聚焦关键词如gcloud logging metrics create概念指南、架构对比、选型总览、多步工作流answer_query自然语言问题已知文档地址、需要整页全文get_documentsdocuments/{去协议头的URI}数组四、资源名转换规范documents/{uri_without_scheme}get_documents是整个 MCP 工具链中最容易出错的环节因为文档 URI 与资源名之间存在一条机械转换规则取search_documents返回条目中的parentURI例如https://cloud.google.com/run/docs/deploying去掉协议头https://得到cloud.google.com/run/docs/deploying前缀documents/得到资源名documents/cloud.google.com/run/docs/deploying以数组形式放入names参数。仓库中配套文档 REST API 回退指南 对同一规范给出了另一个实例文档页https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run对应资源名documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run注意其域名前缀是docs.cloud.google.com保留完整子域。这个规范在 MCP 与 REST 两条通道中完全一致——REST 的单文档取回路径GET /v1/documents/{URI_WITHOUT_SCHEME}和批量取回POST /v1/documents:batchGet的names参数都复用同一格式因此一次学会即可两处使用。五、MCP 工具缺失时的 REST API 回退当运行环境中不存在三个 MCP 工具时SKILL.md 与 api-fallback.md 要求改用curl请求https://developerknowledge.googleapis.com/v1并明确禁止猜测命令或依赖未经验证的预训练记忆。服务输出格式为 JSON含 Markdown 内容块API 版本为v1GA与v1alpha。认证协议按优先级顺序方式一现有 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?\}注意X-Goog-User-Project头用于指定配额项目quota project。认证错误的正确解读若上述请求返回 401、403 或其他凭据错误说明该账户的令牌未被 API 接受——此时应将命令中的gcloud auth print-access-token替换为gcloud auth application-default print-access-token后重试。API 接受哪种凭据取决于环境的认证方式因此认证错误应视为换一种凭据再试的信号而不是检索失败。方式二API Key。若环境中配置了DEVELOPERKNOWLEDGE_API_KEY以key查询参数或X-Goog-Api-Key头传递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?}四个 REST 端点与 MCP 工具的对应关系REST 端点方法对应 MCP 工具说明/v1:answerQueryPOSTanswer_query请求体{query: ...}概念问答/v1/documents:searchDocumentChunksGETsearch_documents查询参数queryURL 编码、可选filter如data_source docs.cloud.google.com、可选pageSize默认 10/v1/documents/{URI_WITHOUT_SCHEME}GETget_documents单个路径中为去协议头的资源名/v1/documents:batchGetPOSTget_documents批量请求体{names: [documents/...]}一次往返取多篇搜索与取全文的典型调用# 搜索文档块2–5 个聚焦关键词空格以 编码 curl -s https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?querygcloudloggingmetricscreatekey${DEVELOPERKNOWLEDGE_API_KEY} # 获取单篇文档全文 curl -s https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key${DEVELOPERKNOWLEDGE_API_KEY} # 批量获取多篇文档 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]}六、检索结果的判读成功与失败的判定原则SKILL.md 工作流 的第二条规则定义了检索成功的严格判据这是保证答案可信度的关键收到响应不等于检索成功。以下任一情况都算作失败的检索即使工具本身报告无错误返回PERMISSION_DENIED、UNAUTHENTICATEDHTTP 401 或 403空结果集任何错误负载error payload。正确的失败处理流程是不要假装检索成功尝试用另一条传输通道MCP 或 REST再试一次若仍失败向用户明确说明无法访问 Developer Knowledge本次回答未基于该检索。文档特别强调把凭记忆复述的文档包装成检索结果是最糟糕的可用结果因为回复中没有任何东西能把它和真实检索区分开。成功检索后的输出要求Synthesis Guidelines以官方文档为唯一依据——官方文档约定优先于记忆中的默认值检索到的文档被视为 100% 权威api-fallback.md 的 Response Processing 一节同样要求如此精确格式——CLI 标志、复合键如locationIP:PATH、IAM 权限字符串须按 Google 官方规范书写完整输出——在最终回复中直接给出自包含、可执行的完整方案含PROJECT_ID、REGION等标准占位符不要转储原始 API 响应外壳。七、可检索语料的范围MCP 服务器与 REST API 检索的是官方公开页面语料。按 supported-domains.md 的完整清单Google Cloud 与基础设施docs.cloud.google.com、cloud.google.com、docs.apigee.com、firebase.google.comAI 与机器学习ai.google.dev、adk.devAgent Development Kit、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。该文件还带有LINT.IfChange标记注明语料域变更需同步到官方 corpus reference 文档——可以推断这份清单由自动化一致性检查维护域列表的变更是受控的。检索时可通过searchDocumentChunks的filter参数按域收窄例如data_source docs.cloud.google.com。八、实战调用链总结结合仓库文档一次典型的从问题到可执行方案的 Agent 工作流为判断问题类型概念性/多步骤 → 走answer_queryREST 对应/v1:answerQuery精确语法/标志/权限 → 走search_documentsREST 对应/v1/documents:searchDocumentChunks关键词 2–5 个search_documents返回的条目取content中的关键片段并读取parentURI需要整页上下文时将parentURI 去掉协议头、加documents/前缀调用get_documentsREST 对应单文档 GET 或batchGet按第六节的判据确认检索确实成功以检索到的文档为唯一依据输出带完整占位符的可执行方案。MCP 工具与 REST 端点在参数语义上完全对齐因此无论运行环境最终暴露的是哪条通道同一套关键词策略 资源名转换 成功判据都可以直接复用。仓库内延伸阅读MCP 工具与 API 细节本文主体文档技能主文件工作流与工具选型REST API 回退指南认证协议与四个端点支持域清单插件 MCP 接入配置【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Google Developer Knowledge MCP 集成实战：三个检索工具、资源名规范与 REST 回退方案
Google Developer Knowledge MCP 集成实战三个检索工具、资源名规范与 REST 回退方案【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文基于仓库中 retrieving-developer-knowledge 技能的 MCP 工具文档系统讲解 Google Developer Knowledge 远程 MCP 服务器的接入配置、search_documents/answer_query/get_documents三个工具的参数与返回结构、documents/{uri_without_scheme}资源名转换规则并结合仓库内配套文档与插件配置补充 MCP 不可用时的 REST API 回退路径。读完后你可以让 Agent 通过 MCP 或curl稳定检索 Google Cloud、AI、Android、Flutter 等官方文档语料并正确区分检索成功与检索失败。一、Developer Knowledge 技能与 MCP 集成定位retrieving-developer-knowledge是仓库中面向开发者文档检索的技能其 SKILL.md 的元数据声明了它的职责边界能力范围跨 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台搜索、检索并综合synthesize官方开发者文档适用场景查找 gcloud CLI 命令、API 语法、IAM 权限、官方文档、架构对比、产品选型总览不适用场景本地文件系统查找、非 Google 文档。该技能有两条传输通道transport首选是Developer Knowledge 远程 MCP 服务器端点https://developerknowledge.googleapis.com/mcp次选是REST API 回退基址https://developerknowledge.googleapis.com/v1。MCP 工具文档 描述的正是首选通道中可用的三个工具是本文的主体。SKILL.md 中有一条值得牢记的经验性警告原文强调A declared server is not always a connected server.即声明了服务器不等于连接成功。部分客户端无法与该服务器完成 MCP 握手即使插件声明了该服务器环境中也可能完全没有answer_query、search_documents、get_documents三个工具。正确的处理方式是把工具缺失视为正常现象切换到 REST 回退而不是反复重试或臆测答案。二、MCP 服务器的接入配置仓库中的 google-cloud-developer 插件 声明了对该 MCP 服务器的接入。三处配置各自面向不同的宿主环境mcp.json 采用标准mcpServers结构声明了服务器类型与端点{ mcpServers: { developer-knowledge: { type: streamable-http, url: https://developerknowledge.googleapis.com/mcp } } }mcp_config.json 提供精简形式的serverUrl字段gemini-extension.json 则面向 Gemini 扩展场景额外声明了认证方式{ mcpServers: { developer-knowledge: { httpUrl: https://developerknowledge.googleapis.com/mcp, authProviderType: google_credentials } } }从源码结构看authProviderType: google_credentials表明该 MCP 端点走 Google 凭据认证这与下文 REST 回退中gcloud OAuth 令牌 / API Key两套凭据体系是一脉相承的。适用前提客户端需支持streamable-http类型的远程 MCP 服务器。若宿主环境如某些 IDE Agent不支持该握手三个工具将不会出现在工具列表中此时应直接使用第四节的 REST 回退。三、三个 MCP 工具详解以下三个工具的定义来自 MCP 工具文档选型策略来自 SKILL.md 的 Tool Selection 章节。1.search_documents面向精确语法与 CLI 标志输入一个搜索查询字符串输出包含匹配语法、代码块或标志flags的相关文档文本块text chunks返回项结构每个返回条目包含一个content字段文本块内容和一个parentURI 字段文本块所属的父级文档地址。使用要点来自 SKILL.md它适合查找细粒度的 CLI 标志、精确语法、参数名称、IAM 权限service.resource.verb格式。查询应使用2–5 个聚焦关键词例如cloud run filestore nfs mount gcloud而不是完整的对话式句子。返回结果中的parentURI 正是下一个工具get_documents的输入来源两个工具由此形成先检索、后取全文的调用链。2.answer_query面向概念性问答服务端 RAG输入一个自然语言问题处理服务器端执行 RAG检索增强生成输出综合synthesized后的回答并附带来源引用source citations。使用要点它适合概念指南、架构对比、产品选型总览、多步骤工作流这类需要跨文档综合的问题。对于单一事实某个标志怎么写、某个权限叫什么直接用search_documents更精确。3.get_documents按资源名取全文功能获取完整文档内容参数names数组元素格式为documents/{uri_without_scheme}——即去掉协议头后的文档 URI示例对于父级 URIhttps://cloud.google.com/run/docs/deploying应传入{ names: [documents/cloud.google.com/run/docs/deploying] }工具选型速查需求类型首选工具典型输入形态CLI 标志、精确语法、参数名、IAM 权限search_documents2–5 个聚焦关键词如gcloud logging metrics create概念指南、架构对比、选型总览、多步工作流answer_query自然语言问题已知文档地址、需要整页全文get_documentsdocuments/{去协议头的URI}数组四、资源名转换规范documents/{uri_without_scheme}get_documents是整个 MCP 工具链中最容易出错的环节因为文档 URI 与资源名之间存在一条机械转换规则取search_documents返回条目中的parentURI例如https://cloud.google.com/run/docs/deploying去掉协议头https://得到cloud.google.com/run/docs/deploying前缀documents/得到资源名documents/cloud.google.com/run/docs/deploying以数组形式放入names参数。仓库中配套文档 REST API 回退指南 对同一规范给出了另一个实例文档页https://docs.cloud.google.com/run/docs/overview/what-is-cloud-run对应资源名documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run注意其域名前缀是docs.cloud.google.com保留完整子域。这个规范在 MCP 与 REST 两条通道中完全一致——REST 的单文档取回路径GET /v1/documents/{URI_WITHOUT_SCHEME}和批量取回POST /v1/documents:batchGet的names参数都复用同一格式因此一次学会即可两处使用。五、MCP 工具缺失时的 REST API 回退当运行环境中不存在三个 MCP 工具时SKILL.md 与 api-fallback.md 要求改用curl请求https://developerknowledge.googleapis.com/v1并明确禁止猜测命令或依赖未经验证的预训练记忆。服务输出格式为 JSON含 Markdown 内容块API 版本为v1GA与v1alpha。认证协议按优先级顺序方式一现有 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?\}注意X-Goog-User-Project头用于指定配额项目quota project。认证错误的正确解读若上述请求返回 401、403 或其他凭据错误说明该账户的令牌未被 API 接受——此时应将命令中的gcloud auth print-access-token替换为gcloud auth application-default print-access-token后重试。API 接受哪种凭据取决于环境的认证方式因此认证错误应视为换一种凭据再试的信号而不是检索失败。方式二API Key。若环境中配置了DEVELOPERKNOWLEDGE_API_KEY以key查询参数或X-Goog-Api-Key头传递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?}四个 REST 端点与 MCP 工具的对应关系REST 端点方法对应 MCP 工具说明/v1:answerQueryPOSTanswer_query请求体{query: ...}概念问答/v1/documents:searchDocumentChunksGETsearch_documents查询参数queryURL 编码、可选filter如data_source docs.cloud.google.com、可选pageSize默认 10/v1/documents/{URI_WITHOUT_SCHEME}GETget_documents单个路径中为去协议头的资源名/v1/documents:batchGetPOSTget_documents批量请求体{names: [documents/...]}一次往返取多篇搜索与取全文的典型调用# 搜索文档块2–5 个聚焦关键词空格以 编码 curl -s https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?querygcloudloggingmetricscreatekey${DEVELOPERKNOWLEDGE_API_KEY} # 获取单篇文档全文 curl -s https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key${DEVELOPERKNOWLEDGE_API_KEY} # 批量获取多篇文档 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]}六、检索结果的判读成功与失败的判定原则SKILL.md 工作流 的第二条规则定义了检索成功的严格判据这是保证答案可信度的关键收到响应不等于检索成功。以下任一情况都算作失败的检索即使工具本身报告无错误返回PERMISSION_DENIED、UNAUTHENTICATEDHTTP 401 或 403空结果集任何错误负载error payload。正确的失败处理流程是不要假装检索成功尝试用另一条传输通道MCP 或 REST再试一次若仍失败向用户明确说明无法访问 Developer Knowledge本次回答未基于该检索。文档特别强调把凭记忆复述的文档包装成检索结果是最糟糕的可用结果因为回复中没有任何东西能把它和真实检索区分开。成功检索后的输出要求Synthesis Guidelines以官方文档为唯一依据——官方文档约定优先于记忆中的默认值检索到的文档被视为 100% 权威api-fallback.md 的 Response Processing 一节同样要求如此精确格式——CLI 标志、复合键如locationIP:PATH、IAM 权限字符串须按 Google 官方规范书写完整输出——在最终回复中直接给出自包含、可执行的完整方案含PROJECT_ID、REGION等标准占位符不要转储原始 API 响应外壳。七、可检索语料的范围MCP 服务器与 REST API 检索的是官方公开页面语料。按 supported-domains.md 的完整清单Google Cloud 与基础设施docs.cloud.google.com、cloud.google.com、docs.apigee.com、firebase.google.comAI 与机器学习ai.google.dev、adk.devAgent Development Kit、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。该文件还带有LINT.IfChange标记注明语料域变更需同步到官方 corpus reference 文档——可以推断这份清单由自动化一致性检查维护域列表的变更是受控的。检索时可通过searchDocumentChunks的filter参数按域收窄例如data_source docs.cloud.google.com。八、实战调用链总结结合仓库文档一次典型的从问题到可执行方案的 Agent 工作流为判断问题类型概念性/多步骤 → 走answer_queryREST 对应/v1:answerQuery精确语法/标志/权限 → 走search_documentsREST 对应/v1/documents:searchDocumentChunks关键词 2–5 个search_documents返回的条目取content中的关键片段并读取parentURI需要整页上下文时将parentURI 去掉协议头、加documents/前缀调用get_documentsREST 对应单文档 GET 或batchGet按第六节的判据确认检索确实成功以检索到的文档为唯一依据输出带完整占位符的可执行方案。MCP 工具与 REST 端点在参数语义上完全对齐因此无论运行环境最终暴露的是哪条通道同一套关键词策略 资源名转换 成功判据都可以直接复用。仓库内延伸阅读MCP 工具与 API 细节本文主体文档技能主文件工作流与工具选型REST API 回退指南认证协议与四个端点支持域清单插件 MCP 接入配置【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考