Google Developer Knowledge API и MCP — первоисточники для AI-агентов

Обычный web search смешивает официальную документацию, старые статьи, форумы и пересказы. Google Developer Knowledge предоставляет отдельный corpus публичной developer-документации и два способа доступа:

• REST/API для программного поиска и получения Markdown-документов;
• remote MCP server для coding/research agents.

Это удобно, когда агент должен сначала проверить первоисточник по Google Cloud, Chrome, Firebase, Android, Maps и другим технологиям, а затем писать код или материал.

Что изменилось в 2026 году

• 16 апреля Developer Knowledge API и MCP server стали GA;
• 17 июля endpoint AnswerQuery стал GA;
• 18 августа появились команды gcloud alpha developer-knowledge;
• 21 августа поле relevance_score появилось в стабильном v1 API;
• 9 сентября команды gcloud beta developer-knowledge стали доступны в beta-компоненте CLI;
• 22 сентября команды gcloud developer-knowledge стали GA: answer-query, documents describe, documents search-chunks.

CLI-раздел обновлён 24 сентября 2026 года по release notes и официальному руководству. Предыдущая проверка beta — 14 сентября; alpha и beta сохранены как этапы развития. Рабочие примеры ниже используют GA. Это не сообщение об отключении старых команд или изменении статуса всех MCP tools; остальные разделы не объявлены заново проверенными.

В REST JSON поле называется relevanceScore и имеет диапазон 0.0–1.0: большее значение означает более высокую релевантность chunk поисковому запросу.

Что находится в corpus

Corpus включает публичные страницы поддерживаемых developer-доменов, среди которых Google Cloud, Firebase, Android, Chrome, web.dev, Maps и другие источники из официального списка.

Важно понимать ограничения:

• результаты пока только на английском;
• GitHub, сторонние OSS-сайты, блоги и YouTube не входят в corpus;
• наличие страницы в интернете не гарантирует её наличие в Developer Knowledge;
• updateTime помогает оценить свежесть записи, но не отменяет проверку исходного URL;
• это специализированный источник, а не замена всему web search.

API, MCP и обычный web search

Способ	Когда использовать	Что возвращает	Контроль
Web search	новости, сторонние кейсы, обсуждения, продукты вне corpus	страницы из разных источников	нужен ручной отбор доверия
SearchDocumentChunks / search_documents	найти релевантные фрагменты официальной документации	chunks, metadata, parent, URL, score	высокий контроль источника
GetDocument / get_documents	прочитать полную страницу после поиска	полный Markdown и metadata	расходует больше context
AnswerQuery / answer_query	получить синтезированный grounded answer	ответ с references/citations	нужно проверить ссылки и цитаты

Для подготовки технической статьи обычно лучше начинать с chunks, затем получать только нужные полные документы.

Подготовка Google Cloud project

Задайте project и включите API:

export PROJECT_ID="your-project-id"

gcloud services enable developerknowledge.googleapis.com \
  --project="$PROJECT_ID"

После 17 марта 2026 года remote MCP server должен включаться вместе с API. Если для проекта это не произошло, официальный guide предлагает отдельную команду:

gcloud beta services mcp enable developerknowledge.googleapis.com \
  --project="$PROJECT_ID"

Для REST или MCP через API key создайте отдельный key, ограничьте его Developer Knowledge API и не сохраняйте значение в Git.

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Поиск chunks через REST

Пример поиска материалов Chrome только в developer.chrome.com:

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Chrome WebMCP executeTool" \
  --data-urlencode 'filter=data_source = "developer.chrome.com"' \
  --data-urlencode "pageSize=10" \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Результат содержит:

• parent — resource name полного документа;
• id — идентификатор chunk;
• content — найденный фрагмент;
• document.title и document.uri;
• document.dataSource и document.updateTime;
• relevanceScore — относительную релевантность запросу.

Как использовать relevanceScore

Score полезен для сортировки и отсечения слабых совпадений, но не является оценкой истинности или качества всей страницы.

Пример локальной эвристики:

curl -sG "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Chrome WebMCP executeTool" \
  --data-urlencode 'filter=data_source = "developer.chrome.com"' \
  --data-urlencode "pageSize=20" \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY" \
| jq '.results[]
    | select(.relevanceScore >= 0.75)
    | {
        score: .relevanceScore,
        title: .document.title,
        uri: .document.uri,
        updated: .document.updateTime,
        parent
      }'

Порог 0.75 — пример для конкретного pipeline, а не правило Google. Его нужно подбирать по своим запросам и не использовать как единственное условие.

Фильтры

SearchDocumentChunks поддерживает строгие фильтры по metadata родительского документа:

• data_source;
• update_time;
• uri;
• content_length_bytes.

Пример нескольких официальных web-источников и ограничения по дате:

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2026-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Фильтр ограничивает corpus, а текстовый query определяет релевантность внутри него.

Получение полного документа

Возьмите parent из результата, например:

documents/developer.chrome.com/docs/ai/webmcp/imperative-api

И передайте его в path:

PARENT="documents/developer.chrome.com/docs/ai/webmcp/imperative-api"

curl "https://developerknowledge.googleapis.com/v1/${PARENT}?key=$DEVELOPERKNOWLEDGE_API_KEY"

Полный content приходит в Markdown. Для экономии bandwidth/context можно запросить только metadata:

curl "https://developerknowledge.googleapis.com/v1/${PARENT}?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Batch endpoint получает до 20 документов, но не следует без необходимости загружать в LLM все найденные страницы.

Подключение remote MCP

Endpoint:

https://developerknowledge.googleapis.com/mcp

Claude Code

claude mcp add google-dev-knowledge \
  --transport http \
  https://developerknowledge.googleapis.com/mcp \
  --header "X-Goog-Api-Key: YOUR_API_KEY"

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "google-developer-knowledge": {
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Не коммитьте реальный key. Способ подстановки environment variable зависит от конкретного MCP client.

MCP tools

Remote server предоставляет:

• search_documents — ищет chunks и возвращает parent;
• get_documents — получает полное содержимое нескольких документов;
• answer_query — формирует grounded answer; в MCP reference инструмент пока отмечен как Preview.

AnswerQuery API endpoint уже GA, но статус конкретного MCP tool нужно проверять отдельно.

Проверочный prompt:

Найди в Google Developer Knowledge официальную документацию о Chrome WebMCP executeTool.
Сначала используй search_documents, покажи title, URL, update time и relevance score.
Полный документ получи только для двух самых релевантных результатов.
Не используй сторонние источники до завершения этого шага.

gcloud: GA с 22 сентября

С 22 сентября 2026 года три команды Developer Knowledge доступны без префикса beta. Сначала проверьте установленную версию CLI и справку именно GA-команд:

gcloud version
gcloud developer-knowledge answer-query --help
gcloud developer-knowledge documents describe --help
gcloud developer-knowledge documents search-chunks --help

Задача	REST	MCP	gcloud GA
Поиск фрагментов	SearchDocumentChunks	search_documents	documents search-chunks
Полная страница	GetDocument	get_documents	documents describe
Синтез ответа	AnswerQuery	answer_query	answer-query

Это соответствие задач, а не гарантия одинаковой схемы ответа. GA этих CLI-команд не повышает автоматически статус REST API или отдельных MCP tools. Закрепляйте версию CLI и проверяйте JSON-контракт в автоматизации. Переменная DEVELOPERKNOWLEDGE_API_KEY из REST-примеров сама по себе не настраивает аутентификацию gcloud: используйте отдельно настроенную конфигурацию CLI и нужный проект.

Переход beta → GA

Было	Теперь
gcloud beta developer-knowledge answer-query	gcloud developer-knowledge answer-query
gcloud beta developer-knowledge documents describe	gcloud developer-knowledge documents describe
gcloud beta developer-knowledge documents search-chunks	gcloud developer-knowledge documents search-chunks

Меняйте только эту группу команд. Например, gcloud beta services mcp enable из раздела настройки относится к другому компоненту и этим релизом не переводится на новый синтаксис. Если GA-команда не распознана, обновите Cloud SDK способом, соответствующим вашей установке, затем повторите --help; не заменяйте команду молча другой API-версией.

Для CI закрепите протестированную версию SDK и проверьте фактический JSON, ошибки доступа и отсутствие результатов. GA не означает отсутствие квот или гарантированную корректность сгенерированного ответа.

Поиск → документ → необязательный ответ

Для ограничения corpus применяется --query-filter, а не общий флаг CLI --filter, который фильтрует выдаваемые результаты:

gcloud developer-knowledge documents search-chunks \
  --query="How to create a Cloud Storage bucket?" \
  --query-filter='data_source = "docs.cloud.google.com"' \
  --limit=5 --format=json

Скопируйте parent выбранного результата. Ниже приведён resource name из официального примера; для своего запроса используйте фактически полученный parent:

PARENT="documents/docs.cloud.google.com/storage/docs/creating-buckets"
gcloud developer-knowledge documents describe "$PARENT" \
  --view=content --format=json

--view=basic возвращает базовые metadata, content — содержимое с metadata, full — полную запись. Не переносите названия REST enum напрямую в CLI.

При необходимости запросите синтезированный ответ:

gcloud developer-knowledge answer-query \
  --query="How to create a Cloud Storage bucket?" \
  --query-filter='data_source = "docs.cloud.google.com"' \
  --format=json

Последний вызов — отдельный поиск и генерация по corpus, а не ответ исключительно по документу, прочитанному предыдущей командой. Сверяйте возвращённые references/citations с исходными страницами. Синтаксис GA сверён с руководством поиска и получения документов и справкой answer-query. Локально проверен Bash-синтаксис; команды в реальном облачном проекте не выполнялись.

Pipeline для SEO Recipes

Практическая последовательность:

технический вопрос
  ↓
search_documents / SearchDocumentChunks
  ↓
убрать слабые и нерелевантные chunks
  ↓
проверить title, URL, dataSource, updateTime
  ↓
get_documents только для нужных страниц
  ↓
составить черновик со ссылками на первоисточники
  ↓
дополнить web search новостями и сторонними кейсами
  ↓
финально перепроверить утверждения по исходным страницам

Для материалов про Chrome, Google Cloud или Firebase это снижает риск сослаться на старый пересказ вместо текущей документации.

Пример policy для research agent

При вопросах о технологиях Google:

1. Сначала используй Google Developer Knowledge.
2. Предпочитай SearchDocumentChunks/search_documents прямому answer_query, если нужны точные формулировки.
3. Не загружай полные документы без необходимости.
4. Отбрасывай результаты с неподходящим dataSource даже при высоком score.
5. Указывай исходный URL и updateTime.
6. Считай relevanceScore сигналом ранжирования, а не доказательством корректности.
7. После официального corpus используй web search для новостей, GitHub issues и сторонних кейсов.

Ограничения и безопасность

• ограничивайте API key конкретным API;
• не храните key в репозитории или prompt history;
• учитывайте quotas и HTTP 429;
• запрашивайте конкретные темы, иначе полные документы быстро заполняют context window;
• результаты только на английском;
• corpus не содержит все источники;
• updateTime относится к записи документа и не гарантирует, что каждая деталь страницы новая;
• generated answer всё равно проверяется по references;
• для сторонних библиотек нужен отдельный поиск в официальном repo/docs.

Источники

• Developer Knowledge release notes
• Connect to the Developer Knowledge MCP server
• Search and retrieve documents
• Developer Knowledge corpus reference
• MCP tools reference
• Developer Knowledge REST API
• GA CLI: настройка
• gcloud GA: grounded answer
• Историческая beta: поиск chunks
• Историческая beta: получение документа
• Историческая beta: grounded answer