MCPQL

Instructions

Implementation Reference

• src/tools/dataOperations.ts:95-141 (handler)

  The core handler function that implements the mcp_get_column_stats tool. It queries the SQL Server database to compute statistics like total rows, null count, distinct count, min/max values, and top 10 sample values for the specified column.

  export const mcp_get_column_stats = async (args: { table_name: string, column_name: string }): Promise<ToolResult<any>> => {
    const { table_name, column_name } = args;
    console.log('Executing mcp_get_column_stats with:', args);
  
    try {
      const pool = getPool();
      const normalizedTableName = normalizeSqlObjectName(table_name);
      
      // Note: We're using double quotes for identifiers and params for values to prevent SQL injection
      const query = `
        SELECT
          '${column_name}' as column_name,
          COUNT(*) AS total_rows,
          SUM(CASE WHEN [${column_name}] IS NULL THEN 1 ELSE 0 END) AS null_count,
          COUNT(DISTINCT [${column_name}]) AS distinct_count,
          MIN([${column_name}]) AS min_value,
          MAX([${column_name}]) AS max_value
        FROM ${normalizedTableName}
      `;
      
      const result = await pool.request().query(query);
      
      // Get sample values
      const sampleQuery = `
        SELECT TOP 10 [${column_name}] AS value
        FROM ${normalizedTableName}
        WHERE [${column_name}] IS NOT NULL
        GROUP BY [${column_name}]
        ORDER BY COUNT(*) DESC
      `;
      
      const sampleResult = await pool.request().query(sampleQuery);
      
      const stats = result.recordset[0] || {};
      
      return { 
        success: true, 
        data: {
          ...stats,
          sample_values: sampleResult.recordset.map(row => row.value)
        }
      };
    } catch (error: any) {
      console.error(`Error in mcp_get_column_stats for table ${table_name}, column ${column_name}: ${error.message}`);
      return { success: false, error: error.message };
    }
  };

• src/tools.ts:62-79 (schema)

  The tool definition including name, description, and input schema (parameters: table_name and column_name) used for tool listing and validation in the MCP server.

  {
    name: "mcp_get_column_stats",
    description: "Get comprehensive statistics for a specific column in a table",
    inputSchema: {
      type: "object",
      properties: {
        table_name: {
          type: "string",
          description: "Fully qualified table name (schema.table), e.g. \"api.Idiomas\""
        },
        column_name: {
          type: "string",
          description: "Name of the column to analyze"
        }
      },
      required: ["table_name", "column_name"]
    }
  },

• src/tools/index.ts:20-27 (registration)

  Re-export of the mcp_get_column_stats handler (and related tools) from dataOperations.ts, making it available by name in the toolHandlers object imported by the MCP server for dynamic execution.

  export {
    mcp_preview_data,      // Data preview with filters
    mcp_preview_data_enhanced, // Para compatibilidad con server.ts
    mcp_get_column_stats,   // Column statistics
    mcp_get_column_stats_enhanced, // Para compatibilidad con server.ts
    mcp_quick_data_analysis, // Quick table analysis
    mcp_get_sample_values   // Sample values from column
  } from './dataOperations.js';