woolsocks-bigquery-mcp 2.0.0

package/tools/schema/get-table-schema.js

@@ -0,0 +1,102 @@
+// Get detailed table schema
+
+import { getClient } from '../../proxy-client.js';
+import { getCachedSchema, setCachedSchema } from '../../cache.js';
+
+export default {
+  name: 'bigquery__get-table-schema',
+  description: 'Get detailed schema for a BigQuery table including all columns, data types, partitioning, and clustering info. Essential before writing queries. Results are cached for 15 minutes.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      dataset_id: {
+        type: 'string',
+        description: 'The dataset ID containing the table'
+      },
+      table_id: {
+        type: 'string',
+        description: 'The table ID to get schema for'
+      }
+    },
+    required: ['dataset_id', 'table_id']
+  },
+
+  async handler(args) {
+    const { dataset_id, table_id } = args;
+
+    if (!dataset_id || !table_id) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: 'Both dataset_id and table_id are required',
+            hint: 'Use bigquery__list-tables to see available tables'
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    // Check cache first
+    const cached = getCachedSchema(dataset_id, table_id);
+    if (cached) {
+      return formatSchemaResponse(cached, true);
+    }
+
+    const client = await getClient();
+    const schema = await client.getTableSchema(dataset_id, table_id);
+
+    // Cache the result
+    setCachedSchema(dataset_id, table_id, schema);
+
+    return formatSchemaResponse(schema, false);
+  }
+};
+
+function formatSchemaResponse(schema, cached) {
+  // Format schema fields for readability
+  const formatFields = (fields, indent = 0) => {
+    return fields.map(f => {
+      const prefix = '  '.repeat(indent);
+      let line = `${prefix}${f.name}: ${f.type}`;
+      if (f.mode === 'REQUIRED') line += ' (required)';
+      if (f.mode === 'REPEATED') line += ' (array)';
+      if (f.description) line += ` -- ${f.description}`;
+
+      if (f.fields) {
+        line += '\n' + formatFields(f.fields, indent + 1);
+      }
+      return line;
+    }).join('\n');
+  };
+
+  const schemaText = formatFields(schema.schema);
+
+  // Build query hints
+  let queryHint = 'Use bigquery__validate-query to check query cost before running.';
+  if (schema.partitioning) {
+    const partField = schema.partitioning.field || '_PARTITIONTIME';
+    queryHint = `This table is partitioned on ${partField}. ALWAYS include a date filter like WHERE ${partField} >= 'YYYY-MM-DD' to avoid expensive full scans.`;
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        table: `${schema.datasetId}.${schema.id}`,
+        type: schema.type,
+        location: schema.location,
+        numRows: schema.numRows,
+        sizeGB: schema.sizeGB,
+        lastModified: schema.lastModified,
+        partitioning: schema.partitioning,
+        clustering: schema.clustering,
+        description: schema.description,
+        schemaFormatted: schemaText,
+        schema: schema.schema,
+        cached,
+        queryHint
+      }, null, 2)
+    }]
+  };
+}

package/tools/schema/index.js

@@ -0,0 +1,13 @@
+// Schema discovery tools
+
+import listDatasets from './list-datasets.js';
+import listTables from './list-tables.js';
+import getTableSchema from './get-table-schema.js';
+import previewTable from './preview-table.js';
+
+export default [
+  listDatasets,
+  listTables,
+  getTableSchema,
+  previewTable
+];

package/tools/schema/list-datasets.js

@@ -0,0 +1,69 @@
+// List all BigQuery datasets
+
+import { getClient } from '../../proxy-client.js';
+import { getCachedDatasets, setCachedDatasets } from '../../cache.js';
+
+export default {
+  name: 'bigquery__list-datasets',
+  description: 'List all BigQuery datasets accessible to Woolsocks. Returns dataset names, locations, and basic metadata. Use this first to discover available data. Results are cached for 5 minutes.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: []
+  },
+
+  async handler(args) {
+    // Check cache first
+    const cached = getCachedDatasets();
+    if (cached) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            datasets: cached.datasets,
+            count: cached.count,
+            cached: true,
+            hint: 'Use bigquery__list-tables with a dataset_id to see tables in a dataset.'
+          }, null, 2)
+        }]
+      };
+    }
+
+    const client = await getClient();
+    let result;
+    try {
+      result = await client.listDatasets();
+    } catch (err) {
+      const isAuthError = err.status === 401 || err.status === 403 ||
+        err.message?.toLowerCase().includes('permission') ||
+        err.message?.toLowerCase().includes('unauthorized');
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: err.message,
+            hint: isAuthError
+              ? 'You do not have BigQuery access. Ask your infra manager to grant access by creating a ticket in the Jira PERM project: https://woolsocks.atlassian.net/jira/software/projects/PERM/boards — request "BigQuery read access for Claude Code".'
+              : 'Failed to list datasets. Check that the BigQuery proxy is reachable.'
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    // Cache the result
+    setCachedDatasets(result);
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          datasets: result.datasets,
+          count: result.count,
+          cached: false,
+          hint: 'Use bigquery__list-tables with a dataset_id to see tables in a dataset.'
+        }, null, 2)
+      }]
+    };
+  }
+};

package/tools/schema/list-tables.js

@@ -0,0 +1,72 @@
+// List tables in a BigQuery dataset
+
+import { getClient } from '../../proxy-client.js';
+import { getCachedTables, setCachedTables } from '../../cache.js';
+
+export default {
+  name: 'bigquery__list-tables',
+  description: 'List all tables in a BigQuery dataset with size (GB), row count, and type (TABLE/VIEW). Tables are sorted by size descending. Results are cached for 5 minutes.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      dataset_id: {
+        type: 'string',
+        description: 'The dataset ID to list tables from (e.g., "analytics", "raw_data")'
+      }
+    },
+    required: ['dataset_id']
+  },
+
+  async handler(args) {
+    const { dataset_id } = args;
+
+    if (!dataset_id) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: 'dataset_id is required',
+            hint: 'Use bigquery__list-datasets first to see available datasets'
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    // Check cache first
+    const cached = getCachedTables(dataset_id);
+    if (cached) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            datasetId: cached.datasetId,
+            tables: cached.tables,
+            count: cached.count,
+            cached: true,
+            hint: 'Use bigquery__get-table-schema to see column details for a specific table.'
+          }, null, 2)
+        }]
+      };
+    }
+
+    const client = await getClient();
+    const result = await client.listTables(dataset_id);
+
+    // Cache the result
+    setCachedTables(dataset_id, result);
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          datasetId: result.datasetId,
+          tables: result.tables,
+          count: result.count,
+          cached: false,
+          hint: 'Use bigquery__get-table-schema to see column details for a specific table.'
+        }, null, 2)
+      }]
+    };
+  }
+};

package/tools/schema/preview-table.js

@@ -0,0 +1,65 @@
+// Preview sample rows from a table
+
+import { getClient } from '../../proxy-client.js';
+import { DEFAULT_PREVIEW_ROWS, MAX_PREVIEW_ROWS } from '../../config.js';
+
+export default {
+  name: 'bigquery__preview-table',
+  description: `Get sample rows from a BigQuery table to understand data format. Limited to ${MAX_PREVIEW_ROWS} rows max. Only works on EU-region tables. Results are NOT cached.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      dataset_id: {
+        type: 'string',
+        description: 'The dataset ID containing the table'
+      },
+      table_id: {
+        type: 'string',
+        description: 'The table ID to preview'
+      },
+      max_rows: {
+        type: 'number',
+        description: `Number of rows to preview (default: ${DEFAULT_PREVIEW_ROWS}, max: ${MAX_PREVIEW_ROWS})`,
+        minimum: 1,
+        maximum: MAX_PREVIEW_ROWS
+      }
+    },
+    required: ['dataset_id', 'table_id']
+  },
+
+  async handler(args) {
+    const { dataset_id, table_id, max_rows } = args;
+
+    if (!dataset_id || !table_id) {
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            error: 'Both dataset_id and table_id are required',
+            hint: 'Use bigquery__list-tables to see available tables'
+          }, null, 2)
+        }],
+        isError: true
+      };
+    }
+
+    const client = await getClient();
+    const maxRows = Math.min(max_rows || DEFAULT_PREVIEW_ROWS, MAX_PREVIEW_ROWS);
+    const preview = await client.previewTable(dataset_id, table_id, maxRows);
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          table: `${preview.datasetId}.${preview.tableId}`,
+          location: preview.location,
+          rowCount: preview.rowCount,
+          maxRowsRequested: preview.maxRowsRequested,
+          totalRowsInTable: preview.totalRowsInTable,
+          rows: preview.rows,
+          hint: 'This is a sample of actual data. Use bigquery__execute-query for filtered/aggregated queries.'
+        }, null, 2)
+      }]
+    };
+  }
+};