Context
packages/gittensory-mcp/bin/gittensory-mcp.js already exists as a working MCP stdio server harness (package.json bin/files wiring, executable shebang, MCP SDK server init, stdio transport). packages/gittensory-miner has no MCP entry point at all today — per the candidate audit, "packages/gittensory-mcp and packages/gittensory-miner have zero cross-references today." This issue adds the first bin entry under packages/gittensory-miner, following the same harness pattern, so that future AMS-state-reading tools (status/doctor, portfolio dashboard, claim listing) have a real server to be added to.
Dependencies
None — independently shippable. Note that this issue is itself a blocker: the other MCP-exposure issues in this batch (status/doctor diagnostics, portfolio dashboard, claim-ledger listing) add tools "to the AMS MCP server (from the scaffold)" and cannot start until this scaffold merges.
Requirements
- Add a new bin entry (e.g.
gittensory-miner-mcp) under packages/gittensory-miner, mirroring the harness pattern used by packages/gittensory-mcp/bin/gittensory-mcp.js (MCP SDK server init + stdio transport).
- Update packages/gittensory-miner/package.json's
bin field to register the new executable, and its files field so the new script ships in the published package.
- Give the new entry file an executable shebang (
#!/usr/bin/env node) and correct executable file permissions.
- Ship exactly one tool in this PR:
gittensory_miner_ping, a trivial health check returning a static status object (e.g. { status: "ok", tool: "gittensory_miner_ping" }), with a minimal/empty input schema — no argument validation logic beyond that.
- Do NOT add any AMS-state-reading tools in this PR (no status/doctor, no portfolio dashboard, no claim ledger). Those are explicitly out of scope here and land as separate follow-up issues/PRs on top of this scaffold.
- Add a smoke test that spawns the new MCP server (as a child process, or via whatever in-process test harness packages/gittensory-mcp already uses to test its own server) and calls the
gittensory_miner_ping tool, asserting the returned status object's shape and values.
- Add a short README pointer (in packages/gittensory-miner's README, or a new short doc) describing what the new bin entry is, how to run it, and that it currently exposes only the ping tool pending follow-ups.
Deliverables / Acceptance Criteria
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new bin entry's server initialization and the gittensory_miner_ping tool's success path, (2) an invariant test asserting that the gittensory_miner_ping tool always returns the same static, non-secret status object regardless of input, and that the server starts and can be queried without requiring any AMS state to exist on disk, and (3) no regression test is needed since this is new functionality, not a bug fix.
Codecov visibility note: packages/gittensory-miner/**, apps/gittensory-miner-ui/**, and apps/gittensory-miner-extension/** currently sit entirely outside vitest's coverage.include glob, so codecov/patch cannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change under packages/gittensory-engine/src/** or the repo's own src/** remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.
Expected Outcome
Contributors and operators get a working gittensory-miner-mcp executable that any MCP-compatible client can connect to today, and future issues can add real AMS-state-reading tools on top of a scaffold that is already tested end-to-end.
Links & Resources
- packages/gittensory-mcp/bin/gittensory-mcp.js — the harness pattern to follow
- packages/gittensory-miner/ — where the new bin entry and package.json changes land
- This scaffold unlocks the other MCP-exposure issues in this same batch (status/doctor diagnostics, portfolio dashboard, claim-ledger listing)
- Theme: MCP exposure
Context
packages/gittensory-mcp/bin/gittensory-mcp.js already exists as a working MCP stdio server harness (package.json
bin/fileswiring, executable shebang, MCP SDK server init, stdio transport). packages/gittensory-miner has no MCP entry point at all today — per the candidate audit, "packages/gittensory-mcp and packages/gittensory-miner have zero cross-references today." This issue adds the first bin entry under packages/gittensory-miner, following the same harness pattern, so that future AMS-state-reading tools (status/doctor, portfolio dashboard, claim listing) have a real server to be added to.Dependencies
None — independently shippable. Note that this issue is itself a blocker: the other MCP-exposure issues in this batch (status/doctor diagnostics, portfolio dashboard, claim-ledger listing) add tools "to the AMS MCP server (from the scaffold)" and cannot start until this scaffold merges.
Requirements
gittensory-miner-mcp) under packages/gittensory-miner, mirroring the harness pattern used by packages/gittensory-mcp/bin/gittensory-mcp.js (MCP SDK server init + stdio transport).binfield to register the new executable, and itsfilesfield so the new script ships in the published package.#!/usr/bin/env node) and correct executable file permissions.gittensory_miner_ping, a trivial health check returning a static status object (e.g.{ status: "ok", tool: "gittensory_miner_ping" }), with a minimal/empty input schema — no argument validation logic beyond that.gittensory_miner_pingtool, asserting the returned status object's shape and values.Deliverables / Acceptance Criteria
binandfilesfields updated to register and ship the new executablegittensory_miner_pingtool implemented and wired into the server with a static, non-secret responsegittensory_miner_ping, asserting the responsenpm run test:cigreen locally; coverage measured unsharded vianpm run test:coverageTest Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new bin entry's server initialization and the
gittensory_miner_pingtool's success path, (2) an invariant test asserting that thegittensory_miner_pingtool always returns the same static, non-secret status object regardless of input, and that the server starts and can be queried without requiring any AMS state to exist on disk, and (3) no regression test is needed since this is new functionality, not a bug fix.Codecov visibility note:
packages/gittensory-miner/**,apps/gittensory-miner-ui/**, andapps/gittensory-miner-extension/**currently sit entirely outside vitest'scoverage.includeglob, socodecov/patchcannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change underpackages/gittensory-engine/src/**or the repo's ownsrc/**remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.Expected Outcome
Contributors and operators get a working
gittensory-miner-mcpexecutable that any MCP-compatible client can connect to today, and future issues can add real AMS-state-reading tools on top of a scaffold that is already tested end-to-end.Links & Resources