# 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**: 2026-04-15

## 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>A Research Framework for MCP-based AI Agent Prototypes</p>
  <div>
    <a href="README_cn.md">中文版本</a> | 
    <a href="https://github.com/">GitHub</a> | 
    <a href="#documentation">Documentation</a>
  </div>
</div>

## Table of Contents

- [Project Overview](#project-overview)
- [Core Features](#core-features)
- [Architecture](#architecture)
- [Technology Stack](#technology-stack)
- [Getting Started](#getting-started)
- [MCP Server Integration](#mcp-server-integration)
- [API Reference](#api-reference)
- [Development Guide](#development-guide)
- [Deployment](#deployment)
- [Contributing](#contributing)
- [License](#license)

## Project Overview

Scorpio is a research-oriented framework designed to explore the implementation of simple, understandable AI agent prototypes based on the MCP (Model Context Protocol) protocol. It provides a unified interface to integrate different AI providers, models, and multiple MCP servers, serving as a foundation for in-depth AI application research. For more information about MCP, please refer to the [official documentation](https://modelcontextprotocol.io/docs/getting-started/intro).

The primary goal of Scorpio is to simplify the complex landscape of AI agent development by offering:

- A modular architecture for easy extension
- Seamless integration with various AI models and services
- Tools for experimenting with agent capabilities through MCP servers
- A web-based console for interactive testing and visualization

## Core Features

- **Multi-Model Support**: Unified interface for working with different AI models
- **MCP Protocol Implementation**: Robust integration with MCP servers for enhanced agent capabilities
- **Agent Framework**: Simple yet powerful agent architecture for research purposes
- **Interactive Web Console**: User-friendly interface for testing and visualizing agent behavior
- **WebSocket Communication**: Real-time interaction with AI models and agents
- **Extensible Architecture**: Easy to extend with new providers, models, and capabilities
- **Containerized Deployment**: Simplified environment setup using Docker

## Architecture

Scorpio follows a modular, layered architecture that separates concerns and enables flexibility:

1. **Backend Services** (Python/FastAPI)

   - **API Layer**: REST and WebSocket endpoints for client-server communication
   - **Service Layer**: Business logic implementation
   - **Core Layer**: MCP client, model abstractions, and agent implementations
   - **Agent Hub**: Collection of pre-built agents for different use cases

2. **Frontend Application** (React 19/TypeScript)

   - **UI Components**: Reusable interface elements
   - **API Clients**: Frontend services for backend communication
   - **State Management**: Client-side state handling

3. **MCP Integration**
   - Connection management to multiple MCP servers
   - Protocol implementation for standardized communication

## Technology Stack

### Backend

- **Python 3.10+**: Python version required for project scorpio
- **FastAPI**: Modern, fast (high-performance) web framework
- **Uvicorn**: ASGI server for running FastAPI
- **uv**: Python package manager and virtual environment tool
- **fastmcp**: Library for MCP protocol implementation
- **Pydantic**: Data validation and settings management

### Frontend

- **React 19**: UI library
- **TypeScript**: Typed superset of JavaScript
- **Vite**: Build tool and development server
- **Ant Design**: UI component library
- **React Router**: Client-side routing

### Deployment

- **Docker**: Containerization platform
- **Docker Compose**: Multi-container orchestration

## Getting Started

### Prerequisites

- Python 3.10+
- Node.js 22+
- uv package manager
- Docker (for containerized deployment)

### Backend Setup

1. **Create and activate virtual environment**

```shell
# Create virtual environment
uv venv --prompt scorpio

# Activate virtual environment
source .venv/bin/activate  # On Unix/MacOS
# or
source .venv/Scripts/activate  # On Windows
```

2. **Install dependencies**

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

3. **Configure pip mirror (optional)**

Add to `uv.toml` to accelerate package downloads:

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

4. **Start development server**

```shell
# From project root
uvicorn py.scorpio.main:app --reload

# Or from py directory
cd py
uvicorn scorpio.main:app --reload
```

Backend service will be available at http://127.0.0.1:8000

### Frontend Setup

1. **Navigate to frontend directory**

```shell
cd frontend
```

2. **Install dependencies**

```shell
npm install
```

3. **Start development server**

```shell
npm run dev
```

Frontend application will be available at http://localhost:5173

## MCP Server Integration

Scorpio uses the `fastmcp` library for MCP server integration. This section explains how to run and interact with MCP servers.

### Starting an MCP Server

```shell
# Start with custom port and transport protocol
fastmcp run server.py --transport streamable-http --port 9000
```

### Using MCP Inspector for Debugging

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

MCP Inspector will be available at http://127.0.0.1:6274

### Command Line Options

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

For detailed information about MCP protocol and implementation, please refer to the [official fastmcp documentation](https://gofastmcp.com/).

## API Reference

### Chat API

- **WebSocket Chat**: `/api/chat/ws` - Real-time chat interface
- **HTTP Chat**: `/api/chat` - Single request-response chat endpoint
- **Chat History**: `/api/chat/history` - Retrieve chat history

### Authentication API

- **Login**: `/api/auth/login` - User authentication
- **Logout**: `/api/auth/logout` - End user session
- **User Info**: `/api/auth/me` - Retrieve current user information

## Development Guide

### Project Structure

#### Backend

- `py/scorpio/`: Main backend source code
  - `agenthub/`: Agent implementations
  - `core/`: Core components (MCP client, models, etc.)
  - `services/`: Business logic services
  - `routers/`: API route definitions
  - `schemas/`: Data models and validation

#### Frontend

- `frontend/src/`: Main frontend source code
  - `components/`: React components
  - `api/`: API client services
  - `types/`: TypeScript type definitions
  - `utils/`: Utility functions

### Adding New AI Models

1. Extend the model configuration in `py/scorpio/core/providers/`
2. Update the frontend type definitions in `frontend/src/types/`
3. Restart the backend service to apply changes

### Implementing New MCP Servers

1. Create a new MCP server implementation in `py/mcp_servers/`
2. Ensure the server uses `streamable-http` transport protocol
3. Update the configuration to include the new server
4. Restart the backend service

## Deployment

### Building the Backend

```shell
# Create production requirements
uv pip compile pyproject.toml -o requirements.txt

# Build Docker image
docker build -t scorpio-backend -f images/scorpio/Dockerfile .
```

### Building the Frontend

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

Build artifacts will be available in `frontend/dist` directory

### Docker Compose Deployment

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

## Contributing

Contributions to Scorpio are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a pull request

## License

This project is open-sourced under the permissive MIT License. For details, please see the [LICENSE](LICENSE) file.