mcp-agent-trace-inspector 1.0.0

package/.env.example

@@ -0,0 +1,10 @@
+# mcp-agent-trace-inspector environment variables
+# Copy this file to .env and fill in values as needed.
+
+# API key for HTTP endpoint authentication (optional).
+# When set, all HTTP requests must include the header: X-API-Key: <value>
+# MCP_API_KEY=your-api-key-here
+
+# JWT secret for Bearer token authentication (optional).
+# When set, all HTTP requests must include: Authorization: Bearer <jwt>
+# MCP_JWT_SECRET=your-jwt-secret-here

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to MCP Agent Trace Inspector will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-03-23
+
+### Changed
+
+- `@modelcontextprotocol/sdk` upgraded from `^1.0.0` to `^1.12.0`.
+- `@types/node` upgraded from `^22.x` to `^24.12.0` (Node 24 LTS).
+- `eslint` upgraded from `^9.x` to `^10.0.3`; `eslint-config-prettier` from `^9.x` to `^10.1.8`.
+- `yargs` upgraded from `^17.x` to `^18.0.0`.
+- Added `author`, `repository`, and `homepage` fields to `package.json` for npm registry and marketplace metadata.
+- Added `.env.example` documenting `MCP_API_KEY` and `MCP_JWT_SECRET`.
+
+### Fixed
+
+- Removed two unused function references (`checkAndAlert`, `loadAlertRules`) from `src/server.ts`.
+- Prefixed unused test helper variables with `_` in `tests/auth.test.ts` and `tests/trace.test.ts` to satisfy `no-unused-vars` lint rule.
+
+### Security
+
+- Resolved **GHSA-67mh-4wv8-2f99** (`esbuild` ≤ 0.24.2 dev-server cross-origin exposure) by upgrading `vitest` and `@vitest/coverage-v8` to `^4.1.0`. Affects local development only; not a production runtime concern.
+
+## [0.2.0] - 2026-03-23
+
+### Added
+
+- **Alerting** (`src/alerting.ts`): configurable alert rules on latency, error rate, and total cost. Fires to Slack webhooks or generic HTTP endpoints. Alert rules persist to SQLite between restarts.
+- **Audit log** (`src/audit-log.ts`): append-only JSONL audit trail written to `~/.mcp/trace-inspector-audit.jsonl`; queryable by time range via `export_compliance_log`.
+- **JWT / API-key auth middleware** (`src/auth.ts`): HTTP transport protected via `MCP_API_KEY` (X-API-Key header) or `MCP_JWT_SECRET` (HMAC-SHA256 Bearer token). stdio transport is unaffected.
+- **Per-client rate limiter** (`src/rate-limiter.ts`): sliding-window request throttle on the HTTP transport.
+- **OpenTelemetry exporter** (`src/otel-exporter.ts`): export traces to any OTLP-compatible backend (Jaeger, Grafana Tempo, etc.). Supports single-trace and all-traces export with `format=json`.
+- **Retention policy** (`src/retention.ts`): archive or delete trace records older than a configurable number of days. Archives traces past the threshold; deletes archived traces past 2× the threshold.
+- **New tools**: `configure_alerts`, `set_retention_policy`, `apply_retention`, `export_otel`, `export_compliance_log`.
+- **`npm run inspect` script**: launches MCP Inspector (`npx @modelcontextprotocol/inspector node dist/index.js`) for interactive pre-publish verification.
+- MCP Inspector verification instructions added to README.
+- Tests for alerting, audit log, auth, OpenTelemetry exporter, rate limiter, and retention.
+
+### Fixed
+
+- `export_compliance_log` was always returning an empty array. The shared `AuditLog` instance was never written to because `trace_step` did not call `record()`. Fixed by creating a single `AuditLog` instance in `server.ts` and calling `_auditLog.record()` from the `trace_step` handler. Audit entries are now correctly appended to `~/.mcp/trace-inspector-audit.jsonl` on every recorded step.
+- `apply_retention` now returns a clear error (`InvalidParams`) when called before `set_retention_policy` has been invoked in the current session, rather than silently operating on a null policy.
+
+## [0.1.0] - 2026-03-12
+
+### Added
+
+- Initial public release of `mcp-agent-trace-inspector`.
+- `trace_start`, `trace_step`, and `trace_end` tools for full trace lifecycle management.
+- `get_trace_summary`, `list_traces`, and `compare_traces` inspection tools.
+- `export_dashboard` tool generating a self-contained single-file HTML dashboard.
+- Persistent SQLite storage with configurable path via `--db`.
+- Token cost estimation using a built-in model pricing table (no external API calls required).
+- Automatic trace retention via `--retention-days`.
+- Custom pricing table support via `--pricing-table`.
+- `--no-token-count` flag to disable token counting.
+- Streamable HTTP transport via `--http-port` flag (default: disabled, uses stdio).
+- GitHub Actions CI workflow running build, test, and lint on push/PR to `main`.
+- Vitest test suite with coverage via `@vitest/coverage-v8`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP Agent Trace Inspector contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# MCP Agent Trace Inspector
+
+npm `mcp-agent-trace-inspector` package
+
+Local-first, MCP-native observability for agent workflows. Every tool call, prompt transformation, latency, and token count is recorded in a local SQLite database — no cloud account, no API key, no traces leaving your machine. Built specifically for MCP rather than bolted onto a generic LLM proxy.
+
+[Tool reference](#tools) | [Configuration](#configuration) | [Contributing](#contributing) | [Troubleshooting](#troubleshooting) | [Design principles](#design-principles)
+
+## Key features
+
+- **Tool call tracing**: Captures inputs, outputs, latency, and token usage for every step in a workflow.
+- **Persistent storage**: Traces survive session restarts; stored locally in SQLite with no external dependencies.
+- **HTML dashboard**: Generates a self-contained single-file dashboard with an interactive step timeline.
+- **Token cost estimation**: Calculates USD cost per trace using a configurable model pricing table — no API calls required.
+- **Trace comparison**: Diff two traces side by side to measure the impact of prompt or tool changes.
+- **Low overhead**: Adds less than 5ms per step; never becomes the bottleneck.
+
+## Why this over LangSmith / AgentOps?
+
+|                 | mcp-agent-trace-inspector                        | LangSmith / AgentOps                          |
+| --------------- | ------------------------------------------------ | --------------------------------------------- |
+| Data location   | Local SQLite — never leaves your machine         | Cloud-hosted; traces sent to external servers |
+| Setup           | `npx` one-liner, zero config                     | Account signup, API key, SDK instrumentation  |
+| MCP-aware       | Native — records tool calls as first-class steps | Generic LLM proxy; MCP structure is opaque    |
+| Run diffs       | Built-in `compare_traces` diff                   | Separate paid feature or manual export        |
+| Cost estimation | Offline tiktoken + configurable pricing table    | Requires live API traffic through their proxy |
+| Overhead        | <5ms per step                                 | Network round-trip per event                  |
+
+If your traces contain sensitive tool outputs, proprietary prompts, or data that must stay on-device, this is the right tool. If you need cross-team trace sharing or a managed SaaS, use LangSmith.
+
+## Disclaimers
+
+`mcp-agent-trace-inspector` stores tool call inputs and outputs locally in a SQLite database. Traces may contain sensitive information passed to or returned from your tools. Review trace contents before sharing dashboard exports. Traces are not automatically transmitted; optional alert webhooks are available.
+
+## Requirements
+
+- Node.js v22.5.0 or newer.
+- npm.
+
+## Getting started
+
+Add the following config to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "trace-inspector": {
+      "command": "npx",
+      "args": ["-y", "mcp-agent-trace-inspector@latest"]
+    }
+  }
+}
+```
+
+To set a custom storage path:
+
+```json
+{
+  "mcpServers": {
+    "trace-inspector": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-agent-trace-inspector@latest",
+        "--db=~/traces/my-project.db"
+      ]
+    }
+  }
+}
+```
+
+### MCP Client configuration
+
+Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed
+
+## Your first prompt
+
+Enter the following in your MCP client to verify everything is working:
+
+```
+Start a trace called "test-run", then list the files in the current directory, then end the trace and show me the summary.
+```
+
+Your client should return a summary showing step count, total tokens, and latency.
+
+## Tools
+
+### Trace lifecycle (3 tools)
+
+- `trace_start` — begin a new trace; returns a `trace_id` for subsequent calls
+- `trace_step` — record one tool call step (inputs, outputs, optional token count and latency)
+- `trace_end` — mark a trace as completed
+
+### Inspection (4 tools)
+
+- `list_traces` — list stored traces with names, statuses, and timestamps
+- `get_trace_summary` — token totals, step count, latency, and cost estimate for a trace
+- `compare_traces` — diff two traces side by side (step counts, tokens, latency)
+- `extract_reasoning_chain` — extract only reasoning/thinking steps from a trace
+
+### Export (3 tools)
+
+- `export_dashboard` — generate a self-contained single-file HTML dashboard with latency waterfall
+- `export_otel` — export one or all traces in OpenTelemetry OTLP JSON span format
+- `export_compliance_log` — export the compliance audit log as JSON or CSV, with optional date range filtering
+
+### Operations (3 tools)
+
+- `configure_alerts` — configure alert rules on latency, error rate, or cost; fire to Slack or generic webhooks
+- `set_retention_policy` — set how many days to keep traces (in-memory; must be called before `apply_retention`)
+- `apply_retention` — archive traces older than the configured threshold; delete traces past 2x the threshold
+
+## Configuration
+
+### `--db` / `--db-path`
+
+Path to the SQLite database file used to store traces.
+
+Type: `string`
+Default: `~/.mcp/traces.db`
+
+### `--retention-days`
+
+Automatically delete traces older than N days. Set to `0` to disable.
+
+Type: `number`
+Default: `0`
+
+### `--pricing-table`
+
+Path to a JSON file containing custom model pricing ($/1K tokens). Overrides the built-in table.
+
+Type: `string`
+
+### `--no-token-count`
+
+Disable tiktoken-based token counting. Traces will omit token usage metrics.
+
+Type: `boolean`
+Default: `false`
+
+Pass flags via the `args` property in your JSON config:
+
+```json
+{
+  "mcpServers": {
+    "trace-inspector": {
+      "command": "npx",
+      "args": ["-y", "mcp-agent-trace-inspector@latest", "--retention-days=30"]
+    }
+  }
+}
+```
+
+## Design principles
+
+- **Append-only traces**: Steps are immutable once recorded. Trust requires integrity.
+- **Local-first**: All core functionality works without a network connection.
+- **Portable dashboards**: HTML exports are always single-file; no server required to view them.
+
+## Verification
+
+Before publishing a new version, verify the server with MCP Inspector to confirm all tools are exposed correctly and the protocol handshake succeeds.
+
+**Interactive UI** (opens browser):
+
+```bash
+npm run build && npm run inspect
+```
+
+**CLI mode** (scripted / CI-friendly):
+
+```bash
+# List all tools
+npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
+
+# List resources and prompts
+npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
+npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list
+
+# Call a tool (example — replace with a relevant read-only tool for this plugin)
+npx @modelcontextprotocol/inspector --cli node dist/index.js \
+  --method tools/call --tool-name list_traces
+
+# Call a tool with arguments
+npx @modelcontextprotocol/inspector --cli node dist/index.js \
+  --method tools/call --tool-name list_traces --tool-arg key=value
+```
+
+Run before publishing to catch regressions in tool registration and runtime startup.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full contribution guidelines.
+
+```bash
+npm install && npm test
+```
+
+## MCP Registry & Marketplace
+
+This plugin is available on:
+
+- [MCP Registry](https://registry.modelcontextprotocol.io)
+- [MCP Marketplace](https://marketplace.modelcontextprotocol.io)
+
+Search for `mcp-agent-trace-inspector`.

package/dist/alerting.d.ts

@@ -0,0 +1,18 @@
+import { DatabaseSync } from "node:sqlite";
+export interface AlertChannels {
+    slackWebhook?: string;
+    genericWebhook?: string;
+}
+export interface AlertRule {
+    type: "latency" | "error_rate" | "cost";
+    threshold: number;
+}
+export interface AlertFired {
+    rule: AlertRule;
+    value: number;
+    message: string;
+}
+export declare function checkAndAlert(db: DatabaseSync, rules: AlertRule[], channels: AlertChannels): Promise<AlertFired[]>;
+export declare function initAlertRulesTable(db: DatabaseSync): void;
+export declare function saveAlertRules(db: DatabaseSync, rules: AlertRule[]): void;
+export declare function loadAlertRules(db: DatabaseSync): AlertRule[];

package/dist/alerting.js

@@ -0,0 +1,169 @@
+import { request as httpsRequest } from "node:https";
+import { request as httpRequest } from "node:http";
+import { URL } from "node:url";
+import { listTraces, getSteps } from "./db.js";
+// Pricing per 1K tokens (input+output average) — rough estimate
+const COST_PER_1K_TOKENS_USD = 0.003;
+function computeAverageLatencyMs(db) {
+    const traces = listTraces(db);
+    if (traces.length === 0)
+        return 0;
+    let totalLatency = 0;
+    let count = 0;
+    for (const trace of traces) {
+        const steps = getSteps(db, trace.id);
+        for (const step of steps) {
+            if (step.latency_ms !== null && step.latency_ms !== undefined) {
+                totalLatency += step.latency_ms;
+                count++;
+            }
+        }
+    }
+    return count > 0 ? totalLatency / count : 0;
+}
+function computeErrorRatePct(db) {
+    const traces = listTraces(db);
+    if (traces.length === 0)
+        return 0;
+    let totalSteps = 0;
+    let errorSteps = 0;
+    for (const trace of traces) {
+        const steps = getSteps(db, trace.id);
+        for (const step of steps) {
+            totalSteps++;
+            try {
+                const output = JSON.parse(step.output_json);
+                if (output.error || output.isError === true) {
+                    errorSteps++;
+                }
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return totalSteps > 0 ? (errorSteps / totalSteps) * 100 : 0;
+}
+function computeTotalCostUsd(db) {
+    const traces = listTraces(db);
+    let totalTokens = 0;
+    for (const trace of traces) {
+        const steps = getSteps(db, trace.id);
+        for (const step of steps) {
+            if (step.token_count !== null && step.token_count !== undefined) {
+                totalTokens += step.token_count;
+            }
+        }
+    }
+    return (totalTokens / 1000) * COST_PER_1K_TOKENS_USD;
+}
+function postJson(url, body) {
+    return new Promise((resolve, reject) => {
+        const parsed = new URL(url);
+        const data = JSON.stringify(body);
+        const isHttps = parsed.protocol === "https:";
+        const reqFn = isHttps ? httpsRequest : httpRequest;
+        const options = {
+            hostname: parsed.hostname,
+            port: parsed.port || (isHttps ? 443 : 80),
+            path: parsed.pathname + parsed.search,
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(data),
+            },
+        };
+        const req = reqFn(options, (res) => {
+            res.resume(); // drain response
+            res.on("end", resolve);
+        });
+        req.on("error", reject);
+        req.write(data);
+        req.end();
+    });
+}
+function buildSlackBlocks(alert) {
+    return {
+        blocks: [
+            {
+                type: "section",
+                text: {
+                    type: "mrkdwn",
+                    text: `*Alert Fired: ${alert.rule.type}*\n${alert.message}\nValue: ${alert.value.toFixed(2)}, Threshold: ${alert.rule.threshold}`,
+                },
+            },
+        ],
+    };
+}
+export async function checkAndAlert(db, rules, channels) {
+    const fired = [];
+    for (const rule of rules) {
+        let value = 0;
+        let message = "";
+        switch (rule.type) {
+            case "latency":
+                value = computeAverageLatencyMs(db);
+                message = `Average step latency ${value.toFixed(0)}ms exceeds threshold ${rule.threshold}ms`;
+                break;
+            case "error_rate":
+                value = computeErrorRatePct(db);
+                message = `Error rate ${value.toFixed(1)}% exceeds threshold ${rule.threshold}%`;
+                break;
+            case "cost":
+                value = computeTotalCostUsd(db);
+                message = `Total cost $${value.toFixed(4)} exceeds threshold $${rule.threshold}`;
+                break;
+        }
+        if (value > rule.threshold) {
+            const alert = { rule, value, message };
+            fired.push(alert);
+            const sendPromises = [];
+            if (channels.slackWebhook) {
+                sendPromises.push(postJson(channels.slackWebhook, buildSlackBlocks(alert)).catch((err) => {
+                    console.error("[alerting] Slack webhook failed:", err);
+                }));
+            }
+            if (channels.genericWebhook) {
+                sendPromises.push(postJson(channels.genericWebhook, {
+                    alert_type: rule.type,
+                    threshold: rule.threshold,
+                    value,
+                    message,
+                    timestamp: new Date().toISOString(),
+                }).catch((err) => {
+                    console.error("[alerting] Generic webhook failed:", err);
+                }));
+            }
+            await Promise.all(sendPromises);
+        }
+    }
+    return fired;
+}
+// Database helpers for persisting alert rules
+export function initAlertRulesTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS alert_rules (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      threshold REAL NOT NULL
+    );
+  `);
+}
+export function saveAlertRules(db, rules) {
+    initAlertRulesTable(db);
+    db.exec("DELETE FROM alert_rules");
+    const stmt = db.prepare("INSERT INTO alert_rules (type, threshold) VALUES (?, ?)");
+    for (const rule of rules) {
+        stmt.run(rule.type, rule.threshold);
+    }
+}
+export function loadAlertRules(db) {
+    initAlertRulesTable(db);
+    const rows = db
+        .prepare("SELECT type, threshold FROM alert_rules")
+        .all();
+    return rows.map((r) => ({
+        type: r.type,
+        threshold: r.threshold,
+    }));
+}

package/dist/audit-log.d.ts

@@ -0,0 +1,15 @@
+export interface AuditEntry {
+    timestamp: string;
+    trace_id: string;
+    tool_name: string;
+    user_id: string;
+    token_count: number;
+    cost_usd: number;
+}
+export declare class AuditLog {
+    private readonly filePath;
+    constructor(filePath?: string);
+    private ensureDir;
+    record(entry: AuditEntry): void;
+    export(from?: string, to?: string): AuditEntry[];
+}

package/dist/audit-log.js

@@ -0,0 +1,49 @@
+import { appendFileSync, readFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_AUDIT_PATH = join(homedir(), ".mcp", "trace-inspector-audit.jsonl");
+export class AuditLog {
+    filePath;
+    constructor(filePath = DEFAULT_AUDIT_PATH) {
+        this.filePath = filePath;
+        this.ensureDir();
+    }
+    ensureDir() {
+        const dir = dirname(this.filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    record(entry) {
+        this.ensureDir();
+        const line = JSON.stringify(entry) + "\n";
+        appendFileSync(this.filePath, line, "utf8");
+    }
+    export(from, to) {
+        if (!existsSync(this.filePath)) {
+            return [];
+        }
+        const raw = readFileSync(this.filePath, "utf8");
+        const lines = raw.split("\n").filter((l) => l.trim() !== "");
+        const entries = [];
+        for (const line of lines) {
+            try {
+                const entry = JSON.parse(line);
+                entries.push(entry);
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        const fromDate = from ? new Date(from).getTime() : null;
+        const toDate = to ? new Date(to).getTime() : null;
+        return entries.filter((e) => {
+            const ts = new Date(e.timestamp).getTime();
+            if (fromDate !== null && ts < fromDate)
+                return false;
+            if (toDate !== null && ts > toDate)
+                return false;
+            return true;
+        });
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+import type { RequestHandler } from "express";
+export declare function createAuthMiddleware(): RequestHandler;

package/dist/auth.js

@@ -0,0 +1,83 @@
+import { createHmac } from "node:crypto";
+function base64urlDecode(str) {
+    // Convert base64url to base64
+    const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    return Buffer.from(padded, "base64");
+}
+function verifyJwt(token, secret) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return false;
+    const [headerB64, payloadB64, signatureB64] = parts;
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const expectedSig = createHmac("sha256", secret)
+        .update(signingInput)
+        .digest("base64url");
+    // Constant-time comparison
+    const expected = Buffer.from(expectedSig);
+    const actual = Buffer.from(signatureB64);
+    if (expected.length !== actual.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+        diff |= expected[i] ^ actual[i];
+    }
+    return diff === 0;
+}
+function verifyPayloadExpiry(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return false;
+    try {
+        const payloadJson = base64urlDecode(parts[1]).toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        if (typeof payload.exp === "number" &&
+            payload.exp < Math.floor(Date.now() / 1000)) {
+            return false;
+        }
+    }
+    catch {
+        // If payload can't be parsed, don't block — just ignore expiry check
+    }
+    return true;
+}
+export function createAuthMiddleware() {
+    return (req, res, next) => {
+        const apiKeyEnv = process.env.MCP_API_KEY;
+        const jwtSecretEnv = process.env.MCP_JWT_SECRET;
+        // If neither env var is set, pass through
+        if (!apiKeyEnv && !jwtSecretEnv) {
+            next();
+            return;
+        }
+        // Validate X-API-Key if MCP_API_KEY is set
+        if (apiKeyEnv) {
+            const providedKey = req.headers["x-api-key"];
+            if (typeof providedKey !== "string" || providedKey !== apiKeyEnv) {
+                res.status(401).json({ error: "Unauthorized: invalid API key" });
+                return;
+            }
+        }
+        // Validate Authorization: Bearer <token> if MCP_JWT_SECRET is set
+        if (jwtSecretEnv) {
+            const authHeader = req.headers["authorization"];
+            if (typeof authHeader !== "string" || !authHeader.startsWith("Bearer ")) {
+                res.status(401).json({
+                    error: "Unauthorized: missing or malformed Authorization header",
+                });
+                return;
+            }
+            const token = authHeader.slice("Bearer ".length).trim();
+            if (!verifyJwt(token, jwtSecretEnv)) {
+                res.status(401).json({ error: "Unauthorized: invalid JWT signature" });
+                return;
+            }
+            if (!verifyPayloadExpiry(token)) {
+                res.status(401).json({ error: "Unauthorized: JWT has expired" });
+                return;
+            }
+        }
+        next();
+    };
+}

package/dist/db.d.ts

@@ -0,0 +1,37 @@
+import { DatabaseSync } from "node:sqlite";
+export type Db = DatabaseSync;
+export interface TraceRow {
+    id: string;
+    name: string;
+    status: string;
+    started_at: number;
+    ended_at: number | null;
+    metadata: string | null;
+}
+export interface StepRow {
+    id: string;
+    trace_id: string;
+    tool_name: string;
+    input_json: string;
+    output_json: string;
+    token_count: number | null;
+    latency_ms: number | null;
+    created_at: number;
+}
+export declare function expandPath(p: string): string;
+export declare function openDatabase(dbPath: string): DatabaseSync;
+export declare function insertTrace(db: DatabaseSync, id: string, name: string): void;
+export declare function endTrace(db: DatabaseSync, id: string): void;
+export declare function insertStep(db: DatabaseSync, step: Omit<StepRow, "created_at">): void;
+export declare function getTrace(db: DatabaseSync, id: string): TraceRow | undefined;
+export declare function getSteps(db: DatabaseSync, traceId: string): StepRow[];
+export declare function listTraces(db: DatabaseSync, limit?: number): TraceRow[];
+export declare function deleteOldTraces(db: DatabaseSync, retentionDays: number): number;
+export interface TraceSummary {
+    trace: TraceRow;
+    stepCount: number;
+    totalTokens: number;
+    totalLatencyMs: number;
+    steps: StepRow[];
+}
+export declare function computeSummary(db: DatabaseSync, traceId: string): TraceSummary | null;