feat(mcp): hy3-research-assistant — Deep Research MCP Server

[cooldeveloper-code]

1. 🎯 项目简介

hy3-research-assistant-mcp 是一个基于 MCP（Model Context Protocol）协议的开源 Server，将腾讯 Hy3 的推理能力封装为即插即用的研究助手，接入 Cursor / CodeBuddy / WorkBuddy / Cline 等任意 MCP 客户端即可使用，无需额外开发。

应用场景：深度研究助手 — 网页搜索 + 文档阅读 + Hy3 深度分析 + 报告生成 + 个性化推荐

---

2. ✨ 核心亮点

亮点 说明

🔌 即插即用 ：stdio 模式，一条命令启动，兼容主流 MCP 客户端
🧠 Hy3 驱动 ： 核心推理调用 Hy3 API（OpenAI 兼容），支持 reasoning_effort 深度控制
📚 智能分类 ： 每次阅读文档自动 Hy3 分类，持久化用户兴趣历史
🔍 个性化推荐 ： 基于历史阅读数据，自动搜索最新网页并生成推荐
📦 一键安装 ：install.ps1 / install.sh，附完整 README 与中英文文档
🎬 Demo 可复现 ： 含 CLI Demo 脚本 + 10 帧动画 GIF，验证流程清晰

---

3. 🏗 架构

hy3-research-assistant-mcp/
├── pyproject.toml
├── README.md
├── .env.example
├── Makefile
├── src/
│ └── hy3_research_assistant_mcp/
│ ├── init.py
│ ├── server.py # MCP Server 主入口
│ ├── hy3_client.py # Hy3 API 封装
│ ├── search_client.py # 搜索客户端
│ ├── document_reader.py # 本地文件读取
│ ├── history_store.py # history_store.json 管理
│ └── tools/
│ ├── init.py
│ ├── search_web.py
│ ├── read_document.py
│ ├── read_and_classify.py
│ ├── get_recommendations.py
│ ├── deep_analyze.py
│ ├── synthesize_report.py
│ └── research_pipeline.py
├── prompts/
│ ├── classify.txt
│ ├── analyze.txt
│ ├── synthesize.txt
│ └── recommend.txt
└── examples/
├── codebuddy/
│ └── mcp_settings.json
├── cursor/
│ └── mcp.json
└── cline/
└── cline_mcp_settings.json

---

4. 🛠 MCP Tools（共 9 个）

Tool	功能	外部依赖
search_web	DuckDuckGo / Wikipedia 网页搜索	网络（无需 Key）
read_document	读取本地 .txt/.md/.csv/.json 等文档	本地文件
read_and_classify_document	读文档 + Hy3 自动分类 + 写入历史	Hy3 API
get_reading_history	查看用户阅读与分类历史	本地 JSON
get_personalized_recommendations	基于历史兴趣搜索最新网页并推荐	Hy3 API + 网络
deep_analyze	Hy3 结构化深度分析（摘要/发现/开放问题）	Hy3 API
synthesize_report	Hy3 生成 brief/detailed/executive 报告	Hy3 API
research_pipeline	一键：搜索 → 读文件 → 分析 → 报告	全部
get_interest_summary	聚合用户兴趣画像（分类统计、高频标签）	本地 JSON

---

5. 🆕 特色功能说明

1️⃣ 文档阅读自动分类（需求扩展）

用户每次调用 read_and_classify_document 时：

• Hy3 对文档输出 category / tags / summary
• 记录写入 ~/.hy3-research/reading_history.json
• 支持 HY3_HISTORY_DIR 自定义存储路径

2️⃣ 基于历史的个性化推荐（需求扩展）

用户调用 get_personalized_recommendations 时：

1. 从历史记录聚合兴趣画像（分类频次、高频标签）
2. 自动生成搜索关键词，检索最新网页
3. Hy3 结合历史 + 最新结果，输出个性化推荐列表

---

6. 📦 安装与配置

cd mcp-servers/hy3-research-assistant
./install.sh          # macOS/Linux
.\install.ps1         # Windows