mcp-agent-trace-inspector 1.0.0

package/dist/db.js

@@ -0,0 +1,107 @@
+// Uses the built-in node:sqlite module (Node.js >= 22.5.0)
+import { DatabaseSync } from "node:sqlite";
+import { homedir } from "node:os";
+import { mkdirSync, existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+export function expandPath(p) {
+    if (p.startsWith("~")) {
+        return resolve(homedir() + p.slice(1));
+    }
+    return resolve(p);
+}
+export function openDatabase(dbPath) {
+    const expanded = expandPath(dbPath);
+    const dir = dirname(expanded);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const db = new DatabaseSync(expanded);
+    initSchema(db);
+    return db;
+}
+function initSchema(db) {
+    db.exec(`
+    PRAGMA journal_mode = WAL;
+    PRAGMA foreign_keys = ON;
+
+    CREATE TABLE IF NOT EXISTS traces (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'running',
+      started_at INTEGER NOT NULL,
+      ended_at INTEGER,
+      metadata TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS steps (
+      id TEXT PRIMARY KEY,
+      trace_id TEXT NOT NULL,
+      tool_name TEXT NOT NULL,
+      input_json TEXT NOT NULL,
+      output_json TEXT NOT NULL,
+      token_count INTEGER,
+      latency_ms INTEGER,
+      created_at INTEGER NOT NULL,
+      FOREIGN KEY (trace_id) REFERENCES traces(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_steps_trace_id ON steps(trace_id);
+    CREATE INDEX IF NOT EXISTS idx_traces_started_at ON traces(started_at);
+  `);
+}
+export function insertTrace(db, id, name) {
+    db.prepare(`INSERT INTO traces (id, name, status, started_at) VALUES (?, ?, 'running', ?)`).run(id, name, Date.now());
+}
+export function endTrace(db, id) {
+    db.prepare(`UPDATE traces SET status = 'completed', ended_at = ? WHERE id = ?`).run(Date.now(), id);
+}
+export function insertStep(db, step) {
+    db.prepare(`
+    INSERT INTO steps (id, trace_id, tool_name, input_json, output_json, token_count, latency_ms, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(step.id, step.trace_id, step.tool_name, step.input_json, step.output_json, step.token_count ?? null, step.latency_ms ?? null, Date.now());
+}
+export function getTrace(db, id) {
+    return db.prepare(`SELECT * FROM traces WHERE id = ?`).get(id);
+}
+export function getSteps(db, traceId) {
+    return db
+        .prepare(`SELECT * FROM steps WHERE trace_id = ? ORDER BY created_at ASC`)
+        .all(traceId);
+}
+export function listTraces(db, limit) {
+    if (limit && limit > 0) {
+        return db
+            .prepare(`SELECT * FROM traces ORDER BY started_at DESC LIMIT ?`)
+            .all(limit);
+    }
+    return db
+        .prepare(`SELECT * FROM traces ORDER BY started_at DESC`)
+        .all();
+}
+export function deleteOldTraces(db, retentionDays) {
+    if (retentionDays <= 0)
+        return 0;
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    // Delete steps for old traces first (foreign key safety)
+    db.prepare(`DELETE FROM steps WHERE trace_id IN (SELECT id FROM traces WHERE started_at < ?)`).run(cutoff);
+    const result = db
+        .prepare(`DELETE FROM traces WHERE started_at < ?`)
+        .run(cutoff);
+    return result.changes;
+}
+export function computeSummary(db, traceId) {
+    const trace = getTrace(db, traceId);
+    if (!trace)
+        return null;
+    const steps = getSteps(db, traceId);
+    const totalTokens = steps.reduce((acc, s) => acc + (s.token_count ?? 0), 0);
+    const totalLatencyMs = steps.reduce((acc, s) => acc + (s.latency_ms ?? 0), 0);
+    return {
+        trace,
+        stepCount: steps.length,
+        totalTokens,
+        totalLatencyMs,
+        steps,
+    };
+}

package/dist/http-server.d.ts

@@ -0,0 +1 @@
+export declare function startHttpServer(port: number, dbPath: string, noTokenCount: boolean): Promise<void>;

package/dist/http-server.js

@@ -0,0 +1,34 @@
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "./server.js";
+import { openDatabase } from "./db.js";
+import { createAuthMiddleware } from "./auth.js";
+import { createRateLimiter } from "./rate-limiter.js";
+export async function startHttpServer(port, dbPath, noTokenCount) {
+    const app = express();
+    app.use(express.json());
+    const db = openDatabase(dbPath);
+    const server = createServer({ db, noTokenCount });
+    const auth = createAuthMiddleware();
+    const rateLimiter = createRateLimiter(60, 60000);
+    app.post("/mcp", auth, rateLimiter, async (req, res) => {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.get("/mcp", auth, rateLimiter, async (req, res) => {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    });
+    app.delete("/mcp", (_req, res) => {
+        res.status(405).json({ error: "Method not allowed" });
+    });
+    app.listen(port, () => {
+        console.error(`MCP Agent Trace Inspector HTTP server listening on port ${port}`);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { openDatabase, deleteOldTraces } from "./db.js";
+import { createServer } from "./server.js";
+import { loadPricingTable } from "./pricing.js";
+import { startHttpServer } from "./http-server.js";
+async function main() {
+    const argv = await yargs(hideBin(process.argv))
+        .option("db", {
+        alias: "db-path",
+        type: "string",
+        default: "~/.mcp/traces.db",
+        description: "Path to the SQLite database file",
+    })
+        .option("retention-days", {
+        type: "number",
+        default: 0,
+        description: "Auto-delete traces older than this many days. 0 = disabled.",
+    })
+        .option("no-token-count", {
+        type: "boolean",
+        default: false,
+        description: "Disable token counting",
+    })
+        .option("pricing-table", {
+        type: "string",
+        description: "Path to a custom JSON pricing table file",
+    })
+        .option("http-port", {
+        type: "number",
+        description: "Start in HTTP mode on the given port instead of stdio. Example: --http-port=3000",
+    })
+        .help()
+        .parseAsync();
+    // Load pricing table (for future use / extensions)
+    if (argv["pricing-table"]) {
+        try {
+            const customPricing = loadPricingTable(argv["pricing-table"]);
+            console.error(`[init] Loaded custom pricing table with ${Object.keys(customPricing).length} model(s)`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[warn] Failed to load pricing table: ${message}`);
+        }
+    }
+    // Open database (uses built-in node:sqlite)
+    const dbPath = argv.db;
+    const db = openDatabase(dbPath);
+    console.error(`[init] Database opened at: ${dbPath}`);
+    // Apply retention policy
+    const retentionDays = argv["retention-days"];
+    if (retentionDays > 0) {
+        const deleted = deleteOldTraces(db, retentionDays);
+        if (deleted > 0) {
+            console.error(`[retention] Deleted ${deleted} trace(s) older than ${retentionDays} day(s)`);
+        }
+    }
+    const noTokenCount = argv["no-token-count"];
+    const httpPort = argv["http-port"];
+    if (httpPort !== undefined) {
+        await startHttpServer(httpPort, dbPath, noTokenCount);
+        return;
+    }
+    const server = createServer({ db, noTokenCount });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[init] MCP Agent Trace Inspector server running on stdio");
+}
+main().catch((err) => {
+    console.error("[fatal]", err);
+    process.exit(1);
+});

package/dist/otel-exporter.d.ts

@@ -0,0 +1,20 @@
+import { DatabaseSync } from "node:sqlite";
+export interface OTLPSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: Record<string, string | number | boolean>;
+    status: {
+        code: number;
+        message?: string;
+    };
+}
+export interface OTLPTrace {
+    traceId: string;
+    spans: OTLPSpan[];
+}
+export declare function exportToOTLP(db: DatabaseSync, traceId: string): OTLPTrace;
+export declare function exportAllOTLP(db: DatabaseSync): OTLPTrace[];

package/dist/otel-exporter.js

@@ -0,0 +1,98 @@
+import { getTrace, getSteps, listTraces } from "./db.js";
+/** Convert a UUID-like string to a 32-hex-char trace ID (no hyphens) */
+function toTraceId(id) {
+    return id.replace(/-/g, "").padEnd(32, "0").slice(0, 32);
+}
+/** Convert a UUID-like string to a 16-hex-char span ID (no hyphens) */
+function toSpanId(id) {
+    return id.replace(/-/g, "").padEnd(16, "0").slice(0, 16);
+}
+function msToNano(ms) {
+    return (BigInt(Math.floor(ms)) * 1000000n).toString();
+}
+function traceRowToRootSpan(trace) {
+    const endMs = trace.ended_at ?? trace.started_at;
+    const statusCode = trace.status === "completed" ? 1 : 2; // 1=OK, 2=ERROR
+    const attributes = {
+        "trace.name": trace.name,
+        "trace.status": trace.status,
+    };
+    if (trace.metadata) {
+        try {
+            const meta = JSON.parse(trace.metadata);
+            for (const [k, v] of Object.entries(meta)) {
+                if (typeof v === "string" ||
+                    typeof v === "number" ||
+                    typeof v === "boolean") {
+                    attributes[`trace.metadata.${k}`] = v;
+                }
+            }
+        }
+        catch {
+            // ignore malformed metadata
+        }
+    }
+    return {
+        traceId: toTraceId(trace.id),
+        spanId: toSpanId(trace.id),
+        name: trace.name,
+        startTimeUnixNano: msToNano(trace.started_at),
+        endTimeUnixNano: msToNano(endMs),
+        attributes,
+        status: { code: statusCode, message: trace.status },
+    };
+}
+function stepRowToSpan(step, traceId, parentSpanId) {
+    const endMs = step.created_at + (step.latency_ms ?? 0);
+    const attributes = {
+        "step.tool_name": step.tool_name,
+        "step.trace_id": step.trace_id,
+    };
+    if (step.token_count !== null && step.token_count !== undefined) {
+        attributes["step.token_count"] = step.token_count;
+    }
+    if (step.latency_ms !== null && step.latency_ms !== undefined) {
+        attributes["step.latency_ms"] = step.latency_ms;
+    }
+    // Check for error in output
+    let statusCode = 1; // OK
+    try {
+        const output = JSON.parse(step.output_json);
+        if (output.error || output.isError === true) {
+            statusCode = 2; // ERROR
+            if (typeof output.error === "string") {
+                attributes["error.message"] = output.error;
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return {
+        traceId: toTraceId(traceId),
+        spanId: toSpanId(step.id),
+        parentSpanId,
+        name: step.tool_name,
+        startTimeUnixNano: msToNano(step.created_at),
+        endTimeUnixNano: msToNano(endMs),
+        attributes,
+        status: { code: statusCode },
+    };
+}
+export function exportToOTLP(db, traceId) {
+    const trace = getTrace(db, traceId);
+    if (!trace) {
+        throw new Error(`Unknown trace_id: ${traceId}`);
+    }
+    const steps = getSteps(db, traceId);
+    const rootSpan = traceRowToRootSpan(trace);
+    const stepSpans = steps.map((s) => stepRowToSpan(s, traceId, rootSpan.spanId));
+    return {
+        traceId: toTraceId(traceId),
+        spans: [rootSpan, ...stepSpans],
+    };
+}
+export function exportAllOTLP(db) {
+    const traces = listTraces(db);
+    return traces.map((t) => exportToOTLP(db, t.id));
+}

package/dist/pricing.d.ts

@@ -0,0 +1,10 @@
+export interface ModelPricing {
+    input: number;
+    output: number;
+}
+export interface PricingTable {
+    [modelName: string]: ModelPricing;
+}
+export declare const DEFAULT_PRICING: PricingTable;
+export declare function loadPricingTable(filePath: string): PricingTable;
+export declare function estimateCost(tokenCount: number, model: string, pricing: PricingTable): number | null;

package/dist/pricing.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "fs";
+export const DEFAULT_PRICING = {
+    "claude-opus-4-6": { input: 0.015, output: 0.075 },
+    "claude-sonnet-4-6": { input: 0.003, output: 0.015 },
+    "claude-haiku-4-5": { input: 0.0008, output: 0.004 },
+};
+export function loadPricingTable(filePath) {
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new Error("Pricing table must be a JSON object");
+        }
+        const table = parsed;
+        for (const [model, pricing] of Object.entries(table)) {
+            if (typeof pricing !== "object" ||
+                pricing === null ||
+                typeof pricing.input !== "number" ||
+                typeof pricing.output !== "number") {
+                throw new Error(`Invalid pricing entry for model "${model}": must have numeric input and output fields`);
+            }
+        }
+        return table;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to load pricing table from "${filePath}": ${message}`);
+    }
+}
+export function estimateCost(tokenCount, model, pricing) {
+    const entry = pricing[model];
+    if (!entry)
+        return null;
+    // Treat all tokens as input tokens for simple estimation
+    return (tokenCount / 1000) * entry.input;
+}

package/dist/prompts.d.ts

@@ -0,0 +1,21 @@
+export declare function handleListPrompts(): {
+    prompts: Array<{
+        name: string;
+        description: string;
+        arguments: Array<{
+            name: string;
+            description: string;
+            required: boolean;
+        }>;
+    }>;
+};
+export declare function handleGetPrompt(name: string, args: Record<string, string> | undefined): {
+    description: string;
+    messages: Array<{
+        role: string;
+        content: {
+            type: string;
+            text: string;
+        };
+    }>;
+};

package/dist/prompts.js

@@ -0,0 +1,66 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+const ANALYZE_TRACE_PROMPT = `You are an expert in analyzing AI agent workflow traces.
+
+Given the trace data for trace_id: {{trace_id}}, please perform a thorough investigation:
+
+1. **Overview**: Summarize what the agent was trying to accomplish based on the tool names and inputs.
+
+2. **Performance Analysis**:
+   - Identify the slowest steps (highest latency_ms) and explain potential causes.
+   - Highlight any steps with unusually high token consumption.
+   - Calculate and comment on the total cost if pricing data is available.
+
+3. **Error Detection**:
+   - Flag any steps where the output contains an error field or isError flag.
+   - Suggest remediation for each error found.
+
+4. **Reasoning Chain**:
+   - Detect if the agent follows a prompt→reasoning→action pattern.
+   - Assess whether the reasoning steps appear logically sound given the inputs.
+
+5. **Optimization Opportunities**:
+   - Identify redundant steps (same tool called multiple times with similar inputs).
+   - Suggest steps that could be parallelized.
+   - Recommend caching opportunities.
+
+6. **Overall Assessment**:
+   - Rate the trace quality (1–5) on: efficiency, error handling, and goal completion.
+   - Provide 3 specific, actionable recommendations to improve this workflow.
+
+Use the get_trace_summary tool with trace_id={{trace_id}} to fetch the data before beginning your analysis.`;
+export function handleListPrompts() {
+    return {
+        prompts: [
+            {
+                name: "analyze-trace",
+                description: "Guide an investigation of a completed agent trace — surfaces performance bottlenecks, errors, reasoning chains, and optimization opportunities.",
+                arguments: [
+                    {
+                        name: "trace_id",
+                        description: "The ID of the trace to analyze.",
+                        required: true,
+                    },
+                ],
+            },
+        ],
+    };
+}
+export function handleGetPrompt(name, args) {
+    if (name !== "analyze-trace") {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${name}`);
+    }
+    const traceId = args?.trace_id ?? "<trace_id>";
+    const promptText = ANALYZE_TRACE_PROMPT.replace(/{{trace_id}}/g, traceId);
+    return {
+        description: "Analyze an agent trace for performance, errors, reasoning chains, and optimization opportunities.",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: promptText,
+                },
+            },
+        ],
+    };
+}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,2 @@
+import type { RequestHandler } from "express";
+export declare function createRateLimiter(maxRequests?: number, windowMs?: number): RequestHandler;

package/dist/rate-limiter.js

@@ -0,0 +1,34 @@
+function getClientKey(req) {
+    const apiKey = req.headers["x-api-key"];
+    if (typeof apiKey === "string" && apiKey) {
+        return `apikey:${apiKey}`;
+    }
+    // Fall back to IP address
+    const ip = req.ip ?? req.socket?.remoteAddress ?? "unknown";
+    return `ip:${ip}`;
+}
+export function createRateLimiter(maxRequests = 60, windowMs = 60000) {
+    // Each limiter instance has its own window map (not module-level)
+    const windows = new Map();
+    return (req, res, next) => {
+        const key = getClientKey(req);
+        const now = Date.now();
+        const windowStart = now - windowMs;
+        let entry = windows.get(key);
+        if (!entry) {
+            entry = { timestamps: [] };
+            windows.set(key, entry);
+        }
+        // Slide the window: remove timestamps older than windowMs
+        entry.timestamps = entry.timestamps.filter((t) => t > windowStart);
+        if (entry.timestamps.length >= maxRequests) {
+            res.status(429).json({
+                error: "Too Many Requests",
+                retryAfterMs: windowMs,
+            });
+            return;
+        }
+        entry.timestamps.push(now);
+        next();
+    };
+}

package/dist/resources.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseSync } from "node:sqlite";
+export declare function handleListResources(db: DatabaseSync): {
+    resources: Array<{
+        uri: string;
+        name: string;
+        description: string;
+        mimeType: string;
+    }>;
+};
+export declare function handleReadResource(db: DatabaseSync, uri: string): {
+    contents: Array<{
+        uri: string;
+        mimeType: string;
+        text: string;
+    }>;
+};

package/dist/resources.js

@@ -0,0 +1,55 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { listTraces, computeSummary } from "./db.js";
+export function handleListResources(db) {
+    const traces = listTraces(db);
+    return {
+        resources: traces.map((t) => ({
+            uri: `trace://${t.id}`,
+            name: t.name,
+            description: `Agent trace "${t.name}" — status: ${t.status}, started: ${new Date(t.started_at).toISOString()}`,
+            mimeType: "application/json",
+        })),
+    };
+}
+export function handleReadResource(db, uri) {
+    const match = uri.match(/^trace:\/\/(.+)$/);
+    if (!match) {
+        throw new McpError(ErrorCode.InvalidParams, `Unsupported resource URI: ${uri}`);
+    }
+    const traceId = match[1];
+    const summary = computeSummary(db, traceId);
+    if (!summary) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown trace: ${traceId}`);
+    }
+    const { trace, stepCount, totalTokens, totalLatencyMs, steps } = summary;
+    const durationMs = trace.ended_at != null
+        ? trace.ended_at - trace.started_at
+        : Date.now() - trace.started_at;
+    const content = {
+        trace_id: trace.id,
+        name: trace.name,
+        status: trace.status,
+        started_at: trace.started_at,
+        ended_at: trace.ended_at,
+        duration_ms: durationMs,
+        step_count: stepCount,
+        total_tokens: totalTokens,
+        total_latency_ms: totalLatencyMs,
+        steps: steps.map((s) => ({
+            id: s.id,
+            tool_name: s.tool_name,
+            token_count: s.token_count,
+            latency_ms: s.latency_ms,
+            created_at: s.created_at,
+        })),
+    };
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(content, null, 2),
+            },
+        ],
+    };
+}

package/dist/retention.d.ts

@@ -0,0 +1,13 @@
+import { DatabaseSync } from "node:sqlite";
+export interface RetentionResult {
+    archived: number;
+    deleted: number;
+}
+/**
+ * Applies retention policy:
+ * - Marks traces older than `retentionDays` as archived (archived=1)
+ * - Deletes archived traces that are older than 2× retentionDays (plus their steps)
+ *
+ * Returns counts of archived and deleted traces.
+ */
+export declare function applyRetentionPolicy(db: DatabaseSync, retentionDays: number): RetentionResult;

package/dist/retention.js

@@ -0,0 +1,43 @@
+/**
+ * Ensures the traces table has an `archived` column.
+ * If it already exists, the ALTER TABLE is a no-op.
+ */
+function ensureArchivedColumn(db) {
+    try {
+        db.exec("ALTER TABLE traces ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
+    }
+    catch {
+        // Column already exists — ignore
+    }
+}
+/**
+ * Applies retention policy:
+ * - Marks traces older than `retentionDays` as archived (archived=1)
+ * - Deletes archived traces that are older than 2× retentionDays (plus their steps)
+ *
+ * Returns counts of archived and deleted traces.
+ */
+export function applyRetentionPolicy(db, retentionDays) {
+    if (retentionDays <= 0) {
+        return { archived: 0, deleted: 0 };
+    }
+    ensureArchivedColumn(db);
+    const now = Date.now();
+    const archiveCutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+    const deleteCutoff = now - 2 * retentionDays * 24 * 60 * 60 * 1000;
+    // Archive traces older than retentionDays that aren't already archived
+    const archiveResult = db
+        .prepare(`UPDATE traces SET archived = 1 WHERE started_at < ? AND archived = 0`)
+        .run(archiveCutoff);
+    const archived = archiveResult.changes;
+    // Delete steps for archived traces past 2× threshold
+    db.prepare(`DELETE FROM steps WHERE trace_id IN (
+       SELECT id FROM traces WHERE archived = 1 AND started_at < ?
+     )`).run(deleteCutoff);
+    // Delete the archived traces past 2× threshold
+    const deleteResult = db
+        .prepare(`DELETE FROM traces WHERE archived = 1 AND started_at < ?`)
+        .run(deleteCutoff);
+    const deleted = deleteResult.changes;
+    return { archived, deleted };
+}

package/dist/server.d.ts

@@ -0,0 +1,9 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { DatabaseSync } from "node:sqlite";
+export declare function isRequestCancelled(requestId: string): boolean;
+export declare function clearCancellation(requestId: string): void;
+export interface ServerOptions {
+    db: DatabaseSync;
+    noTokenCount: boolean;
+}
+export declare function createServer(options: ServerOptions): Server;