google-dev-knowledge-mcp-bridge

Local stdio MCP bridge for the Google Developer Knowledge MCP endpoint. It forwards upstream tool calls and adds a higher-signal search_documents mode that:

• caches semantically equivalent search requests
• expands top search hits with batch_get_documents
• extracts concise markdown sections for easier downstream citation and synthesis

The bridge does not embed credentials in tracked code. Authentication is resolved from Application Default Credentials plus service account impersonation configured through environment variables.

Requirements

• Node.js 18+
• gcloud installed and authenticated with gcloud auth application-default login
• Permission to impersonate the target service account

Installation

1. Install dependencies:

   npm install

1. Copy the sample environment file:

   cp .env.example .env

1. Fill in only the values required for your environment.

Environment Variables

Required

• GOOGLE_IMPERSONATE_SERVICE_ACCOUNT

Optional

• GOOGLE_QUOTA_PROJECT_ID
• DEBUG_MCP=false
• AUTO_EXPAND_SEARCH=true
• EXPAND_TOP_N=4
• EXPAND_MAX_CHARS=9000
• EXPAND_PER_DOC_MAX_CHARS=2600
• CACHE_TTL_MS=300000
• REQUEST_TIMEOUT_MS=20000
• MAX_RETRIES=2
• BACKOFF_BASE_MS=400

Authentication Flow

The bridge uses this sequence:

1. Loads Application Default Credentials from the local environment.
2. Impersonates the service account named in GOOGLE_IMPERSONATE_SERVICE_ACCOUNT.
3. Calls the Google Developer Knowledge MCP endpoint with an OAuth access token.

If GOOGLE_QUOTA_PROJECT_ID is set, the bridge also sends it as the quota project header.

MCP Server Launch

Run the bridge directly over stdio:

npm start

Equivalent direct command:

node server.js

Example Codex MCP launch configuration:

{
  "mcpServers": {
    "google-dev-knowledge-mcp-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/google-dev-knowledge/server.js"],
      "cwd": "/absolute/path/to/google-dev-knowledge",
      "env": {
        "GOOGLE_IMPERSONATE_SERVICE_ACCOUNT": "[email protected]",
        "GOOGLE_QUOTA_PROJECT_ID": "your-project-id",
        "AUTO_EXPAND_SEARCH": "true",
        "DEBUG_MCP": "false"
      }
    }
  }
}

Repository Layout

• server.js: CLI entrypoint
• src/config.js: environment parsing and validation
• src/google-client.js: ADC + impersonation + HTTP retry logic
• src/content-pack.js: search expansion and excerpt construction helpers
• src/bridge.js: stdio JSON-RPC loop and caching

Upstream MCP Tools

The bridge forwards upstream Google Developer Knowledge MCP tool calls. Common tools include:

• search_documents
• get_document
• batch_get_documents

When AUTO_EXPAND_SEARCH=true, search_documents responses are transformed into a context pack that includes:

• canonical source links
• top ranked search chunks
• extracted document excerpts sized for model context windows

All other tool calls are passed through unchanged.

Sample MCP Tool Calls

Example search_documents input:

{
  "query": "Cloud Storage create bucket required permissions"
}

Example get_document input:

{
  "name": "documents/cloud-storage-create-buckets"
}

Example batch_get_documents input:

{
  "names": [
    "documents/cloud-storage-create-buckets",
    "documents/iam-roles-overview"
  ]
}

Smoke Tests

Syntax check the bridge:

npm run check

Troubleshooting

Missing required environment

• The process exits immediately if GOOGLE_IMPERSONATE_SERVICE_ACCOUNT is unset.

Failed authentication

• Re-run gcloud auth application-default login.
• Confirm the authenticated principal can impersonate the configured service account.
• If you use quota billing, confirm GOOGLE_QUOTA_PROJECT_ID is valid for the caller.

Request failures or timeouts

• Increase REQUEST_TIMEOUT_MS in slower environments.
• Leave MAX_RETRIES above 0 if you want automatic retry on 429 and 5xx responses.

Publishing hygiene

• .env and node_modules/ are ignored by .gitignore.
• Use .env.example as the only tracked environment template.