feat(mcp): GeneFoundry contract-hardening sweep (behaviour gate CONFORMANT)

[berntpopp]

GeneFoundry fleet MCP contract-hardening sweep

Brings stringdb-link into compliance with the GeneFoundry MCP contract standards and closes every defect the vendored behaviour gate — and the live MCP audit (#33) — surfaced.

Standards adopted:

• Response-Envelope Standard v1 / v1.1a — isError on every error frame, the closed error_code enum, actionable errors.
• Tool-Schema Documentation Standard v1 (genefoundry-router#75) — examples on every required + array param; closed vocabularies declared as enums matching the runtime.
• Tool-Surface Budget Standard v1 (genefoundry-router#73) — outputSchema suppressed, dereference_schemas=False.
• Behaviour gate (genefoundry-router#76) vendored byte-identical from genefoundry-router@791363c and wired into mcp-conformance CI.

The enum rule followed here is schema ⊆ runtime: never advertise a value the runtime rejects (verified live — e.g. output_format narrowed to the single value STRING actually serves).

Closes the contract half of #33.

Behaviour gate — before / after

Both run against a locally-running server (docs/conformance/behaviour.py):

BEFORE:  NON-CONFORMANT: stringdb-link (21 pass, 20 fail, 10 UNGATED, 0 inconclusive)
AFTER:   CONFORMANT:     stringdb-link (48 pass,  0 fail,  0 UNGATED, 3 inconclusive)

The 20 failures were isError:false on every error envelope + a non-actionable "The request was rejected as invalid." on every tool. The 10 UNGATED were every tool's required params lacking examples (which also blocked the dynamic filter probes). The 3 remaining "inconclusive" are single-item tools (get_network_link, compute_ppi_enrichment, get_network_image) that return no collection to filter-probe — honest, not a defect.

Surface survey — before / after

                       ver     tools  surface  out%  doc%  ex
BEFORE  stringdb-link  4.0.6      10   4,625t   24%  100%   0
AFTER   stringdb-link  4.1.0      10   4,083t    0%  100%  26

Live repros (local server, tools/call)

isError + canonical error_code + actionable field (all error frames):

get_network_link output_format=svg   -> isError=True  error_code=invalid_input  field=output_format
compute_functional_enrichment (bad background) -> isError=True error_code=invalid_input field=background_string_identifiers retryable=False

Defect 1 — get_network_image (was internal_error / empty in every format):

get_network_image {TP53,MDM2 @9606} -> success  result={image_format:image, content_type:image/png, image_size_bytes:9772, image_base64:"iVBORw0KGgo…"}

Defect 2 — get_functional_annotations (was not_found "tool is not available"):

get_functional_annotations {CFTR @9606} -> success  total_count=885  (description fenced as untrusted_text)

Defect 3 — compute_functional_enrichment pagination (was ~992 terms / ~421k tokens, no knob):

compute_functional_enrichment {30-gene epilepsy panel, limit:5} -> success  results=5  total_count=478  truncated=True

Defect 4 — get_network_link output_format (was 8/9 enum values → success:true, result:{}):

output_format=json -> success  result={url:"https://version-12-0.string-db.org/cgi/link?to=…"}
output_format=svg  -> isError=True  error_code=invalid_input  field=output_format

Defect 5 — enrichment background_error (was false upstream_unavailable, retryable:true):

bad background -> isError=True  error_code=invalid_input  field=background_string_identifiers  retryable=False

Homology camelCase lead — verified NOT a live defect: get_protein_homology_scores {CDK1,CDK2} returns populated string_id_a/bitscore rows. required_score scaling lead — not a silent-empty: the schema declares a 0.0–1.0 confidence (bounded ge/le, description "Minimum confidence score (0.0-1.0)"), and the service scales it to STRING's 0–1000 internally (round(required_score * 1000)). A caller passing 1000 is rejected by the le=1.0 bound rather than silently matching nothing.

Notes

• Version 4.0.6 → 4.1.0 (MINOR: schemas gain fields; outputSchema drops an optional field). CHANGELOG updated under ## [4.1.0].
• make ci-local green (452 passed, 2 skipped).
• Untrusted-text fencing is preserved on the wire (Response-Envelope v1.1a); suppressing outputSchema does not weaken it.

🤖 Generated with Claude Code

https://claude.ai/code/session_019BYK7j7jsPXmBspMsDtfhH