内容
# IDC API
[](https://github.com/fedorov/IDC-REST-MCP/actions/workflows/ci.yml)
首个 **REST API** 和 **MCP 服务器**，专为 [NCI 成像数据 commons（IDC）](https://imaging.datacommons.cancer.gov/) 而设计，
背后由 [`idc-index`](https://github.com/ImagingDataCommons/idc-index) Parquet 索引支持，
通过 DuckDB 进行本地查询。所有 IDC 数据都是开放的 - **无需身份验证**。
一个与后端无关的 **核心** 库，两个基于它的薄适配器：
- **REST API** （FastAPI）- 语言无关的 HTTP 访问，带有自动生成的 OpenAPI 文档。
- **MCP 服务器** - 与模型上下文协议工具相同的功能，因此 LLM 代理
（Claude 等）可以直接查询 IDC。
两个表面共享一个核心，因此功能实现和测试一次，并在两者中公开。
> **状态：** 正在积极使用。发现、队列/清单构建、受保护的只读 SQL、模式
> 发现、查看器 URL、引用和许可证 - 通过 REST 和 MCP。SQL 可以查询和
> 加入专用索引（seg/ann/rtstruct，ct/mr/pt，幻灯片显微镜，对比/几何）
> 和每个集合的临床表，所有这些都在构建时获取；本地下载在 stdio
> MCP 模式下运行。仍在开发中：可选的 BigQuery 后端（用于每个分段的详细信息、SR 辐射组学和
> 私有 DICOM 元素）和 CDN 缓存（参见 [`dev/caching_and_cdn.md`](dev/caching_and_cdn.md)）。
## 文档
- **[用户指南](docs/user-guide.md)** - 概念、查询接口及其关系、推荐的工作流程以及 REST/MCP 示例。**从这里开始学习如何使用它。**
- [`dev/architecture.md`](dev/architecture.md) - 内部设计（一个核心，两个适配器）。
- [`dev/api_v3_plan.md`](dev/api_v3_plan.md) - 完整设计原理 + SQL 威胁模型。
- [`dev/deployment.md`](dev/deployment.md) - Cloud Run 部署。
- [`dev/developer_guide.md`](dev/developer_guide.md) - 贡献/添加功能。
- [`SECURITY.md`](SECURITY.md) - 威胁模型、强化措施以及如何报告漏洞。
## 安装（开发）
```bash
uv venv --python 3.12
uv pip install -e ".[dev]"
uv run --directory . pytest tests -q
```
第一次运行会构建一个只读 DuckDB 数据库（缓存在您的临时目录下，固定到索引版本；仅在 `idc-index-data` 升级时重建）。默认情况下，它还会从 idc-index 版本中获取专用索引（约 40 MB），因此 **第一次构建会下载数据** -
设置 `IDC_API_INCLUDE_INDICES=none` 以仅从捆绑的 Parquet 构建（无需构建时下载，`idc-index-data` 已经附带的内容）。无需 GCP 帐户或凭证。
## 运行
```bash
uv run idc-api # REST API → http://127.0.0.1:8000 （Swagger 在 /docs）
uv run idc-mcp # MCP 服务器，stdio（本地）- 也可以下载文件
uv run idc-mcp --http --host 0.0.0.0 --port 8080 # MCP 服务器，托管/共享（仅限清单）
```
快速体验 - 通过 REST 构建一个乳腺 MRI 队列：
```bash
curl -s localhost:8000/v3/cohort/manifest \
-H 'content-type: application/json' \
-d '{"filters": {"terms": {"Modality": ["MR"], "BodyPartExamined": ["BREAST"]}}, "page_size": 3}'
```
有关端点/工具参考、MCP 客户端设置、下载和配置，请参阅
**[用户指南](docs/user-guide.md)**。
## 部署
使用精简镜像在任何地方运行：
```bash
docker build -t idc-api .
docker run -p 8080:8080 idc-api # REST API
```
镜像在构建时烘焙只读 DuckDB 文件（通过 `IDC_API_DUCKDB_PATH` 设置），因此
冷启动是即时的，容器是完全无状态的（无机密，无 GCP 数据访问）。
在每个 IDC 版本上重建以获取新的 `idc-index-data`。
**Cloud Run：** 分步说明（构建/推送，部署，DuckDB 内存大小调整规则，
更新 IDC 版本以及可选的托管 MCP 服务）位于
[`dev/deployment.md`](dev/deployment.md)。
## 致谢 IDC
基于 [NCI 成像数据 commons（IDC）](https://imaging.datacommons.cancer.gov/) 构建。在使用 IDC 数据发布结果时，请包含每个数据集的引用 **和** 引用 IDC 本身
通过引用 IDC 论文 - Fedorov 等人，[10.1148/rg.230180](https://doi.org/10.1148/rg.230180)。
`citations` 功能返回两者；请参阅
[用户指南](docs/user-guide.md#6-licenses--citations).
该软件部分由 NCI 成像数据 commons 项目维护，该项目已获得
全部或部分联邦资金来自美国国家癌症研究所、美国国家卫生研究院、卫生和人类服务部，
任务订单编号 HHSN26110071，合同编号 HHSN261201500003I。声明不一定反映
美国卫生和人类服务部的观点或政策，也不意味着提及贸易名称、商业产品或
组织意味着得到美国政府的认可。
