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 文件：

# 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. 安装依赖

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

3. 启动服务

直接运行

python main.py

使用 PM2

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	全部时间

使用示例

搜索比亚迪研报

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

批量查询多家公司

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

使用每日简报提示词

{
  "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 常用命令

# 启动服务
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