# Uno MCP Server

[![PyPI version](https://badge.fury.io/py/uno-mcp.svg)](https://pypi.org/project/uno-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**All-in-One MCP Gateway with Skills** - 集成的 MCP 网关服务，通过 Skills 机制优化 LLM 上下文空间使用。

## 🎯 核心理念

Uno 是一个「MCP 元网关」，借鉴 Claude Skills 思想，通过分层索引机制实现按需加载工具定义，解决大量 MCP server 占用过多 LLM 上下文空间的问题。

```
┌─────────────────────────────────────────────────────────────────┐
│                    LLM 上下文空间                                │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │  常驻：Uno 的 4 个核心工具定义（~200 tokens）                 │ │
│  │  - get_servers: 描述中包含所有 server 名字和简介            │ │
│  │  - get_skill: 根据问题匹配 skill                           │ │
│  │  - call: 调用远程工具                                      │ │
│  │  - execute: 执行脚本（沙盒）                                │ │
│  └───────────────────────────────────────────────────────────┘ │
│                              ↓ 按需加载                         │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │  具体 tools 的详细定义（调用 get_servers/get_skill 后获得）  │ │
│  └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## ✨ 核心特性

- **🔧 核心工具**
  - `get_servers`: 工具描述中**内嵌所有 server 索引**，LLM 一眼就知道有哪些可用
  - `get_skill`: 智能匹配 Skill（跨 server 的工具组合）
  - `call`: 调用任意远程 MCP 工具
  - `execute`: 安全沙盒执行脚本

- **🎯 Skills 系统**
  - 预定义常用 Skill（旅游订票、网络研究、时间工具等）
  - 支持自定义 Skill（YAML 配置）
  - 智能语义匹配（关键词 + LLM）

- **🔐 安全认证**
  - OAuth 2.0 认证（复用 MCPMarket）
  - 用户隔离
  - 沙盒脚本执行

- **🖥️ 开发者 GUI**
  - 直观查看所有 Server 和 Tools
  - Skill 匹配测试
  - 调用日志和统计

## 🚀 快速开始

### 方式一：通过 PyPI 安装（推荐）

```bash
# 使用 uvx 直接运行（无需安装）
uvx uno-mcp

# 或使用 pip 安装
pip install uno-mcp
uno
```

### 方式二：从源码安装

```bash
# 克隆项目
git clone https://github.com/xray918/uno-mcp.git
cd uno-mcp

# 安装依赖
uv sync

# 运行
uv run uno
```

### 环境变量配置

Uno 开箱即用，所有配置都有合理的默认值。可选配置：

```bash
# OpenAI API Key（用于智能 Skill 匹配，可选）
export OPENAI_API_KEY=sk-your-api-key

# 运行服务器
uvx uno-mcp
```

详细配置说明请参考 [.env.example](.env.example) 文件。

### 开发模式

```bash
# 开发模式运行
DEBUG=True uvx uno-mcp

# 或从源码运行
DEBUG=True uv run uno
```

### 访问

- **GUI 控制台**: <http://localhost:8089/gui>
- **MCP 端点**: <http://localhost:8089/mcp>
- **API 文档**: <http://localhost:8089/.well-known/mcp.json>

## 📡 MCP 协议使用

### 1. 发现服务

```bash
curl http://localhost:8089/.well-known/mcp.json
```

### 2. 列出工具

```bash
curl -X POST http://localhost:8089/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

### 3. 获取 Server 详情

```bash
curl -X POST http://localhost:8089/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"tools/call",
    "params":{
      "name":"get_servers",
      "arguments":{"server_names":["time","fetch"]}
    },
    "id":2
  }'
```

### 4. 匹配 Skill

```bash
curl -X POST http://localhost:8089/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"tools/call",
    "params":{
      "name":"get_skill",
      "arguments":{"question":"帮我查一下北京到上海的机票"}
    },
    "id":3
  }'
```

### 5. 调用远程工具

```bash
curl -X POST http://localhost:8089/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"tools/call",
    "params":{
      "name":"call",
      "arguments":{
        "tool_name":"time.get_current_time",
        "arguments":{"timezone":"Asia/Shanghai"}
      }
    },
    "id":4
  }'
```

## 🎯 Skill 配置

Skills 定义在 `src/skills/presets/` 目录下，使用 YAML 格式：

```yaml
# travel.yaml
name: travel_booking
description: 旅游订票技能
tags:
  - 旅游
  - 订票
  - 酒店
keywords:
  - 订酒店
  - 订机票

instructions: |
  使用说明...

tools:
  - hotel.search_hotels
  - flight.search_flights
  - map.get_route
```

## 🏗️ 项目结构

```
uno/
├── src/
│   ├── main.py              # 入口
│   ├── server.py            # MCP Server
│   ├── config.py            # 配置
│   ├── tools/               # 核心工具
│   │   ├── get_servers.py   # 获取 servers
│   │   ├── get_skill.py     # 匹配 skill
│   │   ├── call.py          # 调用工具
│   │   └── execute.py       # 执行脚本
│   ├── skills/              # Skill 管理
│   │   ├── skill_manager.py
│   │   ├── matcher.py
│   │   └── presets/         # 预定义 skills
│   ├── registry/            # Server 注册
│   └── auth/                # OAuth 认证
├── gui/                     # 开发者界面
│   ├── templates/
│   └── static/
├── pyproject.toml
└── README.md
```

## 🔧 配置说明

### 必需配置

无。Uno 开箱即用，所有功能都有合理的默认值或降级方案。

### 可选配置

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `HOST` | 服务器地址 | `0.0.0.0` |
| `PORT` | 服务器端口 | `8089` |
| `DEBUG` | 调试模式 | `False` |
| `OPENAI_API_KEY` | OpenAI Key（智能 Skill 匹配） | - |
| `OPENAI_BASE_URL` | OpenAI API 地址 | - |
| `SKILL_MATCHER_MODEL` | 匹配模型 | `gpt-4o-mini` |
| `SANDBOX_TIMEOUT` | 脚本执行超时（秒） | `30` |

### 功能降级说明

- **未配置 `OPENAI_API_KEY`**：Skill 匹配将使用关键词模式，仍然可用

## 🛣️ 路线图

- [x] 核心工具实现（get_servers, get_skill, call, execute）
- [x] Skills 系统
- [x] OAuth 2.0 认证
- [x] 开发者 GUI
- [ ] 调用统计和分析
- [ ] Server 分组（Group）
- [ ] 第三方 Skill 提交
- [ ] WebSocket 支持

## 📄 License

MIT
