fix(mcp): resolve deprecated surface_id aliases in get_api_schema and get_fixture

[andriypolanski]

Summary

• Resolve surface_id through findSurface + SURFACE_ALIASES_PATH in get_api_schema and get_fixture before building artifact paths.
• Use the resolved surface's current id for /metagraph/schemas/{id}.json and /metagraph/fixtures/{id}.json.
• Add MCP tests: deprecated alias verifies and fetches schema/fixture successfully after a rename.

Closes #2169

Why

Agent workflows often cache deprecated ids from older catalog snapshots. Verify works; schema/fixture do not — breaking the integration loop after renames.

Test plan

• npm test -- tests/mcp-server.test.mjs tests/surface-aliases.test.mjs
• Deprecated id → schema/fixture load via alias map
• Unknown id still 404s

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.18%. Comparing base (f7b9e60) to head (b55cf75).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2170      +/-   ##
==========================================
+ Coverage   93.16%   93.18%   +0.01%     
==========================================
  Files          52       52              
  Lines        8263     8272       +9     
  Branches     3032     3035       +3     
==========================================
+ Hits         7698     7708      +10     
+ Misses         97       96       -1     
  Partials      468      468              

Files with missing lines	Coverage Δ
src/mcp-server.mjs	88.04% <100.00%> (+0.30%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gittensory-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review — safe to merge

3 files · 1 AI reviewers · no blockers · readiness 55/100 · CI green · clean

✅ Approved — safe to merge

Review summary
This fix correctly extends deprecated-alias resolution to `get_api_schema` and `get_fixture`, which previously used the raw user-supplied `surface_id` directly as an artifact path key. The new `findCataloguedSurface` helper faithfully mirrors the two-step lookup (`findSurface` → lazy alias load) that `verify_integration` used inline, and the `resolveArtifactSurfaceId` fallback to the original id preserves the existing 404 behaviour for truly unknown surfaces. The refactor of `verify_integration` to call `findCataloguedSurface` is a clean DRY win, though it introduces a subtle latency cost.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewers, synthesized
Linked issue	✅ Linked	#2169
Related work	⚠️ 2 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Review load	❌ 8/20	Readiness component derived from cached public PR metadata and labels.
Validation evidence	❌ 5/25	Cached preflight status is hold.
Open PR queue	❌ 3/10	15 open PR(s), 13 likely reviewable, 2 unlinked.
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 76 PR(s), 7 issue(s).
Gate result	✅ Passing	No configured blocker found.

Nits — 6 non-blocking

• src/mcp-server.mjs (verify_integration call-site): before this PR `verify_integration` resolved aliases against a `surfaces` array that was already loaded earlier in the handler; the refactor silently discards that pre-loaded array and re-reads `operational-surfaces.json` inside `findCataloguedSurface`, adding one extra artifact round-trip per `verify_integration` call — consider giving `findCataloguedSurface` an optional `surfaces` parameter so callers with a pre-loaded list can skip the re-read.
• tests/network-routing.test.mjs:346-378: the deleted test (`retired current-health raw artifacts return 410 under a network prefix`) is entirely unrelated to MCP alias resolution and is removed without explanation — if the 410 route is still live this silently drops coverage; the PR description should state whether the handler was retired or the test was stale.
• src/mcp-server.mjs (resolveArtifactSurfaceId): the resolved `artifactId` comes from `surface.surface_id` in the catalog and is used directly in the artifact path without re-applying `SURFACE_ID_PATTERN`; the catalog is a trusted internal source so this is unlikely to be exploitable, but an assertion that the catalog-sourced id is well-formed would be cheap defensive hardening.
• Parameterise `findCataloguedSurface(ctx, surfaceId, preloadedSurfaces?)` — when `preloadedSurfaces` is supplied skip the `loadOptionalArtifact` catalog read; this recovers the zero-extra-read behaviour for `verify_integration` while keeping the new helper usable by `get_api_schema`/`get_fixture` which have no pre-loaded surfaces.
• Add a brief comment or PR note explaining the `network-routing.test.mjs` deletion (retired route, superseded test, etc.) so future `git blame` readers aren't left guessing why 410 coverage disappeared in a MCP-alias commit.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: not available
• Official Gittensor activity: 76 PR(s), 7 issue(s).
• Related work: Items reference the same linked issue MCP get_api_schema / get_fixture ignore deprecated surface_id aliases #2169. (issue #2169)
• Related work: Open PR work references issue MCP get_api_schema / get_fixture ignore deprecated surface_id aliases #2169. (issue #2169)

Contributor next steps

• Review top overlaps.
• Add scope summary.
• Fix blocker.
• Expect slower review.
• Refresh registry data or choose a registered active repo.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Review load = cached public PR metadata such as size labels, changed paths, and preflight status.
• Open PR queue = repo-wide review pressure; it is not a PR quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

Review details

Generated from public PR metadata and the diff. Advisory only; deterministic signals remain authoritative.

This fix correctly extends deprecated-alias resolution to `get_api_schema` and `get_fixture`, which previously used the raw user-supplied `surface_id` directly as an artifact path key. The new `findCataloguedSurface` helper faithfully mirrors the two-step lookup (`findSurface` → lazy alias load) that `verify_integration` used inline, and the `resolveArtifactSurfaceId` fallback to the original id preserves the existing 404 behaviour for truly unknown surfaces. The refactor of `verify_integration` to call `findCataloguedSurface` is a clean DRY win, though it introduces a subtle latency cost.

Nits (5)

• src/mcp-server.mjs (verify_integration call-site): before this PR `verify_integration` resolved aliases against a `surfaces` array that was already loaded earlier in the handler; the refactor silently discards that pre-loaded array and re-reads `operational-surfaces.json` inside `findCataloguedSurface`, adding one extra artifact round-trip per `verify_integration` call — consider giving `findCataloguedSurface` an optional `surfaces` parameter so callers with a pre-loaded list can skip the re-read.
• tests/network-routing.test.mjs:346-378: the deleted test (`retired current-health raw artifacts return 410 under a network prefix`) is entirely unrelated to MCP alias resolution and is removed without explanation — if the 410 route is still live this silently drops coverage; the PR description should state whether the handler was retired or the test was stale.
• src/mcp-server.mjs (resolveArtifactSurfaceId): the resolved `artifactId` comes from `surface.surface_id` in the catalog and is used directly in the artifact path without re-applying `SURFACE_ID_PATTERN`; the catalog is a trusted internal source so this is unlikely to be exploitable, but an assertion that the catalog-sourced id is well-formed would be cheap defensive hardening.
• Parameterise `findCataloguedSurface(ctx, surfaceId, preloadedSurfaces?)` — when `preloadedSurfaces` is supplied skip the `loadOptionalArtifact` catalog read; this recovers the zero-extra-read behaviour for `verify_integration` while keeping the new helper usable by `get_api_schema`/`get_fixture` which have no pre-loaded surfaces.
• Add a brief comment or PR note explaining the `network-routing.test.mjs` deletion (retired route, superseded test, etc.) so future `git blame` readers aren't left guessing why 410 coverage disappeared in a MCP-alias commit.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review