USQL MCP Server

Instructions

Implementation Reference

• src/tools/list-tables.ts:42-58 (handler)

  Core handler implementation for the 'list_tables' tool. It resolves the connection string, detects the database type, and generates the appropriate SQL command to list tables using a helper function.

  const _handleListTables = createToolHandler({
    name: "list-tables",
    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 getListTablesCommand(dbType);
    },
    errorType: "ListTablesError",
    getErrorDetails: (input) => ({
      ...(input.database && { database: input.database }),
    }),
  });
  
  export const handleListTables = withBackgroundSupport("list_tables", _handleListTables);

• src/tools/list-tables.ts:11-40 (schema)

  Input schema definition for the 'list_tables' tool, specifying optional parameters like connection_string, database, output_format, and timeout_ms.

  export const listTablesSchema: Tool = {
    name: "list_tables",
    description: "List all tables in a database. 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 (e.g., "oracle" for USQL_ORACLE). Use get_server_info to discover available connections.',
        },
        database: {
          type: "string",
          description: "Optional database name to list tables from (if not specified in connection)",
        },
        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 listTablesSchema in the MCP server's list of available tools.

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

• src/index.ts:189-190 (registration)

  Dispatch to the list_tables handler in the server's tool execution switch statement.

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

• src/utils/database-mapper.ts:42-79 (helper)

  Helper function that maps database types to specific commands for listing tables, used by the list_tables handler.

  /**
   * Get the command to list all tables in a database
   */
  export function getListTablesCommand(dbType: string): string {
    const db = dbType.toLowerCase();
  
    switch (db) {
      case "postgres":
      case "cockroach":
        // PostgreSQL-style
        return "\\dt";
  
      case "mysql":
      case "mariadb":
        // MySQL-style
        return "SHOW TABLES;";
  
      case "sqlite":
        // SQLite-style
        return "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;";
  
      case "oracle":
        // Oracle-style
        return "SELECT table_name FROM user_tables ORDER BY table_name;";
  
      case "sqlserver":
        // SQL Server-style
        return "SELECT TABLE_NAME FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE='BASE TABLE' ORDER BY TABLE_NAME;";
  
      case "mongodb":
        // MongoDB doesn't have tables, but collections
        return "db.listCollections();";
  
      default:
        // Fallback to generic (PostgreSQL-style)
        return "\\dt";
    }
  }