woolsocks-bigquery-mcp 2.0.0

package/README.md

@@ -0,0 +1,86 @@
+# BigQuery MCP Server
+
+MCP server for BigQuery schema exploration and query execution via the woolsocks-ai-proxy.
+
+## Architecture
+
+```
+Claude Code → BigQuery MCP (local) → woolsocks-ai-proxy (Cloud Run) → BigQuery
+```
+
+### Why Local MCP + Cloud Proxy?
+
+This setup deliberately splits responsibilities:
+
+| Component | Location | Responsibility |
+|-----------|----------|----------------|
+| **BigQuery MCP** | Local (your Mac) | Caching, retry logic, MCP protocol |
+| **woolsocks-ai-proxy** | Cloud Run | Cost limits, auth, audit logging, BigQuery access |
+
+**Why not put everything in the proxy (like Zendesk)?**
+
+BigQuery is different from Zendesk/Sentry because:
+
+1. **Interactive exploration** - You browse datasets → tables → schemas → write query. Local caching makes this fluid without network latency.
+2. **Schema stability** - Table schemas rarely change, so 15-min cache is very effective.
+3. **Cost sensitivity** - Every BigQuery metadata call costs money. Local caching reduces API calls significantly.
+4. **MCP tool semantics** - Structured tools (`list-datasets`, `get-schema`) that Claude can chain intelligently.
+
+For comparison, Zendesk uses a skill → proxy pattern because ticket data changes constantly (no caching benefit) and queries are more "fetch and analyze" rather than iterative exploration.
+
+## Tools (7)
+
+| Tool | Description |
+|------|-------------|
+| `bigquery__list-datasets` | List all accessible datasets (cached 5 min) |
+| `bigquery__list-tables` | List tables in dataset with sizes (cached 5 min) |
+| `bigquery__get-table-schema` | Get columns, types, partitioning (cached 15 min) |
+| `bigquery__preview-table` | Sample up to 100 rows (NOT cached) |
+| `bigquery__execute-query` | Run validated SQL query (max 10K rows) |
+| `bigquery__validate-query` | Dry-run cost estimation |
+| `bigquery__get-status` | Check usage limits |
+
+## Authentication
+
+API key is loaded from **Google Secret Manager** at startup:
+- Secret: `ai-proxy-api-keys` in project `woolsocks-marketing-ai`
+- Uses Application Default Credentials (your `gcloud auth`)
+- Fallback: `BIGQUERY_API_KEY` env var for local dev
+
+## Cost Limits (enforced by proxy)
+
+| Limit | Value |
+|-------|-------|
+| Per query | 10 GB |
+| Daily | 50 GB |
+| Monthly | €20 |
+
+## Development
+
+```bash
+# Test locally
+npm run inspect  # Opens MCP Inspector
+
+# Check syntax
+node --check index.js
+```
+
+## Files
+
+```
+bigquery-mcp/
+├── index.js           # MCP server entry point
+├── config.js          # Proxy URL, timeouts, cache TTLs
+├── secrets.js         # Secret Manager integration
+├── proxy-client.js    # HTTP client with retry/circuit breaker
+├── cache.js           # In-memory schema cache
+└── tools/
+    ├── schema/        # 4 schema discovery tools
+    └── query/         # 3 query execution tools
+```
+
+## Related
+
+- Proxy: `~/projects/woolsocks-ai-proxy` (schema endpoints in `src/bigquery-schema.js`)
+- Config: `~/.mcp.json` (bigquery server entry)
+- Documentation: `~/.claude/context/claude-code-setup.md`

package/cache.js

@@ -0,0 +1,119 @@
+// Simple in-memory cache with TTL
+
+import { CACHE_TTLS } from './config.js';
+
+class CacheEntry {
+  constructor(value, ttlMs) {
+    this.value = value;
+    this.expiresAt = Date.now() + ttlMs;
+  }
+
+  isExpired() {
+    return Date.now() > this.expiresAt;
+  }
+}
+
+class SchemaCache {
+  constructor() {
+    this.cache = new Map();
+  }
+
+  /**
+   * Get a cached value by key
+   * @returns {any|null} The cached value or null if not found/expired
+   */
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return null;
+
+    if (entry.isExpired()) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.value;
+  }
+
+  /**
+   * Set a value in cache with TTL
+   */
+  set(key, value, ttlMs) {
+    this.cache.set(key, new CacheEntry(value, ttlMs));
+  }
+
+  /**
+   * Invalidate entries matching a pattern
+   * @param {string} pattern - Prefix to match (e.g., 'tables:' invalidates all table entries)
+   */
+  invalidate(pattern) {
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(pattern)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear the entire cache
+   */
+  clear() {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache stats
+   */
+  getStats() {
+    let validEntries = 0;
+    let expiredEntries = 0;
+
+    for (const entry of this.cache.values()) {
+      if (entry.isExpired()) {
+        expiredEntries++;
+      } else {
+        validEntries++;
+      }
+    }
+
+    return {
+      totalEntries: this.cache.size,
+      validEntries,
+      expiredEntries,
+    };
+  }
+}
+
+// Singleton instance
+export const schemaCache = new SchemaCache();
+
+// Helper functions for specific cache types
+export function getCachedDatasets() {
+  return schemaCache.get('datasets');
+}
+
+export function setCachedDatasets(datasets) {
+  schemaCache.set('datasets', datasets, CACHE_TTLS.datasets);
+}
+
+export function getCachedTables(datasetId) {
+  return schemaCache.get(`tables:${datasetId}`);
+}
+
+export function setCachedTables(datasetId, tables) {
+  schemaCache.set(`tables:${datasetId}`, tables, CACHE_TTLS.tables);
+}
+
+export function getCachedSchema(datasetId, tableId) {
+  return schemaCache.get(`schema:${datasetId}.${tableId}`);
+}
+
+export function setCachedSchema(datasetId, tableId, schema) {
+  schemaCache.set(`schema:${datasetId}.${tableId}`, schema, CACHE_TTLS.schema);
+}
+
+export function invalidateDatasetCache(datasetId) {
+  schemaCache.invalidate(`tables:${datasetId}`);
+  schemaCache.invalidate(`schema:${datasetId}.`);
+}
+
+export default schemaCache;

package/config.js

@@ -0,0 +1,43 @@
+// BigQuery MCP Configuration
+
+import { getAuthTokens } from './secrets.js';
+
+// Proxy URL - Cloud Run deployment
+export const PROXY_URL = process.env.BIGQUERY_PROXY_URL ||
+  'https://woolsocks-ai-proxy-1009713156898.europe-west1.run.app';
+
+// Auth tokens for the current gcloud user (cached 45 min)
+// Use getAuthTokens() to retrieve { identityToken, accessToken }
+export { getAuthTokens };
+
+// Request configuration
+export const REQUEST_TIMEOUT_MS = 30000;  // 30 seconds
+export const RATE_LIMIT_MS = 200;         // Min time between requests
+
+// Retry configuration
+export const RETRY_CONFIG = {
+  maxAttempts: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 10000,
+  retryableStatuses: [408, 429, 500, 502, 503, 504]
+};
+
+// Circuit breaker configuration
+export const CIRCUIT_BREAKER_CONFIG = {
+  failureThreshold: 5,      // Open after 5 consecutive failures
+  cooldownMs: 30000,        // 30s before trying again
+};
+
+// Cache TTLs (in milliseconds)
+export const CACHE_TTLS = {
+  datasets: 5 * 60 * 1000,      // 5 min
+  tables: 5 * 60 * 1000,        // 5 min
+  schema: 15 * 60 * 1000,       // 15 min
+};
+
+// Result limits
+// Kept low intentionally — colleagues new to BigQuery should use LIMIT in their SQL
+// rather than relying on the MCP to truncate. This also keeps response sizes manageable.
+export const MAX_PREVIEW_ROWS = 50;
+export const MAX_QUERY_ROWS = 1000;
+export const DEFAULT_PREVIEW_ROWS = 5;

package/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+
+// BigQuery MCP Server
+// Provides BigQuery access via woolsocks-ai-proxy for Claude Code
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { TOOLS, TOOL_MAP } from './tools/index.js';
+import { getClient } from './proxy-client.js';
+
+// Server info
+const SERVER_INFO = {
+  name: 'bigquery-mcp',
+  version: '1.0.0',
+  description: 'MCP server for BigQuery - schema exploration and query execution via woolsocks-ai-proxy'
+};
+
+// Create server instance
+const server = new Server(SERVER_INFO, {
+  capabilities: {
+    tools: {}
+  }
+});
+
+// Handle tool listing
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: TOOLS.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema
+    }))
+  };
+});
+
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  const tool = TOOL_MAP.get(name);
+
+  if (!tool) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: `Unknown tool: ${name}`,
+          availableTools: TOOLS.map(t => t.name)
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+
+  try {
+    return await tool.handler(args || {});
+  } catch (error) {
+    // Handle proxy API errors
+    if (error.status !== undefined) {
+      let message = error.message;
+      let hint = null;
+
+      // Provide helpful hints for common errors
+      switch (error.status) {
+        case 401:
+          message = 'Authentication failed.';
+          hint = 'Check that BIGQUERY_API_KEY is set correctly in ~/.zshrc';
+          break;
+        case 402:
+          hint = 'Query was blocked by cost controls. Try a smaller query or add date filters.';
+          break;
+        case 403:
+          hint = 'Access denied. Only EU-region tables are accessible.';
+          break;
+        case 404:
+          message = 'Resource not found.';
+          hint = 'Check dataset/table names are correct.';
+          break;
+        case 408:
+          message = 'Request timeout.';
+          hint = 'The query may be too complex. Try simplifying or adding LIMIT.';
+          break;
+        case 429:
+          message = 'Rate limited.';
+          hint = 'Please wait a moment and try again.';
+          break;
+        case 503:
+          hint = 'Proxy may be unavailable. Circuit breaker is active.';
+          break;
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: message,
+            hint,
+            status: error.status,
+            endpoint: error.endpoint
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    // Handle other errors
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: error.message,
+          hint: 'Check that BIGQUERY_API_KEY is set in ~/.zshrc and the proxy is accessible.'
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+});
+
+// Start server
+async function main() {
+  // Verify API key is set before starting
+  try {
+    getClient();
+  } catch (error) {
+    console.error(`[BigQuery MCP] Startup error: ${error.message}`);
+    console.error('[BigQuery MCP] Ensure BIGQUERY_API_KEY is exported in ~/.zshrc');
+    process.exit(1);
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Log to stderr (stdout is reserved for MCP protocol)
+  console.error(`[BigQuery MCP] Server started (${TOOLS.length} tools available)`);
+}
+
+main().catch((error) => {
+  console.error('[BigQuery MCP] Failed to start:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "woolsocks-bigquery-mcp",
+  "version": "2.0.0",
+  "description": "Query Woolsocks BigQuery data with built-in cost guardrails and a complete data catalog covering all datasets, tables, and conventions.",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "woolsocks-bigquery-mcp": "index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.1.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.10.2"
+  },
+  "author": {
+    "name": "Woolsocks Product Team"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "bigquery",
+    "woolsocks",
+    "data-analysis"
+  ]
+}