# scorpio

**Repository Path**: MarsBighead/scorpio

## Basic Information

- **Project Name**: scorpio
- **Description**: MCP Client with web console to integrate different providers, models and multiple MCP servers.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://gitee.com/MarsBighead/scorpio
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-05-21
- **Last Updated**: 2025-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI, MCP

## README

# Scorpio

<div align="center">
  <img src="frontend/public/scorpio.svg" width="120" height="120" />
  <h2>Scorpio</h2>
  <p>基于MCP协议的AI Agent原型研究框架</p>
  <div>
    <a href="README.md">English Version</a> | 
    <a href="https://github.com/">GitHub</a> | 
    <a href="#目录">文档</a>
  </div>
</div>

## 目录

- [项目概述](#项目概述)
- [核心功能](#核心功能)
- [系统架构](#系统架构)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [MCP服务器集成](#mcp服务器集成)
- [API参考](#api参考)
- [开发指南](#开发指南)
- [部署说明](#部署说明)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 项目概述

Scorpio是一个面向研究的框架，旨在探索基于MCP（Model Context Protocol，模型上下文协议）构建简单、易于理解的AI Agent原型。它提供了统一的接口来集成不同的AI提供商、模型和多个MCP服务器，为深入研究AI应用奠定基础。关于MCP的更多信息，请参阅[官方文档](https://modelcontextprotocol.io/docs/getting-started/intro)。

Scorpio的主要目标是通过以下方式简化AI Agent开发的复杂局面：

- 模块化架构，便于扩展
- 与各种AI模型和服务的无缝集成
- 通过MCP服务器实验Agent能力的工具
- 用于交互式测试和可视化的基于Web的控制台

## 核心功能

- **多模型支持**：统一接口，支持使用不同的AI模型
- **MCP协议实现**：与MCP服务器的强大集成，增强Agent能力
- **Agent框架**：用于研究目的的简单而强大的Agent架构
- **交互式Web控制台**：用户友好的界面，用于测试和可视化Agent行为
- **WebSocket通信**：与AI模型和Agent的实时交互
- **可扩展架构**：易于扩展新的提供商、模型和功能
- **容器化部署**：使用Docker简化环境设置

## 系统架构

Scorpio采用模块化、分层架构，实现关注点分离并提高灵活性：

1. **后端服务**（Python/FastAPI）

   - **API层**：REST和WebSocket端点，用于客户端-服务器通信
   - **服务层**：业务逻辑实现
   - **核心层**：MCP客户端、模型抽象和Agent实现
   - **Agent Hub**：用于不同用例的预构建Agent集合
2. **前端应用**（React 19/TypeScript）

   - **UI组件**：可重用的界面元素
   - **API客户端**：用于后端通信的前端服务
   - **状态管理**：客户端状态处理
3. **MCP集成**

   - 管理与多个MCP服务器的连接
   - 协议实现，用于标准化通信

## 技术栈

### 后端

- **Python 3.10+**：主要编程语言
- **FastAPI**：现代、快速（高性能）的Web框架
- **Uvicorn**：用于运行FastAPI的ASGI服务器
- **uv**：Python包管理器和虚拟环境工具
- **fastmcp**：MCP协议实现库
- **Pydantic**：数据验证和设置管理

### 前端

- **React 19**：UI库
- **TypeScript**：JavaScript的类型化超集
- **Vite**：构建工具和开发服务器
- **Ant Design**：UI组件库
- **React Router**：客户端路由

### 部署

- **Docker**：容器化平台
- **Docker Compose**：多容器编排

## 快速开始

### 前提条件

- Python 3.10+
- Node.js 22+
- uv包管理器
- Docker（用于容器化部署）

### 后端设置

1. **创建并激活虚拟环境**

```shell
# 创建虚拟环境
uv venv --prompt scorpio

# 激活虚拟环境
source .venv/bin/activate  # Unix/MacOS系统
# 或
source .venv/Scripts/activate  # Windows系统
```

2. **安装依赖**

```shell
uv pip sync pyproject.toml
```

3. **配置pip镜像（可选）**

在 `uv.toml`中添加以加速包下载：

```toml
[pip]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
```

4. **启动开发服务器**

```shell
# 从项目根目录
uvicorn py.scorpio.main:app --reload

# 或从py目录
cd py
uvicorn scorpio.main:app --reload
```

后端服务将在 http://127.0.0.1:8000 可用

### 前端设置

1. **导航到前端目录**

```shell
cd frontend
```

2. **安装依赖**

```shell
npm install
```

3. **启动开发服务器**

```shell
npm run dev
```

前端应用将在 http://localhost:5173 可用

## MCP服务器集成

Scorpio使用 `fastmcp`库进行MCP服务器集成。本节说明如何运行和与MCP服务器交互。

### 启动MCP服务器

```shell
# 使用自定义端口和传输协议启动
fastmcp run server.py --transport streamable-http --port 9000
```

### 使用MCP Inspector进行调试

```shell
fastmcp dev server.py
```

MCP Inspector将在 http://127.0.0.1:6274 可用

### 命令行选项

```shell
fastmcp run server.py --help
```

有关MCP协议和实现的详细信息，请参阅[官方fastmcp文档](https://gofastmcp.com/)。

## API参考

### 聊天API

- **WebSocket聊天**：`/api/chat/ws` - 实时聊天接口
- **HTTP聊天**：`/api/chat` - 单次请求-响应聊天端点
- **聊天历史**：`/api/chat/history` - 检索聊天历史

### 认证API

- **登录**：`/api/auth/login` - 用户认证
- **注销**：`/api/auth/logout` - 结束用户会话
- **用户信息**：`/api/auth/me` - 检索当前用户信息

## 开发指南

### 项目结构

#### 后端

- `py/scorpio/`：主要后端源代码
  - `agenthub/`：Agent实现
  - `core/`：核心组件（MCP客户端、模型等）
  - `services/`：业务逻辑服务
  - `routers/`：API路由定义
  - `schemas/`：数据模型和验证

#### 前端

- `frontend/src/`：主要前端源代码
  - `components/`：React组件
  - `api/`：API客户端服务
  - `types/`：TypeScript类型定义
  - `utils/`：实用函数

### 添加新的AI模型

1. 在 `py/scorpio/core/providers/`中扩展模型配置
2. 在 `frontend/src/types/`中更新前端类型定义
3. 重启后端服务以应用更改

### 实现新的MCP服务器

1. 在 `py/mcp_servers/`中创建新的MCP服务器实现
2. 确保服务器使用 `streamable-http`传输协议
3. 更新配置以包含新服务器
4. 重启后端服务

## 部署说明

### 构建后端

```shell
# 创建生产环境依赖
uv pip compile pyproject.toml -o requirements.txt

# 构建Docker镜像
docker build -t scorpio-backend -f images/scorpio/Dockerfile .
```

### 构建前端

```shell
cd frontend
npm run build
```

构建产物将在 `frontend/dist`目录中可用

### Docker Compose部署

```shell
docker-compose -f resource/basic/docker-compose.yaml up -d
```

## 贡献指南

欢迎为Scorpio做出贡献！请遵循以下步骤：

1. Fork仓库
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建拉取请求

## 许可证

本项目采用宽松的MIT许可证开源,详情请参阅[LICENSE](LICENSE)文件。