MCP server coordination, check_version.py fix, and 1.7.0 release - #31
Merged
Conversation
IDC now runs an MCP server at api.imaging.datacommons.cancer.gov/mcp (streamable HTTP, no auth). Add guidance for agents that have it connected, without making the skill depend on it. - SKILL.md: new "IDC MCP Server" section covering identification, the division of labor with idc-index, and the SeriesInstanceUID handoff. Listed in Quick Navigation, Data Access Options, and Tool Selection. - references/mcp_guide.md: endpoint, verified tool inventory, overlap resolution rules, handoff code, version authority, host-specific notes. - USAGE.md: optional setup section with the endpoint and a Claude Code registration example. Identification uses the idc://guide MCP resource, or a fingerprint of three or more IDC-specific tool names; generic names such as run_sql are excluded because another server could expose them. This disambiguates IDC from a user's other servers but does not authenticate the endpoint, so the guidance fails soft to idc-index whenever identification is ambiguous. Kept vendor-neutral in SKILL.md per the Agent Skills format: tool names and resource URIs are server-defined and portable, while host-specific mechanics (tool namespacing, resource enumeration, permission rules, install commands) are confined to a labeled section of the reference guide and to USAGE.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The tool-name fingerprint and resource URI the skill uses to identify the server are a contract with a service that versions independently of this repo, and the server is still at beta (3.0.0b2). Without a check, the docs go stale silently. The tests parse expectations out of the documentation rather than duplicating them, so SKILL.md and references/mcp_guide.md stay the single source of truth: - fingerprint names and the mcp_guide.md inventory still exist on the server - the inventory covers every tool the server exposes (catches additions) - idc://guide is still published - offline: the endpoint URL agrees across SKILL.md, USAGE.md and the guide, the fingerprint meets its own "three or more" threshold, and it never relies on generic names such as run_sql Network tests skip rather than fail when the server is unreachable, so an outage does not turn CI red while genuine drift still does. Added as a separate CI step, and USAGE.md to the workflow path filter since the URL consistency test reads it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Overview set up version check, install, and core workflow entirely in idc-index terms before the IDC MCP Server section appeared, so a session that already had the server could install a Python package before learning it did not need to. The only earlier signal was a parenthetical inside the bold CRITICAL block, which an agent is more likely to obey than to read conditionally. Put the fork next to "Primary tool", where the reader's model is set, and make the version-check line unconditional again. idc-index stays the primary, always-available path: MCP presence is a property of the session, not of IDC, so it is not co-primary. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
check_version.py no longer installs anything. It previously ran `pip3 install --upgrade --break-system-packages`, which bypassed the PEP 668 guard on externally managed interpreters and — combined with the `pandas<=2.2.4` cap in idc-index <= 0.12.4 — could silently downgrade a system-wide pandas 3.x as a side effect of a version *check*. It now prints the exact install command for the running interpreter and exits non-zero. Reported in review of K-Dense-AI/scientific-agent-skills#158. Pinned minimum moves to idc-index 0.12.5, which relaxes the dependency to `pandas>=2.2.2,<4`, so installing it no longer perturbs a pandas 3.x environment (verified against pandas 3.0.5). use_cases.md, digital_pathology_guide.md, and parquet_access_guide.md carried a "Tested with" header but had no tests behind it, so the headers could not be refreshed honestly. Adds 31 tests covering the use-case selection queries, every SM/ANN/SEG query in the pathology guide, and the DuckDB-over-HTTPS Parquet queries (98 total, up from 67). The pathology tests assert the TCGA-BRCA counts quoted inline in that guide, so a data release that moves them fails CI instead of quietly making the prose wrong. Minor rather than patch: the MCP server support already on this branch adds a new routing surface, and dropping the auto-install changes documented startup behavior for anyone who relied on it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two related bodies of work, released together as 1.7.0: teaching the skill to coexist with IDC's hosted MCP server, and responding to the
check_version.pyreview on K-Dense-AI/scientific-agent-skills#158.IDC MCP server coordination
IDC now runs a hosted MCP server at
https://api.imaging.datacommons.cancer.gov/mcp(streamable HTTP, no authentication). A session that already has it connected shouldn't be told topip install idc-indexand re-derive what the server can answer directly.SKILL.mdplusreferences/mcp_guide.md: how to recognize the server, how to divide work between it andidc-index, and how to hand offSeriesInstanceUIDs for download.SKILL.mdOverview next to "Primary tool", so it's read before theidc-indexsetup rather than discovered after.idc-indexremains the primary, always-available path and the version check stays unconditional.idc://guideMCP resource, or a fingerprint of three or more IDC-specific tool names. Generic names likerun_sqlare explicitly not evidence, and anything ambiguous falls back toidc-index.USAGE.mdsection with the endpoint and a Claude Code registration example.tests/test_mcp_server.pyparses the documented fingerprint and tool inventory back out ofSKILL.md/references/mcp_guide.mdand checks them against the live server, so the docs can't drift silently as the beta server evolves. Network tests skip rather than fail when the server is unreachable; the offline checks guard URL consistency and keep generic tool names out of the fingerprint.check_version.pyno longer installs anythingThe script previously ran
pip3 install --upgrade --break-system-packages. That bypassed the PEP 668 guard on externally managed interpreters and — combined with thepandas<=2.2.4cap in idc-index ≤ 0.12.4 — could silently downgrade a system-wide pandas 3.x as a side effect of a version check. It also invoked whateverpip3resolved to onPATH, which is not necessarily the running interpreter's pip, so the install could land in a different environment than the one that failed to importidc_index.It now prints the exact
pip installcommand for the running interpreter and exits non-zero, leaving the choice of environment to the user.SKILL.mddocuments the new behavior.Also fixed:
parse_versionno longer raises on pre-release or suffixed tags (0.13.0rc1,v1.7.0-beta), so an upstream pre-release can't crash the startup check. Pre-releases compare equal to their base release, which keeps update notices conservative.idc-index 0.12.5
The pinned minimum moves from 0.12.3 to 0.12.5, which relaxes the dependency to
pandas>=2.2.2,<4. Installing the skill's minimum no longer perturbs a pandas 3.x environment — verified against pandas 3.0.5. IDC data version remains v24.Snippet test coverage and stale headers
use_cases.md,digital_pathology_guide.md, andparquet_access_guide.mdeach carried aTested with:header but had no tests behind it, so those headers couldn't be refreshed honestly. This adds 31 tests (98 total, up from 67):TestUseCases— the selection query from each use case, plus the viewer-URL preview step. Downloads and the pydicom/SimpleITK steps stay excluded per the module docstring.TestDigitalPathologyGuide— all 18 slide microscopy / annotation / segmentation queries. Two assert the TCGA-BRCA counts quoted inline in the guide (2704 primary / 399 normal; barcode sample types 01/06/11), so a data release that moves them fails CI instead of quietly making the prose wrong.TestParquetAccessGuide— the DuckDB-over-HTTPS queries, plus checks that every Parquet file listed in the guide exists undercurrent/and thatcurrent/resolves to the installedidc-index-datarelease.All snippets were re-run against idc-index 0.12.5 / idc-index-data 24.2.2 before the headers were updated.
bigquery_guide.mdwas reworded rather than version-bumped — its SQL doesn't use idc-index, so it now names the dataset it was actually validated against (bigquery-public-data.idc_current, viabq query --dry_run).The
VERSION = "23.10.1"pinning example inparquet_access_guide.mdis left as-is on purpose: it demonstrates pinning to an older release, and that URL still resolves.Why 1.7.0 and not 1.6.6
The MCP support adds a new routing surface, and dropping the auto-install changes documented startup behavior for anyone who relied on it. Neither is a patch-level change.
Testing
Run locally against idc-index 0.12.5 / idc-index-data 24.2.2 / pandas 3.0.5:
tests/test_snippets.pytests/test_bq_snippets.pybq query --dry_runagainstidc_currenttests/test_mcp_server.pyThe CI cache key and the
test-snippets.ymlpath filter were updated to match.Follow-up
Downstream K-Dense-AI/scientific-agent-skills#158 vendors v1.6.5 and is waiting on the
check_version.pyfix; it can sync to 1.7.0 once this lands and is tagged.🤖 Generated with Claude Code