Databricks Tools MCP

Databricks 工具 MCP 服务器

一个用于Databricks Unity Catalog探索的基于角色访问控制的模型上下文协议（MCP）服务器。

特点/功能

• 基于角色的访问控制（分析师/开发者模式）
• 多工作区支持
• SQL查询执行，自动分块响应
• Unity 目录探索（目录、模式、表、列）
• 集中化响应管理，具备自动令牌验证功能
• 智能分块响应（每条响应限制9000个标记）
• 所有工具中一致的错误格式化
• 用户定义函数（UDF）管理
• 13种综合的MCP工具

快速入门

安装

选项1：交互式向导（推荐）

开始的最简单方法：

# Clone the repository
git clone https://github.com/afia28/databricks-tools.git
cd databricks-tools

# Install dependencies
uv sync

# Run interactive setup wizard
uv run databricks-tools-init

# Follow the prompts to configure your workspace
# Restart Claude Desktop when complete

向导将：

• 引导您进行凭证收集
• 验证您的Databricks连接
• 自动更新Claude桌面配置
• 创建一个安全的 .env 文件

选项2：手动安装

对于高级用户或自定义设置：

# Clone/navigate to the repository
cd databricks-tools

# Install dependencies
uv sync

# Create environment file
cp .env.example .env
# Edit .env with your Databricks credentials

见 docs/guides/INSTALLATION.md 翻译为中文是：文档/指南/安装指南.md 如需详细的安装说明、故障排除方法以及针对特定平台的指南，请参阅相关文档。

配置

编辑 .env 提供您的Databricks工作区详细信息：

DATABRICKS_SERVER_HOSTNAME=https://your-workspace.cloud.databricks.com
DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/your-warehouse-id
DATABRICKS_TOKEN=dapi_your_token_here

对于多个工作区（仅限开发者模式），添加前缀变量：

PRODUCTION_DATABRICKS_SERVER_HOSTNAME=https://prod.cloud.databricks.com
PRODUCTION_DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/prod-id
PRODUCTION_DATABRICKS_TOKEN=dapi_prod_token

运行服务器

# Analyst mode (default workspace only)
uv run databricks-tools

# Developer mode (all configured workspaces)
uv run databricks-tools --developer

Claude 桌面集成

添加到Claude桌面配置（~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "databricks-tools": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/ahmed/PycharmProjects/PythonProject/databricks-tools-clean",
        "databricks-tools"
      ]
    }
  }
}

可用工具

基于角色的访问控制

分析模式（默认）

• 仅限访问默认工作区
• 工作区参数为 被忽视
• 非常适合商务用户和分析师
• 运行： uv run databricks-tools

开发者模式

• 访问所有已配置的工作区
• 可以在不同的工作区之间切换
• 非常适合技术用户
• 运行： uv run databricks-tools --developer

看 文档/开发/角色说明.md 以获取详细信息。

发展

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Type checking
uv run mypy .

# Install pre-commit hooks (includes mypy, pytest, coverage)
uv run pre-commit install

# Run pre-commit checks (includes type checking, tests, 85% coverage threshold)
uv run pre-commit run --all-files

# Run tests manually
uv run pytest tests/

# Run tests with coverage
uv run pytest tests/ --cov=src/databricks_tools --cov-report=term-missing

持续集成/持续交付（CI/CD）与发布

该项目包含用于测试、代码检查（linting）和发布版本的自动化CI/CD流水线。

自动化工作流

• 持续集成（CI）工作流 - 在所有推送和拉取请求（PRs）上运行，以验证代码质量和执行测试
• 发布工作流 - 当推送版本标签时，自动发布到私有PyPI
• 克劳德代码审查 - 为拉取请求提供基于AI的代码审查

创建发布版本

# Update version in src/databricks_tools/__init__.py
# Update CHANGELOG.md with release notes

# Commit changes
git add src/databricks_tools/__init__.py CHANGELOG.md
git commit -m "chore: bump version to 0.3.0"
git push origin main

# Create and push version tag
git tag v0.3.0
git push origin v0.3.0

# GitHub Actions will automatically:
# 1. Build source distribution and wheel
# 2. Publish to private PyPI
# 3. Create GitHub release with artifacts

看 文档/guides/CICD_SETUP.md（或可译为：指南/文档/CICD设置指南.md，具体翻译可能根据上下文调整） 用于全面的CI/CD设置、配置和故障排除。

项目结构

databricks-tools-clean/
   src/databricks_tools/
      __init__.py
      server.py           # Main MCP server
      config/
         __init__.py
         models.py        # Pydantic configuration models (US-1.1)
         workspace.py     # Workspace configuration manager (US-1.2)
      core/
         __init__.py
         token_counter.py # Token counting utility with caching (US-2.1)
         connection.py    # Database connection manager (US-2.2)
         query_executor.py # SQL query executor service (US-2.3)
      security/
         __init__.py
         role_manager.py  # Role-based access control manager (US-1.3)
      services/
         __init__.py
         catalog_service.py  # Catalog operations service (US-3.1)
         table_service.py    # Table operations service (US-3.2)
         function_service.py # UDF operations service (US-3.3)
         chunking_service.py # Response chunking service (US-4.1)
         response_manager.py # Response formatting manager (US-4.2)
   tests/
      test_config/
         __init__.py
         test_models.py   # Configuration model tests (32 tests, 100% coverage)
         test_workspace.py # Workspace manager tests (14 tests, 94% coverage)
      test_core/
         __init__.py
         test_token_counter.py # Token counter tests (28 tests, 100% coverage)
         test_connection.py    # Connection manager tests (16 tests, 100% coverage)
         test_query_executor.py # Query executor tests (22 tests, 100% coverage)
      test_security/
         __init__.py
         test_role_manager.py # Role manager tests (21 tests, 92% coverage)
      test_services/
         __init__.py
         test_catalog_service.py  # Catalog service tests (30 tests, 100% coverage)
         test_table_service.py    # Table service tests (41 tests, 100% coverage)
         test_function_service.py # Function service tests (36 tests, 100% coverage)
         test_chunking_service.py # Chunking service tests (30 tests, 100% coverage)
         test_response_manager.py # Response manager tests (39 tests, 100% coverage)
   .github/workflows/
      ci.yml              # CI pipeline (linting, testing)
      publish.yml         # Publish to private PyPI on version tags
      claude-code-review.yml # Claude Code review
      claude.yml          # Claude integration
   .claude/
      CLAUDE.md           # Development guide
      settings.local.json # Claude permissions
   pyproject.toml          # Project config
   .env.example            # Environment template
   README.md               # This file
   ROLES.md                # Role documentation

建筑学

这个项目遵循了整洁架构原则，采用了模块化、类型安全的设计。参见 文档/架构/ARCHITECTURE.md 以进行全面记录。

设计模式

该代码库实现了多种成熟的设计模式：

• 仓储模式（或仓库模式） (QueryExecutor- 抽象数据库访问，并提供简洁的数据操作界面
• 策略模式 （RoleManager- 实现基于角色的访问控制，并支持可替换的策略（分析师策略、开发者策略）
• 工厂模式 （WorkspaceConfig.from_env- 从环境变量中封装复杂对象的创建过程
• 依赖注入 (ApplicationContainer- 线程处理所有依赖项并消除全局状态
• 服务层模式 - 业务逻辑被组织成专注于服务的类（目录服务、表服务、功能服务、分块服务、响应管理器）
• 上下文管理器协议 (ConnectionManager) - 确保数据库连接资源的安全管理

组件概览

MCP Client → Server (13 Tools) → ApplicationContainer → Services → Core → Databricks

层：

• MCP 服务器 - 13个通过模型上下文协议暴露功能的工具
• 应用容器 - 依赖注入容器连接所有服务
• 服务层 - 业务逻辑（目录、表格、函数、分块处理、响应服务）
• 核心服务 - 令牌计数，连接管理，查询执行
• 安全层 - 基于角色的访问控制，采用策略模式
• 配置 - 用于类型安全配置的 Pydantic 模型

见 文档/架构/ARCHITECTURE.md 以获取详细的图表和数据流文档。

使用示例

这个（或“该”） examples/ 目录中包含全面的使用示例：

• basic_usage.py 翻译为中文是：“基本用法.py” - 简单操作、错误处理、工作区配置
• advanced_queries.py 翻译为中文是“高级查询.py” - 复杂SQL，多工作区查询，响应分块
• custom_service.py 翻译为中文是：“自定义服务.py” 或者更简洁地表述为“自定义服务文件”。不过，在中文语境中，我们通常不会直接翻译文件名，而是根据文件内容或用途来命名，但在这里，为了保持原意，可以这样翻译 - 使用依赖注入创建自定义服务
• testing_example.py 翻译为中文是：“测试示例.py” 或者 “测试用例.py” - 测试模式、模拟、固定装置（或测试用例）、覆盖率策略

快速示例：列出目录

from databricks_tools.core.container import ApplicationContainer
from databricks_tools.security.role_manager import Role

# Create application container
container = ApplicationContainer(role=Role.ANALYST)

# List all catalogs
catalogs = container.catalog_service.list_catalogs()
print(f"Available catalogs: {catalogs['catalogs']}")

快速示例：执行查询

from databricks_tools.core.container import ApplicationContainer

# Create container
container = ApplicationContainer()

# Execute SQL query
result_df = container.query_executor.execute_query(
    "SELECT * FROM main.default.my_table LIMIT 10"
)

print(result_df)

看 示例/ 以获取更多全面的示例。

文档

主要文档

• README.md（通常翻译为“README文件”或保持原样，因为它是文件名，直接翻译可能不常见） - 此文件 - 快速入门及概述
• CHANGELOG.md 翻译为中文是：“变更日志.md” 或 “更新记录.md” - 版本历史和发行说明
• CLAUDE.md（文件名或标题，可译为“克劳德.md”或保持原样，具体取决于上下文是否需要翻译文件名） - Claude Code 开发指南

用户指南

• docs/guides/INSTALLATION.md 翻译为中文是：docs/guides/安装指南.md - 详细的安装指南及故障排除方法
• docs/guides/PROJECT_SETUP.md 翻译为中文是：文档/指南/项目设置.md - 开发者环境设置
• 文档/指南/CICD_SETUP.md - CI/CD流水线设置与发布管理

建筑与设计

• 文档/架构/ARCHITECTURE.md - 带有设计模式和图表的架构文档

开发文档

• docs/development/ROLES.md 翻译为中文是：文档/开发/角色说明.md - 基于角色的访问控制详情
• 文档/开发/用户故事框架.md - 用户故事创建框架
• docs/development/用户故事自动化演练指南.md - 自动化指南
• docs/development/IMPLEMENTATION_SUMMARY.md 翻译为中文是：docs/development/实施概要.md - 实施总结

示例与配置

• 示例/例子 - 使用示例和模式
• .env.example - 配置选项

安全

• 存储凭据于 .env （从不提交到git）
• 定期更换令牌
• 使用适当的Databricks权限
• 考虑为生产环境设置服务主体

许可证

麻省理工学院（MIT）