Google Cloud MCP Server

Implementation Reference

• src/services/spanner/tools.ts:52-127 (handler)

  The core handler for the 'execute-spanner-query' tool. Defines the input schema using Zod, retrieves Spanner configuration and client, executes the SQL query with optional parameters, formats the results as a markdown table (limited to 100 rows), and returns the response. Handles errors by throwing them.
  server.tool( 'execute-spanner-query', { sql: z.string().describe('The SQL query to execute'), instanceId: z.string().optional().describe('Spanner instance ID (defaults to SPANNER_INSTANCE env var)'), databaseId: z.string().optional().describe('Spanner database ID (defaults to SPANNER_DATABASE env var)'), params: z.record(z.any()).optional().describe('Query parameters') }, async ({ sql, instanceId, databaseId, params }, _extra) => { try { const projectId = await getProjectId(); const config = await getSpannerConfig( Array.isArray(instanceId) ? instanceId[0] : instanceId, Array.isArray(databaseId) ? databaseId[0] : databaseId ); const spanner = await getSpannerClient(); console.log(`Using Spanner client with project ID: ${spanner.projectId} for execute-spanner-query`); const instance = spanner.instance(config.instanceId); const database = instance.database(config.databaseId); // Execute the query const [result] = await database.run({ sql, params: params || {} }); if (!result || result.length === 0) { return { content: [{ type: 'text', text: `# Query Results\n\nProject: ${projectId}\nInstance: ${config.instanceId}\nDatabase: ${config.databaseId}\n\nQuery executed successfully. No results returned.` }] }; } // Convert to markdown table const columns = Object.keys(result[0]); let markdown = `# Query Results\n\nProject: ${projectId}\nInstance: ${config.instanceId}\nDatabase: ${config.databaseId}\n\n`; markdown += `SQL: \`${sql}\`\n\n`; markdown += `Rows: ${result.length}\n\n`; // Table header markdown += '| ' + columns.join(' | ') + ' |\n'; markdown += '| ' + columns.map(() => '---').join(' | ') + ' |\n'; // Table rows (limit to 100 rows for display) const displayRows = result.slice(0, 100); for (const row of displayRows) { const rowValues = columns.map(col => { const value = (row as any)[col]; if (value === null || value === undefined) return 'NULL'; if (typeof value === 'object') return JSON.stringify(value); return String(value); }); markdown += '| ' + rowValues.join(' | ') + ' |\n'; } if (result.length > 100) { markdown += '\n*Results truncated. Showing 100 of ' + result.length + ' rows.*'; } return { content: [{ type: 'text', text: markdown }] }; } catch (error: any) { console.error('Error executing Spanner query:', error); throw error; } } );
• src/services/spanner/tools.ts:54-59 (schema)

  Input schema validation for the 'execute-spanner-query' tool using Zod. Defines required SQL query and optional instanceId, databaseId, and params.
  { sql: z.string().describe('The SQL query to execute'), instanceId: z.string().optional().describe('Spanner instance ID (defaults to SPANNER_INSTANCE env var)'), databaseId: z.string().optional().describe('Spanner database ID (defaults to SPANNER_DATABASE env var)'), params: z.record(z.any()).optional().describe('Query parameters') },
• src/index.ts:140-140 (registration)

  Top-level registration call that invokes registerSpannerTools(server), which in turn registers the 'execute-spanner-query' tool on the MCP server.
  registerSpannerTools(server);
• src/services/spanner/types.ts:43-69 (helper)

  Helper function to initialize and return a configured Google Cloud Spanner client, used by the tool handler.
  export async function getSpannerClient(): Promise<Spanner> { // Import the state manager here to avoid circular dependencies const { stateManager } = await import('../../utils/state-manager.js'); // Get the project ID from state manager let projectId = stateManager.getCurrentProjectId(); // If not available in state manager, try to get it from auth if (!projectId) { const { getProjectId } = await import('../../utils/auth.js'); projectId = await getProjectId(); } if (!projectId) { throw new GcpMcpError( 'Unable to detect a Project ID in the current environment.\nTo learn more about authentication and Google APIs, visit:\nhttps://cloud.google.com/docs/authentication/getting-started', 'UNAUTHENTICATED', 401 ); } console.log(`Initializing Spanner client with project ID: ${projectId}`); return new Spanner({ projectId: projectId }); }
• src/services/spanner/types.ts:78-99 (helper)

  Helper function to resolve Spanner instance and database IDs from parameters or environment variables, used by the tool handler.
  export async function getSpannerConfig(instanceId?: string, databaseId?: string): Promise<{ instanceId: string; databaseId: string }> { const instance = instanceId || process.env.SPANNER_INSTANCE; const database = databaseId || process.env.SPANNER_DATABASE; if (!instance) { throw new GcpMcpError( 'Spanner instance ID not provided. Set SPANNER_INSTANCE environment variable or provide instanceId parameter.', 'INVALID_ARGUMENT', 400 ); } if (!database) { throw new GcpMcpError( 'Spanner database ID not provided. Set SPANNER_DATABASE environment variable or provide databaseId parameter.', 'INVALID_ARGUMENT', 400 ); } return { instanceId: instance, databaseId: database }; }