mcp-turso-cloud

Instructions

Implementation Reference

• src/clients/database.ts:120-151 (handler)

  Core implementation that executes the SQL query against the Turso database client, handling read-only detection, permission selection, parameter conversion, and error wrapping.

  export async function execute_query(
  	database_name: string,
  	query: string,
  	params: Record<string, any> = {},
  ): Promise<ResultSet> {
  	try {
  		// Determine if this is a read-only query
  		const is_read_only = query
  			.trim()
  			.toLowerCase()
  			.startsWith('select');
  		const permission = is_read_only ? 'read-only' : 'full-access';
  
  		const client = await get_database_client(
  			database_name,
  			permission,
  		);
  
  		// Execute the query
  		return await client.execute({
  			sql: query,
  			args: convert_parameters(params),
  		});
  	} catch (error) {
  		throw new TursoApiError(
  			`Failed to execute query for database ${database_name}: ${
  				(error as Error).message
  			}`,
  			500,
  		);
  	}
  }

• src/tools/handler.ts:243-281 (registration)

  MCP tool registration for 'execute_query', including input schema reference, safety validation to prevent read-only misuse, database context resolution, delegation to core handler, result formatting, and error handling.

  server.tool(
  	{
  		name: 'execute_query',
  		description: `⚠️ DESTRUCTIVE: Execute SQL that can modify/delete data (INSERT, UPDATE, DELETE, DROP, ALTER). Always confirm with user before destructive operations.`,
  		schema: QuerySchema,
  	},
  	async ({ query, params = {}, database }) => {
  		try {
  			// Validate that this is not a read-only query
  			const normalized_query = query.trim().toLowerCase();
  			if (
  				normalized_query.startsWith('select') ||
  				normalized_query.startsWith('pragma')
  			) {
  				throw new Error(
  					'SELECT and PRAGMA queries should use execute_read_only_query',
  				);
  			}
  
  			const database_name = resolve_database_name(database);
  			if (database) set_current_database(database);
  
  			const result = await database_client.execute_query(
  				database_name,
  				query,
  				params,
  			);
  
  			const formatted_result = format_query_result(result);
  			return create_tool_response({
  				database: database_name,
  				query,
  				result: formatted_result,
  			});
  		} catch (error) {
  			return create_tool_error_response(error);
  		}
  	},
  );

• src/tools/handler.ts:36-40 (schema)

  Zod input schema validation for the execute_query tool parameters.

  const QuerySchema = z.object({
  	query: z.string().describe('SQL query to execute'),
  	params: z.record(z.string(), z.any()).optional().describe('Query parameters (optional) - Use parameterized queries for security'),
  	database: z.string().optional().describe('Database name (optional, uses context if not provided)'),
  });

• src/clients/database.ts:12-36 (helper)

  Utility to convert input parameters to libsql client expected format (named object or positional array).

  function convert_parameters(params: Record<string, any>): any {
  	if (!params || Object.keys(params).length === 0) {
  		return {};
  	}
  
  	// Check if parameters are positional (numbered keys like "1", "2", etc.)
  	const keys = Object.keys(params);
  	const is_positional = keys.every((key) => /^\d+$/.test(key));
  
  	if (is_positional) {
  		// Convert to array for positional parameters
  		const max_index = Math.max(...keys.map((k) => parseInt(k)));
  		const param_array: any[] = new Array(max_index);
  
  		for (const [key, value] of Object.entries(params)) {
  			const index = parseInt(key) - 1; // Convert 1-based to 0-based indexing
  			param_array[index] = value;
  		}
  
  		return param_array;
  	}
  
  	// Return as-is for named parameters
  	return params;
  }

• src/tools/handler.ts:366-380 (helper)

  Formats the libsql ResultSet for JSON-safe tool response, converting BigInt to string.

  function format_query_result(result: ResultSet): any {
  	// Convert BigInt to string to avoid serialization issues
  	const lastInsertRowid =
  		result.lastInsertRowid !== null &&
  		typeof result.lastInsertRowid === 'bigint'
  			? result.lastInsertRowid.toString()
  			: result.lastInsertRowid;
  
  	return {
  		rows: result.rows,
  		rowsAffected: result.rowsAffected,
  		lastInsertRowid: lastInsertRowid,
  		columns: result.columns,
  	};
  }