Guepard MCP SERVER

Guepard MCP Server - 完整 API 实现

面向 Guepard 数据库管理平台的综合 Model Context Protocol（MCP）服务，通过模块化组织提供对所有 Guepard API 的访问。

🚀 快速开始

使用 Docker Hub 镜像

# Pull the image
docker pull mghassen/guepard-custom-mcp:latest

# Run the MCP server
docker run --rm -i -e ACCESS_TOKEN="your_guepard_token" mghassen/guepard-custom-mcp:latest

与 Cursor 搭配使用

将以下内容添加到 Cursor MCP 设置（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "guepard": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "ACCESS_TOKEN=your_guepard_token", "mghassen/guepard-custom-mcp:latest"],
      "env": {}
    }
  }
}

本地开发

# Clone the repository
git clone <repository-url>
cd guepard-mcp-server

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export ACCESS_TOKEN="your_guepard_token"
export GUEPARD_API_URL="https://api.guepard.run"
export GUEPARD_AUTH_API="https://auth.guepard.run"
export SUPABASE_ANON_KEY="your_supabase_key"

# Run the server
python main.py

🛠️ 可用工具

此 MCP 服务通过模块化组织，提供对所有 Guepard API 的全面访问：

🔐 身份验证

• login_supabase - 使用 Supabase 身份验证登录
• refresh_token_supabase - 使用 Supabase 刷新访问令牌
• logout_supabase - 使用 Supabase 登出并使令牌失效

🚀 部署

• list_deployments - 获取所有部署（可选筛选）
• create_deployment - 创建新的数据库部署
• get_deployment - 获取部署详情
• update_deployment - 更新部署
• delete_deployment - 删除部署

🌿 分支

• list_branches - 获取部署的分支
• create_branch_from_snapshot - 从快照创建新分支
• update_branch - 更新分支

🔄 检出

• checkout_branch - 检出到指定快照
• checkout_snapshot - 检出到部署中的随机快照

📸 快照

• create_snapshot - 创建快照
• list_snapshots_deployment - 获取部署的快照
• list_snapshots_branch - 获取分支的快照

🏗️ 影子部署

• list_shadows_for_deployment - 列出指定部署的影子部署
• list_all_shadows - 列出所有影子部署
• create_shadow - 从快照创建新的影子部署

🖥️ 节点

• list_nodes - 获取所有节点
• create_node - 创建新节点
• get_node - 获取节点详情

⚡ 性能配置

• list_performance_profiles - 获取所有性能配置
• create_performance_profile - 创建性能配置
• update_performance_profile - 更新性能配置
• apply_performance_profile - 将性能配置应用到部署

💻 计算资源

• get_compute_status - 获取计算资源状态
• get_compute - 获取计算资源信息
• start_compute - 启动部署的计算资源
• stop_compute - 停止部署的计算资源

📊 日志与指标

• get_deployment_logs - 获取部署日志
• get_deployment_metrics - 获取部署指标

👥 数据库用户

• list_database_users - 获取部署的数据库用户
• create_database_user - 创建数据库用户
• update_database_user - 更新数据库用户
• delete_database_user - 删除数据库用户
• grant_privileges - 向数据库用户授予权限
• revoke_privileges - 撤销数据库用户的权限
• list_user_privileges - 列出数据库用户的权限

🔑 令牌

• list_tokens - 获取所有令牌
• generate_token - 生成新令牌
• revoke_token - 撤销令牌

📡 通知与订阅

• subscribe_deployment - 订阅部署通知
• unsubscribe_deployment - 取消订阅部署通知
• list_subscriptions - 列出所有部署订阅
• manage_subscriptions - 管理多个部署订阅

🛠️ 实用工具

• test_connection - 测试与 Guepard API 的连接
• list_configurations - 列出可用的预定义配置
• get_configuration - 获取当前服务配置

📋 先决条件

• 已安装并运行 Docker（用于 Docker）
• Python 3.12+（用于本地开发）
• 有效的 Guepard 访问令牌
• Cursor IDE（用于 MCP 集成）

🔧 配置

环境变量

必需：

• ACCESS_TOKEN：你的 Guepard 平台访问令牌

可选：

• GUEPARD_API_URL：Guepard API 基础 URL（默认为 https://api.guepard.run）
• GUEPARD_AUTH_API：Guepard 身份验证 API URL（默认为 https://auth.guepard.run）
• SUPABASE_ANON_KEY：用于身份验证的 Supabase 匿名密钥
• POSTGRES16_PROFILE_ID：PostgreSQL 16 的性能配置文件 ID
• POSTGRES17_PROFILE_ID：PostgreSQL 17 的性能配置文件 ID

工具启用（新增！）：

• GUEPARD_CONFIG：使用预定义配置（minimal、read_only、production、development、monitoring）
• GUEPARD_ENABLED_MODULES：要启用的模块列表，以逗号分隔
• GUEPARD_ENABLED_TOOLS：要启用的特定工具列表，以逗号分隔
• GUEPARD_DISABLED_TOOLS：要禁用的工具列表，以逗号分隔
• GUEPARD_DISABLED_MODULES：要禁用的模块列表，以逗号分隔

使用示例

# Test the connection (all tools enabled)
docker run --rm -i -e ACCESS_TOKEN="your_token" mghassen/guepard-custom-mcp:latest

# Use predefined configuration (minimal tools)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_CONFIG="minimal" mghassen/guepard-custom-mcp:latest

# Use predefined configuration (read-only)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_CONFIG="read_only" mghassen/guepard-custom-mcp:latest

# Use predefined configuration (production-safe)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_CONFIG="production" mghassen/guepard-custom-mcp:latest

# Custom configuration (specific tools only)
docker run --rm -i -e ACCESS_TOKEN="your_token" -e GUEPARD_ENABLED_TOOLS="test_connection,list_deployments,get_deployment,start_compute,stop_compute" mghassen/guepard-custom-mcp:latest

# In Cursor, ask:
# "Test my Guepard connection"
# "Get all my deployments"
# "Create a new deployment with PostgreSQL 17"
# "Start compute for deployment xyz"
# "Create a database user with specific privileges"
# "List available configurations"
# "Get current configuration"

⚙️ 工具启用与配置

Guepard MCP Server 现在支持有选择地启用工具和模块，让你能够针对不同用例构建自定义配置。

🚀 预定义配置

配置	描述	用例
minimal	仅进行最基本的部署管理	基本操作
read_only	对部署和监控进行只读访问	监控仪表板
production	不包含危险操作的生产环境	生产部署
development	包含所有工具的完整开发环境	开发工作
monitoring	仅用于监控和可观测性	系统监控

🛠️ 自定义配置示例

# Enable only specific modules
docker run --rm -i \
  -e ACCESS_TOKEN="your_token" \
  -e GUEPARD_ENABLED_MODULES="deployments,compute" \
  mghassen/guepard-custom-mcp:latest

# Enable only specific tools
docker run --rm -i \
  -e ACCESS_TOKEN="your_token" \
  -e GUEPARD_ENABLED_TOOLS="test_connection,list_deployments,get_deployment,start_compute,stop_compute" \
  mghassen/guepard-custom-mcp:latest

# Disable dangerous operations
docker run --rm -i \
  -e ACCESS_TOKEN="your_token" \
  -e GUEPARD_DISABLED_TOOLS="delete_deployment,delete_database_user,revoke_token" \
  mghassen/guepard-custom-mcp:latest

🔍 配置验证

使用内置工具验证配置：

• list_configurations - 列出所有可用的预定义配置
• get_configuration - 获取当前服务的配置详情

🏗️ 项目结构

guepard-mcp-server/
├── src/
│   └── guepard_mcp/
│       ├── auth/           # Authentication tools
│       ├── deployments/   # Deployment management
│       ├── branches/       # Branch management
│       ├── snapshots/      # Snapshot management
│       ├── shadows/        # Shadow deployment management
│       ├── nodes/          # Node management
│       ├── performance/    # Performance profiles
│       ├── compute/        # Compute management
│       ├── users/          # Database users
│       ├── tokens/         # Token management
│       ├── utils/          # Base classes and utilities
│       └── server.py       # Main server implementation
├── main.py                 # Entry point
├── requirements.txt        # Python dependencies
├── Dockerfile             # Docker configuration
└── README.md              # This file

🐳 Docker 镜像

• mghassen/guepard-custom-mcp:latest - 最新版本
• mghassen/guepard-custom-mcp:2.0.0 - 稳定版 2.0.0

🔍 故障排除

常见问题

1. “ACCESS_TOKEN is required”

   • 确保已设置 ACCESS_TOKEN 环境变量
   • 验证令牌是否有效

2. “Cursor 中没有可用工具”

   • 更新 mcp.json 后重启 Cursor
   • 检查 Docker 是否正在运行
   • 验证镜像是否已拉取：docker pull mghassen/guepard-custom-mcp:latest

3. 连接问题

   • 先测试连接：docker run --rm -i -e ACCESS_TOKEN="your_token" mghassen/guepard-custom-mcp:latest
   • 检查互联网连接
   • 验证 Guepard 凭据是否有效

4. 身份验证错误

   • 确保已设置 SUPABASE_ANON_KEY，以用于身份验证操作
   • 验证 GUEPARD_AUTH_API 是否正确

调试模式

启用调试日志运行：

docker run --rm -i -e ACCESS_TOKEN="your_token" -e DEBUG=true mghassen/guepard-custom-mcp:latest

📚 API 参考

工具参数

身份验证工具

• login_supabase：email（必需）、password（必需）
• refresh_token_supabase：refresh_token（必需）
• logout_supabase：refresh_token（必需）

部署工具

• list_deployments：status（可选）、limit（可选）
• create_deployment：repository_name（必需）、performance_profile_id（必需），以及可选字段
• get_deployment：deployment_id（必需）
• update_deployment：deployment_id（必需），以及要更新的字段
• delete_deployment：deployment_id（必需）

分支工具

• list_branches：deployment_id（必需）
• create_branch_from_snapshot：deployment_id、branch_id、snapshot_id、branch_name（均为必需），is_ephemeral（可选）
• update_branch：deployment_id、branch_id（必需），以及要更新的字段

检出工具

• checkout_branch：deployment_id、branch_id、snapshot_id（均为必填）
• checkout_snapshot：deployment_id（必填），以及可选参数

快照工具

• create_snapshot：deployment_id、branch_id、snapshot_comment（均为必填）
• list_snapshots_deployment：deployment_id（必填）
• list_snapshots_branch：deployment_id、branch_id（均为必填）

Shadow 工具

• list_shadows_for_deployment：deployment_id（必填）
• list_all_shadows：无参数
• create_shadow：deployment_id、snapshot_id、repository_name、branch_name、performance_profile_id（均为必填）

节点工具

• list_nodes：无参数
• create_node：label_name、node_type、memory、cpu、storage（必填），以及可选字段
• get_node：node_id（必填）

性能配置文件工具

• list_performance_profiles：无参数
• create_performance_profile：label_name、min_cpu、min_memory（必填），以及可选字段
• update_performance_profile：performance_profile_id（必填），以及要更新的字段
• apply_performance_profile：deployment_id、performance_profile_id（均为必填）

计算工具

• get_compute_status：deployment_id（必填）
• get_compute：deployment_id（必填）
• start_compute：deployment_id（必填），notify（可选）
• stop_compute：deployment_id（必填），notify（可选）

日志与指标工具

• get_deployment_logs：deployment_id（必填），lines（可选）、level（可选）、component（可选）
• get_deployment_metrics：deployment_id（必填），time_range（可选）、metric_type（可选）

数据库用户工具

• list_database_users：deployment_id（必填）
• create_database_user：deployment_id、username、password（必填），privileges（可选）
• update_database_user：deployment_id、username（必填），password（可选）
• delete_database_user：deployment_id、username（必填）
• grant_privileges：deployment_id、username、privileges（均为必填）
• revoke_privileges：deployment_id、username、privileges（均为必填）
• list_user_privileges：deployment_id、username（均为必填）

令牌工具

• list_tokens：无参数
• generate_token：name（必填），expires_in（可选）
• revoke_token：token_id（必填）

通知与订阅工具

• subscribe_deployment：deployment_id（必填）
• unsubscribe_deployment：deployment_id（必填）
• list_subscriptions：无参数
• manage_subscriptions：action（必填），deployment_ids（必填）

实用工具

• test_connection：无参数
• list_configurations：无参数
• get_configuration：无参数

🆘 支持

• 问题反馈：在 GitHub 上报告问题
• 文档：查看主 README.md
• Guepard 平台：访问 guepard.run

📄 许可证

MIT 许可证——详情请参阅 LICENSE 文件。

---

即可开始使用！ 拉取镜像，并使用 Cursor 开始管理 Guepard 部署！🎉