scientific-agent-skills 中 IDC MCP Server 实战指南识别方法、工具清单、与 idc-index 的分工边界【免费下载链接】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本篇基于 scientific-agent-skills 仓库中imaging-data-commons技能的 MCP Server 指南讲清 NCI Imaging Data CommonsIDC托管的 MCP 服务器在 AI Agent 会话中的定位如何可靠地识别它、它的工具清单快照、它与本地idc-index包在元数据查询和文件下载上的分工规则以及两者之间以SeriesInstanceUID列表为边界的交接模式。读完本篇你应能在任意支持 MCP 的 Agent 环境中正确路由 IDC 元数据请求、完成服务端到本地的数据交接并理解版本权威性判断背后的实现依据。1. 定位MCP 服务器是可选加速路径不是前置依赖IDC 运营一个托管的 Model Context ProtocolMCP服务器把 IDC 的发现discovery与元数据能力暴露为 Agent 工具。指南开宗明义地指出这个服务器是可选的SKILL.md中的所有内容在没有它时依然可用。端点信息如下属性值URLhttps://api.imaging.datacommons.cancer.gov/mcp传输方式Streamable HTTPstreamable-http有时写作http认证无服务器身份IDC (Imaging Data Commons)在主文档 SKILL.md 中MCP 服务器是四条访问路径路由门routing gate的第一分支当前会话已有 IDC MCP 服务器把发现与元数据查询路由过去即本篇主题。否则idc-index已安装运行python scripts/check_version.py通过后用idc-index完成所有工作。未安装且任务是只读元数据计数、属性取值、集合查找、10000 行以内的 SQL、许可、引用、查看器 URL直接用curl走 REST API不要安装任何东西——安装idc-index需要约 77 MB 打包索引数据外加 pandas、pyarrow、duckdb这些对一个元数据问题来说是浪费。未安装且任务超出元数据下载文件、pandas 分析、pydicom/SimpleITK、病理切片处理、超 10000 行结果、需要复跑的脚本安装idc-indexcheck_version.py会退出非零并打印针对当前解释器的精确安装命令。从 SKILL.md 的路由门设计可以看出该技能的核心理念没有唯一默认路径最便宜的正确路径取决于会话状态与任务性质。MCP 服务器恰好处于这条决策链的最前端——它在时它是发现与元数据的权威入口。2. 识别 IDC MCP 服务器工具名与资源 URI 由服务器定义因此在所有宿主机上是一致的。应使用这些标识而不是宿主机特有的命名习惯来判断服务器是否存在。2.1 最强信号idc://资源 URI服务器在idc://scheme 下发布两个资源URI内容idc://guide数据模型与推荐工作流Markdownidc://tables可供run_sql使用的表含描述与列数JSON如果宿主 Agent 能够枚举 MCP 资源那么存在 URI 为idc://guide的资源即可无歧义地识别出该服务器。2.2 后备手段工具名指纹若无法枚举资源则要求工具名build_cohort、get_cohort_urls、list_analysis_results、get_idc_version中至少命中三个。不要把run_sql、get_stats、list_tables、get_citations单独作为证据——这些名字过于通用别的服务器也可能暴露同名工具。2.3 这是消歧不是认证指南特别强调任何运行时检查都无法证明对端服务器由 NCI 运营——一个恶意服务器同样可以返回idc://guide并把工具命名为任意值。信任锚是用户配置的那个 URL 加上 TLS它在服务器被添加时就已确立而不是技能运行时。对路由而言这就够了这个检查只需区分IDC与用户安装的其它服务器。2.4 Fail soft有歧义就降级不报错如果识别结果有歧义、或某次工具调用失败应当回退而不是报告错误回退到 REST APIREST API 指南处理只读元数据——它是同一服务去掉配置后的形态无需任何安装或回退到idc-index——当它已安装、或任务需要下载与本地分析时。同时注意工具名可能随服务器成熟而变化因此识别逻辑必须允许这种漂移。3. 工具清单对3.0.0b3的快照以下清单对照服务器版本3.0.0b3验证。指南明确提醒把它当作快照而非契约——应调用服务器自身的列表接口而不是假设这份清单仍是最新。分组工具版本与规模get_idc_version、get_stats集合list_collections、get_collection、list_analysis_results属性落地groundinglist_attributes、get_attribute_values队列Cohortbuild_cohort、get_cohort_urlsSQLlist_tables、get_table_schema、run_sql临床数据list_clinical_tables、get_clinical_table_schema、get_clinical_table归属Attributionget_citations、get_licenses可视化get_viewer_url三条使用纪律值得注意服务器自带使用说明大多数宿主会自动注入。工具编排应遵循那些说明过滤前先用list_attributes/get_attribute_values落地取值写 SQL 前先查list_tables不要从SKILL.md重新推导这套工作流——服务器下一次发布时两者就会漂移。队列结果自带过滤器回显。build_cohort与get_cohort_urls要求至少一个过滤谓词缺失时会干净地失败而不是返回整个档案库结果会回显实际应用的过滤器并对被丢弃的谓词或大小写不匹配的值给出警告。报告计数前先读警告——零计数且无警告意味着过滤器生效但确实没有匹配这是一个真实答案而不是错误。这与它们所包装的 REST 端点是同一契约详见 rest_api_guide.md。4. 分工规则服务器与idc-index在哪重叠、在哪分道扬镳服务器与idc-index只在元数据查询上重叠其余各处分工明确任务使用IDC 数据版本、集合与序列计数服务器get_idc_version、get_stats构建查询前的合法过滤值服务器get_attribute_values按属性过滤选择队列服务器build_cohort一次性元数据 SQL、结果以散文形式消费服务器run_sql结果要喂给本地 Python 的元数据 SQLidc-indexclient.sql_query下载 DICOM 文件idc-indexclient.download_from_selectionpandas / notebook 分析、绘图idc-index读取像素数据pydicom、SimpleITKidc-index 本地文件DICOMweb、BigQuery、直连 S3/GCS、Parquetidc-index及对应参考指南数字病理切片与标注工作流idc-index 病理指南用户要复跑的可复现脚本idc-index脚本的生命周期长于会话两条规则解决重叠地带发现discovery优先用服务器。它托管在当前 IDC 发布之上不依赖SKILL.md中固定的idc-index版本。结果必须变成 Python 对象时优先idc-index。让 DataFrame 绕道工具输出往返既浪费上下文又丢失类型。5. 从服务器到idc-index的交接边界工件是一份SeriesInstanceUID值列表。指南给出的交接模式# UIDs 来自 MCP 服务器的 build_cohort / run_sql 输出 series_uids [ 1.3.6.1.4.1.14519.5.2.1.7009.2403.334240657131972136850343327463, # ... ] from idc_index import IDCClient client IDCClient() # 下载前先确认大小 —— 服务器会报告 size_TB但本地要复核 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, # 是列表不是 DataFrame dirTemplate%collection_id/%PatientID/%Modality, )几个容易踩的坑结合 SKILL.md 与源码download_from_selection接收过滤关键字参数不接收 DataFrame——from_selection 指的是按条件过滤 IDC 索引而非接受 pandas 对象。要先从查询结果中把 UID 提取成列表。会话中第一次调用idc-index之前要运行python scripts/check_version.py即便发现工作是在服务器端完成的——两个组件独立演进版本。get_cohort_urls还会返回现成的idcCLI 命令。当用户要一条能在会话之外复跑的 shell 命令时这是更好的交接形式参见 CLI 指南。反方向几乎没有必要idc-index的结果本来就在本地很少需要再送回服务器。5.1check_version.py的源码级行为交接前必须跑的检查脚本 check_version.py 的行为可以从源码精确确认版本钉在 check_version.pyMIN_VERSION 0.12.5对应idc-indexSKILL_VERSION 1.8.1对应技能上游发布两者与 SKILL.md frontmatter 中的idc-index与source-skill-version字段保持同步。它从不安装任何东西不满足最低版本时打印安装命令并以非零码退出把环境选择留给调用方。安装命令由install_commands()生成始终显式指定正在运行的解释器——优先uv pip install --python 解释器否则python -m pip install两者都不绕过 PEP 668 对外部管理解释器的保护。版本比较用parse_version()取各段前导数字生成数值三元组容忍0.13.0rc1、v1.7.0-beta这类预发布标签使更新提示保持保守。对 PyPI / GitHub 的更新探测是尽力而为best-effort离线时静默跳过。仓库自带了离线、无第三方依赖的契约测试 test_check_version.py从源码层面固化了三类关键性质TestNeverInstalls断言脚本源码中不存在subprocess、pip3、os.system、eval(、exec(等安装或动态执行痕迹TestVersionsMatchFrontmatter用正则解析SKILL.mdfrontmatter断言脚本中的MIN_VERSION与SKILL_VERSION和 frontmatter 一致——因为脚本与SKILL.md的钉住值被不同消费者读取漂移会误导用户。这解释了为什么指南把交接前先跑check_version.py写成硬性步骤而不是建议。6. 版本权威性听谁的当 MCP 服务器在场时它是 IDC 数据版本的权威应调用get_idc_version而不是引用SKILL.mdfrontmatter 中的idc-data-version值当前为v24——那个值只记录技能最后一次被验证时对应的发布版本。如果服务器与本地安装的idc-index报告了不同版本要明说并把两个版本都报出来。这个不一致是真实存在的——托管服务器独立于用户安装的包跟随 IDC 发布——而且它直接改变新增了什么这类问题的正确答案。从配套的 REST API 指南 可以进一步读出比较的精确方法两侧都构建在idc-index-data包上主版本号即 IDC 数据发布24.x.y服务v24主次号不同仅意味着索引构建不同新增/修正的表与列序列集合相同主号落后则意味着本地idc-index无法下载其索引中没有的新序列此时应升级本地包或直接从存储桶转移。7. 宿主相关的注意事项以下各项不具备可移植性只适用于特定 Agent 环境。7.1 Claude Code工具命名MCP 工具暴露为mcp__server__tool其中server是配置的服务名所有不属于A-Za-z0-9_-的字符替换为_。CLI 安装时命名为idc则得到mcp__idc__build_cohortclaude.ai 连接器命名为IDC MCP prod则得到mcp__claude_ai_IDC_MCP_prod__build_cohort。枚举资源ListMcpResourcesTool返回的每个资源带server字段一次调用即可同时找到idc://guide资源及其所属服务器名。添加服务器claude mcp add --transport http idc https://api.imaging.datacommons.cancer.gov/mcp权限规则允许规则需要字面、不含通配的服务器段——mcp__idc__*有效mcp__*无效。连接器安装需要各自的mcp__claude_ai_name__*规则因此规则因安装路径而异。用 CLI 检测不可靠claude mcp list只读取文件型配置~/.claude.json、.mcp.json。对于同一会话中已连接且工作正常的 claude.ai 连接器它会报告 No MCP servers configured因此不能用作存在性检查。7.2 其它宿主任何支持 streamable HTTP 上 MCP 的 Agent 都可以使用该服务器。查对应宿主文档了解服务器注册方式与工具命名空间规则配置端只需要端点 URL 和无需认证这一条信息。8. 延伸阅读均在当前仓库内SKILL.md技能总纲含四条访问路径路由门、数据模型、索引表与核心 API 模式。rest_api_guide.mdMCP 工具所包装的同一 REST 服务含过滤器语法、filters_applied/warnings契约与版本比较方法。cli_guide.mdidc download/download-from-manifest/download-from-selection的完整参数与可复跑 shell 工作流。check_version.py 与 test_check_version.py版本检查脚本及其行为契约测试。digital_pathology_guide.mdget_viewer_url之外的病理切片本地工作流。【免费下载链接】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），仅供参考