feat(miner): scaffold the gittensory-miner MCP stdio server

[jaytbarimbao-collab]

Scaffolds the first MCP entry point under packages/gittensory-miner, mirroring the packages/gittensory-mcp/bin/gittensory-mcp.js harness (MCP SDK server + stdio transport). Independently shippable; unblocks the other MCP-exposure issues in this batch (status/doctor diagnostics, portfolio dashboard, claim-ledger listing).

(Resubmit of #5232, which auto-closed on two CI-only failures now fixed: a missing .d.ts declaration for the new bin (TS7016 typecheck) and the check-miner-package allowlist rejecting the new bin. Both resolved and verified locally — see Validation.)

What this adds

• bin/gittensory-miner-mcp.js — new executable booting an McpServer over StdioServerTransport. Exports a createMinerMcpServer() factory so tests drive it in-process; the transport only starts when run directly as the bin (realpath-matched for npm/npx symlinks).
• bin/gittensory-miner-mcp.d.ts — hand-written declarations (per the package's .d.ts convention) for createMinerMcpServer() and MINER_PING_STATUS.
• One tool only: gittensory_miner_ping — health check returning a static { "status": "ok", "tool": "gittensory_miner_ping" }, empty input schema, no AMS-state reads. No status/doctor, portfolio, or claim tools here — those are explicit follow-ups.
• package.json — registers the gittensory-miner-mcp bin, adds @modelcontextprotocol/sdk@1.29.0 (pinned to match gittensory-mcp), node---checks the new bin in build. Lockfile updated.
• scripts/check-miner-package.mjs — broadened the bin allowlist from the exact gittensory-miner.js to gittensory-miner*.{js,d.ts} so the pack validator accepts the new flat bin + its declaration (still flat — no subdirectories, per the chore(miner): scaffold calibration module types (#2332) #3704 regression note).
• README — a short "MCP server" section.

Validation (local)

• tsc --noEmit: 0 errors (the .d.ts closes the TS7016 that sank feat(miner): scaffold the gittensory-miner MCP stdio server #5232).
• vitest on the three affected files — miner-mcp-scaffold (in-memory-transport smoke: lists exactly gittensory_miner_ping, asserts the static response + invariant), miner-package-skeleton (updated exact-bin assertion), and check-miner-package (the validator test that failed on feat(miner): scaffold the gittensory-miner MCP stdio server #5232): 16/16 pass.
• node scripts/check-miner-package.mjs, command-reference:check, docs:drift-check, engine-parity:drift-check, git diff --check: all clean.

Note: packages/gittensory-miner/** sits outside vitest's coverage.include, so codecov/patch cannot measure it yet (closed separately by #4864/#4865); the tests above enforce full behavioral coverage regardless.

Closes #5153

[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.27%. Comparing base (a6d93c6) to head (fff0f26).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5254   +/-   ##
=======================================
  Coverage   94.27%   94.27%           
=======================================
  Files         474      474           
  Lines       40078    40078           
  Branches    14612    14612           
=======================================
  Hits        37782    37782           
  Misses       1609     1609           
  Partials      687      687           

Flag	Coverage Δ
shard-1	46.38% <ø> (ø)
shard-2	34.58% <ø> (ø)
shard-3	32.04% <ø> (ø)
shard-4	32.12% <ø> (ø)
shard-5	33.72% <ø> (ø)
shard-6	44.79% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

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

[gittensory-orb]

Warning

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

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-12 12:07:55 UTC}

8 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · unknown

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): scripts/check-miner-package.mjs (matched scripts/**).

Review summary
This scaffolds a minimal MCP stdio server for gittensory-miner, mirroring the existing gittensory-mcp harness: one static health-check tool, a hand-written .d.ts (matching the package's declared convention), and an updated allowlist regex in check-miner-package.mjs to accept the new bin plus its declaration. The direct-invocation guard using realpathSync correctly handles npm bin symlinks, and the in-memory-transport test exercises the real server rather than a mock. This is a narrow, well-scoped scaffold with no AMS-state reads, consistent with its stated intent as a resubmit of #5232 with CI fixes applied.

Nits — 6 non-blocking

• The allowlist regex change in scripts/check-miner-package.mjs:8 (`/^bin\/gittensory-miner(-[a-z0-9-]+)?\.(js|d\.ts)$/`) is broader than strictly needed for this one bin+d.ts pair — worth a comment noting it's intentionally future-proofed for follow-up MCP bins, or tighten it to the exact filenames if that wasn't the intent.
• console.error at packages/gittensory-miner/bin/gittensory-miner-mcp.js:47 is appropriate here (mirrors the mcp harness's fatal-startup-error path) but is CI-invisible since the transport-connect branch only runs when invoked directly as the bin, not under the in-memory-transport test — confirm this matches the mcp harness's own untested convention.
• The engine dependency `@​jsonbored/gittensory-engine: "*"` pre-existed this diff (unchanged), so it's not something this PR introduces, but flagging for awareness since the brief calls it out as a wildcard range.
• Consider whether the ALLOWED regex broadening in scripts/check-miner-package.mjs should be scoped tighter (e.g. `gittensory-miner-mcp\.(js|d\.ts)$` alongside the existing exact-match line) rather than opening up arbitrary `gittensory-miner-<anything>` bins, to keep the allowlist as a real gate rather than a rubber stamp for future additions.
• The README's MCP section is a good addition; consider a one-line note on how a client's transport config should point at this bin (e.g. sample claude_desktop_config.json entry), matching whatever gittensory-mcp's README does, for parity.
• 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	#5153
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low 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: 18 registered-repo PR(s), 7 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	jaytbarimbao-collab; Gittensor profile; 18 PR(s), 1 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

• Author: jaytbarimbao-collab
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Rust
• Official Gittensor activity: 18 PR(s), 1 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

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