Cybershuttle MCP 服务器

这是一个用于 Apache Cybershuttle 的模型上下文协议（MCP）服务器。该服务器使AI代理能够与Cybershuttle研究目录进行交互，支持对数据集、笔记本、模型、仓库、项目和会话进行自然语言查询和操作。

功能

• 完整的Cybershuttle API集成：封装了Cybershuttle研究服务的所有主要端点。
• MCP协议支持：完全兼容Model Context Protocol以实现AI代理集成。
• 认证：使用OAuth2设备流认证并管理令牌。
• 工具发现：通过全面的/tools端点实现代理能力发现。
• OpenAI集成：提供带有OpenAI函数调用的即用型演示。
• 资源管理：创建、读取、更新和删除所有资源类型的操作。
• 会话管理：启动和管理交互式研究会话。
• 项目组织：创建和管理包含多个资源的研究项目。

架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI代理       │    │   MCP服务器     │    │   Cybershuttle  │
│   (OpenAI)      │◄──►│                 │◄──►│   API           │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

• AI代理：具有函数调用能力的OpenAI GPT-4。
• MCP服务器：基于FastAPI的服务器，封装了Cybershuttle API。
• Cybershuttle API：Apache Airavata研究服务的REST端点。

预备条件

• Python 3.8+
• OpenAI API密钥（用于演示）
• 访问Cybershuttle平台（请联系dev@airavata.apache.org获取访问权限）

安装

1. 克隆仓库：

git clone https://github.com/cyber-shuttle/mcp-server.git
cd mcp-server

2. 创建虚拟环境：

python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

3. 安装依赖项：

pip install -r requirements.txt

4. 设置环境变量：

# 对于OpenAI演示所需
export OPENAI_API_KEY="your-openai-api-key"

# Cybershuttle访问令牌（通过设备流获得）
export CS_ACCESS_TOKEN="your-cybershuttle-token"

认证

服务器使用OAuth2设备流认证与真实的Cybershuttle平台进行交互：

获取认证令牌

1. 运行认证脚本：

python cybershuttle_auth.py

2. 按照提示操作：

   • 访问提供的URL
   • 输入设备码
   • 使用您的机构凭证登录

3. 导出令牌：

export CS_ACCESS_TOKEN="your-token-from-script"

认证使用以下内容：

• 认证服务器：https://auth.cybershuttle.org
• API服务器：https://api.dev.cybershuttle.org:18899
• 客户端ID：cybershuttle-agent

使用方法

1. 启动MCP服务器

python cybershuttle_mcp_server.py

服务器将在http://localhost:8000启动。您可以在http://localhost:8000/docs访问API文档。

2. 测试服务器

检查健康端点：

curl http://localhost:8000/health

列出可用工具：

curl http://localhost:8000/tools

3. 运行OpenAI演示

python cybershuttle_openai_demo.py

这将启动一个交互式聊天会话，您可以询问关于Cybershuttle目录的问题。

示例交互

这里是一些可以尝试的示例提示：

资源发现

• "展示目录中的所有数据集"
• "查找与机器学习相关的笔记本"
• "搜索关于深度学习的仓库"
• "目录中有哪些标签？"

资源管理

• "为气候研究创建一个新的数据集"
• "添加一个关于数据可视化的笔记本"
• "从GitHub导入一个仓库"

项目管理

• "为我的研究创建一个新的项目"
• "列出我所有的项目"
• "开始项目XYZ的会话"

会话管理

• "显示所有活动会话"
• "为我的机器学习项目开始新的会话"

API端点

MCP服务器提供了以下主要端点：

资源管理

• GET /resources - 列出所有资源并进行过滤
• GET /resources/{id} - 获取特定资源
• POST /resources/dataset - 创建数据集
• POST /resources/notebook - 创建笔记本
• POST /resources/repository - 创建仓库
• POST /resources/model - 创建模型
• GET /resources/search - 搜索资源
• GET /resources/tags - 获取所有标签

项目管理

• GET /projects - 列出项目
• POST /projects - 创建项目
• GET /projects/{owner_id} - 根据拥有者获取项目
• DELETE /projects/{id} - 删除项目

会话管理

• GET /sessions - 列出会话
• GET /hub/start-session/{project_id} - 开始会话
• GET /hub/resume-session/{session_id} - 恢复会话
• PATCH /sessions/{id} - 更新会话
• DELETE /sessions/{id} - 删除会话

工具发现

• GET /tools - 列出代理可用的所有工具
• GET /health - 健康检查

监控和日志

服务器包括全面的日志和监控：

# 检查服务器健康状况
curl http://localhost:8000/health

# 监控日志
tail -f logs/cybershuttle_m_日志

测试

运行测试套件：

# 快速测试（仅限MCP服务器）
python test_cybershuttle_mcp.py --quick

# 完整测试套件
python test_cybershuttle_mcp.py

测试认证：

python cybershuttle_auth.py

故障排除

常见问题

1. 认证错误：

   • 确保CS_ACCESS_TOKEN正确设置
   • 检查令牌过期时间（令牌有效期约为2小时）
   • 验证API端点的可访问性

2. OpenAI集成问题：

   • 确保OPENAI_API_KEY已设置
   • 检查OpenAI账户信用额度
   • 验证函数定义是否与服务器端点匹配

3. 连接问题：

   • 检查Cybershuttle开发API是否可访问
   • 验证网络连接
   • 检查防火墙设置

调试模式

在调试模式下运行服务器：

python cybershuttle_mcp_server.py --debug

项目结构

mcp-server/
├── src/
│   ├── cybershuttle_mcp_server.py
│   ├── cybershuttle_auth.py
│   └── __init__.py
├── demos/
│   └── cybershuttle_openai_demo.py
├── tests/
│   └── test_cybershuttle_mcp.py
├── requirements.txt
├── cybershuttle.yml
└── README.md

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

此项目根据Apache 2.0许可证发布。

致谢

• Apache Airavata团队为Cybershuttle平台
• OpenAI为函数调用能力
• Model Context Protocol社区