tokentrace 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.14.2] - 2026-05-21
+
+### Added
+
+- Added `get_agent_guide` to the MCP server with registry install snippets, recommended agent workflows, copy-paste `AGENTS.md` guidance, and local-first guardrails.
+- Added `tokentrace mcp selftest --json` to verify MCP initialization, tool listing, agent guide output, and scan-confirmation refusal without scanning files.
+- Added `docs/agent-adoption.md` with MCP setup instructions and evidence-backed recipes for coding agents.
+
+### Changed
+
+- MCP tool responses now include an agent-oriented envelope with summary, confidence, next actions, warnings, evidence hints, human-confirmation state, and the underlying data payload.
+- Package inspection and CLI smoke checks now verify the MCP agent guide, self-test, and adoption documentation.
+
+### Fixed
+
+- Data-backed CLI command help now prints before touching local runtime state, so `tokentrace scan --help`, `doctor --help`, `evidence --help`, `repair --help`, and related commands stay safe on broken or fresh local databases.
+
+## [0.14.1] - 2026-05-20
+
+### Fixed
+
+- Added the required npm `mcpName` package metadata so the MCP registry can verify the TokenTrace npm package.
+
 ## [0.14.0] - 2026-05-20
 
 ### Added

package/README.md

@@ -105,6 +105,7 @@ or npm package contents before invoking commands:
 
 - [TOKENTRACE_AGENT.md](TOKENTRACE_AGENT.md)
 - [llms.txt](llms.txt)
+- [docs/agent-adoption.md](docs/agent-adoption.md)
 - [docs/agent-discovery.schema.json](docs/agent-discovery.schema.json)
 
 MCP-capable clients can start the local stdio server after installing or using
@@ -114,6 +115,16 @@ the npm package:
 tokentrace mcp
 ```
 
+Registry name: `io.github.abhiyoheswaran1/tokentrace`.
+
+First MCP call for agents: `get_agent_guide`.
+
+Self-test the local MCP entrypoint without scanning files:
+
+```bash
+tokentrace mcp selftest --json
+```
+
 The MCP server exposes the same local-first surfaces as tools: capabilities,
 status, Scan Health, evidence, repair queue, reports, and an explicit scan tool.
 It does not scan files on startup, and its scan tool requires

package/TOKENTRACE_AGENT.md

@@ -25,6 +25,21 @@ MCP-capable clients can use the local stdio server:
 tokentrace mcp
 ```
 
+MCP registry name:
+
+```text
+io.github.abhiyoheswaran1/tokentrace
+```
+
+Agents should call `get_agent_guide` first. It returns the recommended workflow,
+install snippets, copy-paste `AGENTS.md` guidance, and local-first guardrails.
+
+Verify the MCP entrypoint without scanning files:
+
+```bash
+tokentrace mcp selftest --json
+```
+
 The MCP server does not scan on startup. Its `run_scan` tool requires
 `confirmLocalScan=true` before reading local usage files or writing the local
 database.
@@ -53,19 +68,25 @@ curl http://127.0.0.1:3030/api/roadmap
    tokentrace agent --json
    ```
 
-2. Refresh local data when the human expects current usage:
+2. In MCP clients, ask for the operating loop:
+
+   ```text
+   get_agent_guide
+   ```
+
+3. Refresh local data when the human expects current usage:
 
    ```bash
    tokentrace scan --json
    ```
 
-3. Check trust before making claims:
+4. Check trust before making claims:
 
    ```bash
    tokentrace doctor --json
    ```
 
-4. Explain totals with evidence:
+5. Explain totals with evidence:
 
    ```bash
    tokentrace evidence --json

package/app/guide/page.tsx

@@ -148,6 +148,14 @@ const roadmapSteps = [
   ["Dashboard API", "/api/roadmap", "Fetch the same roadmap status from a running local dashboard."]
 ];
 
+const mcpAgentEntries = [
+  ["Registry", "io.github.abhiyoheswaran1/tokentrace", "Use this name when an MCP client discovers TokenTrace from the registry."],
+  ["Start", "tokentrace mcp", "Start the local stdio MCP server. Startup is read-only and does not scan files."],
+  ["First tool", "get_agent_guide", "Return the recommended operating loop, install snippets, and AGENTS.md copy block."],
+  ["Self-test", "tokentrace mcp selftest --json", "Verify MCP initialization, tool listing, guide output, and scan refusal."],
+  ["Scan rule", "confirmLocalScan=true", "Only pass this to run_scan when the human expects a local filesystem scan."]
+];
+
 const workflows = [
   {
     problem: "No records imported",
@@ -506,6 +514,27 @@ export default function GuidePage() {
                 </p>
               </div>
             </div>
+            <div className="border-t p-4">
+              <div className="flex items-center gap-2">
+                <LockKeyhole className="h-4 w-4 text-primary" />
+                <h3 className="text-sm font-semibold leading-tight">MCP for agents</h3>
+              </div>
+              <p className="mt-2 max-w-[72ch] text-sm leading-6 text-muted-foreground">
+                MCP clients should connect locally, call <MonoText>get_agent_guide</MonoText> first, and use evidence before reporting
+                token, cost, model, or session numbers. The full copy-paste workflow lives in <MonoText>docs/agent-adoption.md</MonoText>.
+              </p>
+              <div className="mt-4 grid gap-3 md:grid-cols-2 xl:grid-cols-5">
+                {mcpAgentEntries.map(([label, value, detail]) => (
+                  <div key={label} className="rounded-md border bg-muted/30 p-3">
+                    <FieldLabel>{label}</FieldLabel>
+                    <div className="mt-2 min-h-10 break-words text-sm font-medium leading-5">
+                      <MonoText>{value}</MonoText>
+                    </div>
+                    <p className="mt-2 text-xs leading-5 text-muted-foreground">{detail}</p>
+                  </div>
+                ))}
+              </div>
+            </div>
             <div className="border-t p-4">
               <h3 className="text-sm font-semibold leading-tight">Agent quickstart</h3>
               <div className="table-scroll mt-3">

package/dist/runtime/agent.mjs

@@ -135,11 +135,13 @@ var commands = [
     startsLongRunningProcess: true,
     requiresNetwork: false,
     safeForAutomation: false,
-    useWhen: "An MCP-capable agent or client wants structured access to TokenTrace status, doctor, evidence, repair, report, and explicit scan tools.",
+    useWhen: "An MCP-capable agent or client wants structured access to TokenTrace guidance, status, doctor, evidence, repair, report, and explicit scan tools.",
     followUps: [
+      ["tokentrace", "mcp", "selftest", "--json"],
       ["tokentrace", "agent", "--json"]
     ],
     notes: [
+      "Agents should call get_agent_guide first after connecting through MCP.",
       "The MCP server itself does not scan files on startup.",
       "The run_scan MCP tool requires confirmLocalScan=true before reading local usage files and writing the local database."
     ]