Skip to content

Scaffold a minimal gittensory-miner mcp stdio server (bin entry, one health-check tool) #5153

Description

@JSONbored

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

  1. 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).
  2. 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.
  3. Give the new entry file an executable shebang (#!/usr/bin/env node) and correct executable file permissions.
  4. 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.
  5. 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.
  6. 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.
  7. 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

  • New bin script under packages/gittensory-miner implementing the MCP stdio server, following the packages/gittensory-mcp/bin/gittensory-mcp.js pattern
  • package.json bin and files fields updated to register and ship the new executable
  • gittensory_miner_ping tool implemented and wired into the server with a static, non-secret response
  • Smoke test spawning the server and invoking gittensory_miner_ping, asserting the response
  • README pointer added/updated documenting the new entry point and its current single-tool scope
  • npm run test:ci green locally; coverage measured unsharded via npm run test:coverage

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.gittensor:priorityMaintainer-selected Gittensor priority — scores a 1.5x multiplier.help wantedExtra attention is needed

    Projects

    Status
    In Progress

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions