Skip to content

feat(grounding-mcp): add ledger_status no-arg health verb#73

Merged
LanNguyenSi merged 1 commit into
masterfrom
feat/grounding-mcp-ledger-status
May 13, 2026
Merged

feat(grounding-mcp): add ledger_status no-arg health verb#73
LanNguyenSi merged 1 commit into
masterfrom
feat/grounding-mcp-ledger-status

Conversation

@LanNguyenSi
Copy link
Copy Markdown
Owner

Adds a ledger_status MCP tool to grounding-mcp so harness's MCP doctor can probe it with an empty-args tools/call.

Why

Every existing grounding-mcp tool requires a sessionId (or other args). Calling any of them with {} returns a JSON-RPC validation error, which harness's MCP probe treats as unhealthy. The example manifest in harness therefore cannot register grounding-mcp with a working health verb today (harness task bd4ee1c9).

What

  • packages/grounding-mcp/src/ledger-bridge.ts: new ledgerStatus() helper. Read-only queries (SELECT COUNT(*), SELECT MAX(created_at)) wrapped in try/catch, returns a discriminated union { status: 'ok', dbPath, entryCount, lastWriteAt } | { status: 'error', message }.
  • packages/grounding-mcp/src/server.ts: register ledger_status tool with no input schema, delegates to ledgerStatus().
  • packages/grounding-mcp/tests/roundtrip.test.ts: two new Vitest cases.
    • Happy path: two ledger entries, asserts status=ok, entryCount=2, dbPath echoes the env var, lastWriteAt is a string.
    • Error path: writes non-sqlite bytes to a file, points EVIDENCE_LEDGER_DB at it, asserts status=error with a non-empty message. (First attempt used a missing parent dir but evidence-ledger's getDb auto-mkdirs, so the corrupt-file approach was needed.)

Dogfood

$ node dist/server.js  # with isolated EVIDENCE_LEDGER_DB
> tools/call { name: 'ledger_status', arguments: {} }
< { status: 'ok', dbPath: '/tmp/.../l.db', entryCount: 0, lastWriteAt: null }

Confirms harness's probe contract (tools/call with empty arguments) is satisfied.

Out of scope

  • Other new tools (per task acceptance).
  • Ledger schema changes.
  • Auth / rate limiting.
  • The pre-existing TypeScript deprecation warnings on server.tool(name, description, schema, cb) — every existing tool emits them; not introduced by this PR.

Evidence

.agent-grounding/evidence/feat/grounding-mcp-ledger-status.jsonl committed for the review-claim-gate auto-detect path.

Closes agent-tasks task 453d86f4.

Add a `ledger_status` MCP tool that takes no arguments and returns
ledger reachability + lightweight stats (db path, entry count,
last-write timestamp). Backs a `ledgerStatus()` helper in
`ledger-bridge.ts` that wraps the two read-only queries in a try/catch
so an unreachable ledger does not crash the server.

Designed to satisfy harness's `harness doctor` MCP probe, which calls
`tools/call` with empty `arguments` against a server's health verb.
Today every other grounding-mcp tool requires a sessionId or some
other arg, so an empty-args probe always failed validation. With
`ledger_status` the example manifest in harness can now register a
working health verb for grounding-mcp.

Vitest covers happy path (counts + dbPath echo) and the unreachable
case (corrupt file → structured error response, not a throw).

Closes agent-tasks 453d86f4.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@LanNguyenSi LanNguyenSi added review:tests-pass merge-approval prereq review:checklist-complete merge-approval prereq review:comments-resolved merge-approval prereq review:scope-matches-task merge-approval prereq review:evidence-logged merge-approval prereq labels May 13, 2026
@LanNguyenSi LanNguyenSi merged commit 2f726b3 into master May 13, 2026
3 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:checklist-complete merge-approval prereq review:comments-resolved merge-approval prereq review:evidence-logged merge-approval prereq review:scope-matches-task merge-approval prereq review:tests-pass merge-approval prereq

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants