内容
# 研究智能服务器
一款生产级别的MCP（模型上下文协议）服务器，通过工具、资源和提示提供研究论文智能。
作为文章系列的配套实现：
- **第一部分：** [生产代理系统的MCP设计模式](https://medium.com/@shubhodaya.hampiholi/mcp-design-patterns-for-production-agentic-systems-b42c9fdb4b24)
- **第二部分：** [MCP内部：协议机制、原语和实现](https://medium.com/@shubhodaya.hampiholi/mcp-internals-protocol-mechanics-primitives-and-implementation-72d84fdb33e9)
---
## 服务器功能
服务器通过三个MCP原语，公开了跨越4个领域（机器学习、NLP、分布式系统、计算机视觉）的12篇精选研究论文的集合：
**工具** — 模型调用的动作：
- `搜索论文` — 按主题、领域、年份范围或引用阈值搜索
- `获取引用网络` — 遍历引用图到指定的深度和方向
- `比较论文` — 在指定维度上对2-4篇论文进行结构化比较
- `获取领域统计` — 某个研究领域的分析统计
**资源** — URI寻址数据：
- `research://papers` — 完整论文索引（仅元数据）
- `research://domains` — 领域索引，包含论文数量和热门标签
- `research://papers/{paper_id}` — 单篇论文全文
- `research://papers/{paper_id}/citations` — 论文的扁平引用列表
**提示** — 可重用的交互模板：
- `文献综述` — 某个主题的结构化文献综述
- `论文批评` — 特定论文的严格学术批评
- `研究空白分析` — 某个研究领域的空白分析
---
## 项目结构
```
src/research_server/
├── models/
│ └── domain.py # Pydantic领域模型 — 动态合约
├── data/
│ ├── papers.py # 静态模拟数据集（12篇论文）
│ └── store.py # 数据访问层
├── primitives/
│ ├── resources.py # 资源处理程序
│ ├── tools.py # 工具处理程序
│ └── prompts.py # 提示处理程序
├── server.py # 与传输无关的服务器组装
├── transport/
│ ├── stdio.py # stdio传输运行器
│ └── http.py # 可流式HTTP传输运行器
└── observability/
└── logging.py # 结构化JSON日志记录（仅stderr）
```
---
## 传输
### stdio（适用于本地客户端 — Claude Desktop, Cursor等）
```bash
uv run research-server-stdio
```
### 流式HTTP（适用于网络/远程客户端）
```bash
uv run research-server-http
```
服务器默认启动于 `http://127.0.0.1:8000/mcp/`。
环境变量：`HOST`，`PORT`，`LOG_LEVEL`
---
## Claude Desktop集成
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"research-intelligence-server": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/research-intelligence-server",
"research-server-stdio"
]
}
}
}
```
重启Claude Desktop。服务器的工具和提示将出现在界面中。
---
## 验证服务器
### stdio
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | uv run research-server-stdio 2>/dev/null
```
### 流式HTTP
```bash
# 终端1 — 启动服务器
uv run research-server-http
# 终端2 — 发送初始化请求
curl -L -X POST http://127.0.0.1:8000/mcp/ \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
```
## 设置
```bash
git clone https://github.com/YOUR_USERNAME/research-intelligence-server.git
cd research-intelligence-server
uv sync
```
### 运行测试
```bash
uv run pytest tests/ -v
```
### 运行stdio服务器
```bash
uv run research-server-stdio
```
### 运行HTTP服务器
```bash
uv run research-server-http
```
---
## 设计原则
- **与传输无关的服务器** — `server.py`在两种传输方式下相同
- **枚举而非布尔值** — 所有语义值都使用枚举以提高LLM推理清晰度
- **两个错误级别** — 协议错误与应用错误（`isError=True`）
- **`Paper`与`PaperSummary`** — 集合不会意外返回全文
- **结构化日志输出到stderr** — 在stdio传输中，stdout是协议通道
- **通过存储进行数据访问** — 原语不会直接导入原始数据
---
## 要求
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
