Advanced Hasura GraphQL MCP Server

Instructions

Implementation Reference

• src/index.ts:173-244 (handler)

  The core handler function that implements the logic for listing tables: introspects query_root fields, filters non-table fields, parses schema from descriptions, groups by schema, sorts, and returns JSON-formatted list.

  async ({ schemaName }) => {
      console.log(`[INFO] Executing tool 'list_tables' for schema: ${schemaName || 'ALL'}`);
      try {
        const schema = await getIntrospectionSchema();
        
        const query = gql`
          query GetTablesWithDescriptions {
            __type(name: "query_root") {
              fields {
                name
                description
                type {
                  name
                  kind
                }
              }
            }
          }
        `;
        
        const result = await makeGqlRequest(query);
        
        const tablesData: Record<string, Array<{name: string, description: string | null}>> = {};
        
        if (result.__type && result.__type.fields) {
          const fieldEntries = result.__type.fields;
          
          for (const field of fieldEntries) {
            if (field.name.includes('_aggregate') || 
                field.name.includes('_by_pk') || 
                field.name.includes('_stream') ||
                field.name.includes('_mutation') ||
                field.name.startsWith('__')) {
              continue;
            }
            
            let currentSchema = 'public';
            if (field.description && field.description.includes('schema:')) {
              const schemaMatch = field.description.match(/schema:\s*([^\s,]+)/i);
              if (schemaMatch && schemaMatch[1]) {
                currentSchema = schemaMatch[1];
              }
            }
            
            if (schemaName && currentSchema !== schemaName) {
              continue;
            }
            
            if (!tablesData[currentSchema]) {
              tablesData[currentSchema] = [];
            }
            
            tablesData[currentSchema].push({
              name: field.name,
              description: field.description
            });
          }
        }
        
        const formattedOutput = Object.entries(tablesData)
          .map(([schema, tables]) => ({
            schema,
            tables: tables.sort((a, b) => a.name.localeCompare(b.name))
          }))
          .sort((a, b) => a.schema.localeCompare(b.schema));
          
        return { content: [{ type: "text", text: JSON.stringify(formattedOutput, null, 2) }] };
      } catch (error: any) {
        console.error(`[ERROR] Tool 'list_tables' failed: ${error.message}`);
        throw error;
      }
  }

• src/index.ts:170-172 (schema)

  Zod input schema defining the optional 'schemaName' parameter for filtering tables by database schema.

  {
    schemaName: z.string().optional().describe("Optional. The database schema name to filter results. If omitted, returns tables from all schemas.")
  },

• src/index.ts:167-245 (registration)

  MCP server.tool call registering the 'list_tables' tool with name, description, input schema, and inline handler function.

  server.tool(
    "list_tables",
    "Lists available data tables (or collections) managed by Hasura, organized by schema with descriptions",
    {
      schemaName: z.string().optional().describe("Optional. The database schema name to filter results. If omitted, returns tables from all schemas.")
    },
    async ({ schemaName }) => {
        console.log(`[INFO] Executing tool 'list_tables' for schema: ${schemaName || 'ALL'}`);
        try {
          const schema = await getIntrospectionSchema();
          
          const query = gql`
            query GetTablesWithDescriptions {
              __type(name: "query_root") {
                fields {
                  name
                  description
                  type {
                    name
                    kind
                  }
                }
              }
            }
          `;
          
          const result = await makeGqlRequest(query);
          
          const tablesData: Record<string, Array<{name: string, description: string | null}>> = {};
          
          if (result.__type && result.__type.fields) {
            const fieldEntries = result.__type.fields;
            
            for (const field of fieldEntries) {
              if (field.name.includes('_aggregate') || 
                  field.name.includes('_by_pk') || 
                  field.name.includes('_stream') ||
                  field.name.includes('_mutation') ||
                  field.name.startsWith('__')) {
                continue;
              }
              
              let currentSchema = 'public';
              if (field.description && field.description.includes('schema:')) {
                const schemaMatch = field.description.match(/schema:\s*([^\s,]+)/i);
                if (schemaMatch && schemaMatch[1]) {
                  currentSchema = schemaMatch[1];
                }
              }
              
              if (schemaName && currentSchema !== schemaName) {
                continue;
              }
              
              if (!tablesData[currentSchema]) {
                tablesData[currentSchema] = [];
              }
              
              tablesData[currentSchema].push({
                name: field.name,
                description: field.description
              });
            }
          }
          
          const formattedOutput = Object.entries(tablesData)
            .map(([schema, tables]) => ({
              schema,
              tables: tables.sort((a, b) => a.name.localeCompare(b.name))
            }))
            .sort((a, b) => a.schema.localeCompare(b.schema));
            
          return { content: [{ type: "text", text: JSON.stringify(formattedOutput, null, 2) }] };
        } catch (error: any) {
          console.error(`[ERROR] Tool 'list_tables' failed: ${error.message}`);
          throw error;
        }
    }
  );