内容
# 研究智能MCP
学术论文发现、引用探索和研究智能工作流的生产结构化模型上下文协议（MCP）服务器。
研究智能MCP提供多个科学知识源的统一接口，同时暴露可被ChatGPT、Claude Desktop、Cursor、ResearchMind等AI系统以及自定义代理使用的标准化MCP工具。
*作为标准MCP服务器连接到Claude Desktop、Cursor或ResearchMind等应用程序*
*单个查询跨Semantic Scholar、arXiv，返回单个统一结果集*
*丰富的结构化论文元数据——摘要、引用和开放访问链接——直接在对话中呈现*
---
# 动机
现代AI系统越来越多地需要访问外部研究知识。
学术信息分散在多个提供商中：
* Semantic Scholar
* arXiv
* OpenAlex
* CrossRef
* PubMed
* IEEE
* Springer
* Nature
每个提供商都暴露不同的API、模式、标识符和功能。
该项目通过提供以下功能解决了这个问题：
* 统一的论文模型
* 提供商抽象层
* 搜索联合
* 引用图探索
* 开放访问论文解析
* MCP兼容工具
---
# 功能
## 当前版本
### 学术搜索
* 搜索科学论文
* 搜索最近的arXiv出版物
* 检索论文元数据
* 发现相关论文
* 检索引用和参考文献
* 解析可用的开放访问PDF
### 架构
* 官方MCP Python SDK
* 异步Python架构
* 提供商抽象层
* 规范化领域模型
* 结构化日志记录
* 重试策略
* 缓存支持
* 速率限制支持
* 生产质量项目结构
---
# 支持的提供商
## 第一阶段
* Semantic Scholar
* arXiv
## 计划中的提供商
* CrossRef
* OpenAlex
* Papers With Code
* PubMed
* IEEE
* Springer Nature
---
# 示例用例
## 查找近期论文
```text
查找关于Agentic RAG的近期论文。
```
## 发现相关工作
```text
查找与LangGraph多智能体系统相关的论文。
```
## 引用探索
```text
哪些论文引用了原始RAG论文？
```
## 开放访问解析
```text
为这篇研究论文找到PDF。
```
## 研究代理集成
```text
ResearchMind
↓
研究智能MCP
↓
Semantic Scholar
arXiv
```
---
# 架构
```text
┌──────────────────────┐
│ MCP工具 │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ 服务 │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ 提供商抽象层 │
└──────────┬───────────┘
│
┌─────────┴─────────┐
│ │
▼ ▼
Semantic Scholar arXiv
```
---
# 项目结构
```text
research-intelligence-mcp/
├── src/
│ └── research_intelligence_mcp/
├── tests/
├── scripts/
│ └── generate_dev_token.py
├── deployment/
│ ├── ecs/
│ │ ├── task-definition.json
│ │ ├── service-connect-example.json
│ │ └── README.md
│ ├── observability/
│ │ ├── prometheus.yml
│ │ └── grafana/
│ └── scripts/
│ ├── smoke_test.py
│ └── wait_for_ready.py
├── Dockerfile
├── .dockerignore
├── docker-compose.yml
├── pyproject.toml
├── README.md
└── .env.example
```
---
# 需求
* Python 3.12+
* uv
* Git
---
# 安装
克隆仓库：
```bash
git clone <仓库网址>
cd research-intelligence-mcp
```
创建虚拟环境：
```bash
uv venv
source .venv/bin/activate
```
安装依赖：
```bash
uv sync
```
创建环境文件：
```bash
cp .env.example .env
```
---
# 运行
运行MCP服务器：
```bash
uv run research-intelligence-mcp
```
或
```bash
python -m research_intelligence_mcp
```
---
# 质量检查
格式：
```bash
uv run ruff format .
```
检查：
```bash
uv run ruff check .
uv run ruff check . --fix
```
类型检查：
```bash
uv run mypy src
```
测试：
```bash
uv run pytest
```
软件包构建验证：
```bash
uv build
```
---
# MCP配置示例
```json
{
"mcpServers": {
"research-intelligence-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/research-intelligence-mcp",
"run",
"research-intelligence-mcp"
]
}
}
}
```
有关Claude Desktop、Cursor、MCP Inspector和远程`streamable-http`客户端（包括承载者JWT身份验证）的完整逐步说明，请参见
[`docs/research_intelligence_mcp_client_setup.md`](docs/research_intelligence_mcp_client_setup.md)。
---
# 使用MCP Inspector测试
官方MCP Inspector是查看注册的MCP工具、其模式、参数和执行结果的推荐交互式工具。在项目根目录中运行：
```bash
npx @modelcontextprotocol/inspector \
uv \
--directory "$(pwd)" \
run \
research-intelligence-mcp
```
Inspector应该在您的浏览器中打开。
然后：
连接MCP服务器
打开工具选项卡。
列出工具
选择health_check。
运行工具。
预期结构化结果：
```json
{
"status": "healthy",
"service": "研究智能MCP",
"server_name": "research-intelligence-mcp",
"version": "0.1.0",
"environment": "development",
"transport": "stdio",
"timestamp": "2026-07-20T..."
}
```
# 启动流程
```
main()
│
├── 加载设置
├── 配置stderr日志记录
├── 构建依赖容器
├── 创建FastMCP服务器
├── 注册工具
└── 运行stdio传输
```
# MCP工具
## 搜索工具
---
# 远程部署和身份验证
有关完整的部署指南（Docker、AWS ECS、机密、烟雾测试和剩余的手动AWS步骤），请参见
[`docs/research_intelligence_mcp_deployment_guide.md`](docs/research_intelligence_mcp_deployment_guide.md)。
摘要如下。
`stdio`仍然是默认的本地传输，不需要身份验证。
对于远程部署（例如，与ResearchMind集成），服务器还支持具有服务间承载者JWT身份验证的`streamable-http`传输：
```bash
MCP_TRANSPORT=streamable-http
AUTH_ENABLED=true
AUTH_ISSUER=https://auth.researchmind.ai
AUTH_AUDIENCE=research-intelligence-mcp
AUTH_JWKS_URL=https://auth.researchmind.ai/.well-known/jwks.json
```
有关完整的架构，请参见`docs/research_intelligence_mcp_authentication.md`，有关本地测试的逐步指南，请参见
`docs/research_intelligence_mcp_authentication_testing.md`，
有关每个`AUTH_*`和`MCP_*`设置的说明，请参见`.env.example`。
在`streamable-http`上，服务器还公开了未经身份验证的HTTP路由以及`/mcp`：
| 路由 | 目的 |
|---|---|
| `GET /health` | 仅限活跃度。永不调用Semantic Scholar或arXiv。 |
| `GET /ready` | 准备就绪。返回`503`，一旦开始优雅关闭。 |
| `GET /metrics` | Prometheus文本格式（工具、提供商、缓存和HTTP指标）。请保持此端点网络私有。 |
## 容器
构建和运行生产容器：
```bash
docker build -t research-intelligence-mcp:local .
docker run --rm -p 8000:8000 --env-file .env research-intelligence-mcp:local
```
镜像默认为`MCP_TRANSPORT=streamable-http`，绑定`0.0.0.0:8000`，
以非根用户身份运行，并为`/health`提供容器级`HEALTHCHECK`。
参见`Dockerfile`和`.dockerignore`。
## AWS ECS
参考（未应用的）任务定义和服务连接模板，
安全组指导和部署/回滚手册位于
`deployment/ecs/README.md`。
## 部署烟雾测试
```bash
uv run python deployment/scripts/wait_for_ready.py --base-url http://127.0.0.1:8000
uv run python deployment/scripts/smoke_test.py --base-url http://127.0.0.1:8000
```
`smoke_test.py`检查`/health`、`/ready`、`/metrics`、MCP会话
初始化、工具发现和身份验证的`health_check` +
`search_papers`调用。 当`AUTH_ENABLED=true`时，请传递`--auth-token`。
## 本地可观察性栈
### 为什么
`/metrics`本身只是在您访问时的时间快照——它无法告诉您arXiv的错误率在五分钟前是否飙升，
缓存是否实际上可以支付其成本，或者`search_papers`
在更改后是否变慢。这需要一些东西来重复抓取它
存储历史记录并让您查看趋势而不是一个
数字。`docker-compose.yml`运行它：MCP服务器、Prometheus和
Grafana，连接在一起。
```bash
docker compose up -d --build
```
| 服务 | URL | 角色 |
|---|---|---|
| Prometheus | http://127.0.0.1:9090 | **收集和存储指标。** 每15秒抓取`/metrics`到时间序列数据库，并回答PromQL查询（`rate(mcp_tool_requests_total[1m])`等）。其自身的UI功能性但不适合仪表盘。 |
| Grafana | http://127.0.0.1:3002 | **可视化** Prometheus存储的内容。没有自己的存储——它查询Prometheus并将结果呈现为图表。预配置了Prometheus数据源和10个面板的仪表盘（**仪表盘 → 研究智能MCP**，匿名查看器访问，无需登录）。 |
| MCP服务器 | http://127.0.0.1:8001 | 应用程序本身，在映射的主机端口上（`8000`通常已在使用中 - 在`docker-compose.yml`中更改它，如果`8001`也冲突）。 |
简而言之：Prometheus是记住指标随时间变化的数据库；
Grafana是通过它查看的窗口——两者在这里如果没有对方都不是很有用。
### 你实际上可以用它做什么
一旦流量通过（`uv run python deployment/scripts/smoke_test.py --base-url http://127.0.0.1:8001`，
或仅使用服务器），仪表盘的10个面板允许您：
- **实时查看工具使用情况** — 哪些MCP工具实际被调用，速率是多少，其p95延迟随时间变化（`mcp_tool_requests_total`，`mcp_tool_duration_seconds`）。
- **按原因捕获失败次数** — `mcp_tool_failures_total{error_type="ValidationError"}`与`{error_type="ProviderTransportError"}`的峰值立即告诉您是输入错误还是上游中断，而不是grep日志。
- **查看哪个提供商是瓶颈或失败者** — `provider_requests_total` / `provider_failures_total`，按`provider`（Semantic Scholar vs. arXiv）和`operation`（搜索、获取论文、引用...）分解，以便您不必猜测哪个提供商速度慢或限制您的速率。
- **判断缓存是否值得** — 缓存命中率面板（`cache_hits_total / (hits + misses)`）显示每个缓存（搜索vs.论文），重复查找是否实际上从内存中提供服务。
- **观察HTTP层负载** — 请求路由/状态码的速率和飞行中请求计数，有助于注意到重试、客户端行为不端或负载在成为真正的问题之前。
- **在Prometheus中临时查询任何内容** （http://127.0.0.1:9090/graph） — 仪表盘仅涵盖预建的面板；任何上述指标名称都可以使用PromQL实时查询和绘制。
此栈仅用于本地开发 — 它不作为上述ECS设置的一部分部署（尚未有任何指标收集这些指标；参见
部署指南）。 参见
`docs/research_intelligence_mcp_deployment_guide.md` §8以了解拆除和
更多细节。
---
# 许可证
MIT
