MCP API registry

🔌 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

安装脚本将提示您：

⚠️ 重要提示：使用个人访问令牌（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)

部署过程中会发生什么：

1. ✅ 构建前端 -将React TypeScript编译为静态资产
2. ✅ 打包后端 -准备FastAPI服务器和MCP工具
3. ✅ 创建copula应用程序 -在工作区中注册您的应用程序
4. ✅ 生成服务主体 -自动为您的应用程序创建服务主体
5. ✅ 将代码部署到应用程序 -上传您的代码并自动将其附加到应用程序计算
6. ✅ 启动应用程序 -您的应用程序现在正在运行并可访问
7. ✅ 启用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：

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

此脚本的作用：

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

为什么需要这样做：

• 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（无授权）：

"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 头球

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

______________________________________________________________________

使用应用程序

网络界面

打开应用程序URL以访问：

1. 聊天游乐场 -自然语言API注册和查询
2. API注册表 -查看、编辑、删除已注册的API
3. 痕迹 -调试AI代理执行
4. 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  --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.常见原因及解决方法：

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

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

5.手动验证：

# Check app exists and get details
databricks apps get 

# Verify service principal was created
databricks apps get  --output json | grep service_principal_id

# Try restarting
databricks apps restart 

# Last resort: Delete and recreate
databricks apps delete 
./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 

# 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