tokentrace 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to TokenTrace are documented here.
 
 ## Unreleased
 
+## [0.14.0] - 2026-05-20
+
+### Added
+
+- `tokentrace mcp` now starts a local stdio MCP server for capabilities, status, Scan Health, evidence, repair queue, reports, and explicit local scans.
+- Added a validated MCP registry manifest for the npm package, with `tokentrace mcp` as the stdio entrypoint and no placeholder secrets.
+
+### Changed
+
+- Agent discovery, package smoke checks, packed-install smoke checks, and package inspection now cover the MCP server surface.
+
 ## [0.13.0] - 2026-05-20
 
 ### Changed

package/README.md

@@ -41,6 +41,7 @@ tokentrace capabilities --json
                         # Alias for agent discovery manifest
 tokentrace roadmap --json
                         # Print release status handoff
+tokentrace mcp          # Start the local stdio MCP server
 tokentrace scan         # Scan local AI CLI usage logs
 tokentrace doctor --json
                         # Inspect scan health and repair recommendations
@@ -106,6 +107,19 @@ or npm package contents before invoking commands:
 - [llms.txt](llms.txt)
 - [docs/agent-discovery.schema.json](docs/agent-discovery.schema.json)
 
+MCP-capable clients can start the local stdio server after installing or using
+the npm package:
+
+```bash
+tokentrace mcp
+```
+
+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
+`confirmLocalScan=true` before reading local usage files or writing the local
+database.
+
 When the local dashboard is already running, agents can fetch the same manifest
 over localhost:
 

package/TOKENTRACE_AGENT.md

@@ -19,6 +19,16 @@ tokentrace capabilities --json
 
 The manifest follows the schema in `docs/agent-discovery.schema.json`.
 
+MCP-capable clients can use the local stdio server:
+
+```bash
+tokentrace mcp
+```
+
+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.
+
 If the local dashboard is already running, the same manifest is available from:
 
 ```bash
@@ -67,6 +77,7 @@ curl http://127.0.0.1:3030/api/roadmap
 - Do not call processed tokens current context size. Use `ctx` for live context-window pressure.
 - Treat database paths, source file paths, prompts, and raw transcript settings as local sensitive data.
 - Discovery is read-only: it does not scan files, initialize the dashboard database, start a server, or make a network request.
+- MCP startup is read-only; use `run_scan` only when the human expects a local scan.
 
 ## Integrations
 

package/dist/runtime/agent.mjs

@@ -125,6 +125,25 @@ var commands = [
       ["tokentrace", "agent", "--json"]
     ]
   },
+  {
+    id: "mcp",
+    title: "Start local MCP server",
+    command: ["tokentrace", "mcp"],
+    description: "Expose TokenTrace's local-first JSON workflows as a stdio Model Context Protocol server.",
+    output: "terminal",
+    mutatesLocalState: false,
+    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.",
+    followUps: [
+      ["tokentrace", "agent", "--json"]
+    ],
+    notes: [
+      "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."
+    ]
+  },
   {
     id: "status",
     title: "Print local live usage status",
@@ -221,7 +240,8 @@ function buildAgentDiscoveryManifest(options = {}) {
     },
     discoveryCommands: [
       ["tokentrace", "agent", "--json"],
-      ["tokentrace", "capabilities", "--json"]
+      ["tokentrace", "capabilities", "--json"],
+      ["tokentrace", "mcp"]
     ],
     apiEndpoints: [
       {

package/dist/runtime/mcp.mjs

@@ -0,0 +1,286 @@
+import { createRequire as __tokentraceCreateRequire } from 'node:module'; const require = __tokentraceCreateRequire(import.meta.url);
+
+// scripts/mcp.ts
+import { createInterface } from "node:readline";
+
+// src/lib/mcp-server.ts
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+var protocolVersion = "2025-06-18";
+function packageVersion() {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"));
+    return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function toolInputSchema(properties = {}, required = []) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    required
+  };
+}
+var mcpTools = [
+  {
+    name: "get_capabilities",
+    title: "Get TokenTrace capabilities",
+    description: "Return the read-only TokenTrace agent discovery manifest. Does not initialize local app data.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "get_status",
+    title: "Get local usage status",
+    description: "Return the current local TokenTrace usage status snapshot as JSON.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "run_doctor",
+    title: "Run Scan Health doctor",
+    description: "Inspect scan freshness, parser trust, source coverage, package trust, and repair recommendations.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "get_evidence",
+    title: "Get metric evidence trail",
+    description: "Return evidence behind a TokenTrace metric without raw prompt or message bodies.",
+    inputSchema: toolInputSchema({
+      metric: {
+        type: "string",
+        enum: [
+          "processed-tokens",
+          "non-cache-tokens",
+          "cached-tokens",
+          "estimated-cost",
+          "sessions",
+          "unknown-cost",
+          "guardrails",
+          "review-queue"
+        ],
+        description: "Evidence metric to inspect. Defaults to processed-tokens."
+      }
+    })
+  },
+  {
+    name: "get_repair_queue",
+    title: "Get unknown-cost repair queue",
+    description: "Return grouped unknown-cost repair causes, next actions, and review state.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "get_report",
+    title: "Get local usage report",
+    description: "Return a deterministic local report as markdown or JSON.",
+    inputSchema: toolInputSchema({
+      format: {
+        type: "string",
+        enum: ["markdown", "json"],
+        description: "Report format. Defaults to markdown."
+      },
+      since: {
+        type: "string",
+        description: "Optional scope: last-scan, yesterday, or YYYY-MM-DD."
+      }
+    })
+  },
+  {
+    name: "run_scan",
+    title: "Run local scan",
+    description: "Explicitly scan local AI CLI artifacts and update the local TokenTrace database. Requires confirmLocalScan=true.",
+    inputSchema: toolInputSchema(
+      {
+        confirmLocalScan: {
+          type: "boolean",
+          description: "Must be true to confirm local file reads and local database writes."
+        },
+        folders: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional local folders to scan. Defaults to TokenTrace's supported local roots."
+        },
+        force: {
+          type: "boolean",
+          description: "Force parser reprocessing for files that would otherwise be deduplicated."
+        }
+      },
+      ["confirmLocalScan"]
+    )
+  }
+];
+function jsonRpcResponse(id, result) {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    result
+  };
+}
+function jsonRpcError(id, code, message) {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: { code, message }
+  };
+}
+function command(args) {
+  const bin = path.join(process.cwd(), "bin", "tokentrace.js");
+  const result = spawnSync(process.execPath, [bin, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 6e4,
+    maxBuffer: 4 * 1024 * 1024
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const stderr = result.stderr.trim();
+    const stdout = result.stdout.trim();
+    throw new Error(stderr || stdout || `tokentrace ${args.join(" ")} exited with code ${result.status}`);
+  }
+  return result.stdout;
+}
+function commandJson(args) {
+  return JSON.parse(command(args));
+}
+function toolResult(value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+function toolError(error) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: error instanceof Error ? error.message : String(error)
+      }
+    ]
+  };
+}
+function stringArg(args, key) {
+  const value = args[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function scanArgs(args) {
+  if (args.confirmLocalScan !== true) {
+    throw new Error("run_scan requires confirmLocalScan=true to acknowledge local file reads and local database writes.");
+  }
+  const cliArgs = ["scan"];
+  if (args.force === true) cliArgs.push("--force");
+  if (Array.isArray(args.folders)) {
+    for (const folder of args.folders) {
+      if (typeof folder !== "string" || !folder.trim()) {
+        throw new Error("run_scan folders must be non-empty strings.");
+      }
+      cliArgs.push(folder);
+    }
+  }
+  cliArgs.push("--json");
+  return cliArgs;
+}
+async function callTool(params) {
+  const args = params.arguments ?? {};
+  try {
+    if (params.name === "get_capabilities") {
+      return toolResult(commandJson(["agent", "--json"]));
+    }
+    if (params.name === "get_status") {
+      return toolResult(commandJson(["status", "--json"]));
+    }
+    if (params.name === "run_doctor") {
+      return toolResult(commandJson(["doctor", "--json"]));
+    }
+    if (params.name === "get_evidence") {
+      const metric = stringArg(args, "metric");
+      return toolResult(commandJson(metric ? ["evidence", "--json", `--metric=${metric}`] : ["evidence", "--json"]));
+    }
+    if (params.name === "get_repair_queue") {
+      return toolResult(commandJson(["repair", "--json"]));
+    }
+    if (params.name === "get_report") {
+      const format = stringArg(args, "format") ?? "markdown";
+      const since = stringArg(args, "since");
+      const cliArgs = ["report", format === "json" ? "--json" : "--markdown"];
+      if (since) cliArgs.push("--since", since);
+      const output = command(cliArgs);
+      return toolResult(format === "json" ? JSON.parse(output) : output.trimEnd());
+    }
+    if (params.name === "run_scan") {
+      return toolResult(commandJson(scanArgs(args)));
+    }
+    throw new Error(`Unknown TokenTrace MCP tool: ${params.name ?? "(missing name)"}`);
+  } catch (error) {
+    return toolError(error);
+  }
+}
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+async function handleMcpMessage(message) {
+  const id = message.id;
+  const method = message.method;
+  if (!method) return jsonRpcError(id, -32600, "Invalid JSON-RPC request: missing method.");
+  if (method.startsWith("notifications/")) return null;
+  if (method === "initialize") {
+    return jsonRpcResponse(id, {
+      protocolVersion,
+      capabilities: { tools: {} },
+      serverInfo: {
+        name: "tokentrace",
+        version: packageVersion()
+      },
+      instructions: "TokenTrace is local-first. Tools read local TokenTrace data; run_scan requires explicit confirmation before local file reads and database writes."
+    });
+  }
+  if (method === "ping") {
+    return jsonRpcResponse(id, {});
+  }
+  if (method === "tools/list") {
+    return jsonRpcResponse(id, { tools: mcpTools });
+  }
+  if (method === "tools/call") {
+    return jsonRpcResponse(id, await callTool(asObject(message.params)));
+  }
+  return jsonRpcError(id, -32601, `Method not found: ${method}`);
+}
+
+// scripts/mcp.ts
+function write(message) {
+  process.stdout.write(`${JSON.stringify(message)}
+`);
+}
+async function handleLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let message;
+  try {
+    message = JSON.parse(trimmed);
+  } catch {
+    write(jsonRpcError(null, -32700, "Parse error: expected one JSON-RPC message per line."));
+    return;
+  }
+  const response = await handleMcpMessage(message);
+  if (response) write(response);
+}
+var reader = createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity
+});
+var queue = Promise.resolve();
+reader.on("line", (line) => {
+  queue = queue.then(() => handleLine(line)).catch((error) => {
+    write(jsonRpcError(null, -32603, error instanceof Error ? error.message : String(error)));
+  });
+});
+reader.on("close", () => {
+  queue.finally(() => process.exit(0));
+});

package/llms.txt

@@ -18,6 +18,16 @@ tokentrace capabilities --json
 
 The manifest is read-only and follows `docs/agent-discovery.schema.json`.
 
+MCP-capable clients can start TokenTrace over stdio:
+
+```bash
+tokentrace mcp
+```
+
+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.
+
 When the local dashboard is running, the same manifest is available at
 `/api/agent` and `/api/capabilities`.
 
@@ -32,6 +42,7 @@ Roadmap status is available through `tokentrace roadmap --json` and
 - `tokentrace repair --json`: inspect unknown-cost repair work.
 - `tokentrace digest --json`: summarize local usage.
 - `tokentrace roadmap --json`: inspect the current release handoff, action recipes, evidence paths, and release status.
+- `tokentrace mcp`: start the local stdio MCP server.
 - `tokentrace statusline setup claude`: print Claude Code status-line setup.
 - `tokentrace watch --session --compact`: terminal sidecar fallback for Codex.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokentrace",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Local-first dashboard for AI CLI token, cost, and session analytics.",
   "author": {
     "name": "Abhi Yoheswaran",
@@ -27,6 +27,7 @@
     "components",
     "docs/agent-discovery.schema.json",
     "docs/assets",
+    "server.json",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md",

package/scripts/build-cli-runtime.mjs

@@ -15,6 +15,7 @@ const entryPoints = {
   doctor: "scripts/doctor.ts",
   evidence: "scripts/evidence.ts",
   insights: "scripts/insights.ts",
+  mcp: "scripts/mcp.ts",
   "pricing-refresh": "scripts/pricing-refresh.ts",
   report: "scripts/report.ts",
   repair: "scripts/repair.ts",

package/scripts/mcp.ts

@@ -0,0 +1,39 @@
+import { createInterface } from "node:readline";
+import { handleMcpMessage, jsonRpcError } from "@/src/lib/mcp-server";
+
+function write(message: unknown) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+async function handleLine(line: string) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  let message: unknown;
+  try {
+    message = JSON.parse(trimmed);
+  } catch {
+    write(jsonRpcError(null, -32700, "Parse error: expected one JSON-RPC message per line."));
+    return;
+  }
+
+  const response = await handleMcpMessage(message as Parameters<typeof handleMcpMessage>[0]);
+  if (response) write(response);
+}
+
+const reader = createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity
+});
+
+let queue = Promise.resolve();
+
+reader.on("line", (line) => {
+  queue = queue.then(() => handleLine(line)).catch((error) => {
+    write(jsonRpcError(null, -32603, error instanceof Error ? error.message : String(error)));
+  });
+});
+
+reader.on("close", () => {
+  queue.finally(() => process.exit(0));
+});

package/scripts/package-inspect.mjs

@@ -68,6 +68,7 @@ const requiredPackageFiles = [
   "TOKENTRACE_AGENT.md",
   "llms.txt",
   "docs/agent-discovery.schema.json",
+  "server.json",
   expectedBin
 ];
 
@@ -136,7 +137,7 @@ console.log("- no npm install lifecycle scripts");
 console.log("- Next.js dependency floor is pinned to the patched range");
 console.log("- Drizzle ORM and PostCSS floors are pinned to patched ranges");
 console.log("- generated Next.js build output is excluded from the package");
-console.log("- agent discovery docs, schema, and executable CLI bin are included");
+console.log("- agent discovery docs, MCP registry manifest, schema, and executable CLI bin are included");
 for (const note of notes) {
   console.log(`- ${note}`);
 }

package/scripts/smoke-cli/commands.mjs

@@ -24,6 +24,19 @@ export function jsonCommand(context, args) {
   return JSON.parse(output);
 }
 
+function mcpSmoke(context) {
+  const input = [
+    { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18" } },
+    { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }
+  ].map((message) => JSON.stringify(message)).join("\n") + "\n";
+  const output = run(context, ["mcp"], { input, timeout: 30_000 });
+  const responses = output.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  const toolNames = responses[1]?.result?.tools?.map((tool) => tool.name) ?? [];
+  if (!toolNames.includes("get_capabilities") || !toolNames.includes("run_scan")) {
+    throw new Error("MCP tools/list is missing expected TokenTrace tools.");
+  }
+}
+
 export function expectFailure(context, args, expectedStderr) {
   const result = spawnSync(process.execPath, [context.bin, ...args], {
     cwd: context.root,
@@ -61,6 +74,8 @@ export async function smokeCliDiscovery(context) {
     if (roadmap.version !== "0.12.0" || roadmap.release?.releaseAllowed !== true || roadmap.handoff?.schemaVersion !== "tokentrace.roadmap.v2") {
       throw new Error("Roadmap JSON is missing 0.12.0 release-ready handoff status.");
     }
+
+    mcpSmoke(context);
   } catch (error) {
     throw new Error(`CLI discovery smoke failed: ${error instanceof Error ? error.message : String(error)}`);
   }

package/scripts/smoke-packed-install.mjs

@@ -23,6 +23,7 @@ function run(command, args, options = {}) {
       ...options.env
     },
     encoding: "utf8",
+    input: options.input,
     timeout: options.timeout ?? 120_000
   });
 
@@ -50,6 +51,7 @@ const requiredPackageFiles = [
   "TOKENTRACE_AGENT.md",
   "llms.txt",
   "docs/agent-discovery.schema.json",
+  "server.json",
   "bin/tokentrace.js"
 ];
 
@@ -109,6 +111,17 @@ function assertDiscoverySmoke(bin, cwd, env) {
   if (roadmap.version !== "0.12.0" || roadmap.release?.releaseAllowed !== true) {
     throw new Error("Packed tokentrace roadmap --json is missing the 0.12.0 release-ready status.");
   }
+
+  const mcpInput = [
+    { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18" } },
+    { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }
+  ].map((message) => JSON.stringify(message)).join("\n") + "\n";
+  const mcpOutput = run(bin, ["mcp"], { cwd, env, input: mcpInput, timeout: 30_000 });
+  const mcpResponses = mcpOutput.split("\n").filter(Boolean).map((line) => JSON.parse(line));
+  const mcpTools = mcpResponses[1]?.result?.tools?.map((tool) => tool.name) ?? [];
+  if (!mcpTools.includes("get_capabilities") || !mcpTools.includes("run_scan")) {
+    throw new Error("Packed tokentrace mcp did not expose expected MCP tools.");
+  }
 }
 
 function findFreePort(hostname) {
@@ -223,7 +236,7 @@ try {
     }
 
     const help = run(bin, ["--help"], { cwd: tempRoot });
-    if (!help.includes("tokentrace scan") || !help.includes("tokentrace statusline claude")) {
+    if (!help.includes("tokentrace scan") || !help.includes("tokentrace mcp") || !help.includes("tokentrace statusline claude")) {
       throw new Error("Packed tokentrace --help is missing expected commands.");
     }
 

package/server.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.abhiyoheswaran1/tokentrace",
+  "title": "TokenTrace",
+  "description": "Local-first AI CLI usage analytics for agents.",
+  "websiteUrl": "https://www.abhiyoheswaran.com/apps/tokentrace",
+  "repository": {
+    "url": "https://github.com/abhiyoheswaran1/tokentrace",
+    "source": "github"
+  },
+  "version": "0.14.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "tokentrace",
+      "version": "0.14.0",
+      "runtimeHint": "npx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "mcp"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/src/cli/commands.js

@@ -21,6 +21,14 @@ async function roadmap(context, args) {
   await runNodeScript(context, "roadmap", args, { env: process.env });
 }
 
+async function mcp(context, args) {
+  if (args.length) {
+    console.error("Usage: tokentrace mcp");
+    process.exit(1);
+  }
+  await runNodeScript(context, "mcp", [], { env: process.env });
+}
+
 async function doctor(context, args) {
   await initializeDatabase(context, { quiet: true, refreshPrices: false });
   await runNodeScript(context, "doctor", args);
@@ -214,6 +222,10 @@ export async function runCliCommand(context, rawArgs = process.argv.slice(2)) {
     await roadmap(context, args);
     return;
   }
+  if (command === "mcp") {
+    await mcp(context, args);
+    return;
+  }
   if (command === "scan") {
     await scan(context, args);
     return;

package/src/cli/help.js

@@ -10,6 +10,7 @@ Usage:
                           Alias for agent discovery manifest
   tokentrace roadmap --json
                           Print release status handoff
+  tokentrace mcp          Start the local stdio MCP server
   tokentrace scan         Scan local AI CLI usage logs
   tokentrace doctor --json
                           Inspect scan health and repair recommendations

package/src/lib/agent-discovery.ts

@@ -193,6 +193,25 @@ const commands: AgentDiscoveryCommand[] = [
       ["tokentrace", "agent", "--json"]
     ]
   },
+  {
+    id: "mcp",
+    title: "Start local MCP server",
+    command: ["tokentrace", "mcp"],
+    description: "Expose TokenTrace's local-first JSON workflows as a stdio Model Context Protocol server.",
+    output: "terminal",
+    mutatesLocalState: false,
+    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.",
+    followUps: [
+      ["tokentrace", "agent", "--json"]
+    ],
+    notes: [
+      "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."
+    ]
+  },
   {
     id: "status",
     title: "Print local live usage status",
@@ -290,7 +309,8 @@ export function buildAgentDiscoveryManifest(options: AgentDiscoveryOptions = {})
     },
     discoveryCommands: [
       ["tokentrace", "agent", "--json"],
-      ["tokentrace", "capabilities", "--json"]
+      ["tokentrace", "capabilities", "--json"],
+      ["tokentrace", "mcp"]
     ],
     apiEndpoints: [
       {

package/src/lib/mcp-server.ts

@@ -0,0 +1,289 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+type JsonRpcId = string | number | null;
+
+type JsonRpcRequest = {
+  jsonrpc?: string;
+  id?: JsonRpcId;
+  method?: string;
+  params?: unknown;
+};
+
+type ToolCallParams = {
+  name?: string;
+  arguments?: Record<string, unknown>;
+};
+
+const protocolVersion = "2025-06-18";
+
+function packageVersion() {
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"));
+    return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function toolInputSchema(properties: Record<string, unknown> = {}, required: string[] = []) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties,
+    required
+  };
+}
+
+export const mcpTools = [
+  {
+    name: "get_capabilities",
+    title: "Get TokenTrace capabilities",
+    description: "Return the read-only TokenTrace agent discovery manifest. Does not initialize local app data.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "get_status",
+    title: "Get local usage status",
+    description: "Return the current local TokenTrace usage status snapshot as JSON.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "run_doctor",
+    title: "Run Scan Health doctor",
+    description: "Inspect scan freshness, parser trust, source coverage, package trust, and repair recommendations.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "get_evidence",
+    title: "Get metric evidence trail",
+    description: "Return evidence behind a TokenTrace metric without raw prompt or message bodies.",
+    inputSchema: toolInputSchema({
+      metric: {
+        type: "string",
+        enum: [
+          "processed-tokens",
+          "non-cache-tokens",
+          "cached-tokens",
+          "estimated-cost",
+          "sessions",
+          "unknown-cost",
+          "guardrails",
+          "review-queue"
+        ],
+        description: "Evidence metric to inspect. Defaults to processed-tokens."
+      }
+    })
+  },
+  {
+    name: "get_repair_queue",
+    title: "Get unknown-cost repair queue",
+    description: "Return grouped unknown-cost repair causes, next actions, and review state.",
+    inputSchema: toolInputSchema()
+  },
+  {
+    name: "get_report",
+    title: "Get local usage report",
+    description: "Return a deterministic local report as markdown or JSON.",
+    inputSchema: toolInputSchema({
+      format: {
+        type: "string",
+        enum: ["markdown", "json"],
+        description: "Report format. Defaults to markdown."
+      },
+      since: {
+        type: "string",
+        description: "Optional scope: last-scan, yesterday, or YYYY-MM-DD."
+      }
+    })
+  },
+  {
+    name: "run_scan",
+    title: "Run local scan",
+    description:
+      "Explicitly scan local AI CLI artifacts and update the local TokenTrace database. Requires confirmLocalScan=true.",
+    inputSchema: toolInputSchema(
+      {
+        confirmLocalScan: {
+          type: "boolean",
+          description: "Must be true to confirm local file reads and local database writes."
+        },
+        folders: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional local folders to scan. Defaults to TokenTrace's supported local roots."
+        },
+        force: {
+          type: "boolean",
+          description: "Force parser reprocessing for files that would otherwise be deduplicated."
+        }
+      },
+      ["confirmLocalScan"]
+    )
+  }
+];
+
+function jsonRpcResponse(id: JsonRpcId | undefined, result: unknown) {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    result
+  };
+}
+
+export function jsonRpcError(id: JsonRpcId | undefined, code: number, message: string) {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: { code, message }
+  };
+}
+
+function command(args: string[]) {
+  const bin = path.join(process.cwd(), "bin", "tokentrace.js");
+  const result = spawnSync(process.execPath, [bin, ...args], {
+    cwd: process.cwd(),
+    env: process.env,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 60_000,
+    maxBuffer: 4 * 1024 * 1024
+  });
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const stderr = result.stderr.trim();
+    const stdout = result.stdout.trim();
+    throw new Error(stderr || stdout || `tokentrace ${args.join(" ")} exited with code ${result.status}`);
+  }
+  return result.stdout;
+}
+
+function commandJson(args: string[]) {
+  return JSON.parse(command(args));
+}
+
+function toolResult(value: unknown) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+
+function toolError(error: unknown) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: error instanceof Error ? error.message : String(error)
+      }
+    ]
+  };
+}
+
+function stringArg(args: Record<string, unknown>, key: string) {
+  const value = args[key];
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function scanArgs(args: Record<string, unknown>) {
+  if (args.confirmLocalScan !== true) {
+    throw new Error("run_scan requires confirmLocalScan=true to acknowledge local file reads and local database writes.");
+  }
+
+  const cliArgs = ["scan"];
+  if (args.force === true) cliArgs.push("--force");
+  if (Array.isArray(args.folders)) {
+    for (const folder of args.folders) {
+      if (typeof folder !== "string" || !folder.trim()) {
+        throw new Error("run_scan folders must be non-empty strings.");
+      }
+      cliArgs.push(folder);
+    }
+  }
+  cliArgs.push("--json");
+  return cliArgs;
+}
+
+async function callTool(params: ToolCallParams) {
+  const args = params.arguments ?? {};
+
+  try {
+    if (params.name === "get_capabilities") {
+      return toolResult(commandJson(["agent", "--json"]));
+    }
+    if (params.name === "get_status") {
+      return toolResult(commandJson(["status", "--json"]));
+    }
+    if (params.name === "run_doctor") {
+      return toolResult(commandJson(["doctor", "--json"]));
+    }
+    if (params.name === "get_evidence") {
+      const metric = stringArg(args, "metric");
+      return toolResult(commandJson(metric ? ["evidence", "--json", `--metric=${metric}`] : ["evidence", "--json"]));
+    }
+    if (params.name === "get_repair_queue") {
+      return toolResult(commandJson(["repair", "--json"]));
+    }
+    if (params.name === "get_report") {
+      const format = stringArg(args, "format") ?? "markdown";
+      const since = stringArg(args, "since");
+      const cliArgs = ["report", format === "json" ? "--json" : "--markdown"];
+      if (since) cliArgs.push("--since", since);
+      const output = command(cliArgs);
+      return toolResult(format === "json" ? JSON.parse(output) : output.trimEnd());
+    }
+    if (params.name === "run_scan") {
+      return toolResult(commandJson(scanArgs(args)));
+    }
+    throw new Error(`Unknown TokenTrace MCP tool: ${params.name ?? "(missing name)"}`);
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
+function asObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+export async function handleMcpMessage(message: JsonRpcRequest) {
+  const id = message.id;
+  const method = message.method;
+
+  if (!method) return jsonRpcError(id, -32600, "Invalid JSON-RPC request: missing method.");
+
+  if (method.startsWith("notifications/")) return null;
+
+  if (method === "initialize") {
+    return jsonRpcResponse(id, {
+      protocolVersion,
+      capabilities: { tools: {} },
+      serverInfo: {
+        name: "tokentrace",
+        version: packageVersion()
+      },
+      instructions:
+        "TokenTrace is local-first. Tools read local TokenTrace data; run_scan requires explicit confirmation before local file reads and database writes."
+    });
+  }
+
+  if (method === "ping") {
+    return jsonRpcResponse(id, {});
+  }
+
+  if (method === "tools/list") {
+    return jsonRpcResponse(id, { tools: mcpTools });
+  }
+
+  if (method === "tools/call") {
+    return jsonRpcResponse(id, await callTool(asObject(message.params) as ToolCallParams));
+  }
+
+  return jsonRpcError(id, -32601, `Method not found: ${method}`);
+}