article-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. article_mcp-0.1.0/GEMINI.md +0 -0
  2. article_mcp-0.1.0/IFLOW.md +269 -0
  3. article_mcp-0.1.0/MANIFEST.in +6 -0
  4. article_mcp-0.1.0/PKG-INFO +526 -0
  5. article_mcp-0.1.0/QWEN.md +282 -0
  6. article_mcp-0.1.0/README.md +502 -0
  7. article_mcp-0.1.0/article_mcp.egg-info/PKG-INFO +526 -0
  8. article_mcp-0.1.0/article_mcp.egg-info/SOURCES.txt +36 -0
  9. article_mcp-0.1.0/article_mcp.egg-info/dependency_links.txt +1 -0
  10. article_mcp-0.1.0/article_mcp.egg-info/entry_points.txt +2 -0
  11. article_mcp-0.1.0/article_mcp.egg-info/requires.txt +11 -0
  12. article_mcp-0.1.0/article_mcp.egg-info/top_level.txt +7 -0
  13. article_mcp-0.1.0/json/mcp_config.json +14 -0
  14. article_mcp-0.1.0/json/mcp_config_article_mcp.json +17 -0
  15. article_mcp-0.1.0/json/mcp_config_cherry_studio.json +21 -0
  16. article_mcp-0.1.0/json/mcp_config_examples.json +221 -0
  17. article_mcp-0.1.0/json/mcp_config_simple.json +15 -0
  18. article_mcp-0.1.0/json/mcp_config_sse.json +86 -0
  19. article_mcp-0.1.0/json/mcp_config_sse_client.json +20 -0
  20. article_mcp-0.1.0/main.py +320 -0
  21. article_mcp-0.1.0/pyproject.toml +51 -0
  22. article_mcp-0.1.0/setup.cfg +4 -0
  23. article_mcp-0.1.0/setup.py +24 -0
  24. article_mcp-0.1.0/src/__init__.py +15 -0
  25. article_mcp-0.1.0/src/__main__.py +4 -0
  26. article_mcp-0.1.0/src/arxiv_search.py +300 -0
  27. article_mcp-0.1.0/src/europe_pmc.py +533 -0
  28. article_mcp-0.1.0/src/html_to_markdown.py +326 -0
  29. article_mcp-0.1.0/src/literature_relation_service.py +185 -0
  30. article_mcp-0.1.0/src/pubmed_search.py +665 -0
  31. article_mcp-0.1.0/src/reference_service.py +456 -0
  32. article_mcp-0.1.0/src/resource/journal_info.json +1 -0
  33. article_mcp-0.1.0/src/similar_articles.py +312 -0
  34. article_mcp-0.1.0/tool_modules/article_detail_tools.py +79 -0
  35. article_mcp-0.1.0/tool_modules/quality_tools.py +125 -0
  36. article_mcp-0.1.0/tool_modules/reference_tools.py +202 -0
  37. article_mcp-0.1.0/tool_modules/relation_tools.py +223 -0
  38. article_mcp-0.1.0/tool_modules/search_tools.py +183 -0
File without changes
@@ -0,0 +1,269 @@
1
+ # Article MCP - 学术文献搜索MCP服务器
2
+
3
+ ## 项目概述
4
+
5
+ Article MCP 是一个基于 FastMCP 框架开发的专业学术文献搜索工具,可与 Claude Desktop、Cherry Studio 等 AI 助手无缝集成。项目提供统一的 MCP (Model Context Protocol) 服务器接口,支持搜索 Europe PMC、arXiv 等多个学术数据库。
6
+
7
+ ### 核心特性
8
+ - 🔍 **多数据库搜索** - 支持 Europe PMC、arXiv、PubMed 等学术数据库
9
+ - ⚡ **高性能优化** - 异步并行处理,比传统方法快 6-50 倍
10
+ - 💾 **智能缓存** - 24小时本地缓存,避免重复API请求
11
+ - 🔄 **批量处理** - 支持最多20个DOI同时处理
12
+ - 🛡️ **容错机制** - 自动重试、并发控制、完整的异常处理
13
+ - 🌐 **多传输模式** - 支持 stdio、SSE、Streamable HTTP
14
+
15
+ ## 项目结构
16
+
17
+ ```
18
+ article-mcp/
19
+ ├── main.py # 🚀 主入口文件,统一命令行接口
20
+ ├── pyproject.toml # 📦 uv 项目配置和依赖管理
21
+ ├── bin/article-mcp.js # 🔄 NPM 包装器,支持多平台部署
22
+ ├── src/ # 🔧 核心服务模块
23
+ │ ├── europe_pmc.py # Europe PMC API 服务(高性能优化版)
24
+ │ ├── arxiv_search.py # arXiv 搜索服务
25
+ │ ├── pubmed_search.py # PubMed 搜索服务
26
+ │ ├── reference_service.py # 参考文献处理服务
27
+ │ ├── literature_relation_service.py # 文献关联分析服务
28
+ │ └── resource/ # 📊 数据资源(期刊信息等)
29
+ ├── tool_modules/ # 🛠️ MCP 工具模块
30
+ │ ├── search_tools.py # 搜索工具(Europe PMC、arXiv)
31
+ │ ├── article_detail_tools.py # 文献详情工具
32
+ │ ├── reference_tools.py # 参考文献工具
33
+ │ ├── relation_tools.py # 文献关联工具
34
+ │ └── quality_tools.py # 期刊质量评估工具
35
+ ├── json/ # ⚙️ MCP 配置文件模板
36
+ ├── docs/ # 📖 项目文档和使用指南
37
+ ├── tests/ # 🧪 测试文件
38
+ └── output/ # 📤 输出目录
39
+ ```
40
+
41
+ ## 快速开始
42
+
43
+ ### 环境要求
44
+ - Python ≥ 3.10
45
+ - uv (推荐) 或 pip
46
+
47
+ ### 安装和启动
48
+
49
+ ```bash
50
+ # 使用 uv (推荐)
51
+ uv sync # 安装依赖
52
+ uv run main.py server # 启动服务器
53
+
54
+ # 使用 pip
55
+ pip install fastmcp requests python-dateutil aiohttp
56
+ python main.py server # 启动服务器
57
+ ```
58
+
59
+ ### 基本命令
60
+
61
+ ```bash
62
+ # 启动 MCP 服务器(stdio 模式,推荐用于桌面AI客户端)
63
+ python main.py server
64
+
65
+ # 启动 SSE 服务器(用于Web应用)
66
+ python main.py server --transport sse --host 0.0.0.0 --port 9000
67
+
68
+ # 启动 Streamable HTTP 服务器(用于API集成)
69
+ python main.py server --transport streamable-http --host 0.0.0.0 --port 9000
70
+
71
+ # 运行测试
72
+ python main.py test
73
+
74
+ # 显示项目信息
75
+ python main.py info
76
+ ```
77
+
78
+ ## MCP 工具功能
79
+
80
+ ### 核心搜索工具
81
+
82
+ | 工具名称 | 功能描述 | 性能特点 |
83
+ |---------|---------|----------|
84
+ | `search_europe_pmc` | 搜索 Europe PMC 文献数据库 | 比传统方法快30-50%,支持缓存和并发 |
85
+ | `search_arxiv_papers` | 搜索 arXiv 预印本文献 | 支持关键词、日期范围过滤 |
86
+ | `get_article_details` | 获取文献详细信息 | 比传统方法快20-40%,支持缓存和重试 |
87
+
88
+ ### 参考文献工具
89
+
90
+ | 工具名称 | 功能描述 | 性能特点 |
91
+ |---------|---------|----------|
92
+ | `get_references_by_doi` | 通过DOI获取参考文献 | 比传统方法快10-15倍,批量查询 |
93
+ | `batch_enrich_references_by_dois` | 批量补全多个DOI参考文献 | 支持最多20个DOI同时处理 |
94
+
95
+ ### 文献关联分析
96
+
97
+ | 工具名称 | 功能描述 | 数据来源 |
98
+ |---------|---------|----------|
99
+ | `get_similar_articles` | 获取相似文章推荐 | 基于PubMed相关文章算法 |
100
+ | `get_citing_articles` | 获取引用该文献的文章 | PubMed + Europe PMC |
101
+ | `get_literature_relations` | 一站式获取所有关联信息 | 综合所有数据源 |
102
+
103
+ ### 期刊质量评估
104
+
105
+ | 工具名称 | 功能描述 | 数据来源 |
106
+ |---------|---------|----------|
107
+ | `get_journal_quality` | 获取期刊影响因子、分区等 | 本地缓存 + EasyScholar API |
108
+ | `evaluate_articles_quality` | 批量评估文献期刊质量 | 智能缓存,批量处理 |
109
+
110
+ ## 配置指南
111
+
112
+ ### Claude Desktop 配置
113
+
114
+ 编辑 `claude_desktop_config.json`:
115
+
116
+ ```json
117
+ {
118
+ "mcpServers": {
119
+ "article-mcp": {
120
+ "command": "uv",
121
+ "args": [
122
+ "run",
123
+ "--directory",
124
+ "/path/to/article-mcp",
125
+ "main.py",
126
+ "server"
127
+ ],
128
+ "env": {
129
+ "PYTHONUNBUFFERED": "1"
130
+ }
131
+ }
132
+ }
133
+ }
134
+ ```
135
+
136
+ ### 环境变量
137
+
138
+ ```bash
139
+ export PYTHONUNBUFFERED=1 # 禁用Python输出缓冲
140
+ export EASYSCHOLAR_SECRET_KEY=your_key # EasyScholar API密钥(可选)
141
+ ```
142
+
143
+ ## 性能优化
144
+
145
+ ### 异步并行处理
146
+ - 使用 `asyncio` 和 `aiohttp` 实现并发请求
147
+ - 信号量控制并发数量(默认3个并发)
148
+ - 批量处理优化,减少API调用次数
149
+
150
+ ### 智能缓存机制
151
+ - 24小时本地缓存,避免重复API请求
152
+ - 缓存键基于请求参数生成
153
+ - 支持缓存命中统计
154
+
155
+ ### 容错和重试
156
+ - 自动重试机制(最多3次,指数退避)
157
+ - 网络异常处理
158
+ - API速率限制遵循
159
+
160
+ ## 部署方案
161
+
162
+ ### 本地部署
163
+ ```bash
164
+ # 克隆项目
165
+ git clone https://github.com/gqy20/article-mcp.git
166
+ cd article-mcp
167
+
168
+ # 安装依赖
169
+ uv sync
170
+
171
+ # 启动服务器
172
+ uv run main.py server
173
+ ```
174
+
175
+ ### 魔搭MCP广场部署
176
+ 支持一键部署到阿里云函数计算,提供:
177
+ - ⚡ 毫秒级弹性启动
178
+ - 🔒 多租安全隔离
179
+ - 🌐 自动生成SSE服务地址
180
+ - 🛡️ 内置Bearer鉴权
181
+
182
+ ### NPM 包装器
183
+ ```bash
184
+ # 使用npx直接运行
185
+ npx @gqy20/article-mcp-wrapper@latest server
186
+ ```
187
+
188
+ ### UVX 安装(推荐)
189
+ ```bash
190
+ # 直接通过uvx安装并运行(无需克隆项目)
191
+ uvx --from git+https://github.com/gqy20/article-mcp.git article-mcp server
192
+
193
+ # 或从PyPI安装
194
+ pip install article-mcp
195
+ article-mcp server
196
+ ```
197
+
198
+ ## 开发规范
199
+
200
+ ### 代码风格
201
+ - 使用 Black 格式化(line-length: 88)
202
+ - 类型注解(Python 3.10+)
203
+ - 异步优先设计
204
+
205
+ ### 模块化架构
206
+ - **服务层** (`src/`): 核心业务逻辑
207
+ - **工具层** (`tool_modules/`): MCP工具封装
208
+ - **统一入口** (`main.py`): 命令行接口
209
+
210
+ ### 错误处理
211
+ - 完整的异常捕获和日志记录
212
+ - 用户友好的错误信息
213
+ - 详细的调试信息(开发模式)
214
+
215
+ ## API 限制和优化
216
+
217
+ | API 服务 | 限制 | 优化策略 |
218
+ |---------|------|----------|
219
+ | Europe PMC | 1 request/second | 保守策略,自动延迟 |
220
+ | Crossref | 50 requests/second | 建议提供邮箱获得更高限额 |
221
+ | arXiv | 3 seconds/request | 官方限制,无法优化 |
222
+
223
+ ## 测试和验证
224
+
225
+ ```bash
226
+ # 运行功能测试
227
+ python main.py test
228
+
229
+ # 性能对比测试
230
+ python test_performance_comparison.py
231
+
232
+ # 手动测试示例
233
+ python -c "
234
+ import asyncio
235
+ from src.europe_pmc import create_europe_pmc_service
236
+ service = create_europe_pmc_service()
237
+ results = asyncio.run(service.search_europe_pmc_async('machine learning', max_results=5))
238
+ print(f'找到 {len(results)} 篇文献')
239
+ "
240
+ ```
241
+
242
+ ## 故障排除
243
+
244
+ | 问题 | 解决方案 |
245
+ |------|----------|
246
+ | `cannot import name 'hdrs' from 'aiohttp'` | 运行 `uv sync --upgrade` 更新依赖 |
247
+ | MCP服务器启动失败 | 检查路径配置,确保使用绝对路径 |
248
+ | API请求失败 | 提供邮箱地址,检查网络连接 |
249
+ | 找不到uv命令 | 使用完整路径或pip安装方式 |
250
+
251
+ ## 相关文档
252
+
253
+ - [快速开始指南](docs/发布部署指南.md)
254
+ - [功能使用示例](docs/参考文献功能使用示例.md)
255
+ - [期刊质量评估指南](docs/期刊质量评估功能使用指南.md)
256
+ - [相似文章功能指南](docs/相似文章功能使用指南.md)
257
+ - [arXiv搜索功能指南](docs/arXiv_搜索功能使用指南.md)
258
+ - [Cherry Studio配置指南](docs/Cherry_Studio_配置指南.md)
259
+ - [魔搭MCP广场部署总结](docs/魔搭MCP广场部署总结.md)
260
+
261
+ ## 许可证
262
+
263
+ MIT License - 详见 [LICENSE](LICENSE) 文件
264
+
265
+ ## 贡献和支持
266
+
267
+ - 📧 提交 Issue: [GitHub Issues](https://github.com/gqy20/article-mcp/issues)
268
+ - 📚 项目文档: [GitHub Wiki](https://github.com/gqy20/article-mcp/wiki)
269
+ - 💬 讨论区: [GitHub Discussions](https://github.com/gqy20/article-mcp/discussions)
@@ -0,0 +1,6 @@
1
+ include *.py
2
+ include *.md
3
+ include *.json
4
+ recursive-include src *.py *.json
5
+ recursive-include tool_modules *.py
6
+ recursive-include json *.json