mcp-agent-trace-inspector 1.0.0

package/dist/tools/trace.d.ts

@@ -0,0 +1,33 @@
+import { DatabaseSync } from "node:sqlite";
+export interface TraceStartArgs {
+    name: string;
+}
+export interface TraceStepArgs {
+    trace_id: string;
+    tool_name: string;
+    input: object;
+    output: object;
+    token_count?: number;
+    latency_ms?: number;
+}
+export interface TraceEndArgs {
+    trace_id: string;
+}
+export declare function handleTraceStart(db: DatabaseSync, args: TraceStartArgs): {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+};
+export declare function handleTraceStep(db: DatabaseSync, args: TraceStepArgs, noTokenCount: boolean): {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+};
+export declare function handleTraceEnd(db: DatabaseSync, args: TraceEndArgs): {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+};

package/dist/tools/trace.js

@@ -0,0 +1,146 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { insertTrace, endTrace, insertStep, getTrace } from "../db.js";
+import { getEncoding } from "js-tiktoken";
+/**
+ * Compute offline token count for a text using tiktoken (cl100k_base).
+ * Falls back to the char/4 approximation if tiktoken fails.
+ */
+function computeTokenCount(text) {
+    try {
+        const enc = getEncoding("cl100k_base");
+        return enc.encode(text).length;
+    }
+    catch {
+        return Math.ceil(text.length / 4);
+    }
+}
+function generateAutoName() {
+    const now = new Date();
+    const ts = now.toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const uuidPrefix = crypto.randomUUID().slice(0, 8);
+    return `trace-${ts}-${uuidPrefix}`;
+}
+export function handleTraceStart(db, args) {
+    const raw = args.name;
+    // Auto-generate name if empty, whitespace-only, or "auto"
+    const isAuto = !raw ||
+        typeof raw !== "string" ||
+        raw.trim() === "" ||
+        raw.trim().toLowerCase() === "auto";
+    const name = isAuto ? generateAutoName() : raw.trim();
+    try {
+        const traceId = crypto.randomUUID();
+        insertTrace(db, traceId, name);
+        console.error(`[trace_start] Started trace "${name}" with id=${traceId}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        trace_id: traceId,
+                        name,
+                        status: "running",
+                    }),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new McpError(ErrorCode.InternalError, `Failed to start trace: ${message}`);
+    }
+}
+export function handleTraceStep(db, args, noTokenCount) {
+    const { trace_id, tool_name, input, output, token_count, latency_ms } = args;
+    if (!trace_id || typeof trace_id !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, "trace_id must be a non-empty string");
+    }
+    if (!tool_name || typeof tool_name !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, "tool_name must be a non-empty string");
+    }
+    if (typeof input !== "object" || input === null) {
+        throw new McpError(ErrorCode.InvalidParams, "input must be an object");
+    }
+    if (typeof output !== "object" || output === null) {
+        throw new McpError(ErrorCode.InvalidParams, "output must be an object");
+    }
+    const trace = getTrace(db, trace_id);
+    if (!trace) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown trace_id: ${trace_id}`);
+    }
+    try {
+        // Compute token count offline using tiktoken when not provided by caller
+        let resolvedTokenCount = null;
+        if (!noTokenCount) {
+            if (token_count !== undefined) {
+                resolvedTokenCount = token_count;
+            }
+            else {
+                const text = JSON.stringify(input) + JSON.stringify(output);
+                resolvedTokenCount = computeTokenCount(text);
+            }
+        }
+        const stepId = crypto.randomUUID();
+        insertStep(db, {
+            id: stepId,
+            trace_id,
+            tool_name,
+            input_json: JSON.stringify(input),
+            output_json: JSON.stringify(output),
+            token_count: resolvedTokenCount,
+            latency_ms: latency_ms ?? null,
+        });
+        console.error(`[trace_step] Recorded step "${tool_name}" for trace ${trace_id}, step id=${stepId}`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        step_id: stepId,
+                        trace_id,
+                        tool_name,
+                        token_count: resolvedTokenCount,
+                        latency_ms: latency_ms ?? null,
+                    }),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new McpError(ErrorCode.InternalError, `Failed to record step: ${message}`);
+    }
+}
+export function handleTraceEnd(db, args) {
+    const { trace_id } = args;
+    if (!trace_id || typeof trace_id !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, "trace_id must be a non-empty string");
+    }
+    const trace = getTrace(db, trace_id);
+    if (!trace) {
+        throw new McpError(ErrorCode.InvalidParams, `Unknown trace_id: ${trace_id}`);
+    }
+    try {
+        endTrace(db, trace_id);
+        const durationMs = trace.ended_at != null
+            ? trace.ended_at - trace.started_at
+            : Date.now() - trace.started_at;
+        console.error(`[trace_end] Ended trace ${trace_id} (duration ~${durationMs}ms)`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        trace_id,
+                        status: "completed",
+                        duration_ms: durationMs,
+                    }),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new McpError(ErrorCode.InternalError, `Failed to end trace: ${message}`);
+    }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "mcp-agent-trace-inspector",
+  "mcpName": "io.github.dbsectrainer/mcp-agent-trace-inspector",
+  "version": "1.0.0",
+  "description": "Step-by-step observability for MCP agent workflows",
+  "author": "dbsectrainer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dbsectrainer/mcp-agent-trace-inspector.git"
+  },
+  "homepage": "https://github.com/dbsectrainer/mcp-agent-trace-inspector#readme",
+  "type": "module",
+  "bin": {
+    "mcp-agent-trace-inspector": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "observability",
+    "tracing"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsx src/index.ts",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src tests",
+    "format": "prettier --write src tests",
+    "format:check": "prettier --check src tests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "js-tiktoken": "^1.0.21"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.12.0",
+    "@types/yargs": "^17.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.1",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.0",
+    "yargs": "^18.0.0"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  }
+}