如何选择 NCI Imaging Data Commons 的访问路径本地 idc-index、REST API 还是 MCP【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillsscientific-agent-skills 仓库中的imaging-data-commonsskill 用于从 NCI Imaging Data CommonsIDC查询和下载公开癌症影像数据。它提供三条元数据访问路径本地idc-index包内嵌 DuckDB 索引无需网络、托管 REST APIhttps://api.imaging.datacommons.cancer.gov/v3无认证、托管 MCP 服务器https://api.imaging.datacommons.cancer.gov/mcp无认证。数据访问本身无需任何认证文件下载走公开的 GCS 与 AWS S3。skill 文档SKILL.md明确说明不存在单一默认路径选哪条取决于当前会话状态和任务内容。下面按文档给出的路由规则走完整个选择过程并给出每条路径的落地命令和验证方式。先用四个条件做路由判断SKILL.md 的Overview给出一条按顺序判断的路由门当前会话已接入 IDC MCP 服务器是——把发现discovery和元数据查询路由到 MCP 工具。否则idc-index是否已安装运行python scripts/check_version.py脚本位于 scripts/check_version.py相对 skill 目录执行。通过则全部走idc-index。未安装且任务是只读元数据——数量统计、属性取值、collection 查询、行数小于 10 000 的 SQL、license、引用、viewer URL用curl走 REST API不要安装任何东西安装会引入约 77 MB 的打包索引数据外加 pandas、pyarrow、duckdb元数据问题用不到。未安装且任务超出元数据——下载文件、pandas 或绘图、pydicom/SimpleITK、病理 tiling、超过 10 000 行的结果、需要用户可重复运行的版本固定脚本安装idc-indexcheck_version.py退出码非零并打印针对当前解释器的精确安装命令。优先在虚拟环境中安装然后重启 Python。文档补充了一条原则idc-index仍然是能力最强的路径也是唯一能移动影像字节的本地路径这条路由规则只是让你不要在任务需要之前为它付费。check_version.py本身从不安装任何东西发现新版idc-index或 skill 时会一并提示。路径一MCP 服务器会话已接入时MCP 服务器是 IDC 托管的服务端点为https://api.imaging.datacommons.cancer.gov/mcpstreamable HTTP 传输无认证。详见 mcp_guide.md。判断会话里有没有这个服务器按 mcp_guide.md 的描述用服务器自己定义的标识判断而不是主机侧的命名习惯最强信号——资源 URI服务器发布idc://guide数据模型与推荐工作流Markdown和idc://tablesrun_sql可用表及列数JSON两个资源。能枚举 MCP 资源时出现idc://guide即无歧义地确认是 IDC 服务器。备选——工具名指纹build_cohort、get_cohort_urls、list_analysis_results、get_idc_version四个工具名中至少出现三个才算数。run_sql、get_stats、get_citations这类通用名字本身不能作为证据。识别模糊或工具调用失败时降级而不是报错只读元数据退回 REST API需要下载或本地分析退回idc-index。文档同时提醒这是消歧不是认证——运行时检查无法证明对端服务器就是 NCI 运营的信任锚点是你配置时的 URL 加上 TLS。有 MCP 服务器时的分工mcp_guide.md 给出明确的分工表IDC 版本、数量统计、合法过滤值、队列构建、一次性元数据 SQL 归服务器结果要进入本地 PythonDataFrame、下载 DICOM、DICOMweb、BigQuery、病理 tiling、可复现脚本归idc-index。两条规则解决重叠发现优先走服务器——它对着当前 IDC 版本运行不依赖本地idc-index的固定版本结果必须变成 Python 对象时优先idc-index——把 DataFrame 经工具输出回传会浪费上下文并丢失类型。服务器自带使用说明大多数宿主会自动注入工具调用顺序先list_attributes/get_attribute_values落地取值再list_tables后写 SQL以服务器自己的说明为准不要从 SKILL.md 重新推导——服务器下次发版后两者会漂移。以 Claude Code 为例添加服务器的命令和注意事项见 mcp_guide.md 的Host-specific notesclaude mcp add --transport http idc https://api.imaging.datacommons.cancer.gov/mcp工具会以mcp__idc__tool形式暴露allow 规则需要无通配符的服务器段mcp__idc__*可以mcp__*不行。另外claude mcp list只读文件配置对 claude.ai 连接器会报 No MCP servers configured不能用来做存在性检查。其他支持 MCP over streamable HTTP 的 agent 均可使用只需端点 URL 和无认证这两项配置具体注册方式查宿主自己的文档。路径二REST API未安装 idc-index 时的只读元数据路径端点https://api.imaging.datacommons.cancer.gov/v3无认证、无账号、无凭据任意终端用curl即可。完整端点参考见 rest_api_guide.md。关键前提只用 v3——V1/V2 已被取代并计划下线遇到旧教程里的/v1/路径或Modality_btw这类按属性后缀过滤的写法迁移到 v3 而不是沿用。验证会话起点版本与规模Bhttps://api.imaging.datacommons.cancer.gov/v3 curl -s $B/version # idc_version, idc_index_data_version, api_version curl -s $B/stats # collections, patients, studies, series, instances, size_TB文档示例3.0.0b3构建中/version返回{idc_version:v24,idc_index_data_version:24.2.2,api_version:3.0.0b3,build:0640860}idc_version是 API 提供的 IDC 数据版本是使用 API 时的权威值——优先于 SKILL.md frontmatter 中固定的idc-data-version那个值只记录 skill 最后一次验证时的版本。先落地过滤值再过滤按 rest_api_guide.md猜测Modality、BodyPartExamined的字符串是空结果集最常见的来源。正确顺序GET /attributes看可过滤属性3.0.0b3时为 19 个及它是term还是range再用GET /attributes/{attr}/values取真实取值和大小写——匹配是大小写敏感的。curl -s $B/attributes/Modality/values?limit5 # 真实过滤值带计数队列计数与清单filters 键与 warningscohort/counts、cohort/manifest、cohort/manifest.txt、licenses、citations的过滤对象一律放在filters键下包含terms属性到取值列表属性内 OR、属性间 AND和rangesgte/lte数值或日期区间任一边可省略两部分。curl -s $B/cohort/counts -H content-type: application/json \ -d {filters: {terms: {collection_id: [rider_pilot]}}}文档示例输出{patients:8,studies:154,series:774,instances:21111,size_TB:0.011, filters_applied:{terms:{collection_id:[rider_pilot]},ranges:{}},warnings:[]}每个带过滤的响应都会回显filters_applied和warnings误用会被拒绝而不是被忽略裸过滤对象缺filters键返回422并指出正确形状未识别的键term拼成terms、区间界写成min同样422并点名该键未知属性或把 range 属性当 term 用返回400并指明应做的发现调用未过滤的cohort/manifest或manifest.txt返回400不会枚举整个存档。报告任何计数前先读warnings零计数加空warnings表示过滤生效且确实没匹配到这是真实答案零计数加大小写 warning 表示过滤写错了。filters_applied还覆盖另一种形状检查发现不了的情况请求里带了一个有效谓词加一个不构成约束的谓词如{collection_id: []}返回的数字看起来很合理只有warnings会指出被丢弃的那一半。元数据 SQL 的行数上限POST /sql接受单条只读SELECT/WITH … SELECTDuckDB 执行可查idc-index暴露的表加上clinical.tablemax_rows默认 5 000、上限 10 000命中上限时响应带truncated: true。其他约束30 秒 SQL 超时、4 GB 查询内存无按调用者的限流和配额突发流量会体现为变慢或503退避重试即可。curl -s $B/sql -H content-type: application/json \ -d {sql:SELECT collection_id, COUNT(*) n FROM index GROUP BY 1 ORDER BY n DESC LIMIT 3}超出这个行上限、或需要固定数据版本时文档指路 parquet_access_guide.md直接对 GCS 上的 Parquet 用 DuckDB 查询无需 idc-index但仍需 DuckDB且到不了 per-collection 临床表。路径三本地 idc-indexSKILL.md 给定的标准开场是初始化客户端并验证数据版本from idc_index import IDCClient client IDCClient() # Verify IDC data version (should be v24) print(fIDC data version: {client.get_idc_version()})文档中当前验证的版本是 v24。核心工作流是client.sql_query()查元数据 →client.download_from_selection()下载 →client.get_viewer_URL()生成浏览器 URL按 study 查看时一个 DICOM Study 里的多个 Series——例如一次 MRI 的 T1、T2、DWI——会一起出现在 viewer 里。写 SQL 前先用client.get_index_schema(index)读缓存元数据不执行 SQL或client.indices_overview确认列名和描述client.fetch_index(table_name)在任何表查询前调用是安全且幂等的。两个下载方法的参数顺序是文档点名的高频出错点download_from_selection第一个位置参数是downloadDirdownload_dicom_series第一个是seriesInstanceUID而且download_from_selection收的是过滤关键字参数不是 DataFrame——要把查询结果的 UID 先提取成字符串列表再传入。会话开始时验证版本三条路径各自的检查命令按路由结果在会话开始处验证 IDC 数据版本MCP 路径调用get_idc_version工具REST 路径GET /v3/version本地路径client.get_idc_version()并运行python scripts/check_version.py检查本地包是否需要升级。当 API或 MCP 服务器与本地idc-index同时在场时两边基于同一个idc-index-data包一致性是精确比较而不是猜测。rest_api_guide.md 给出对照脚本import idc_index_data import requests api requests.get(https://api.imaging.datacommons.cancer.gov/v3/version, timeout30).json() api_version, local_version api[idc_index_data_version], idc_index_data.__version__ if api_version.split(.)[0] ! local_version.split(.)[0]: print(fDifferent IDC data release: API {api_version}, local {local_version} — upgrade) elif api_version ! local_version: print(fSame data release, different index build: API {api_version}, local {local_version})解读规则同来源major 是 IDC 数据发布24.x.y对应v2424.0.0 随 v24 发布24.1.0 / 24.2.x 是同一发布的后续索引构建。因此差异含义后果major 不同24.x.y vs 25.x.y不同 IDC 数据发布有 series 新增/修订/移除计数可以合理地不同且idc-index无法下载它索引里没有的 seriesminor/patch 不同24.2.0 vs 24.2.2同一数据发布索引构建不同到处是同一批 series下载不受影响只有触及新增或修正列的元数据查询才可能不同两边不一致时文档要求把两个版本都报出来再调和不要混用两边的结果升级idc-indexcheck_version.py打印命令把本地拉到较新的idc-index-data或在无法升级的环境里从桶直接传。major 落后还会直接破坏下载idc-index把拿到的每个s3://URL 对它自己的索引解析新发布的 manifest 可以列它从未见过的 series——download-from-manifest会记日志后跳过不报错download_from_selection(seriesInstanceUID…)则静默丢弃这些 UID。不要把这种部分下载当成没数据上报rest_api_guide.md 的When the local index is a data release behind the API一节的替代方案是绕开索引、用s5cmd --no-sign-request直接从 manifest URL 传。从 MCP/REST 交接到 idc-index 下载三条路径中文件和 DataFrame 只属于idc-indexREST API永远不移动影像字节它返回公开s3://URL 和 manifest传输发生在云端存储到客户端之间。交接的边界工件是一个SeriesInstanceUID列表或保存好的manifest.txt。mcp_guide.md 的交接示例# UIDs obtained from the MCP servers build_cohort / run_sql output series_uids [ 1.3.6.1.4.1.14519.5.2.1.7009.2403.334240657131972136850343327463, # ... ] from idc_index import IDCClient client IDCClient() # Confirm size before downloading — the server reports size_TB, but re-check locally sizes client.sql_query(f SELECT COUNT(*) AS series, SUM(series_size_MB)/1000 AS size_GB FROM index WHERE SeriesInstanceUID IN ({,.join(f{u} for u in series_uids)}) ) print(sizes) client.download_from_selection( downloadDir./data, seriesInstanceUIDseries_uids, # a list, not a DataFrame dirTemplate%collection_id/%PatientID/%Modality, )series_uids换成你从服务器build_cohort/run_sql输出里实际拿到的 UID文档示例只列了一个作格式说明。downloadDir是本地目录下载前建议用上面的大小查询确认量级——文档提醒先小范围探索再扩大有些 collection 是 TB 级的。首次调用idc-index前运行python scripts/check_version.py即使发现工作是在服务器端完成的——两个组件独立发版。若用户要的是可在会话外重复运行的 shell 命令mcp_guide.md 指出get_cohort_urls返回现成的idcCLI 命令是更好的交接物纯 REST 路径下cohort/manifest.txt保存到本地后用idc download-from-manifest idc_manifest.txt --download-dir ./idc-data执行需要 idc-index 已安装。各路径的能力边界选择路径时对照 SKILL.md 的Data Access Options表方法认证适用idc-index无下载、pandas 分析、无上限查询——能力最强IDC MCP 服务器无会话已接入时的发现、队列构建、元数据IDC REST API无无安装的元数据任何语言或 shellidc-index缺席时的默认Direct Parquet (GCS)无固定数据版本、或结果超过 REST 行上限云存储 (S3/GCS)无直接文件访问、批量传输DICOMweb via IDC proxy无工具/PACS 集成有每日配额适合测试和中等用量DICOMweb via Google Healthcare需 GCP生产量级避开 proxy 配额BigQuery需 GCP完整 DICOM 元数据、私有元素、SR 测量——最后手段几条边界值得记住IDC Portalportal.imaging.datacommons.cancer.gov只有浏览器交互没有程序化接口不要把它写进脚本步骤build_cohort/cohort/manifest类端点要求至少一个过滤谓词空过滤不会被整个存档满足license 挂在 series 上而不是 collection 上176 个 collection 中 39 个带多种 license约 97% 的数据是 CC BY、约 3% 是 CC BY-NC混合队列以最严格条款为准——所以用哪条路径不影响 license 和引用这两件事三条路径都能做POST /v3/licenses、POST /v3/citations或 MCP 的get_licenses/get_citations留在当前会话已在用的路径上即可。路由结论与下一步把文档的路由门压缩成可执行的判断会话有 MCP 服务器idc://guide资源或工具名指纹确认→ 发现与元数据走 MCP下载前把SeriesInstanceUID列表交回idc-index没有 MCP 且check_version.py通过 → 全程idc-index没有 MCP 且未安装、任务只是元数据 →curl走 REST v3不为元数据问题装 77 MB 的索引没有 MCP 且未安装、任务要下载/本地分析/超 10 000 行 → 按check_version.py打印的命令安装后再走idc-index任何时刻 API 与本地版本 major 不一致 → 先报出两个版本升级本地或绕过索引直传再谈下载。深入查询模式过滤值发现、分割/标注查询、版本追踪见 sql_patterns.md表结构细节见 index_tables_guide.mdCLI 下载dirTemplate、manifest 断点续传、dry-run 体积估算见 cli_guide.md。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
