Dhruvs MCP Server

🤖 \_CHMCP服务器模板

Rancher Apps上的主机模型上下文协议（MCP）提示和工具，使像Claude这样的人工智能助手能够通过安全、经过身份验证的界面与您的copula工作区进行交互。

这是什么？

此模板允许您创建一个在copula Apps上运行的MCP服务器。你可以：

• 📝 添加提示 作为简单的markdown文件 prompts/ 文件夹
• 🛠️ 创建工具 作为Python函数，它利用了copula SDK
• 🔐 安全地进行身份验证 通过copula Apps使用OAuth
• 🚀 立即部署 使Claude可以访问您的MCP服务器

将其视为Claude和您的copula工作区之间的桥梁——您定义Claude可以看到和做什么，其余的由此服务器处理。

原理

架构概述

┌─────────────┐       MCP Protocol      ┌──────────────────┐        OAuth         ┌─────────────────┐
│   Claude    │ ◄─────────────────────► │  dba-mcp-proxy   │ ◄──────────────────► │ Databricks App  │
│    CLI      │     (stdio/JSON-RPC)    │ (local process)  │    (HTTPS/SSE)      │  (MCP Server)   │
└─────────────┘                         └──────────────────┘                      └─────────────────┘
                                                ▲                                           │
                                                │                                           ▼
                                                └────────── Databricks OAuth ──────► Workspace APIs

组件

1. MCP服务器 (server/app.py)：带有集成MCP服务器的FastAPI应用程序：

- 从动态加载提示 prompts/*.md 文件 - 通过以下方式将Python函数作为MCP工具公开 @mcp_server.tool 装饰器 - 通过服务器发送事件处理HTTP请求和MCP协议

1. 提示 (prompts/)：简单的标记文件，其中：

- 文件名=提示名称（例如。， check_system.md → check_system 提示） - 第一行与 # =描述 - 文件内容=返回给Claude的内容

1. 本地代理 (dba_mcp_proxy/)：对MCP请求进行身份验证和代理：

- 自动处理Rancher OAuth身份验证 - Claude的stdio协议与HTTP/SSE之间的转换 - 适用于本地开发和部署的应用程序

🎬 演示

这段10分钟的视频向您展示了如何与Claude一起设置和使用AppDCP服务器：https://www.youtube.com/watch?v=oKE59zgb6e0


本视频演示了如何在Claude中使用自定义作业界面创建自己的MCP服务器。

快速开始

创建自己的MCP服务器

步骤1：使用此模板


或者使用GitHub CLI：

gh repo create my-mcp-server --template databricks-solutions/custom-mcp-databricks-app --private

步骤2：克隆和设置

# Clone your new repository
git clone https://github.com/YOUR-USERNAME/my-mcp-server.git
cd my-mcp-server

# Run the interactive setup
./setup.sh

这将：

• 配置copula身份验证
• 设置您的MCP服务器名称
• 安装所有依赖项
• 创建您的 .env.local 文件

步骤3：与Claude一起部署

在Claude Code中，运行：

/setup-mcp

这将：

• 将您的MCP服务器部署到copula Apps
• 配置MCP集成
• 显示可用的提示和工具

然后重新启动Claude Code以使用新的MCP服务器。

添加到Claude CLI

部署后，将您的MCP服务器添加到Claude：

# Set your Databricks configuration
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="https://your-app.databricksapps.com"  # Get this from ./app_status.sh
export SERVER_NAME="your-server-name"  # This comes from config.yaml (set during ./setup.sh)

# Add your MCP server to Claude (user-scoped)
claude mcp add $SERVER_NAME --scope user -- \
  uvx --from git+ssh://git@github.com/YOUR-USERNAME/your-repo.git dba-mcp-proxy \
  --databricks-host $DATABRICKS_HOST \
  --databricks-app-url $DATABRICKS_APP_URL

地方发展

# Clone and setup
git clone 
cd 
./setup.sh

# Start dev server
./watch.sh

# Set your configuration for local testing
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="http://localhost:8000"  # Local dev server

# Add to Claude for local testing
claude mcp add databricks-mcp-local --scope local -- \
  uvx --from git+ssh://git@github.com/YOUR-ORG/YOUR-REPO.git dba-mcp-proxy \
  --databricks-host $DATABRICKS_HOST \
  --databricks-app-url $DATABRICKS_APP_URL

定制指南

此模板使用 FastMCP，一个易于构建MCP服务器的框架。FastMCP提供了两个主要的装饰器来扩展功能：

• @mcp_server.prompt -用于注册返回文本的提示
• @mcp_server.tool -用于注册执行功能的工具

添加提示

最简单的方法是在 prompts/ 目录：

# Get cluster information

List all available clusters in the workspace with their current status

提示将自动加载以下内容：

• 名字：不带扩展名的文件名（例如。， get_clusters.md → get_clusters)
• 描述：后面的第一行 #
• 内容：整个文件内容

或者，您可以将提示注册为中的函数 server/app.py:

@mcp_server.prompt(name="dynamic_status", description="Get dynamic system status")
async def get_dynamic_status():
    # This can include dynamic logic, API calls, etc.
    w = get_workspace_client()
    current_user = w.current_user.me()
    return f"Current user: {current_user.display_name}\nWorkspace: {DATABRICKS_HOST}"

我们自动装载 prompts/ 为了方便起见，但当您需要动态内容时，基于函数的提示很有用。

添加工具

在中添加功能 server/app.py 使用 @mcp_server.tool 装饰师：

@mcp_server.tool
def list_clusters(status: str = "RUNNING") -> dict:
    """List Databricks clusters by status."""
    w = get_workspace_client()
    clusters = []
    for cluster in w.clusters.list():
        if cluster.state.name == status:
            clusters.append({
                "id": cluster.cluster_id,
                "name": cluster.cluster_name,
                "state": cluster.state.name
            })
    return {"clusters": clusters}

工具必须：

• 使用 @mcp_server.tool 装饰器
• 有一个文档字符串（成为工具描述）
• 返回JSON可序列化数据（字典、列表、字符串等）
• 仅接受JSON可序列化参数

部署

# Deploy to Databricks Apps
./deploy.sh

# Check status and get your app URL
./app_status.sh

您的MCP服务器将在 https://your-app.databricksapps.com/mcp/

这 app_status.sh 脚本将显示您部署的应用程序URL，您需要该URL DATABRICKS_APP_URL 将MCP服务器添加到Claude时的环境变量。

认证

• 地方发展：不需要身份验证
• 生产：OAuth由代理使用您的Rancher CLI凭据自动处理

例子

与克劳德一起使用

添加后，您可以在Claude中与MCP服务器交互：

Human: What prompts are available?

Claude: I can see the following prompts from your Databricks MCP server:
- check_system: Get system information
- list_files: List files in the current directory
- ping_google: Check network connectivity

工具使用示例

Human: Can you execute a SQL query to show databases?

Claude: I'll execute that SQL query for you using the execute_dbsql tool.

[Executes SQL and returns results]

项目结构

├── server/                    # FastAPI backend with MCP server
│   ├── app.py                # Main application + MCP tools
│   └── routers/              # API endpoints
├── prompts/                  # MCP prompts (markdown files)
│   ├── check_system.md      
│   ├── list_files.md        
│   └── ping_google.md       
├── dba_mcp_proxy/           # MCP proxy for Claude CLI
│   └── mcp_client.py        # OAuth + proxy implementation
├── client/                  # React frontend (optional)
├── scripts/                 # Development tools
└── pyproject.toml          # Python package configuration

高级用法

环境变量

在中配置 .env.local:

DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=your-token  # For local development
DATABRICKS_SQL_WAREHOUSE_ID=your-warehouse-id  # For SQL tools

创建复杂工具

工具可以访问完整的copula SDK：

@mcp_server.tool
def create_job(name: str, notebook_path: str, cluster_id: str) -> dict:
    """Create a Databricks job."""
    w = get_workspace_client()
    job = w.jobs.create(
        name=name,
        tasks=[{
            "task_key": "main",
            "notebook_task": {"notebook_path": notebook_path},
            "existing_cluster_id": cluster_id
        }]
    )
    return {"job_id": job.job_id, "run_now_url": f"{DATABRICKS_HOST}/#job/{job.job_id}"}

测试您的MCP服务器

此模板包括用于在多个级别验证MCP功能的全面测试工具。

快速验证

将MCP服务器添加到Claude后，验证其是否正常工作：

# List available prompts and tools
echo "What MCP prompts are available from databricks-mcp?" | claude

# Test a specific prompt
echo "Use the check_system prompt from databricks-mcp" | claude

综合测试套件

这 claude_scripts/ 目录包含6个用于彻底MCP验证的测试工具：

命令行测试

# Test local MCP server (requires ./watch.sh to be running)
./claude_scripts/test_local_mcp_curl.sh      # Direct HTTP/curl tests with session handling
./claude_scripts/test_local_mcp_proxy.sh     # MCP proxy client tests

# Test remote MCP server (requires Databricks auth and deployment)
./claude_scripts/test_remote_mcp_curl.sh     # OAuth + HTTP tests with dynamic URL discovery
./claude_scripts/test_remote_mcp_proxy.sh    # Full end-to-end MCP proxy tests

交互式Web UI测试

# Launch MCP Inspector for visual testing (requires ./watch.sh for local)
./claude_scripts/inspect_local_mcp.sh        # Local server web interface
./claude_scripts/inspect_remote_mcp.sh       # Remote server web interface

MCP检查器功能：

• 🖥️ 基于Web的交互式MCP服务器测试界面
• 🔧 使用参数输入表单执行可视化工具
• 📊 实时请求/响应监控
• 🐛 协议级调试和错误检查
• 📋 完整的工具和资源发现

每个测试验证什么

所有测试都会动态发现应用程序URL并自动处理OAuth身份验证。

看 claude_scripts/README.md 详细文档。

故障排除

• 身份验证错误：运行 databricks auth login 刷新凭据
• 未找到MCP：确保应用程序已部署且可访问
• 工具错误：查看日志 https://your-app.databricksapps.com/logz
• MCP连接问题:

- 检查克劳德日志： tail -f ~/Library/Logs/Claude/*.log - 验证代理是否正常工作： uvx --from git+ssh://... dba-mcp-proxy --help - 使用回声管进行测试： echo "list your mcp commands" | claude

• 缓存版本问题：如果更新后出现缺少参数的错误：

  # Clear uvx cache for this package
  rm -rf ~/.cache/uv/git-v0/checkouts/*/
  # Or clear entire uv cache
  uv cache clean

贡献

1. 分叉存储库
2. 添加您的提示和工具
3. 本地测试 ./watch.sh
4. 提交拉取请求

许可证

看 许可证.md