mcp: an agent reads the fleet from its own client, out of the same document

[sanlee-ys]

telltale mcp puts the snapshot document (design.md §7.22) in front of a reader
that is an agent. An MCP client starts the process, speaks JSON-RPC over stdio,
and calls one tool — fleet_snapshot — which takes an optional vendor
argument, runs one scan and returns the document. One flag: --timeout, and it
is the deadline for each CALL rather than for the process.

claude mcp add telltale -- C:\path\to\telltale.exe mcp

The document is not re-made here

The tool result is snapshot.Encode over the document snapshot.Build produced
from the scan telltale snapshot runs. One scan path, one adapter roster, one
vendor vocabulary, one serializer. So zero-vs-absent, the explicit nulls,
estimated, unsupported and self_reported arrive as the same bytes the CLI
prints. structuredContent is that document again, marshalled by the same
package, so the two spellings cannot disagree.

The tool DESCRIPTION carries the value rules, because the calling model reads
that text and nothing else before it decides what a null means. A caller that
does not know them reads an absent reading as a zero, which is the collapse this
repo exists to prevent, moved one process outward into the agent.

It is a reader

Stdio only: the client owns both pipes, so this mode binds no port, calls no
network and writes nothing at all — not even the quota relay, because it renders
no quota of its own to relay. §7.24's question of who may reach a listener does
not arise, because there is no listener. Two tests hold that: an import gate,
and a whole session driven with the home directory redirected and the tree
compared before and after.

internal/mcpserver is hand-written JSON-RPC over encoding/json. That keeps
the module's standing position — no direct dependency outside the TUI stack,
recorded four times in design.md — and four methods with one tool is a smaller
surface than the SDK's own API.

Verified live

Windows 11, against the built binary, driven by a scripted stdio client. Seven
messages in, six responses out (the seventh was the notification, answered by
silence), exit 0, empty stderr.

• The tool's document was written to a file and validated against
  docs/snapshot.schema.json with tools/validate-snapshot.py: ok.
• The zero-vs-absent pair appeared in the real document unstaged: agy's
  3p-weekly window carried used_pct as 0 while cost_usd_total was null
  fleet-wide and five vendors carried quota_read_at: null.
• ~/.telltale held the identical 35 files, sizes and modification times before
  and after the session.

CI drives the same sequence against the built binary on every run and validates
BOTH spellings of the document. That gate was proved non-vacuous: one sentence
was removed from the tool description, the binary rebuilt, and the gate failed
naming the missing word.

What is not verified

No third-party MCP client has connected to this server. The drive proves a
correct server; it says nothing about how a shipped client negotiates a version
or renders a result. Wiring one up writes an entry into the operator's own
client configuration, which is his to make. STATE.md and design.md §7.25 carry
the debt.

🤖 Generated with Claude Code