使用说明

🔌 API注册表MCP服务器

Databricks应用程序，通过AI聊天界面帮助您发现、注册和管理外部API端点。

这是什么？

运行在Databricks应用程序上的API发现和管理平台：

🤖 AI聊天界面：使用Claude提供的自然语言注册API
📊 API注册表：外部API终结点的数据库支持目录
🔐 安全认证：支持公共API、API密钥和承载令牌
🛠️ MCP服务器：程序化API管理工具
📚 智能发现：自动端点测试和文档解析

架构： 此应用程序使用混合MCP设计-内部AI代理直接通过Python（快速、进程内）调用MCP工具，同时在 /mcp 对于像Claude CLI这样的外部客户端。两个路径共享相同的工具注册表，使您能够灵活地与API注册表交互。

快速开始

先决条件

所需工具（在本地计算机上安装）

1.Python包管理器-uv：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

# Verify installation
uv --version

紫外线文件

2.Rancher命令行界面：

# With pip
pip install databricks-cli

# Or with Homebrew
brew tap databricks/tap
brew install databricks

# Verify installation  
databricks --version  # Should be v0.260.0+

Databricks CLI文档

3.Bun（可选-仅用于前端开发）：

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Or with Homebrew
brew install oven-sh/bun/bun

Bun文档

copula工作区要求

您的工作空间需要：

copula应用程序 已启用（公开预览）
API基础模型 使用支持工具的模型（Claude、Llama等）
SQL仓库 -至少一个仓库(创建一个)
Unity目录 -使用目录和模式，您可以写入

📖 详细要求： 工作空间_要求.md

步骤1：克隆和设置

在你的 本地计算机 （不在ViewModel中）：

git clone https://github.com/lucamilletti99/mcp_api_registry_http.git
cd mcp_api_registry_http
./setup.sh

安装脚本将提示您：

提示	用途	默认	备注
copula主机	您的工作区URL	（无默认值）	格式： `https://your-workspace.cloud.databricks.com`
认证方式	如何进行身份验证	`2` （帕特- 推荐)	选项：1=OAuth，2=PAT
个人访问令牌	您的copula PAT	（无默认值）	PAT身份验证所需。在这里获取您的PAT
SQL仓库ID	用于查询的仓库	自动检测第一个仓库	按Enter键使用默认值
Unity目录	目标目录	`main`	按Enter键使用默认值
Unity模式	目标架构	`default`	按Enter键使用默认值

⚠️ 重要提示：使用个人访问令牌（PAT）身份验证

PAT是当地发展的推荐方法
OAuth是实验性的，可能存在问题
获取您的PAT：工作区→ 设置→ 开发者→ 访问令牌→ 生成新令牌
完整的PAT文档

这有什么作用：

安装Python和JavaScript依赖项
配置copula CLI身份验证
创建 .env.local 根据您的配置
验证您的工作区连接

步骤2：创建API注册表表

创建存储API元数据的增量表：

uv run python setup_table.py your_catalog your_schema

例子：

# Using the defaults from Step 1
uv run python setup_table.py main default

这有什么作用：

创建 api_http_registry 指定catalog.schema中的表
表存储：API名称、端点、身份验证类型、HTTP连接详细信息、参数
应用程序需要跟踪已注册的API

替代方案-手动SQL： 从以下位置运行SQL setup_api_http_registry_table.sql 在ConnectionSQL编辑器中

注：首先确保您的目录和架构存在。如果需要，可以在ConnectionSQL编辑器中创建它们。

第3步：部署到copula应用程序

将您的应用程序代码部署到copula：

# First time deployment (creates the app)
./deploy.sh --create

# Future updates (after code changes)
./deploy.sh

在部署过程中，系统将提示您：

应用程序名称：必须以开头 mcp- （例如。， mcp-api-registry, mcp-prod-api)

部署过程中会发生什么：

✅ 构建前端 -将React TypeScript编译为静态资产
✅ 打包后端 -准备FastAPI服务器和MCP工具
✅ 创建copula应用程序 -在工作区中注册您的应用程序
✅ 生成服务主体 -自动为您的应用程序创建服务主体
✅ 将代码部署到应用程序 -上传您的代码并自动将其附加到应用程序计算
✅ 启动应用程序 -您的应用程序现在正在运行并可访问
✅ 启用OAuth（OBO） -自动代表身份验证进行配置

⚠️ 重要提示：不需要手动附件！ 这 deploy.sh 脚本处理整个部署管道。您的代码会自动：

打包成可部署的工件
已上传到copula
连接到应用程序的计算环境
在应用程序URL上启动并可访问

您不需要手动将代码连接到计算-所有这些都由部署过程处理！

查找已部署的应用程序：

# Get app URL and status
./app_status.sh

# Expected output:
# App: mcp-api-registry
# Status: RUNNING  
# URL: https://adb-123456.10.azuredatabricks.net//apps/mcp-api-registry
# Service Principal ID: 00000000-0000-0000-0000-000000000000

或者在Databricks UI中：

工作区→ 计算→ Apps → 单击您的应用程序名称

🔐 代表（OBO）身份验证：

AppDapps自动处理OAuth身份验证：

✅ 用户通过ConnectionUI登录-无需单独的身份验证设置
✅ 所有操作都在用户的权限下运行-适当的访问控制
✅ 完整的审计日志记录-跟踪谁做了什么
✅ 无需手动配置OAuth！

应用程序配置(app.yaml)指定所需的范围。当用户访问该应用程序时，他们会自动获得一个包含其copula权限的OAuth令牌。

📖 更多详情： 看 app.yaml 在项目根中

步骤4：设置密钥作用域（用于经过身份验证的API）

⚠️ 重要提示：在步骤3之后执行此操作 -您首先需要部署时的服务主体ID！

如果只使用没有身份验证的公共API，请跳过。

对于需要API密钥或承载令牌的API：

./setup_shared_secrets.sh

出现提示时，从步骤3输入应用程序的服务主体ID。

在哪里可以找到您的服务负责人ID：

从终端： 跑 ./app_status.sh （如输出所示）
从UI： copula工作区→ 计算→ Apps → 点击您的应用→ “服务主体ID”
格式： 看起来像 00000000-0000-0000-0000-000000000000

此脚本的作用：

创建 mcp_api_keys 作用域-用于API密钥身份验证
创建 mcp_bearer_tokens 范围-用于承载令牌身份验证
授予应用程序的服务主体写访问这两个范围
验证权限设置是否正确

为什么需要这样做：

API密钥和承载令牌必须安全存储
Rancher Secrets提供静态加密
应用程序的服务主体代表所有用户管理机密
用户永远不会看到或处理原始凭据-它们会自动加密

验证：

# Check both scopes exist
databricks secrets list-scopes | grep mcp_

# Check service principal has WRITE access
databricks secrets get-acl mcp_api_keys --principal YOUR_SPN_ID
databricks secrets get-acl mcp_bearer_tokens --principal YOUR_SPN_ID

# Expected output: permission: WRITE

故障排除：

如果作用域创建失败：您可能需要管理员权限
如果权限授予失败：您的SPN ID可能不正确（请检查 ./app_status.sh)

📖 详细指南： 机密_解决方案.md

API身份验证类型

该应用程序支持三种身份验证类型：

类型	何时使用	凭证去向	示例API
无	无身份验证的公共API	不适用	财政部，公共数据集
api_key	密钥作为查询参数传递	`?api_key=xxx` 在URL中	FRED、Alpha Vantage、NewsAPI
bear_token	标头中传递的令牌	`Authorization: Bearer xxx`	GitHub、Stripe、Shopify

快速示例

公共API（无授权）：

"Register the Treasury Fiscal Data API at 
https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v1/accounting/od/rates_of_exchange"

API密钥验证：

"Register the FRED API at https://api.stlouisfed.org/fred/series/observations
Use API key authentication with key: YOUR_API_KEY_HERE"

承载令牌身份验证：

"Register the GitHub API at https://api.github.com/user/repos
Use bearer token authentication with token: ghp_YOUR_TOKEN_HERE"

运作原理

API密钥授权：

密钥存储在 mcp_api_keys 范围
HTTP连接的bear_token为空
密钥从secrets中检索并在运行时添加到params中

承载令牌认证：

令牌存储在 mcp_bearer_tokens 范围
HTTP连接引用了密钥
copula自动添加 Authorization: Bearer <token> 头球

📖 详细的身份验证机制： 请参阅中的“API身份验证类型”部分机密_解决方案.md

使用应用程序

网络界面

打开应用程序URL以访问：

聊天游乐场 -自然语言API注册和查询
API注册表 -查看、编辑、删除已注册的API
痕迹 -调试AI代理执行
MCP信息 -查看可用的MCP工具

工作流示例

You: "Register the FRED economic data API with my API key: abc123"
AI: ✅ Successfully registered "fred" with API key authentication

You: "Get GDP data from FRED, series GDPC1"
AI: [Retrieves API key from secrets, makes request]
    Here's the GDP data from the last 10 observations...

配置

环境变量(`.env.local`)

由自动创建 ./setup.sh:

DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=your-personal-access-token  # For local dev
DATABRICKS_SQL_WAREHOUSE_ID=your-warehouse-id  # Optional

# Optional: Override default secret scope names
MCP_API_KEY_SCOPE=mcp_api_keys
MCP_BEARER_TOKEN_SCOPE=mcp_bearer_tokens

认证

该应用程序使用 代表（OBO）身份验证 默认情况下：

用户使用copula OAuth进行身份验证
所有操作都在用户的权限下运行
适当的访问控制和审计日志记录

📖 海外建筑运营管理局详细信息： 看 app.yaml 项目根目录中的配置

发展

本地开发

# Start dev server with hot reload
./watch.sh

# Access at:
# - Frontend: http://localhost:5173
# - Backend: http://localhost:8000
# - API Docs: http://localhost:8000/docs

调试

# Check app status
./app_status.sh

# Stream app logs
uv run python dba_logz.py https://your-app.databricksapps.com --duration 60

# Format code
./fix.sh

多个环境

为dev/stating/prod部署单独的实例：

./deploy.sh --app-name mcp-dev-registry --create
./deploy.sh --app-name mcp-prod-registry --create

项目结构

├── server/                   # FastAPI backend
│   ├── app.py               # Main app + MCP server
│   ├── tools.py             # MCP tools implementation
│   └── routers/             # API endpoints
├── client/                  # React TypeScript frontend
│   └── src/pages/           # Chat, Registry, Traces pages
├── prompts/                 # Agent system prompts
├── setup_table.py           # DB table setup script
├── deploy.sh                # Deploy to Databricks Apps
├── setup.sh                 # Interactive setup
└── watch.sh                 # Local dev server

故障排除

部署问题-已创建应用程序，但代码不起作用

如果 ./deploy.sh 成功完成，但您的应用程序无法正常工作，请按照以下步骤操作：

1.检查应用程序日志（最重要）：

# View live logs
databricks apps logs <your-app-name> --follow

# Or visit in browser (requires OAuth):
# https://your-app.databricksapps.com/logz

2.验证应用程序状态：

./app_status.sh
# Should show: Status: RUNNING
# If status is FAILED or ERROR, check logs above

3.常见原因及解决方法：

问题	检查	修复
前端构建失败	`cd client && npm run build`	修复TypeScript错误，确保 `client/node_modules` 存在
缺少Python依赖项	`cat requirements.txt`	快跑 `uv run python scripts/generate_semver_requirements.py`
app.yaml配置错误	`cat app.yaml`	验证 `command` 和 `scopes` 是正确的
代码未上传	`databricks workspace ls /Workspace/Users/your.email@company.com/`	检查源路径是否存在，使用重新部署 `--verbose`
应用程序无法启动	检查应用程序日志	查找Python导入错误、缺少环境变量、端口冲突

4.使用详细输出重新部署：

./deploy.sh --verbose
# Shows detailed build and deployment steps

5.手动验证：

# Check app exists and get details
databricks apps get <your-app-name>

# Verify service principal was created
databricks apps get <your-app-name> --output json | grep service_principal_id

# Try restarting
databricks apps restart <your-app-name>

# Last resort: Delete and recreate
databricks apps delete <your-app-name>
./deploy.sh --create

身份验证失败：

运行： databricks current-user me 验证CLI身份验证
检查 .env.local 有正确 DATABRICKS_HOST

找不到表：

跑 setup_table.py 或通过SQL编辑器手动创建

秘密作用域错误：

# Verify scopes exist:
databricks secrets list-scopes | grep mcp_

# Verify service principal has access:
databricks secrets get-acl --scope mcp_api_keys --principal <service-principal-id>

# Check what secrets exist:
databricks secrets list-secrets --scope mcp_api_keys

应用程序无法访问：

检查部署： ./app_status.sh
查看日志： https://your-app.databricksapps.com/logz

注册后API调用失败：

验证密钥是否存在： databricks secrets list-secrets --scope mcp_api_keys
检查应用程序日志中的连接创建错误
对于API密钥验证：确保密钥在 mcp_api_keys 范围
对于承载令牌身份验证：确保令牌在 mcp_bearer_tokens 范围

📖 详细故障排除：

工作空间_要求.md -工作区设置问题
机密_解决方案.md -秘密范围问题

主要特点

MCP工具可用

该应用程序通过其MCP服务器公开这些工具：

smart_register_api -一步API注册，带有自动搜索功能
register_api_in_registry -API手动注册，完全受控
check_api_http_registry -列出并搜索已注册的API
discover_endpoints_from_docs -从文档URL中提取端点
test_api_endpoint -注册前验证端点
execute_dbsql -对仓库运行SQL查询

AI代理功能

聊天界面可以：

分析API文档以发现终结点
自动测试端点
使用适当的身份验证注册API
调用已注册的API以回答查询
为复杂的请求组合多个API调用

文档

工作空间_要求.md -先决条件、设置、工作区配置
机密_解决方案.md -秘密管理、身份验证类型、故障排除
安全.md -安全策略
许可证.md -许可证信息

许可证

看许可证.md

安全

报告漏洞：请参阅安全.md