# 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:

   ```bash
   npm install
   ```

2. Copy the sample environment file:

   ```bash
   cp .env.example .env
   ```

3. 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:

```bash
npm start
```

Equivalent direct command:

```bash
node server.js
```

Example Codex MCP launch configuration:

```json
{
  "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": "service-account@your-project.iam.gserviceaccount.com",
        "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:

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

Example `get_document` input:

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

Example `batch_get_documents` input:

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

## Smoke Tests

Syntax check the bridge:

```bash
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.