USQL MCP Server

Instructions

Implementation Reference

• src/tools/list-databases.ts:39-52 (handler)

  The core handler logic for the list_databases tool. It uses createToolHandler to generate the database-specific list databases command based on detected DB type from connection string.

  const _handleListDatabases = createToolHandler({
    name: "list-databases",
    getQuery: (input) => {
      // Determine the database type from the connection string
      const connectionString = resolveConnectionStringOrDefault(
        (input as Record<string, unknown>).connection_string as string | undefined
      );
      const dbType = detectDatabaseType(connectionString);
      return getListDatabasesCommand(dbType);
    },
    errorType: "ListDatabasesError",
  });
  
  export const handleListDatabases = withBackgroundSupport("list_databases", _handleListDatabases);

• src/tools/list-databases.ts:11-37 (schema)

  The JSON schema (Tool object) defining the input parameters and description for the list_databases tool.

  export const listDatabasesSchema: Tool = {
    name: "list_databases",
    description:
      "List all databases available on a database server. Uses default connection if none specified. Automatically detects the database type and uses the appropriate command.",
    inputSchema: {
      type: "object",
      properties: {
        connection_string: {
          type: "string",
          description:
            '(Optional) Database connection URL or configured connection name. If omitted, uses the default connection from USQL_DEFAULT_CONNECTION. Examples: "oracle" for USQL_ORACLE env var, or full URL like "postgres://localhost". Use get_server_info to discover available connections.',
        },
        output_format: {
          type: "string",
          enum: ["json", "csv"],
          description: "Output format for results (default: json)",
        },
        timeout_ms: {
          type: ["number", "null"],
          description:
            "Optional timeout in milliseconds for this call (overrides defaults). Use null for unlimited.",
          minimum: 1,
        },
      },
      required: [],
    },
  };

• src/index.ts:37-46 (registration)

  Registration of the listDatabasesSchema in the array of available tools, used by MCP's list_tools request.

  private tools = [
    executeQuerySchema,
    listDatabasesSchema,
    listTablesSchema,
    describeTableSchema,
    executeScriptSchema,
    getJobStatusSchema,
    getServerInfoSchema,
    cancelJobSchema,
  ];

• src/index.ts:186-187 (registration)

  Dispatch to the list_databases handler in the main tool execution switch statement.

  case "list_databases":
    return await handleListDatabases(input as Parameters<typeof handleListDatabases>[0]);

• src/utils/database-mapper.ts:84-120 (helper)

  Helper function that maps database type to the specific command for listing databases, used by the handler.

  export function getListDatabasesCommand(dbType: string): string {
    const db = dbType.toLowerCase();
  
    switch (db) {
      case "postgres":
      case "cockroach":
        // PostgreSQL-style
        return "\\l";
  
      case "mysql":
      case "mariadb":
        // MySQL-style
        return "SHOW DATABASES;";
  
      case "sqlite":
        // SQLite doesn't support database listing in the traditional sense
        // Return a query that shows attached databases
        return "PRAGMA database_list;";
  
      case "oracle":
        // Oracle doesn't have user-facing database listing
        // Return tablespaces instead
        return "SELECT tablespace_name FROM dba_tablespaces ORDER BY tablespace_name;";
  
      case "sqlserver":
        // SQL Server-style
        return "SELECT name FROM sys.databases ORDER BY name;";
  
      case "mongodb":
        // MongoDB-style
        return "show dbs;";
  
      default:
        // Fallback to generic (PostgreSQL-style)
        return "\\l";
    }
  }