AI导哈

数据目录元数据服务

Databricks MCP Server 是一个将复杂的Unity Catalog元数据转换为适合LLM处理的Markdown摘要的服务，提供数据发现、SQL生成和管道分析功能。

  • by vinay-ram1999
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 vinay-ram1999/databricks-mcp-server

使用说明

_CHMCP服务器

动机

Rancher Unity Catalog（UC）为目录、模式、表和列元数据提供了一个单独的位置。填充良好的UC元数据可以直接由LLM和代理使用，以改进自动化数据发现、SQL生成和管道分析。该项目演示了以确定性、LLM友好的格式向代理公开元数据的实用模式。

概述

这里实现的MCP服务器侧重于：

  • 将复杂的UC和沿袭元数据转换为针对LLM优化的紧凑Markdown摘要。
  • 提供环境驱动的身份验证（PAT或OAuth客户端凭据）和一个小型REST适配器，用于不使用copula SDK的情况。
  • 公开一组简洁的异步工具（通过FastMCP），让代理发现目录/模式，检查表元数据和沿袭，并执行只读SQL查询。

代码库支持小型、可组合的工具，因此代理可以以安全、可审计的方式协调发现、解释和数据检索。

UC元数据对AI代理的实际好处

  • 更清晰的数据上下文 --模式和列描述减少了歧义，使生成的SQL更准确。
  • 提高查询精度 --了解数据类型、约束和注释有助于代理形成正确的WHERE子句和连接。
  • 更快的探索 --代理可以通过编程找到候选表和列，而不依赖于人工指导。
  • 血统意识推理 --当沿袭包括笔记本和作业时，代理可以检查转换逻辑以验证假设。

这些功能缩短了洞察时间，并增加了对代理建议查询的信任。

可用工具和功能

该原型展示了为代理组合设计的少量工具。工具返回Markdown（用于人类/LLM可读性）或结构化JSON用于编程工作流。

已实施的工具（摘要）

  • fetch_schemas_in_catalog(catalog: str) -> str

    • 检索给定Unity Catalog目录中的所有模式，并返回Markdown格式的摘要（名称、描述、计数）。当代理需要发现目录中存在哪些模式时，请使用此选项。

  • fetch_tables_in_schema(catalog: str, schema: str) -> str

    • 列出特定表中的表 catalog.schema 并将结果作为Markdown（表计数和名称）返回。在详细检查模式中的数据资产之前，使用此功能可以发现它们。

  • fetch_table_info(table_names: List[str]) -> str

    • 获取一个或多个完全限定表的详细表元数据，并为每个表返回一个紧凑的、LLM友好的Markdown描述。输出包括表标识符、列定义（名称、类型、可空、注释）、表约束（如果存在）和沿袭信息（如果可用）。

  • execute_spark_sql_query(query: str) -> Dict[str, Any]

    • 对配置的Rancher SQL Warehouse执行只读Spark SQL查询，并返回包含原始查询、执行的结构化JSON state （例如。， SUCCEEDED / FAILED), data （行可用时为JSON对象），以及 error 如果查询失败，则显示消息。此工具在原型中是有意只读的（SELECT/DQL风格的查询）。

每个实现的工具都是有意设计的小型和确定性工具，以便代理可以组合发现→ 描述→ 安全可靠地查询工作流。

设置

系统要求

  • Python 3.10+
  • 推荐：虚拟开发环境

安装

创建虚拟环境并从安装依赖项 requirements.txt:

# using uv
uv sync

# using pip
pip install -r requirements.txt

配置身份验证（选择一个流）：

PAT流程（易于开发）：

export DATABRICKS_HOST="https://<your-databricks-host>"
export DATABRICKS_TOKEN="<your-pat>"
export DATABRICKS_SQL_WAREHOUSE_ID="<warehouse-id>"  # used for query execution

OAuth客户端凭据（服务器到服务器）：

export DATABRICKS_HOST="https://<your-databricks-host>"
export DATABRICKS_CLIENT_ID="<client-id>"
export DATABRICKS_CLIENT_SECRET="<client-secret>"
export DATABRICKS_OAUTH_TOKEN_URL="https://<your-token-endpoint>"
export DATABRICKS_OAUTH_SCOPE="<optional-scope>"

如果存在PAT，系统将首选PAT，否则它将尝试OAuth客户端凭据和缓存令牌，直到过期。

权限要求

确保服务器使用的令牌或服务主体具有以下最低权限：

  1. Unity目录

    • USE CATALOG 在每个目录上进行检查
    • USE SCHEMA 在每个要检查的模式上
    • SELECT 读取模式和查询数据的表

  2. SQL仓库

    • CAN_USE 关于用于查询执行的SQL仓库

  3. 最小权限原则

    • 对于生产，首选具有最小所需范围的服务主体。

定期审核和轮换凭证。

运行服务器

单独模式

在本地运行服务器进行演示：

uv run server.py
# OR
python server.py

服务器通过以下方式注册异步工具 FastMCP （参见 server.py)并将其暴露给MCP感知的跑步者或LLM代理。

与光标一起使用

此MCP服务器旨在与代理框架或MCP客户端集成。使用代理（使用实现的功能）驾驶时的典型用法：

  1. 呼叫发现工具(fetch_schemas_in_catalog, fetch_tables_in_schema)收集目录中可用模式和表的上下文。
  2. 呼叫 fetch_table_info([full_table_name]) 获取一个或多个表的详细表元数据（列、约束）和沿袭信息。
  3. 构造一个只读SQL查询并调用 execute_spark_sql_query 检索行并验证结果。

保持交互只读，除非您有意修改代码以支持DDL/DML。

示例使用工作流（用于LLM代理）

  1. 客服电话 fetch_schemas_in_catalog(catalog) 列出给定目录中的模式。
  2. 客服电话 fetch_tables_in_schema(catalog, schema) 列出所选架构中的表。
  3. 客服电话 fetch_table_info([full_table_name]) 收集目标表的详细列元数据、约束和沿袭。
  4. 代理人组成 SELECT 查询和呼叫 execute_spark_sql_query(query) 以验证结果。

这种分阶段的方法减少了猜测，并带来了更准确的查询。

处理长时间运行的查询

最佳实践：

  • 使用 LIMIT 或取样进行勘探。
  • 使用API的语句执行 wait_timeout 以及用于长时间运行的作业的可轮询语句id。
  • 返回长时间运行的查询的语句id，以便代理可以轮询完成情况。
  • 注意仓库成本和并发限制。

相关 MCP