scientific-data-mcp 0.6.1__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 (93) hide show
  1. scientific_data_mcp-0.6.1/.codegraph/.gitignore +5 -0
  2. scientific_data_mcp-0.6.1/.dockerignore +17 -0
  3. scientific_data_mcp-0.6.1/.github/workflows/ci.yml +39 -0
  4. scientific_data_mcp-0.6.1/.github/workflows/kdense-sources.yml +54 -0
  5. scientific_data_mcp-0.6.1/.github/workflows/publish.yml +31 -0
  6. scientific_data_mcp-0.6.1/.gitignore +17 -0
  7. scientific_data_mcp-0.6.1/AGENTS.md +76 -0
  8. scientific_data_mcp-0.6.1/Dockerfile +15 -0
  9. scientific_data_mcp-0.6.1/LICENSE +21 -0
  10. scientific_data_mcp-0.6.1/PKG-INFO +173 -0
  11. scientific_data_mcp-0.6.1/README.md +149 -0
  12. scientific_data_mcp-0.6.1/docker-compose.yml +8 -0
  13. scientific_data_mcp-0.6.1/docs/CREDENTIALS.md +105 -0
  14. scientific_data_mcp-0.6.1/docs/handoff/2026-11-18-kdense-finance-gaps.md +152 -0
  15. scientific_data_mcp-0.6.1/docs/memory/MEMORY.md +20 -0
  16. scientific_data_mcp-0.6.1/docs/memory/biogrid.md +11 -0
  17. scientific_data_mcp-0.6.1/docs/memory/boundary-with-siblings.md +19 -0
  18. scientific_data_mcp-0.6.1/docs/memory/dsh-migration.md +23 -0
  19. scientific_data_mcp-0.6.1/docs/memory/flaky-upstream-apis.md +22 -0
  20. scientific_data_mcp-0.6.1/docs/memory/kdense-catalogue-tracking.md +26 -0
  21. scientific_data_mcp-0.6.1/docs/memory/kimi-science-sources-verdicts.md +33 -0
  22. scientific_data_mcp-0.6.1/docs/memory/materials-project-key-gate.md +10 -0
  23. scientific_data_mcp-0.6.1/docs/memory/publishing-hatch-vcs.md +11 -0
  24. scientific_data_mcp-0.6.1/docs/memory/secrets-and-quotas.md +19 -0
  25. scientific_data_mcp-0.6.1/docs/memory/string-openfda-clinicaltrials.md +38 -0
  26. scientific_data_mcp-0.6.1/docs/memory/tool-description-discipline.md +7 -0
  27. scientific_data_mcp-0.6.1/docs/memory/tool-surface-v0.4.md +21 -0
  28. scientific_data_mcp-0.6.1/docs/memory/upstream-drift-signal.md +27 -0
  29. scientific_data_mcp-0.6.1/docs/memory/who-gho.md +10 -0
  30. scientific_data_mcp-0.6.1/docs/research/kdense-coverage.md +111 -0
  31. scientific_data_mcp-0.6.1/docs/research/kdense-databases.json +488 -0
  32. scientific_data_mcp-0.6.1/docs/research/kimi-sources/README.md +17 -0
  33. scientific_data_mcp-0.6.1/docs/research/kimi-sources/chembl.verdict.md +43 -0
  34. scientific_data_mcp-0.6.1/docs/research/kimi-sources/pdb.verdict.md +43 -0
  35. scientific_data_mcp-0.6.1/docs/research/kimi-sources/pubchem.verdict.md +42 -0
  36. scientific_data_mcp-0.6.1/docs/research/kimi-sources/pubmed.verdict.md +50 -0
  37. scientific_data_mcp-0.6.1/docs/research/kimi-sources/uniprot.verdict.md +41 -0
  38. scientific_data_mcp-0.6.1/docs/superpowers/plans/2026-11-17-scientific-data-mcp.md +185 -0
  39. scientific_data_mcp-0.6.1/docs/superpowers/specs/2026-11-17-scientific-data-mcp-design.md +122 -0
  40. scientific_data_mcp-0.6.1/docs//350/256/241/345/210/222.md +143 -0
  41. scientific_data_mcp-0.6.1/pyproject.toml +58 -0
  42. scientific_data_mcp-0.6.1/scripts/kdense_sources.py +216 -0
  43. scientific_data_mcp-0.6.1/scripts/live_smoke.py +99 -0
  44. scientific_data_mcp-0.6.1/src/scientific_data_mcp/__init__.py +12 -0
  45. scientific_data_mcp-0.6.1/src/scientific_data_mcp/__main__.py +34 -0
  46. scientific_data_mcp-0.6.1/src/scientific_data_mcp/config.py +73 -0
  47. scientific_data_mcp-0.6.1/src/scientific_data_mcp/errors.py +76 -0
  48. scientific_data_mcp-0.6.1/src/scientific_data_mcp/http.py +220 -0
  49. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/__init__.py +5 -0
  50. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/base.py +23 -0
  51. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/biogrid.py +80 -0
  52. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/chembl.py +172 -0
  53. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/clinicaltrials.py +72 -0
  54. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/materials_project.py +87 -0
  55. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/openfda.py +52 -0
  56. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/pubchem.py +171 -0
  57. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/pubmed.py +131 -0
  58. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/rcsb.py +97 -0
  59. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/string_db.py +60 -0
  60. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/uniprot.py +208 -0
  61. scientific_data_mcp-0.6.1/src/scientific_data_mcp/providers/who.py +70 -0
  62. scientific_data_mcp-0.6.1/src/scientific_data_mcp/runtime.py +55 -0
  63. scientific_data_mcp-0.6.1/src/scientific_data_mcp/server.py +35 -0
  64. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/__init__.py +30 -0
  65. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/_guard.py +58 -0
  66. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/chemistry.py +199 -0
  67. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/clinical.py +113 -0
  68. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/interactions.py +105 -0
  69. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/literature.py +44 -0
  70. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/materials.py +81 -0
  71. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/protein.py +178 -0
  72. scientific_data_mcp-0.6.1/src/scientific_data_mcp/tools/who.py +78 -0
  73. scientific_data_mcp-0.6.1/tests/test_biogrid.py +108 -0
  74. scientific_data_mcp-0.6.1/tests/test_chembl.py +157 -0
  75. scientific_data_mcp-0.6.1/tests/test_clinicaltrials.py +107 -0
  76. scientific_data_mcp-0.6.1/tests/test_config.py +28 -0
  77. scientific_data_mcp-0.6.1/tests/test_http.py +145 -0
  78. scientific_data_mcp-0.6.1/tests/test_kdense_sources.py +61 -0
  79. scientific_data_mcp-0.6.1/tests/test_materials_project.py +82 -0
  80. scientific_data_mcp-0.6.1/tests/test_openfda.py +107 -0
  81. scientific_data_mcp-0.6.1/tests/test_pubchem.py +107 -0
  82. scientific_data_mcp-0.6.1/tests/test_pubmed.py +127 -0
  83. scientific_data_mcp-0.6.1/tests/test_rcsb.py +88 -0
  84. scientific_data_mcp-0.6.1/tests/test_server.py +69 -0
  85. scientific_data_mcp-0.6.1/tests/test_string.py +69 -0
  86. scientific_data_mcp-0.6.1/tests/test_tools_chemistry.py +189 -0
  87. scientific_data_mcp-0.6.1/tests/test_tools_interactions.py +98 -0
  88. scientific_data_mcp-0.6.1/tests/test_tools_literature.py +61 -0
  89. scientific_data_mcp-0.6.1/tests/test_tools_materials.py +80 -0
  90. scientific_data_mcp-0.6.1/tests/test_tools_protein.py +124 -0
  91. scientific_data_mcp-0.6.1/tests/test_tools_who.py +59 -0
  92. scientific_data_mcp-0.6.1/tests/test_uniprot.py +175 -0
  93. scientific_data_mcp-0.6.1/tests/test_who.py +61 -0
@@ -0,0 +1,5 @@
1
+ # CodeGraph data files — local to each machine, not for committing.
2
+ # Ignore everything except this file so the database, daemon pid/sockets and
3
+ # logs never show up in git.
4
+ *
5
+ !.gitignore
@@ -0,0 +1,17 @@
1
+ .git
2
+ .github
3
+ .venv
4
+ .uv-cache
5
+ .uv-python
6
+ .pip-cache
7
+ .pytest_cache
8
+ .ruff_cache
9
+ __pycache__
10
+ *.pyc
11
+ dist
12
+ build
13
+ docs
14
+ tests
15
+ scripts
16
+ .gitignore
17
+ .env
@@ -0,0 +1,39 @@
1
+ name: ci
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ python-version: ["3.10", "3.12"]
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+ with:
18
+ # hatch-vcs derives the version from tags.
19
+ fetch-depth: 0
20
+ - uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python-version }}
23
+ - name: Install
24
+ run: pip install -e '.[dev]'
25
+ - name: Lint
26
+ run: ruff check .
27
+ - name: Test
28
+ run: pytest -q
29
+
30
+ docker:
31
+ runs-on: ubuntu-latest
32
+ steps:
33
+ - uses: actions/checkout@v4
34
+ with:
35
+ fetch-depth: 0
36
+ - name: Build image
37
+ run: docker build -t scientific-data-mcp:ci .
38
+ - name: Smoke the entrypoint
39
+ run: docker run --rm scientific-data-mcp:ci --help
@@ -0,0 +1,54 @@
1
+ name: kdense-sources
2
+
3
+ on:
4
+ schedule:
5
+ # Quarterly: 03:00 UTC on Jan/Apr/Jul/Oct 1st.
6
+ - cron: "0 3 1 1,4,7,10 *"
7
+ workflow_dispatch:
8
+
9
+ permissions:
10
+ contents: read
11
+ issues: write
12
+
13
+ jobs:
14
+ scan:
15
+ runs-on: ubuntu-latest
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+ - uses: actions/setup-python@v5
19
+ with:
20
+ python-version: "3.12"
21
+
22
+ - name: Diff the upstream K-Dense catalogue
23
+ id: scan
24
+ continue-on-error: true
25
+ shell: bash
26
+ run: |
27
+ set -o pipefail
28
+ python scripts/kdense_sources.py --check --report kdense-diff.md | tee -a "$GITHUB_STEP_SUMMARY"
29
+
30
+ - name: Open or update the tracking issue
31
+ if: steps.scan.outcome == 'failure'
32
+ env:
33
+ GH_TOKEN: ${{ github.token }}
34
+ shell: bash
35
+ run: |
36
+ if head -1 kdense-diff.md | grep -q "扫描失败"; then
37
+ title="K-Dense 扫描失败(上游不可达或格式变了)"
38
+ else
39
+ title="K-Dense 数据源清单有变化"
40
+ fi
41
+ num=$(gh issue list --state open --search "$title in:title" --json number --jq '.[0].number // empty')
42
+ if [ -n "$num" ]; then
43
+ gh issue comment "$num" --body-file kdense-diff.md
44
+ else
45
+ gh issue create --title "$title" --body-file kdense-diff.md
46
+ fi
47
+
48
+ - name: Upload the diff
49
+ if: always()
50
+ uses: actions/upload-artifact@v4
51
+ with:
52
+ name: kdense-diff
53
+ path: kdense-diff.md
54
+ if-no-files-found: ignore
@@ -0,0 +1,31 @@
1
+ name: publish
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+ id-token: write
11
+
12
+ jobs:
13
+ build-and-publish:
14
+ # Tag pushes only publish after the PyPI trusted publisher is configured
15
+ # and the repository variable PYPI_PUBLISH is set to "true".
16
+ if: github.event_name == 'workflow_dispatch' || vars.PYPI_PUBLISH == 'true'
17
+ runs-on: ubuntu-latest
18
+ environment: pypi
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+ with:
22
+ fetch-depth: 0
23
+ - uses: actions/setup-python@v5
24
+ with:
25
+ python-version: "3.12"
26
+ - name: Build sdist and wheel
27
+ run: |
28
+ python -m pip install --upgrade build
29
+ python -m build
30
+ - name: Publish to PyPI
31
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,17 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .venv/
7
+ .uv/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ .coverage
11
+ htmlcov/
12
+ .env
13
+ *.so
14
+ .DS_Store
15
+ .uv-cache/
16
+ .uv-python/
17
+ .pip-cache/
@@ -0,0 +1,76 @@
1
+ # scientific-data-mcp — 维护指南
2
+
3
+ 科研**实体数据** MCP:化合物(PubChem)、生物活性(ChEMBL)、蛋白序列/功能(UniProt)、实验结构(RCSB PDB)、文献元数据(PubMed E-utilities),以及材料/互作数据(Materials Project、BioGRID,需免费 key)、互作/药品/临床数据(STRING、openFDA、ClinicalTrials.gov,基础免 key)。一个 FastMCP server:11 个基础工具(配 MP key 时 12 个);BioGRID key 解锁 `protein_interactions` 的 biogrid source,不增工具。同类输入输出的源合并为一个工具(`kind`/`by` 参数切换)。
4
+
5
+ 本项目由 **DSH 维护**(2026-11-17 从 Claude Code 项目迁移)。`AGENTS.md` 是唯一常驻指令;`docs/memory/` 是本项目的工作记忆,动手前先读 `docs/memory/MEMORY.md`。
6
+
7
+ ## 定位与边界
8
+
9
+ | 项目 | 管什么 | 不管 |
10
+ |------|--------|------|
11
+ | **scientific-data-mcp**(本仓库) | 科研实体数据:化合物 / 活性 / 蛋白 / 结构 / 文献元数据 | 跨库文献检索、全文下载、RAG 入库 |
12
+ | `paper-search` | 找论文 / 读论文 / 入 OpenWebUI Knowledge | 实体数据 |
13
+ | `finance-mcp` | 金融 / 宏观行情 | 科研 |
14
+
15
+ PubMed 只做**实体级记录查询**(pmid/doi → 一条结构化记录),不做 `pubmed_search` —— 文献搜索归 paper-search。
16
+
17
+ ## 命令
18
+
19
+ ```bash
20
+ uv venv --python 3.12 .venv
21
+ uv pip install -e '.[dev]' --python .venv/bin/python
22
+
23
+ pytest -q # hermetic,0 egress
24
+ ruff check .
25
+ python scripts/live_smoke.py # 真实打 9 个基础上游(配 key 时 11 个),人工跑,不进 CI
26
+
27
+ .venv/bin/scientific-data-mcp # stdio(mcpo 用这个)
28
+ .venv/bin/scientific-data-mcp --http --port 8000
29
+ docker build -t scientific-data-mcp:dev .
30
+ ```
31
+
32
+ 本机 uv 的默认缓存目录可能被沙箱挡住;必要时 `export UV_CACHE_DIR=$PWD/.uv-cache UV_PYTHON_INSTALL_DIR=$PWD/.uv-python`。
33
+
34
+ ## 架构纪律
35
+
36
+ - `providers/<source>.py`:URL 构造、分页、字段归一化。`tools/<domain>.py`:LLM-facing schema、参数校验、错误包装。
37
+ - 所有 HTTP 走 `http.PoliteClient`:per-host 限速(见 `config.HOST_DELAYS`)、429/503 与瞬时 5xx(500/502/504)重试、401/403→`AuthError`、404→`NotFound`。**创建服务端任务的 POST(PubChem 相似性、UniProt idmapping run)不自动重试**,只重试其后的轮询 GET。
38
+ - 工具用 `guarded_tool(...)` 注册:最外层兜底任何 `Exception`,保证 never-raise;`CancelledError` 不捕。
39
+ - **工具永不抛异常**:任何失败返回 `{"error": "...", "source": "..."}`;空结果是正常答案(`count: 0`),不是错误。
40
+ - **漂移信号**:非连接/限流类失败(400/405/406/422、非 JSON 200、缺关键字段、解析异常)抛 `UpstreamDrift`,工具返回 `suspect_drift: true` + `action: contact_admin` + 提示联系管理员;限流/网络/5xx 不带该标记。
41
+ - **反幻觉**:只返回上游真实字段;缺失字段省略,不推断、不补全;docstring 写明"不补全"。返回体不带时间戳(测试可复现)。
42
+ - 返回值 `source_url` 指向官方记录页,便于人工复核。
43
+ - 分页:列表返回 `next_cursor`/`next_offset`/`next_start`,最后一页为 `null`。
44
+ - 新增源时同步:provider、tool、`runtime.build_service`、`tools/__init__.register_all`、`tests/test_server.py` 的基础 11 工具断言(+ 有 key 时的工具面)、README 工具表、`docs/memory/`。
45
+ - **key-gated 源只在 key 存在时注册 provider**(Materials Project 先例):MP 没有 key 时 `material` 不注册;BioGRID 没有 key 时 provider 缺席,但共享的 `protein_interactions` 仍注册(STRING 可用),`source="biogrid"` 返回明确错误。
46
+ - 数据源池追踪:`docs/research/kdense-databases.json` + `scripts/kdense_sources.py`;季度 Action 有变化会开 issue,评估后 `--update` 刷新快照。逐源决定见 `docs/research/kdense-coverage.md`(80 行:已实现 / M6 / 兄弟项目 / 不做)。
47
+
48
+ ## 发布纪律
49
+
50
+ - 版本只来自 git tag(hatch-vcs,`pyproject.toml` 里 `dynamic = ["version"]`)。**永不手写 version**。
51
+ - `v*` tag 推上去即发布对应版本;改版本 = 打新 tag,不改文件。
52
+ - 细节见 `docs/memory/publishing-hatch-vcs.md`。
53
+
54
+ ## 记忆
55
+
56
+ `docs/memory/MEMORY.md` 是索引。改动某一域前先读对应笔记:
57
+
58
+ - 改 PubChem / ChEMBL / UniProt / PDB / PubMed → `kimi-science-sources-verdicts.md`
59
+ - 改 HTTP / 重试 / 超时 → `flaky-upstream-apis.md`
60
+ - 改 key / 环境变量 / 限速 / 申请步骤 → `secrets-and-quotas.md` + `docs/CREDENTIALS.md`
61
+ - 改 Materials Project / key-gated 源 → `materials-project-key-gate.md`
62
+ - 改 WHO GHO → `who-gho.md`
63
+ - 改错误分类 / 漂移信号 → `upstream-drift-signal.md`
64
+ - 改 K-Dense 快照 / 季度扫描 → `kdense-catalogue-tracking.md`
65
+ - 改工具面 / 合并规则 → `tool-surface-v0.4.md`
66
+ - 改 PyPI 发布 / 包名 → `publishing-hatch-vcs.md` + README「PyPI 发布」
67
+ - 改 docstring / 工具描述 → `tool-description-discipline.md`
68
+ - 改边界(PubMed 搜索、全文、RAG) → `boundary-with-siblings.md`
69
+ - 改 BioGRID / STRING / openFDA / ClinicalTrials → `string-openfda-clinicaltrials.md`
70
+ - 改发布 / 版本 → `publishing-hatch-vcs.md`
71
+ - 迁移背景 / DSH 形态 → `dsh-migration.md`
72
+
73
+ ## Agent 工具纪律
74
+
75
+ - 仓库根有 `.codegraph/` 时,先用 MCP `codegraph_explore`(或 shell `codegraph query "<符号>"`)再 grep/read。注意 codegraph 0.9.9 没有 `explore` 子命令。
76
+ - 取网页/搜索走 firecrawl(`firecrawl_scrape` / `firecrawl_search`),不用原生 WebFetch。
@@ -0,0 +1,15 @@
1
+ FROM python:3.12-slim AS build
2
+
3
+ WORKDIR /src
4
+ COPY pyproject.toml README.md ./
5
+ COPY src ./src
6
+ # No .git in the build context: hatch-vcs falls back to the configured version.
7
+ RUN pip install --no-cache-dir --prefix=/install .
8
+
9
+ FROM python:3.12-slim
10
+
11
+ COPY --from=build /install /usr/local
12
+ RUN useradd --create-home --uid 10001 appuser
13
+ USER appuser
14
+
15
+ ENTRYPOINT ["scientific-data-mcp"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 eli
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,173 @@
1
+ Metadata-Version: 2.5
2
+ Name: scientific-data-mcp
3
+ Version: 0.6.1
4
+ Summary: Scientific entity data MCP: PubChem, ChEMBL, UniProt, RCSB PDB, PubMed E-utilities, WHO GHO, plus key-gated Materials Project, behind one tool surface.
5
+ Project-URL: Homepage, https://github.com/xyonium/scientific-data-mcp
6
+ Project-URL: Repository, https://github.com/xyonium/scientific-data-mcp
7
+ Project-URL: Issues, https://github.com/xyonium/scientific-data-mcp/issues
8
+ Author-email: eli <shark_xc@hotmail.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: bioinformatics,chembl,chemistry,mcp,pdb,pubchem,pubmed,science,uniprot
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Requires-Python: >=3.10
16
+ Requires-Dist: httpx>=0.27
17
+ Requires-Dist: mcp[cli]<2,>=1.27
18
+ Provides-Extra: dev
19
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
20
+ Requires-Dist: pytest>=8; extra == 'dev'
21
+ Requires-Dist: respx>=0.22; extra == 'dev'
22
+ Requires-Dist: ruff>=0.6; extra == 'dev'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # scientific-data-mcp
26
+
27
+ 科研**实体数据** MCP —— 化合物 / 生物活性 / 蛋白序列与结构 / 文献元数据的**免费官方 API 直连**。一个 server,11 个基础工具(配 Materials Project key 时 12 个;BioGRID key 解锁互作 source,不增工具),零额度。同类输入输出的源合并为一个工具,用 `kind` / `by` 参数切换。
28
+
29
+ > 与 [paper-search](https://github.com/xyonium/paper-search)(文献检索 + RAG)、[finance-mcp](https://github.com/xyonium/finance-mcp)(金融/宏观)互补,不做重复。
30
+
31
+ ## 定位
32
+
33
+ | 项目 | 管什么 | 不管 |
34
+ |------|--------|------|
35
+ | [finance-mcp](https://github.com/xyonium/finance-mcp) | 金融/宏观行情 | 科研 |
36
+ | [paper-search](https://github.com/xyonium/paper-search) | 学术**文献**检索 + RAG 入 OpenWebUI | 实体数据 |
37
+ | **scientific-data-mcp**(本项目) | 科研**实体数据**:化合物、活性、蛋白、结构、文献元数据 | 跨库文献检索、全文下载、RAG |
38
+
39
+ **边界一句话**:paper-search 管"找论文/读论文/入 RAG",本项目管"查实体数据"。PubMed 只做 pmid/doi → 结构化记录,不做 `pubmed_search`。
40
+
41
+ ## 为什么
42
+
43
+ kimi datasource 把一批本来就免 key 的官方科研 API(PubChem / ChEMBL / UniProt / PDB / PubMed)包装成收费额度源。finance-mcp 在 2026-09-13 的去重中把这批源摘除,每源都有 live 实测的免费端点证据(见 [`docs/research/kimi-sources/`](./docs/research/kimi-sources/))。本项目是这批源的免费直连落点。
44
+
45
+ ## 源与工具
46
+
47
+ 八个基础源完全免 key(PubChem / ChEMBL / UniProt / RCSB PDB / WHO / STRING / openFDA / ClinicalTrials.gov),PubMed 可选 `NCBI_API_KEY` 提速(3→10 req/s);**Materials Project 和 BioGRID 需要免费 key**:MP 未配时 `material` 不注册;BioGRID 未配时 `protein_interactions(source="biogrid")` 返回明确错误,STRING 仍可用。openFDA 可选 key 只提额度。申请步骤见 [docs/CREDENTIALS.md](./docs/CREDENTIALS.md)。
48
+
49
+ | 工具 | 源 | 说明 |
50
+ |------|----|------|
51
+ | `chem_compound` | PubChem | 化合物记录:`identifier` + `id_type`(name/cid/smiles/inchikey);可选 `properties` 指定 PubChem 属性集(省略为默认全集) |
52
+ | `chem_similar_compounds` | PubChem | 结构相似性(POST + ListKey 轮询),返回 CID 列表 |
53
+ | `chembl_data` | ChEMBL | `kind="search"`(query/resource)、`"activities"`(chembl_id 或 target_chembl_id)、`"mechanisms"`(chembl_id);统一列表 envelope |
54
+ | `protein_record` | UniProt / RCSB | `kind="uniprot"` 取条目(可选全序列);`kind="pdb"` 取结构条目 + 实体摘要 |
55
+ | `protein_search` | UniProt / RCSB | `kind="uniprot"` 用 UniProt 查询语法;`kind="pdb"` 全文检索;统一 `next_cursor` |
56
+ | `protein_map_ids` | UniProt | 官方 ID Mapping(submit → poll) |
57
+ | `pubmed_record` | PubMed | pmid / doi → 标题、作者、期刊、年卷期页、摘要、DOI、PMCID |
58
+ | `who_data` | WHO GHO | 按指标代码查国家/年份/性别的健康统计(如 `WHOSIS_000001`) |
59
+ | `material` | Materials Project(需免费 key) | `by="id"` 单条;`by="formula" / "chemsys" / "elements"` 检索;统一列表 envelope |
60
+ | `protein_interactions` | STRING / BioGRID | `source="string"`(免 key,含 combined/evidence scores)或 `"biogrid"`(需 key,含实验系统/PubMed);`genes` 支持 `BRCA1|BRCA2` |
61
+ | `openfda` | openFDA | `endpoint="drug/label" / "drug/event" / "drug/enforcement"` + `query`(field:term);无匹配是 `count: 0`;可选 key 提额度 |
62
+ | `clinical_trials` | ClinicalTrials.gov v2 | 自由文本检索 + `status` 过滤;返回 NCT id/标题/状态/分期/干预/入组/赞助方 + `next_cursor` |
63
+
64
+ 所有工具只返回上游真实字段:缺字段就是上游没有,不推断、不补全。失败返回 `{"error": ..., "source": ...}`,不会让一次调用炸掉整轮对话。
65
+
66
+ 如果错误里出现 `"suspect_drift": true` / `"action": "contact_admin"`,表示**上游返回结构与适配器不一致(接口可能漂移)**,不是限流或网络问题:不要用相同参数重试,请告知用户联系管理员更新对应 provider。`rate_limited` / `unavailable` / `auth` / `not_found` 不带这个标记。
67
+
68
+ ## 安装
69
+
70
+ ```bash
71
+ uv venv --python 3.12 .venv
72
+ uv pip install -e . --python .venv/bin/python
73
+ # 或直接从仓库装(PyPI 尚未发布)
74
+ uvx --from git+https://github.com/xyonium/scientific-data-mcp scientific-data-mcp
75
+ ```
76
+
77
+ ## 运行
78
+
79
+ stdio(mcpo / 本地 MCP 客户端):
80
+
81
+ ```bash
82
+ scientific-data-mcp
83
+ ```
84
+
85
+ Streamable HTTP:
86
+
87
+ ```bash
88
+ scientific-data-mcp --http --host 0.0.0.0 --port 8000
89
+ ```
90
+
91
+ mcpo 配置示例(`config.json`):
92
+
93
+ ```json
94
+ {
95
+ "mcpServers": {
96
+ "scientific-data": {
97
+ "command": "uvx",
98
+ "args": ["--from", "git+https://github.com/xyonium/scientific-data-mcp", "scientific-data-mcp"],
99
+ "env": {}
100
+ }
101
+ }
102
+ }
103
+ ```
104
+
105
+ ### 可选 key(不是必需)
106
+
107
+ ```json
108
+ "env": {
109
+ "NCBI_API_KEY": "免费申请,PubMed 限速 3 → 10 req/s",
110
+ "NCBI_EMAIL": "you@example.com",
111
+ "MATERIALS_PROJECT_API_KEY": "免费申请;不配则不注册材料工具",
112
+ "BIOGRID_ACCESS_KEY": "免费申请;不配则 protein_interactions 的 biogrid source 不可用",
113
+ "OPENFDA_API_KEY": "可选;只提额度,不配也能用"
114
+ }
115
+ ```
116
+
117
+ 申请步骤、各源是否有 key、以及 M6 扩展源(NOAA / NASA)的入口见 **[docs/CREDENTIALS.md](./docs/CREDENTIALS.md)**。不配任何 key 时 9 个基础源全部可用(PubMed 慢一些),MP 工具隐藏、BioGRID source 不可用。
118
+
119
+ ## Docker
120
+
121
+ ```bash
122
+ docker build -t scientific-data-mcp:dev .
123
+ docker run --rm -p 8000:8000 scientific-data-mcp:dev --http --host 0.0.0.0
124
+ ```
125
+
126
+ ## PyPI 发布
127
+
128
+ 包名 **`scientific-data-mcp`**(2026-11-18 查询仍未被占用)。PyPI 不需要预先建项目:**首次上传即创建**。
129
+
130
+ 一次性配置(推荐 trusted publishing,免 API token):
131
+
132
+ 1. 注册 PyPI 账号并开启 2FA。
133
+ 2. 打开 https://pypi.org/manage/account/publishing/ ,添加 **pending publisher**:
134
+ - PyPI project name: `scientific-data-mcp`
135
+ - Owner: `xyonium`
136
+ - Repository: `scientific-data-mcp`
137
+ - Workflow name: `publish.yml`
138
+ - Environment: `pypi`
139
+ 3. 仓库 Settings → Secrets and variables → Actions → Variables 新建 `PYPI_PUBLISH=true`。
140
+ 4. 之后 push `v*` tag(或手动运行 `publish` workflow)即构建 sdist/wheel 并上传。
141
+
142
+ 工作流在 [.github/workflows/publish.yml](./.github/workflows/publish.yml):tag 触发时只有在 `PYPI_PUBLISH=true` 才发布,避免未配置时 CI 变红。首次上传会自动创建 PyPI 项目并占用这个名字。
143
+
144
+ ## 数据源清单追踪
145
+
146
+ [docs/research/kdense-databases.json](./docs/research/kdense-databases.json) 是 [K-Dense scientific-agent-skills](https://github.com/K-Dense-AI/scientific-agent-skills) `database-lookup` 的数据库快照(当前 v1.8,80 库,2026-09-30 复核)。
147
+
148
+ ```bash
149
+ python scripts/kdense_sources.py --check # 与上游 diff
150
+ python scripts/kdense_sources.py --update # 刷新快照
151
+ ```
152
+
153
+ GitHub Action `kdense-sources` 每季度(1/4/7/10 月 1 日)自动扫描;上游新增或移除数据库时开 issue(已有 open issue 则追加评论)。
154
+
155
+ 80 个库逐个的“已实现 / M6 / 归兄弟项目 / 不做”决定见 [docs/research/kdense-coverage.md](./docs/research/kdense-coverage.md)。
156
+
157
+ ## 开发
158
+
159
+ ```bash
160
+ pytest -q # hermetic(respx mock),0 egress
161
+ ruff check .
162
+ python scripts/live_smoke.py # 真实打 9 个基础上游(配 key 时 11 个),人工跑
163
+ ```
164
+
165
+ - 设计与决策:[`docs/superpowers/specs/`](./docs/superpowers/specs/)
166
+ - 实施计划:[`docs/superpowers/plans/`](./docs/superpowers/plans/)
167
+ - 工作记忆:[`docs/memory/MEMORY.md`](./docs/memory/MEMORY.md)
168
+ - 立项证据:[`docs/research/kimi-sources/`](./docs/research/kimi-sources/)
169
+ - 维护指南:[`AGENTS.md`](./AGENTS.md)
170
+
171
+ ## License
172
+
173
+ MIT
@@ -0,0 +1,149 @@
1
+ # scientific-data-mcp
2
+
3
+ 科研**实体数据** MCP —— 化合物 / 生物活性 / 蛋白序列与结构 / 文献元数据的**免费官方 API 直连**。一个 server,11 个基础工具(配 Materials Project key 时 12 个;BioGRID key 解锁互作 source,不增工具),零额度。同类输入输出的源合并为一个工具,用 `kind` / `by` 参数切换。
4
+
5
+ > 与 [paper-search](https://github.com/xyonium/paper-search)(文献检索 + RAG)、[finance-mcp](https://github.com/xyonium/finance-mcp)(金融/宏观)互补,不做重复。
6
+
7
+ ## 定位
8
+
9
+ | 项目 | 管什么 | 不管 |
10
+ |------|--------|------|
11
+ | [finance-mcp](https://github.com/xyonium/finance-mcp) | 金融/宏观行情 | 科研 |
12
+ | [paper-search](https://github.com/xyonium/paper-search) | 学术**文献**检索 + RAG 入 OpenWebUI | 实体数据 |
13
+ | **scientific-data-mcp**(本项目) | 科研**实体数据**:化合物、活性、蛋白、结构、文献元数据 | 跨库文献检索、全文下载、RAG |
14
+
15
+ **边界一句话**:paper-search 管"找论文/读论文/入 RAG",本项目管"查实体数据"。PubMed 只做 pmid/doi → 结构化记录,不做 `pubmed_search`。
16
+
17
+ ## 为什么
18
+
19
+ kimi datasource 把一批本来就免 key 的官方科研 API(PubChem / ChEMBL / UniProt / PDB / PubMed)包装成收费额度源。finance-mcp 在 2026-09-13 的去重中把这批源摘除,每源都有 live 实测的免费端点证据(见 [`docs/research/kimi-sources/`](./docs/research/kimi-sources/))。本项目是这批源的免费直连落点。
20
+
21
+ ## 源与工具
22
+
23
+ 八个基础源完全免 key(PubChem / ChEMBL / UniProt / RCSB PDB / WHO / STRING / openFDA / ClinicalTrials.gov),PubMed 可选 `NCBI_API_KEY` 提速(3→10 req/s);**Materials Project 和 BioGRID 需要免费 key**:MP 未配时 `material` 不注册;BioGRID 未配时 `protein_interactions(source="biogrid")` 返回明确错误,STRING 仍可用。openFDA 可选 key 只提额度。申请步骤见 [docs/CREDENTIALS.md](./docs/CREDENTIALS.md)。
24
+
25
+ | 工具 | 源 | 说明 |
26
+ |------|----|------|
27
+ | `chem_compound` | PubChem | 化合物记录:`identifier` + `id_type`(name/cid/smiles/inchikey);可选 `properties` 指定 PubChem 属性集(省略为默认全集) |
28
+ | `chem_similar_compounds` | PubChem | 结构相似性(POST + ListKey 轮询),返回 CID 列表 |
29
+ | `chembl_data` | ChEMBL | `kind="search"`(query/resource)、`"activities"`(chembl_id 或 target_chembl_id)、`"mechanisms"`(chembl_id);统一列表 envelope |
30
+ | `protein_record` | UniProt / RCSB | `kind="uniprot"` 取条目(可选全序列);`kind="pdb"` 取结构条目 + 实体摘要 |
31
+ | `protein_search` | UniProt / RCSB | `kind="uniprot"` 用 UniProt 查询语法;`kind="pdb"` 全文检索;统一 `next_cursor` |
32
+ | `protein_map_ids` | UniProt | 官方 ID Mapping(submit → poll) |
33
+ | `pubmed_record` | PubMed | pmid / doi → 标题、作者、期刊、年卷期页、摘要、DOI、PMCID |
34
+ | `who_data` | WHO GHO | 按指标代码查国家/年份/性别的健康统计(如 `WHOSIS_000001`) |
35
+ | `material` | Materials Project(需免费 key) | `by="id"` 单条;`by="formula" / "chemsys" / "elements"` 检索;统一列表 envelope |
36
+ | `protein_interactions` | STRING / BioGRID | `source="string"`(免 key,含 combined/evidence scores)或 `"biogrid"`(需 key,含实验系统/PubMed);`genes` 支持 `BRCA1|BRCA2` |
37
+ | `openfda` | openFDA | `endpoint="drug/label" / "drug/event" / "drug/enforcement"` + `query`(field:term);无匹配是 `count: 0`;可选 key 提额度 |
38
+ | `clinical_trials` | ClinicalTrials.gov v2 | 自由文本检索 + `status` 过滤;返回 NCT id/标题/状态/分期/干预/入组/赞助方 + `next_cursor` |
39
+
40
+ 所有工具只返回上游真实字段:缺字段就是上游没有,不推断、不补全。失败返回 `{"error": ..., "source": ...}`,不会让一次调用炸掉整轮对话。
41
+
42
+ 如果错误里出现 `"suspect_drift": true` / `"action": "contact_admin"`,表示**上游返回结构与适配器不一致(接口可能漂移)**,不是限流或网络问题:不要用相同参数重试,请告知用户联系管理员更新对应 provider。`rate_limited` / `unavailable` / `auth` / `not_found` 不带这个标记。
43
+
44
+ ## 安装
45
+
46
+ ```bash
47
+ uv venv --python 3.12 .venv
48
+ uv pip install -e . --python .venv/bin/python
49
+ # 或直接从仓库装(PyPI 尚未发布)
50
+ uvx --from git+https://github.com/xyonium/scientific-data-mcp scientific-data-mcp
51
+ ```
52
+
53
+ ## 运行
54
+
55
+ stdio(mcpo / 本地 MCP 客户端):
56
+
57
+ ```bash
58
+ scientific-data-mcp
59
+ ```
60
+
61
+ Streamable HTTP:
62
+
63
+ ```bash
64
+ scientific-data-mcp --http --host 0.0.0.0 --port 8000
65
+ ```
66
+
67
+ mcpo 配置示例(`config.json`):
68
+
69
+ ```json
70
+ {
71
+ "mcpServers": {
72
+ "scientific-data": {
73
+ "command": "uvx",
74
+ "args": ["--from", "git+https://github.com/xyonium/scientific-data-mcp", "scientific-data-mcp"],
75
+ "env": {}
76
+ }
77
+ }
78
+ }
79
+ ```
80
+
81
+ ### 可选 key(不是必需)
82
+
83
+ ```json
84
+ "env": {
85
+ "NCBI_API_KEY": "免费申请,PubMed 限速 3 → 10 req/s",
86
+ "NCBI_EMAIL": "you@example.com",
87
+ "MATERIALS_PROJECT_API_KEY": "免费申请;不配则不注册材料工具",
88
+ "BIOGRID_ACCESS_KEY": "免费申请;不配则 protein_interactions 的 biogrid source 不可用",
89
+ "OPENFDA_API_KEY": "可选;只提额度,不配也能用"
90
+ }
91
+ ```
92
+
93
+ 申请步骤、各源是否有 key、以及 M6 扩展源(NOAA / NASA)的入口见 **[docs/CREDENTIALS.md](./docs/CREDENTIALS.md)**。不配任何 key 时 9 个基础源全部可用(PubMed 慢一些),MP 工具隐藏、BioGRID source 不可用。
94
+
95
+ ## Docker
96
+
97
+ ```bash
98
+ docker build -t scientific-data-mcp:dev .
99
+ docker run --rm -p 8000:8000 scientific-data-mcp:dev --http --host 0.0.0.0
100
+ ```
101
+
102
+ ## PyPI 发布
103
+
104
+ 包名 **`scientific-data-mcp`**(2026-11-18 查询仍未被占用)。PyPI 不需要预先建项目:**首次上传即创建**。
105
+
106
+ 一次性配置(推荐 trusted publishing,免 API token):
107
+
108
+ 1. 注册 PyPI 账号并开启 2FA。
109
+ 2. 打开 https://pypi.org/manage/account/publishing/ ,添加 **pending publisher**:
110
+ - PyPI project name: `scientific-data-mcp`
111
+ - Owner: `xyonium`
112
+ - Repository: `scientific-data-mcp`
113
+ - Workflow name: `publish.yml`
114
+ - Environment: `pypi`
115
+ 3. 仓库 Settings → Secrets and variables → Actions → Variables 新建 `PYPI_PUBLISH=true`。
116
+ 4. 之后 push `v*` tag(或手动运行 `publish` workflow)即构建 sdist/wheel 并上传。
117
+
118
+ 工作流在 [.github/workflows/publish.yml](./.github/workflows/publish.yml):tag 触发时只有在 `PYPI_PUBLISH=true` 才发布,避免未配置时 CI 变红。首次上传会自动创建 PyPI 项目并占用这个名字。
119
+
120
+ ## 数据源清单追踪
121
+
122
+ [docs/research/kdense-databases.json](./docs/research/kdense-databases.json) 是 [K-Dense scientific-agent-skills](https://github.com/K-Dense-AI/scientific-agent-skills) `database-lookup` 的数据库快照(当前 v1.8,80 库,2026-09-30 复核)。
123
+
124
+ ```bash
125
+ python scripts/kdense_sources.py --check # 与上游 diff
126
+ python scripts/kdense_sources.py --update # 刷新快照
127
+ ```
128
+
129
+ GitHub Action `kdense-sources` 每季度(1/4/7/10 月 1 日)自动扫描;上游新增或移除数据库时开 issue(已有 open issue 则追加评论)。
130
+
131
+ 80 个库逐个的“已实现 / M6 / 归兄弟项目 / 不做”决定见 [docs/research/kdense-coverage.md](./docs/research/kdense-coverage.md)。
132
+
133
+ ## 开发
134
+
135
+ ```bash
136
+ pytest -q # hermetic(respx mock),0 egress
137
+ ruff check .
138
+ python scripts/live_smoke.py # 真实打 9 个基础上游(配 key 时 11 个),人工跑
139
+ ```
140
+
141
+ - 设计与决策:[`docs/superpowers/specs/`](./docs/superpowers/specs/)
142
+ - 实施计划:[`docs/superpowers/plans/`](./docs/superpowers/plans/)
143
+ - 工作记忆:[`docs/memory/MEMORY.md`](./docs/memory/MEMORY.md)
144
+ - 立项证据:[`docs/research/kimi-sources/`](./docs/research/kimi-sources/)
145
+ - 维护指南:[`AGENTS.md`](./AGENTS.md)
146
+
147
+ ## License
148
+
149
+ MIT
@@ -0,0 +1,8 @@
1
+ services:
2
+ scientific-data:
3
+ build: .
4
+ image: scientific-data-mcp:dev
5
+ command: ["--http", "--host", "0.0.0.0", "--port", "8000"]
6
+ ports:
7
+ - "8000:8000"
8
+ restart: unless-stopped