Skip to content

Expose AMS claim-ledger listing as a read-only MCP tool (gittensory_miner_list_claims) #5156

Description

@JSONbored

Context

packages/gittensory-miner/lib/claim-ledger.js already tracks claims (repo, issue number, status, claimed-at/released-at), but there is no way to list them remotely today. This is distinct from #4848 ("wire claim-conflict resolution end-to-end"), which is the maintainer-only CLI-side conflict-resolution logic itself, not a read tool.

Dependencies

Requires the MCP scaffold issue in this same batch (gittensory-miner-mcp bin entry) to land first — this tool is added onto that server. Independent of #4848 (claim-conflict resolution) — that issue's conflict-resolution logic is separate, maintainer-only, and this tool does not touch it.

Requirements

  1. Add a new tool (e.g. gittensory_miner_list_claims) to the AMS MCP server.
  2. Return existing claim-ledger entries — repo, issue number, status, claimed-at, released-at — by reading from packages/gittensory-miner/lib/claim-ledger.js's existing read/query functions.
  3. The tool must be strictly read-only: do not expose any claim() or release() mutation capability through this tool.
  4. If claim-ledger.js already exposes a query/filter function (e.g. by repo or status), the tool may accept optional filter parameters that pass through to it; do not add new filtering logic to claim-ledger.js itself in this PR — if no such function exists yet, return the full unfiltered list.
  5. Must not expose any conflict-resolution decision logic — that remains Wire claim-conflict resolution end-to-end #4848's domain; this tool is metadata listing only.

Deliverables / Acceptance Criteria

  • New MCP tool listing claims from claim-ledger.js, read-only
  • No mutation methods (claim/release) reachable through this tool
  • Unit tests + invariant test added
  • README/doc pointer added for the new tool

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 tool's success path (claims present, multiple statuses) and edge paths (empty ledger, optional filters applied and not applied), (2) an invariant test asserting the list_claims tool implementation never calls a mutating claim-ledger method (claim/release) — only read/query functions, 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

An operator can remotely check which issues their miner currently holds — via an MCP-connected agent or client — without shelling into the machine.

Links & Resources

  • packages/gittensory-miner/lib/claim-ledger.js — existing claim state to read from
  • See the MCP scaffold issue in this same batch (must land first)
  • See Wire claim-conflict resolution end-to-end #4848 (claim-conflict resolution wiring) — related but distinct, maintainer-only
  • Theme: MCP exposure

Metadata

Metadata

Assignees

No one assigned

    Labels

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

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions