Superset MCP Server

Instructions

Implementation Reference

• src/index.ts:428-464 (handler)

  The main handler function for the 'list-fields' MCP tool. It fetches fields using getTableFields helper, formats them into a text list, and returns as MCP content.

  async ({ databaseId, schema, tableName }) => {
    try {
      const fields = await getTableFields(databaseId, schema, tableName);
  
      if (fields.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `表 ${schema}.${tableName} 中没有找到字段`,
            },
          ],
        };
      }
      
      const fieldsList = fields.map(field => `名称: ${field.name}, 类型: ${field.type}`).join("\n");
      
      return {
        content: [
          {
            type: "text",
            text: `表 ${schema}.${tableName} 的字段列表:\n\n${fieldsList}`,
          },
        ],
      };
    } catch (error) {
      console.error("获取字段列表失败:", error);
      return {
        content: [
          {
            type: "text",
            text: `获取字段列表失败: ${(error as Error).message}`,
          },
        ],
      };
    }
  }

• src/index.ts:423-427 (schema)

  Zod schema defining the input parameters for the list-fields tool: databaseId (number), schema (string), tableName (string).

  {
    databaseId: z.number().describe("数据库ID"),
    schema: z.string().describe("Schema名称"),
    tableName: z.string().describe("表名"),
  },

• src/index.ts:420-465 (registration)

  Registers the 'list-fields' tool on the MCP server with name, description, input schema, and handler function.

  server.tool(
    "list-fields",
    "获取指定表的字段列表",
    {
      databaseId: z.number().describe("数据库ID"),
      schema: z.string().describe("Schema名称"),
      tableName: z.string().describe("表名"),
    },
    async ({ databaseId, schema, tableName }) => {
      try {
        const fields = await getTableFields(databaseId, schema, tableName);
  
        if (fields.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: `表 ${schema}.${tableName} 中没有找到字段`,
              },
            ],
          };
        }
        
        const fieldsList = fields.map(field => `名称: ${field.name}, 类型: ${field.type}`).join("\n");
        
        return {
          content: [
            {
              type: "text",
              text: `表 ${schema}.${tableName} 的字段列表:\n\n${fieldsList}`,
            },
          ],
        };
      } catch (error) {
        console.error("获取字段列表失败:", error);
        return {
          content: [
            {
              type: "text",
              text: `获取字段列表失败: ${(error as Error).message}`,
            },
          ],
        };
      }
    }
  );

• src/index.ts:69-84 (helper)

  Helper function to retrieve and cache table fields using Superset API.

  async function getTableFields(databaseId: number, schema: string, tableName: string): Promise<Field[]> {
    const cacheKey = `${databaseId}:${schema}:${tableName}`;
    
    if (fieldsCache.has(cacheKey)) {
      return fieldsCache.get(cacheKey) || [];
    }
    
    try {
      const metadata = await supersetApi.getTableMetadata(databaseId, schema, tableName);
      fieldsCache.set(cacheKey, metadata.columns);
      return metadata.columns;
    } catch (error) {
      console.error(`获取表 ${schema}.${tableName} 的字段失败:`, error);
      return [];
    }
  }

• src/services/superset-api.ts:220-238 (helper)

  SupersetApiService method that calls the Superset API to get table metadata (including columns/fields).

  public async getTableMetadata(databaseId: number, schemaName: string, tableName: string): Promise<TableMetadata> {
    try {
      // 使用新的 API 路径格式
      console.log(`尝试使用表元数据API: /api/v1/database/${databaseId}/table/${tableName}/${schemaName}/`);
      
      const response = await this.client.get<TableMetadata>(
        `/api/v1/database/${databaseId}/table/${tableName}/${schemaName}/`
      );
      
      if (!response.success || !response.data) {
        throw new Error(response.error?.message || `获取表 ${schemaName}.${tableName} 的元数据失败`);
      }
      
      return response.data;
    } catch (error) {
      console.error('获取表元数据失败:', error);
      throw error;
    }
  }