feat(miner-rag): wire issue-centric RAG into scoped MCP tool (#4293)

[andriypolanski]

Closes #4293

Summary

• Implements option 1 from decision needed: how does a local miner reach RAG retrieval without a hosted round-trip? #4258 (hosted API round-trip): local stdio MCP proxies to POST /v1/issue-rag/retrieve, and the Worker runs retrieveContextWithMetrics server-side.
• Adds gittensory_retrieve_issue_context — a repo-scoped, metadata-only MCP tool for the miner analyze phase. It composes the query via buildIssueRagQuery (from gittensory-engine, feat(engine): extract buildIssueRagQuery to gittensory-engine #4254) and returns retrieved paths + scores only — never chunk bodies or source text.
• Introduces retrieveIssueRagContext / runIssueRagRetrieval with the same fail-safe degradation pattern as rag-wire.ts (missing Vectorize/AI, cold index, short query, or backend errors → empty telemetry, never throws).

Design notes

• Scoped access: repo read authorization mirrors gittensory_find_opportunities targeted mode (requireRepoAccess / requireApiRepoReadAccess).
• Metadata-only boundary: response shape exposes retrievedPaths, topScore, candidates, etc. — the same telemetry family review RAG uses internally, without returning formatRetrievedContext text over the wire.
• Rate limit: /v1/issue-rag/retrieve is classified expensive (embedding + vector query), like /v1/opportunities/find.

Test plan

• test/unit/issue-rag-retrieval.test.ts — query floor, metadata-only success, missing bindings, parity knobs, slashless repo, fail-safe
• test/unit/issue-rag-mcp.test.ts — input validation + runIssueRagRetrieval statuses
• test/unit/mcp-issue-rag.test.ts — hosted MCP tool registration, auth, metadata-only payload
• test/unit/mcp-cli-issue-rag.test.ts — stdio proxy to /v1/issue-rag/retrieve
• test/integration/api.test.ts — API invalid-request guard
• test/unit/auth.test.ts — expensive route classification
• test/unit/mcp-output-schemas.test.ts — outputSchema registration
• npm run test:ci green locally
• npm audit --audit-level=moderate clean

[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 94.00%. Comparing base (8cebd14) to head (8ae82f8).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4440      +/-   ##
==========================================
+ Coverage   93.97%   94.00%   +0.02%     
==========================================
  Files         411      413       +2     
  Lines       37202    37283      +81     
  Branches    13587    13619      +32     
==========================================
+ Hits        34962    35047      +85     
+ Misses       1585     1580       -5     
- Partials      655      656       +1     

Files with missing lines	Coverage Δ
src/api/routes.ts	94.23% <100.00%> (+0.23%)	⬆️
src/auth/rate-limit.ts	98.83% <ø> (ø)
src/mcp/issue-rag.ts	100.00% <100.00%> (ø)
src/mcp/server.ts	95.48% <100.00%> (+0.07%)	⬆️
src/review/issue-rag-retrieval.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

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

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-09 19:14:21 UTC}

16 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): src/auth/rate-limit.ts (matched src/auth/**).

Review summary
This wires a metadata-only, repo-scoped `gittensory_retrieve_issue_context` MCP tool through the existing hosted-API-round-trip pattern (stdio proxy → `/v1/issue-rag/retrieve` → `retrieveContextWithMetrics`), closing #4293. The plumbing consistently mirrors the `gittensory_find_opportunities` precedent: repo-scoped auth via `requireRepoAccess`/`requireApiRepoReadAccess`, `expensive` rate-limit classification, session path allowlisting, output-schema registration, and the same fail-safe degrade-to-empty-telemetry pattern as `rag-wire.ts`. I traced the metadata-only boundary end-to-end (telemetry only exposes paths/scores, never `formatRetrievedContext` text) and it holds across the MCP tool, API route, and stdio proxy tests. No reachable correctness defect found; the main real issue is a DRY/consistency gap in the error-path telemetry literal.

Nits — 6 non-blocking

• src/mcp/server.ts (`retrieveIssueContext` invalid_request branch) and src/api/routes.ts:2864 both hand-roll a partial telemetry literal (`{ attempted: false, injected: false, retrievedPaths: [] }`) instead of importing `emptyIssueRagTelemetry()` from `src/review/issue-rag-retrieval.ts` — if the telemetry shape grows, these two call sites will silently drift out of parity with the real empty-state shape.
• `buildIssueRagQuery` is invoked twice per successful request — once in `runIssueRagRetrieval` (src/mcp/issue-rag.ts) to check the retrieval floor, then again inside `retrieveIssueRagContext` (src/review/issue-rag-retrieval.ts) — cheap and pure, but worth collapsing to a single call/pass-through if you touch this path again.
• codecov/patch is at 97.53% against a 99% target — worth a quick look at which branches in `issue-rag.ts`/`routes.ts` are uncovered (e.g. the `requireApiRepoReadAccess` forbidden branch or an edge of `cleanLabels`) before merge.
• External lint flags depth-5 nesting at src/mcp/issue-rag.ts:86 (`validateIssueRagInput`) — an early-return per field would flatten it and match the flat-guard style used in `find-opportunities.ts`'s `validateFindOpportunitiesInput`.
• `MAX_ISSUE_RAG_TOP_K`/the literal `12` is repeated across `issue-rag-retrieval.ts`, `issue-rag.ts`, `server.ts`, and `gittensory-mcp.js` — not wrong, but a shared exported constant would remove the four-way duplication risk if the cap ever changes.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4293
Related work	⚠️ 1 scoped overlap	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 137 registered-repo PR(s), 82 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 137 PR(s), 25 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Linked issue satisfaction

Addressed
The PR wires buildIssueRagQuery (imported from gittensory-engine, matching #4254's new location) into a metadata-only MCP tool that retrieves context via a hosted API round-trip implementing option 1 from #4258, exactly matching the second deliverable's described shape once the blocking decision resolves.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 137 PR(s), 25 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #4293, issue #4307)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 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