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_documents`	2–5 个聚焦关键词，如`gcloud logging metrics create`
概念指南、架构对比、选型总览、多步工作流	`answer_query`	自然语言问题
已知文档地址、需要整页全文	`get_documents`	`documents/{去协议头的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 版本为v1（GA）与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:answerQuery`	POST	`answer_query`	请求体`{"query": "..."}`，概念问答
`/v1/documents:searchDocumentChunks`	GET	`search_documents`	查询参数`query`（URL 编码）、可选`filter`（如`data_source = "docs.cloud.google.com"`）、可选`pageSize`（默认 10）
`/v1/documents/{URI_WITHOUT_SCHEME}`	GET	`get_documents`（单个）	路径中为去协议头的资源名
`/v1/documents:batchGet`	POST	`get_documents`（批量）	请求体`{"names": ["documents/..."]}`，一次往返取多篇

搜索与取全文的典型调用：

# 搜索文档块（2–5 个聚焦关键词，空格以 + 编码） curl -s "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=gcloud+logging+metrics+create&key=${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、UNAUTHENTICATED；
HTTP 401 或 403；
空结果集；
任何错误负载（error payload）。

正确的失败处理流程是：不要假装检索成功；尝试用另一条传输通道（MCP 或 REST）再试一次；若仍失败，向用户明确说明"无法访问 Developer Knowledge，本次回答未基于该检索"。文档特别强调：把凭记忆复述的文档包装成检索结果是"最糟糕的可用结果"，因为回复中没有任何东西能把它和真实检索区分开。

成功检索后的输出要求（Synthesis Guidelines）：

以官方文档为唯一依据——官方文档约定优先于记忆中的默认值，检索到的文档被视为 100% 权威（api-fallback.md 的 Response Processing 一节同样要求如此）；
精确格式——CLI 标志、复合键（如location=IP: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.com；
AI 与机器学习：ai.google.dev、adk.dev（Agent 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_query（REST 对应/v1:answerQuery）；精确语法/标志/权限 → 走search_documents（REST 对应/v1/documents:searchDocumentChunks，关键词 2–5 个）；
search_documents返回的条目取content中的关键片段，并读取parentURI；
需要整页上下文时，将parentURI 去掉协议头、加documents/前缀，调用get_documents（REST 对应单文档 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 回退方案