# Gangtise Ultra MCP Server

标准化的港股/研报数据 MCP Server，基于 **FastMCP** 框架，使用 Streamable HTTP 传输协议。

## 特性

- 🚀 **FastMCP 标准化** - 严格遵循 MCP 协议标准，使用 Pydantic V2 Literal 类型生成干净的 JSON Schema
- 📊 **丰富的资源类型** - 支持券商研报、首席观点、公司公告等 8 种资源类型
- 🔍 **智能搜索** - 支持单条搜索和批量搜索，Literal 类型严格约束参数
- 📝 **预设提示词** - 内置每日简报、竞对分析、投资逻辑等场景模板
- 🔗 **资源溯源** - 支持通过 URI 获取文档原文
- ⚡ **高性能** - 标准中间件栈（缓存/日志/错误处理）+ 并发控制 + 指数退避重试

## 项目结构

```
gangtise_ultra/
├── main.py                 # 入口 + 中间件栈配置
├── config.py               # 环境变量配置
├── ecosystem.config.js     # PM2 配置
├── pyproject.toml          # 项目依赖
├── core/
│   ├── auth.py             # 认证（TokenVerifier + URL 签名）
│   ├── client.py           # HTTP 客户端（重试 / 并发控制）
│   ├── utils.py            # 时间解析 / 结果清洗 / URL 签名
│   └── exceptions.py       # 异常定义
├── models/
│   ├── enums.py            # 枚举类型（资源类型 / 知识库 / 时间范围）
│   └── api_schema.py       # Pydantic 模型（内部使用）
├── features/
│   ├── tools.py            # MCP Tools（Literal 类型 + ToolError）
│   ├── resources.py        # MCP Resources
│   ├── prompts.py          # MCP Prompts
│   └── http_routes.py      # HTTP 代理路由
├── assets/
│   └── prompts.json        # 提示词模板
└── logs/                   # 日志目录
```

## 快速开始

### 1. 配置环境变量

创建 `.env` 文件：

```bash
# Gangtise API 认证（二选一）
# 方式一：直接使用 accessToken
GANGTISE_API_KEY=your_access_token

# 方式二：使用 accessKey/secretAccessKey
GANGTISE_ACCESS_KEY=your_access_key
GANGTISE_SECRET_KEY=your_secret_key

# MCP Server 配置
FASTMCP_PORT=8009
```

### 2. 安装依赖

```bash
cd /home/gangtise_ultra
pip install -e .
# 或
pip install fastmcp pydantic pydantic-settings httpx python-dotenv
```

### 3. 启动服务

#### 直接运行
```bash
python main.py
```

#### 使用 PM2
```bash
pm2 start ecosystem.config.js
pm2 logs gangtise-ultra
```

## API 概览

### Tools (工具)

| 工具名 | 描述 |
|-------|------|
| `search_knowledge` | 知识库搜索，支持资源类型、时间范围等筛选 |
| `batch_search` | 批量搜索，一次最多 5 个查询 |
| `get_resource_types` | 获取所有支持的资源类型 |

### Resources (资源)

| URI | 描述 |
|-----|------|
| `gangtise://document/{type}/{id}` | 获取文档原文/溯源链接 |
| `gangtise://knowledge/{query}` | 快速搜索 |
| `gangtise://api/status` | 服务状态 |
| `gangtise://help` | 使用帮助 |
| `gangtise://schema/tools` | 工具 Schema |

### Prompts (提示词)

| 提示词 | 描述 |
|-------|------|
| `daily_briefing` | 每日简报 - 行业最新动态 |
| `competitor_analysis` | 竞对分析 - 竞争格局分析 |
| `investment_thesis` | 投资逻辑 - 投资框架整理 |
| `market_sentiment` | 市场情绪 - 板块情绪分析 |
| `event_tracking` | 事件追踪 - 事件影响跟踪 |
| `summarize_report` | 报告总结 - 研报要点提取 |
| `knowledge_analysis` | 知识分析 - 主题深度分析 |
| `system_context` | 系统上下文 - 输出规范设置 |

## 资源类型

| 名称 | 值 | 描述 | 可下载 |
|-----|----|----|-------|
| `BROKER_REPORT` | 10 | 券商研究报告 | ✅ |
| `INTERNAL_REPORT` | 20 | 内部研究报告 | ✅ |
| `ANALYST_OPINION` | 40 | 首席分析师观点 | ❌ |
| `COMPANY_NOTICE` | 50 | 公司公告 | ✅ |
| `MEETING_MINUTES` | 60 | 会议平台纪要 | ✅ |
| `SURVEY_NOTES` | 70 | 调研纪要公告 | ✅ |
| `WEB_RESOURCE` | 80 | 网络资源纪要 | ✅ |
| `INDUSTRY_OFFICIAL` | 90 | 产业公众号 | ✅ |

## 知识库类型

| 名称 | 值 | 描述 |
|-----|----|----|
| `SYSTEM` | system_knowledge_doc | 系统库（目前唯一可用） |

## 时间范围

| 值 | 描述 |
|---|------|
| `1d` | 近 1 天 |
| `1w` | 近 1 周 |
| `1m` | 近 1 月（默认）|
| `1q` | 近 1 季度 |
| `6m` | 近 6 月 |
| `1y` | 近 1 年 |
| `all` | 全部时间 |

## 使用示例

### 搜索比亚迪研报

```json
{
  "tool": "search_knowledge",
  "arguments": {
    "query": "比亚迪",
    "resource_types": ["BROKER_REPORT"],
    "time_range": "1m",
    "top": 5
  }
}
```

### 批量查询多家公司

```json
{
  "tool": "batch_search",
  "arguments": {
    "queries": ["比亚迪", "宁德时代", "特斯拉"],
    "resource_types": ["BROKER_REPORT", "ANALYST_OPINION"],
    "top": 3
  }
}
```

### 使用每日简报提示词

```json
{
  "prompt": "daily_briefing",
  "arguments": {
    "industry": "新能源汽车",
    "company": "比亚迪"
  }
}
```

## 参数标准化

本服务使用 **Literal 类型** 和 **Pydantic Field 约束** 生成严格、干净的 JSON Schema，
使 LLM 客户端能准确理解每个参数的类型和可选值：

| 参数 | 类型 | 约束 |
|-----|------|------|
| `query` | `string` | 必填 |
| `top` | `integer` | 范围 1-20，默认 10 |
| `resource_types` | `array[Literal]` | 可选，枚举值见下方资源类型表 |
| `time_range` | `Literal` | 枚举: 1d, 1w, 1m, 1q, 6m, 1y, all |

错误处理遵循 MCP 标准：
- **参数校验错误** → FastMCP/Pydantic 自动返回结构化验证错误
- **业务逻辑错误** → 通过 `ToolError` 返回 MCP 标准错误响应
- **未预期异常** → 框架自动捕获并返回安全的错误信息

## PM2 常用命令

```bash
# 启动服务
pm2 start ecosystem.config.js

# 查看日志
pm2 logs gangtise-ultra

# 重启服务
pm2 restart gangtise-ultra

# 停止服务
pm2 stop gangtise-ultra

# 删除服务
pm2 delete gangtise-ultra

# 监控面板
pm2 monit

# 保存进程列表（开机自启）
pm2 save
pm2 startup
```

## 配置说明

### 环境变量

| 变量名 | 默认值 | 描述 |
|-------|-------|------|
| `GANGTISE_API_KEY` | - | 直接使用的 accessToken |
| `GANGTISE_ACCESS_KEY` | - | 用于获取 token 的 accessKey |
| `GANGTISE_SECRET_KEY` | - | 用于获取 token 的 secretAccessKey |
| `FASTMCP_PORT` | 8009 | 服务端口 |
| `FASTMCP_HOST` | 0.0.0.0 | 监听地址 |
| `GANGTISE_API_CONCURRENCY` | 3 | API 并发限制 |
| `GANGTISE_CACHE_TTL_SECONDS` | 900 | 缓存 TTL（秒）|
| `GANGTISE_REQUEST_TIMEOUT` | 20 | 请求超时（秒）|
| `GANGTISE_MAX_RETRIES` | 3 | 最大重试次数 |

## 技术栈

- **FastMCP 2.5+** - MCP Server 框架（含标准中间件支持）
- **Pydantic V2** - 数据验证 + JSON Schema 生成
- **httpx** - 异步 HTTP 客户端
- **uvicorn** - ASGI 服务器
- **PM2** - 进程管理

## License

MIT