@firetrace/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bill Zhang
+
+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,34 @@
+# @firetrace/mcp
+
+Model Context Protocol server for [FireTrace](https://github.com/IdkwhatImD0ing/FireTrace). Lets an AI agent list, inspect, record, and delete LLM traces through a scoped project API key.
+
+## stdio bridge
+
+```bash
+FIRETRACE_ENDPOINT=https://your-deployment.vercel.app \
+FIRETRACE_API_KEY=ft_live_... \
+npx -y @firetrace/mcp
+```
+
+The bridge validates the key against `GET /api/v1/key`, then exposes only the tools the key's scopes allow (`traces:read`, `traces:write`, `traces:delete`). Diagnostics go to stderr; stdout is the MCP stream.
+
+Most clients can instead talk to the deployment directly at `POST /api/mcp` with the same bearer key. See `docs/mcp.md` in the repository for client configuration and the tool reference.
+
+## Library use
+
+```ts
+import { createFireTraceMcpServer, HttpBackend } from "@firetrace/mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const backend = new HttpBackend({
+  endpoint: "https://your-deployment.vercel.app",
+  apiKey: "ft_live_...",
+});
+await backend.init();
+const server = createFireTraceMcpServer(backend);
+await server.connect(new StdioServerTransport());
+```
+
+Implement `TraceBackend` to put the same tools over any other store.
+
+MIT.

package/bin/firetrace-mcp.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// stdio MCP server bridging to a FireTrace deployment over its REST API.
+// Configure with FIRETRACE_ENDPOINT and FIRETRACE_API_KEY.
+import "../dist/cli.js";

package/dist/backend.d.ts

@@ -0,0 +1,191 @@
+/**
+ * The storage-agnostic contract the MCP tools are built on. The dashboard
+ * implements it directly on Firestore (remote MCP endpoint); the stdio CLI
+ * implements it over the REST API. Shapes mirror the REST responses.
+ */
+export type KeyScope = "traces:write" | "traces:read" | "traces:delete";
+export interface ListTracesQuery {
+    status?: string;
+    model?: string;
+    /** Exact trace name. */
+    name?: string;
+    /** One tag the trace must carry. */
+    tag?: string;
+    /** Environment stamped from the ingesting key, or `unassigned` for traces without one. */
+    environment?: string;
+    sessionId?: string;
+    userId?: string;
+    /** newest (default), slowest or costliest; the latter two only with status/model/name/tag/environment. */
+    sort?: "newest" | "slowest" | "costliest";
+    /** Inclusive ISO-8601 lower bound on startedAt. */
+    from?: string;
+    /** Inclusive ISO-8601 upper bound on startedAt. */
+    to?: string;
+    limit?: number;
+    /** nextCursor from a previous page. */
+    cursor?: string;
+}
+export interface UsageLike {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+export interface TraceSummaryLike {
+    id: string;
+    name: string;
+    status: string;
+    /** Copied from the ingesting key; null = unassigned. */
+    environment?: string | null;
+    startedAt: string;
+    /** Null while the trace is still running (status `running`). */
+    endedAt: string | null;
+    durationMs: number | null;
+    provider?: string | null;
+    model?: string | null;
+    sessionId?: string | null;
+    userId?: string | null;
+    tags?: string[];
+    usage?: UsageLike;
+    costUsd?: number | null;
+    spanCount: number;
+    errorCount: number;
+    /** Newest score per name. */
+    scores?: Record<string, {
+        value: number | string | boolean;
+        dataType: string;
+    }>;
+}
+export interface TracePageLike {
+    traces: TraceSummaryLike[];
+    nextCursor: string | null;
+    prevCursor?: string | null;
+    pageSize?: number;
+}
+export interface SpanLike {
+    id: string;
+    parentSpanId: string | null;
+    name: string;
+    kind: string;
+    status: string;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+    provider?: string | null;
+    model?: string | null;
+    input?: unknown;
+    output?: unknown;
+    attributes?: Record<string, unknown>;
+    events?: Array<{
+        name: string;
+        timestamp: string;
+        attributes?: unknown;
+    }>;
+    usage?: UsageLike | null;
+    costUsd?: number | null;
+}
+export interface TraceDetailLike {
+    trace: TraceSummaryLike & {
+        input?: unknown;
+        output?: unknown;
+        metadata?: unknown;
+    };
+    spans: SpanLike[];
+    /** Every score of the trace, newest first. */
+    scores?: ScoreLike[];
+}
+/** A judgement attached to a trace after the run: a rating, a verdict, an eval result. */
+export interface ScoreInputLike {
+    /** Letters, digits, '_' and '-', at most 64 characters. */
+    name: string;
+    dataType: "numeric" | "categorical" | "boolean";
+    /** A number for numeric, a string for categorical, a boolean for boolean. */
+    value: number | string | boolean;
+    comment?: string;
+    spanId?: string;
+}
+export interface ScoreLike {
+    id: string;
+    traceId: string;
+    spanId?: string | null;
+    name: string;
+    dataType: string;
+    value: number | string | boolean;
+    comment?: string | null;
+    source: string;
+    evaluatorId?: string | null;
+    createdAt: string;
+}
+export interface ListScoresQuery {
+    /** Only this trace's scores (its full history, newest first). */
+    traceId?: string;
+    /** Only scores with this name. */
+    name?: string;
+    /** Only scores whose trace is in this environment (`unassigned` for none); ignored with traceId. */
+    environment?: string;
+    limit?: number;
+    /** nextCursor from a previous page. */
+    cursor?: string;
+}
+export interface ScorePageLike {
+    scores: ScoreLike[];
+    nextCursor: string | null;
+}
+export interface ProjectLike {
+    id: string;
+    name: string;
+    slug?: string;
+    description?: string;
+    traceCount: number;
+    spanCount: number;
+    estimatedBytes: number;
+    lastTraceAt: string | null;
+    createdAt?: string;
+    storage?: {
+        limitBytes: number;
+        level: string;
+    };
+}
+export interface RecordResult {
+    ok: boolean;
+    traceId: string;
+    spanCount: number;
+    duplicate: boolean;
+}
+export interface MetadataPatchResult {
+    traceId: string;
+    /** The full merged metadata. */
+    metadata: Record<string, unknown>;
+    /** False when the merge matched what was stored; nothing was written. */
+    changed: boolean;
+}
+export interface TraceBackend {
+    /** Scopes carried by the authenticated key; decides which tools are registered. */
+    readonly scopes: readonly string[];
+    readonly projectId: string;
+    getProject(): Promise<ProjectLike>;
+    listTraces(query: ListTracesQuery): Promise<TracePageLike>;
+    /** Null when the trace does not exist in this project. */
+    getTrace(traceId: string): Promise<TraceDetailLike | null>;
+    /** Body in the ingestion format `{ schemaVersion: 1, trace }`. */
+    recordTrace(body: unknown): Promise<RecordResult>;
+    /**
+     * Shallow-merge keys into a stored trace's metadata, the one mutable part of
+     * a trace. Throws a BackendError with status 404 when it does not exist.
+     */
+    patchTraceMetadata(traceId: string, metadata: Record<string, unknown>): Promise<MetadataPatchResult>;
+    /** Throws a BackendError with status 404 when the trace does not exist. */
+    deleteTrace(traceId: string): Promise<void>;
+    /** Attach a score to a stored trace. Throws a BackendError with status 404 when it does not exist. */
+    addScore(traceId: string, input: ScoreInputLike): Promise<ScoreLike>;
+    /** Scores of one trace, or across the project, newest first. */
+    listScores(query: ListScoresQuery): Promise<ScorePageLike>;
+    /** JSON Schema for the ingestion request body. */
+    ingestSchema(): Promise<unknown>;
+}
+/** Error carrying an HTTP-style status and a stable code; tools render it verbatim. */
+export declare class BackendError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function hasScope(backend: TraceBackend, scope: KeyScope): boolean;

package/dist/backend.js

@@ -0,0 +1,19 @@
+/**
+ * The storage-agnostic contract the MCP tools are built on. The dashboard
+ * implements it directly on Firestore (remote MCP endpoint); the stdio CLI
+ * implements it over the REST API. Shapes mirror the REST responses.
+ */
+/** Error carrying an HTTP-style status and a stable code; tools render it verbatim. */
+export class BackendError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "BackendError";
+    }
+}
+export function hasScope(backend, scope) {
+    return backend.scopes.includes(scope);
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,30 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { HttpBackend } from "./http-backend.js";
+import { createFireTraceMcpServer } from "./server.js";
+/**
+ * stdio entry point: `FIRETRACE_ENDPOINT=https://... FIRETRACE_API_KEY=ft_live_... firetrace-mcp`
+ * Everything on stdout is the MCP stream; diagnostics go to stderr.
+ */
+async function main() {
+    const endpoint = process.env.FIRETRACE_ENDPOINT?.trim();
+    const apiKey = process.env.FIRETRACE_API_KEY?.trim();
+    if (!endpoint || !apiKey) {
+        console.error("firetrace-mcp: set FIRETRACE_ENDPOINT (deployment origin) and FIRETRACE_API_KEY (ft_live_...).");
+        process.exit(2);
+    }
+    const backend = new HttpBackend({ endpoint, apiKey });
+    try {
+        const info = await backend.init();
+        console.error(`firetrace-mcp: key ${info.keyId} → project ${info.projectId} (scopes: ${info.scopes.join(", ")})`);
+    }
+    catch (err) {
+        console.error(`firetrace-mcp: could not validate the key against ${endpoint}: ${err.message}`);
+        process.exit(1);
+    }
+    const server = createFireTraceMcpServer(backend, { version: "0.1.0" });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error(`firetrace-mcp: ${err.stack ?? err}`);
+    process.exit(1);
+});

package/dist/http-backend.d.ts

@@ -0,0 +1,46 @@
+import { type ListScoresQuery, type ListTracesQuery, type MetadataPatchResult, type ProjectLike, type RecordResult, type ScoreInputLike, type ScoreLike, type ScorePageLike, type TraceBackend, type TraceDetailLike, type TracePageLike } from "./backend.ts";
+export interface HttpBackendOptions {
+    /** Deployment origin, e.g. https://tracing.art3m1s.me */
+    endpoint: string;
+    /** ft_live_... key. Its scopes decide which tools the server exposes. */
+    apiKey: string;
+    fetch?: typeof fetch;
+    /** Per-request timeout in milliseconds (default 30 000). */
+    timeoutMs?: number;
+}
+interface KeyInfo {
+    keyId: string;
+    projectId: string;
+    scopes: string[];
+    expiresAt: string | null;
+    /** Absent on deployments that predate environments. */
+    environment?: string | null;
+}
+/**
+ * TraceBackend over the REST API. Used by the stdio CLI so any MCP client
+ * (Claude Desktop, Cursor, Claude Code...) can talk to a deployment without
+ * Firebase credentials.
+ */
+export declare class HttpBackend implements TraceBackend {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private info;
+    constructor(options: HttpBackendOptions);
+    /** Validate the key and learn its scopes. Must run before building the server. */
+    init(): Promise<KeyInfo>;
+    get scopes(): readonly string[];
+    get projectId(): string;
+    getProject(): Promise<ProjectLike>;
+    listTraces(query: ListTracesQuery): Promise<TracePageLike>;
+    getTrace(traceId: string): Promise<TraceDetailLike | null>;
+    recordTrace(body: unknown): Promise<RecordResult>;
+    patchTraceMetadata(traceId: string, metadata: Record<string, unknown>): Promise<MetadataPatchResult>;
+    deleteTrace(traceId: string): Promise<void>;
+    addScore(traceId: string, input: ScoreInputLike): Promise<ScoreLike>;
+    listScores(query: ListScoresQuery): Promise<ScorePageLike>;
+    ingestSchema(): Promise<unknown>;
+    private request;
+}
+export {};

package/dist/http-backend.js

@@ -0,0 +1,132 @@
+import { BackendError, } from "./backend.js";
+/**
+ * TraceBackend over the REST API. Used by the stdio CLI so any MCP client
+ * (Claude Desktop, Cursor, Claude Code...) can talk to a deployment without
+ * Firebase credentials.
+ */
+export class HttpBackend {
+    endpoint;
+    apiKey;
+    fetchImpl;
+    timeoutMs;
+    info = null;
+    constructor(options) {
+        if (!/^https?:\/\//.test(options.endpoint)) {
+            throw new Error("FIRETRACE_ENDPOINT must be an http(s) origin.");
+        }
+        if (!/^ft_live_[0-9a-f]{16}_[0-9a-f]{64}$/.test(options.apiKey)) {
+            throw new Error("FIRETRACE_API_KEY does not look like a FireTrace key (ft_live_...).");
+        }
+        this.endpoint = options.endpoint.replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+    }
+    /** Validate the key and learn its scopes. Must run before building the server. */
+    async init() {
+        this.info = await this.request("GET", "/api/v1/key");
+        return this.info;
+    }
+    get scopes() {
+        return this.info?.scopes ?? [];
+    }
+    get projectId() {
+        return this.info?.projectId ?? "";
+    }
+    getProject() {
+        return this.request("GET", "/api/v1/project");
+    }
+    listTraces(query) {
+        const sp = new URLSearchParams();
+        for (const [k, v] of Object.entries(query)) {
+            if (v === undefined || v === null || v === "")
+                continue;
+            sp.set(k === "cursor" ? "after" : k, String(v));
+        }
+        const qs = sp.toString();
+        return this.request("GET", `/api/v1/traces${qs ? `?${qs}` : ""}`);
+    }
+    async getTrace(traceId) {
+        try {
+            return await this.request("GET", `/api/v1/traces/${traceId}`);
+        }
+        catch (err) {
+            if (err instanceof BackendError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    recordTrace(body) {
+        return this.request("POST", "/api/v1/traces", body);
+    }
+    patchTraceMetadata(traceId, metadata) {
+        return this.request("PATCH", `/api/v1/traces/${traceId}`, { metadata });
+    }
+    async deleteTrace(traceId) {
+        await this.request("DELETE", `/api/v1/traces/${traceId}`);
+    }
+    async addScore(traceId, input) {
+        const res = await this.request("POST", `/api/v1/traces/${traceId}/scores`, input);
+        return res.score;
+    }
+    async listScores(query) {
+        if (query.traceId) {
+            const res = await this.request("GET", `/api/v1/traces/${query.traceId}/scores`);
+            const scores = query.name ? res.scores.filter((s) => s.name === query.name) : res.scores;
+            return { scores, nextCursor: null };
+        }
+        const sp = new URLSearchParams();
+        if (query.name)
+            sp.set("name", query.name);
+        if (query.environment)
+            sp.set("environment", query.environment);
+        if (query.limit)
+            sp.set("limit", String(query.limit));
+        if (query.cursor)
+            sp.set("after", query.cursor);
+        const qs = sp.toString();
+        return this.request("GET", `/api/v1/scores${qs ? `?${qs}` : ""}`);
+    }
+    async ingestSchema() {
+        const doc = await this.request("GET", "/api/v1/openapi.json");
+        return doc.components?.schemas?.IngestRequest ?? doc;
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.endpoint}${path}`, {
+                method,
+                headers: {
+                    authorization: `Bearer ${this.apiKey}`,
+                    accept: "application/json",
+                    ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            throw new BackendError(0, "network_error", `Request to ${path} failed: ${err.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const textBody = await res.text();
+        let parsed = null;
+        if (textBody) {
+            try {
+                parsed = JSON.parse(textBody);
+            }
+            catch {
+                parsed = null;
+            }
+        }
+        if (!res.ok) {
+            const e = parsed?.error;
+            throw new BackendError(res.status, e?.code ?? `http_${res.status}`, e?.message ?? `HTTP ${res.status} from ${path}`);
+        }
+        return parsed;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { BackendError, hasScope, type KeyScope, type ListScoresQuery, type ListTracesQuery, type MetadataPatchResult, type ProjectLike, type RecordResult, type ScoreInputLike, type ScoreLike, type ScorePageLike, type SpanLike, type TraceBackend, type TraceDetailLike, type TracePageLike, type TraceSummaryLike, type UsageLike, } from "./backend.ts";
+export { HttpBackend, type HttpBackendOptions } from "./http-backend.ts";
+export { createFireTraceMcpServer, truncateDeep, type FireTraceMcpOptions } from "./server.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { BackendError, hasScope, } from "./backend.js";
+export { HttpBackend } from "./http-backend.js";
+export { createFireTraceMcpServer, truncateDeep } from "./server.js";

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type TraceBackend } from "./backend.ts";
+export interface FireTraceMcpOptions {
+    /** Reported to clients during initialize. */
+    version?: string;
+    name?: string;
+}
+/** Recursively cap string lengths so a tool result stays readable for a model. */
+export declare function truncateDeep(value: unknown, maxChars: number): unknown;
+/**
+ * Build an MCP server over a TraceBackend. Only tools the key's scopes allow
+ * are registered, so an agent never sees a tool it cannot call.
+ */
+export declare function createFireTraceMcpServer(backend: TraceBackend, options?: FireTraceMcpOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,453 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { hasScope, } from "./backend.js";
+const TRACE_ID = z
+    .string()
+    .regex(/^[0-9a-fA-F]{32}$/, "traceId is 32 hex characters")
+    .transform((s) => s.toLowerCase());
+/** Trace statuses: `running` is a streamed trace that has not ended. Spans are always finished. */
+const STATUS = z.enum(["ok", "error", "unset", "running"]);
+const SPAN_STATUS = z.enum(["ok", "error", "unset"]);
+const SCORE_NAME = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,64}$/, "letters, digits, '_' and '-' only, at most 64 characters");
+function ms(n) {
+    if (n === null)
+        return "—"; // still running; the status column says so
+    if (n < 1000)
+        return `${n}ms`;
+    if (n < 60_000)
+        return `${(n / 1000).toFixed(2)}s`;
+    return `${(n / 60_000).toFixed(1)}m`;
+}
+/** Recursively cap string lengths so a tool result stays readable for a model. */
+export function truncateDeep(value, maxChars) {
+    if (typeof value === "string") {
+        return value.length > maxChars
+            ? `${value.slice(0, maxChars)}…[+${value.length - maxChars} chars truncated]`
+            : value;
+    }
+    if (Array.isArray(value))
+        return value.map((v) => truncateDeep(v, maxChars));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = truncateDeep(v, maxChars);
+        return out;
+    }
+    return value;
+}
+function text(body, structured) {
+    return structured
+        ? { content: [{ type: "text", text: body }], structuredContent: structured }
+        : { content: [{ type: "text", text: body }] };
+}
+function failure(err) {
+    const e = err;
+    const code = typeof e?.code === "string" ? e.code : "error";
+    const status = typeof e?.status === "number" ? ` (HTTP ${e.status})` : "";
+    const message = e?.message ?? String(err);
+    return { content: [{ type: "text", text: `${code}${status}: ${message}` }], isError: true };
+}
+function summarizeLine(t) {
+    const model = t.model ? ` · ${t.model}` : "";
+    const environment = t.environment ? ` [${t.environment}]` : "";
+    return `${t.id}  ${t.startedAt}  ${t.status.padEnd(9)} ${ms(t.durationMs).padStart(8)}  ${t.name}${model}${environment}  (${t.spanCount} spans, ${t.errorCount} errors)`;
+}
+function spanOutline(detail) {
+    const byParent = new Map();
+    for (const s of detail.spans) {
+        const list = byParent.get(s.parentSpanId) ?? [];
+        list.push(s);
+        byParent.set(s.parentSpanId, list);
+    }
+    const ids = new Set(detail.spans.map((s) => s.id));
+    const roots = detail.spans.filter((s) => !s.parentSpanId || !ids.has(s.parentSpanId));
+    const lines = [];
+    const walk = (span, depth) => {
+        const flag = span.status === "error" ? " ✗" : "";
+        lines.push(`${"  ".repeat(depth)}- ${span.id} [${span.kind}] ${span.name} ${ms(span.durationMs)}${span.model ? ` · ${span.model}` : ""}${flag}`);
+        for (const child of byParent.get(span.id) ?? [])
+            if (child !== span)
+                walk(child, depth + 1);
+    };
+    for (const r of roots)
+        walk(r, 0);
+    return lines.join("\n");
+}
+/**
+ * Build an MCP server over a TraceBackend. Only tools the key's scopes allow
+ * are registered, so an agent never sees a tool it cannot call.
+ */
+export function createFireTraceMcpServer(backend, options = {}) {
+    const server = new McpServer({ name: options.name ?? "firetrace", version: options.version ?? "0.1.0" }, {
+        instructions: [
+            "FireTrace stores completed LLM/agent traces (a trace is a tree of spans).",
+            `This key belongs to project ${backend.projectId} with scopes: ${backend.scopes.join(", ") || "none"}.`,
+            "Use list_traces to find traces, get_trace for the full span tree, find_spans to locate specific spans, and record_trace to store a new trace (call get_ingest_schema first if unsure of the shape). add_score attaches a judgement made after the run (a rating, a verdict, an eval result) as a queryable score; list_scores reads scores back. patch_trace_metadata merges free-form keys into a trace's metadata.",
+            'Every trace carries the environment of the key that recorded it (for example production, preview or development; null when the key has none). Pass environment to list_traces and list_scores to keep environments apart, or environment="unassigned" for traces without one.',
+            "A stored trace is immutable apart from its metadata and scores; deletion is explicit and permanent.",
+        ].join(" "),
+    });
+    const canRead = hasScope(backend, "traces:read");
+    const canWrite = hasScope(backend, "traces:write");
+    const canDelete = hasScope(backend, "traces:delete");
+    if (canRead) {
+        server.registerTool("get_project", {
+            title: "Get project",
+            description: "Return the project this key belongs to: name, trace and span counts, estimated storage, and the last trace time.",
+            inputSchema: {},
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        }, async () => {
+            try {
+                const p = await backend.getProject();
+                const summary = [
+                    `Project ${p.name} (${p.id})`,
+                    p.description ? p.description : null,
+                    `${p.traceCount} traces, ${p.spanCount} spans, ~${(p.estimatedBytes / 1_000_000).toFixed(2)} MB stored${p.storage ? ` (${p.storage.level}, limit ${(p.storage.limitBytes / 1_000_000).toFixed(0)} MB)` : ""}`,
+                    `Last trace: ${p.lastTraceAt ?? "never"}`,
+                    `Key scopes: ${backend.scopes.join(", ")}`,
+                ]
+                    .filter(Boolean)
+                    .join("\n");
+                return text(summary, p);
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+        server.registerTool("list_traces", {
+            title: "List traces",
+            description: "List traces newest first (or slowest/costliest first) with optional filters (all combine with AND). Returns one line per trace plus a cursor for the next page. Times are ISO-8601 UTC.",
+            inputSchema: {
+                status: STATUS.optional().describe("Only traces with this status"),
+                model: z.string().max(200).optional().describe("Exact model name, e.g. gpt-5"),
+                name: z.string().max(500).optional().describe("Exact trace name"),
+                tag: z.string().max(64).optional().describe("One tag the trace must carry"),
+                environment: z
+                    .string()
+                    .max(40)
+                    .optional()
+                    .describe('Environment stamped from the recording key (e.g. production, preview), or "unassigned" for traces without one'),
+                sessionId: z.string().max(200).optional(),
+                userId: z.string().max(200).optional(),
+                sort: z
+                    .enum(["newest", "slowest", "costliest"])
+                    .optional()
+                    .describe("Ordering; slowest and costliest combine only with status, model, name, tag and environment"),
+                from: z
+                    .string()
+                    .datetime({ offset: true })
+                    .optional()
+                    .describe("Inclusive lower bound on startedAt"),
+                to: z
+                    .string()
+                    .datetime({ offset: true })
+                    .optional()
+                    .describe("Inclusive upper bound on startedAt"),
+                limit: z.number().int().min(1).max(200).optional().describe("Page size, default 20"),
+                cursor: z.string().max(500).optional().describe("nextCursor from a previous call"),
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        }, async (input) => {
+            try {
+                const query = { ...input, limit: input.limit ?? 20 };
+                const page = await backend.listTraces(query);
+                const header = page.traces.length === 0
+                    ? "No traces match."
+                    : `${page.traces.length} trace(s), newest first. Columns: id, startedAt, status, duration, name · model, spans/errors.`;
+                const lines = page.traces.map(summarizeLine);
+                const footer = page.nextCursor
+                    ? `More available: call again with cursor="${page.nextCursor}".`
+                    : "End of results.";
+                return text([header, ...lines, footer].join("\n"), {
+                    traces: page.traces.map((t) => ({
+                        id: t.id,
+                        name: t.name,
+                        status: t.status,
+                        environment: t.environment ?? null,
+                        startedAt: t.startedAt,
+                        durationMs: t.durationMs,
+                        model: t.model ?? null,
+                        sessionId: t.sessionId ?? null,
+                        userId: t.userId ?? null,
+                        spanCount: t.spanCount,
+                        errorCount: t.errorCount,
+                        costUsd: t.costUsd ?? null,
+                        usage: t.usage ?? null,
+                    })),
+                    nextCursor: page.nextCursor,
+                });
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+        server.registerTool("get_trace", {
+            title: "Get trace",
+            description: "Return one trace with its full span tree: an outline first, then the trace and spans as JSON. Long strings are truncated to maxChars (default 2000); pass a larger value or use find_spans + get_trace with a small maxSpans to focus.",
+            inputSchema: {
+                traceId: TRACE_ID,
+                maxChars: z
+                    .number()
+                    .int()
+                    .min(50)
+                    .max(200_000)
+                    .optional()
+                    .describe("Per-string truncation, default 2000"),
+                maxSpans: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(500)
+                    .optional()
+                    .describe("Cap on spans included in the JSON, default 100"),
+                includeContent: z
+                    .boolean()
+                    .optional()
+                    .describe("Include span input/output/attributes (default true). false returns timing and status only."),
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        }, async (input) => {
+            try {
+                const detail = await backend.getTrace(input.traceId);
+                if (!detail)
+                    return failure({
+                        status: 404,
+                        code: "not_found",
+                        message: `No trace ${input.traceId} in this project.`,
+                    });
+                const maxSpans = input.maxSpans ?? 100;
+                const include = input.includeContent ?? true;
+                const spans = detail.spans.slice(0, maxSpans).map((s) => include
+                    ? s
+                    : {
+                        id: s.id,
+                        parentSpanId: s.parentSpanId,
+                        name: s.name,
+                        kind: s.kind,
+                        status: s.status,
+                        startedAt: s.startedAt,
+                        endedAt: s.endedAt,
+                        durationMs: s.durationMs,
+                        model: s.model ?? null,
+                        usage: s.usage ?? null,
+                    });
+                const omitted = detail.spans.length - spans.length;
+                const body = truncateDeep({
+                    trace: detail.trace,
+                    spans,
+                    ...(detail.scores?.length ? { scores: detail.scores } : {}),
+                }, input.maxChars ?? 2000);
+                const outline = spanOutline(detail);
+                const parts = [
+                    `Trace ${detail.trace.id} "${detail.trace.name}" — ${detail.trace.status}, ${ms(detail.trace.durationMs)}, ${detail.spans.length} spans, ${detail.trace.errorCount} errors, started ${detail.trace.startedAt}.`,
+                    "Span outline:",
+                    outline || "(no spans)",
+                    omitted > 0
+                        ? `JSON below includes the first ${spans.length} spans; ${omitted} omitted (raise maxSpans).`
+                        : "",
+                    JSON.stringify(body, null, 1),
+                ].filter(Boolean);
+                return text(parts.join("\n\n"));
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+        server.registerTool("find_spans", {
+            title: "Find spans",
+            description: "Locate spans inside one trace by kind, status, or name substring without loading their content. Use before get_trace when a trace is large.",
+            inputSchema: {
+                traceId: TRACE_ID,
+                kind: z
+                    .string()
+                    .max(40)
+                    .optional()
+                    .describe("llm, agent, tool, chain, retriever, embedding, reranker, custom"),
+                status: SPAN_STATUS.optional(),
+                nameContains: z
+                    .string()
+                    .max(200)
+                    .optional()
+                    .describe("Case-insensitive substring of the span name"),
+                limit: z.number().int().min(1).max(500).optional().describe("Default 50"),
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        }, async (input) => {
+            try {
+                const detail = await backend.getTrace(input.traceId);
+                if (!detail)
+                    return failure({
+                        status: 404,
+                        code: "not_found",
+                        message: `No trace ${input.traceId} in this project.`,
+                    });
+                const needle = input.nameContains?.toLowerCase();
+                const matches = detail.spans.filter((s) => (!input.kind || s.kind === input.kind) &&
+                    (!input.status || s.status === input.status) &&
+                    (!needle || s.name.toLowerCase().includes(needle)));
+                const shown = matches.slice(0, input.limit ?? 50);
+                const lines = shown.map((s) => `${s.id}  parent=${s.parentSpanId ?? "-"}  [${s.kind}] ${s.status.padEnd(9)} ${ms(s.durationMs).padStart(8)}  ${s.name}${s.model ? ` · ${s.model}` : ""}`);
+                const header = `${matches.length} of ${detail.spans.length} spans match${shown.length < matches.length ? ` (showing ${shown.length})` : ""}.`;
+                return text([header, ...lines].join("\n"), {
+                    spans: shown.map((s) => ({
+                        id: s.id,
+                        parentSpanId: s.parentSpanId,
+                        name: s.name,
+                        kind: s.kind,
+                        status: s.status,
+                        durationMs: s.durationMs,
+                        model: s.model ?? null,
+                    })),
+                    total: matches.length,
+                });
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+        server.registerTool("list_scores", {
+            title: "List scores",
+            description: "Scores are judgements attached to traces after the run (ratings, review verdicts, evaluator results): a name, a numeric/categorical/boolean value and an optional comment. Pass traceId for one trace's full history, or name to see one score across the project, newest first.",
+            inputSchema: {
+                traceId: TRACE_ID.optional().describe("Only this trace's scores"),
+                name: SCORE_NAME.optional().describe("Only scores with this name"),
+                environment: z
+                    .string()
+                    .max(40)
+                    .optional()
+                    .describe('Only scores whose trace is in this environment ("unassigned" for none); ignored with traceId'),
+                limit: z.number().int().min(1).max(500).optional().describe("Page size, default 50"),
+                cursor: z.string().max(500).optional().describe("nextCursor from a previous call"),
+            },
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        }, async (input) => {
+            try {
+                const page = await backend.listScores({ ...input, limit: input.limit ?? 50 });
+                const header = page.scores.length === 0
+                    ? "No scores match."
+                    : `${page.scores.length} score(s), newest first. Columns: id, createdAt, traceId, name=value, source, comment.`;
+                const lines = page.scores.map((s) => {
+                    const comment = s.comment
+                        ? `  ${s.comment.length > 120 ? `${s.comment.slice(0, 120)}…` : s.comment}`
+                        : "";
+                    return `${s.id}  ${s.createdAt}  ${s.traceId}  ${s.name}=${JSON.stringify(s.value)}  ${s.source}${comment}`;
+                });
+                const footer = page.nextCursor
+                    ? `More available: call again with cursor="${page.nextCursor}".`
+                    : "End of results.";
+                return text([header, ...lines, footer].join("\n"), {
+                    scores: page.scores,
+                    nextCursor: page.nextCursor,
+                });
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+    }
+    if (canWrite) {
+        server.registerTool("get_ingest_schema", {
+            title: "Get ingest schema",
+            description: "JSON Schema for the body accepted by record_trace ({ schemaVersion: 1, trace }). Consult it before recording a trace by hand.",
+            inputSchema: {},
+            annotations: { readOnlyHint: true, idempotentHint: true },
+        }, async () => {
+            try {
+                const schema = await backend.ingestSchema();
+                return text(JSON.stringify(schema, null, 1));
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+        server.registerTool("record_trace", {
+            title: "Record trace",
+            description: "Store one complete, immutable trace. `trace` must follow the ingestion schema: id (32 hex), name, status, startedAt/endedAt (ISO-8601), and spans[] each with id (16 hex), parentSpanId, name, kind, status, startedAt, endedAt. Resending an identical trace is a no-op; reusing an id with different content is rejected. Omitting both endedAt and status stores a running trace that the REST API's spans/end endpoints complete later (status alone without endedAt is rejected).",
+            inputSchema: {
+                trace: z.record(z.string(), z.unknown()).describe("The trace object (not the envelope)"),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+        }, async (input) => {
+            try {
+                const result = await backend.recordTrace({ schemaVersion: 1, trace: input.trace });
+                const verb = result.duplicate ? "Already stored (identical duplicate)" : "Stored";
+                return text(`${verb}: trace ${result.traceId} with ${result.spanCount} spans.`, {
+                    ...result,
+                });
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+        server.registerTool("add_score", {
+            title: "Add score",
+            description: "Attach a score to a stored trace: a judgement made after the run, such as a rating, a review verdict or an evaluator's result. Scores are indexed and listable (unlike metadata). Each has a name (letters, digits, '_' and '-'), a dataType with a matching value (numeric → number, categorical → string, boolean → boolean) and an optional comment explaining it. Scores are append-only: adding the same name again records a newer score, and the trace's summary shows the newest per name.",
+            inputSchema: {
+                traceId: TRACE_ID,
+                name: SCORE_NAME.describe("Score name, e.g. accuracy, helpful, topic"),
+                dataType: z.enum(["numeric", "categorical", "boolean"]),
+                value: z
+                    .union([z.number(), z.string().max(200), z.boolean()])
+                    .describe("Must match dataType"),
+                comment: z.string().max(2000).optional().describe("Why this score was given"),
+                spanId: z
+                    .string()
+                    .regex(/^[0-9a-fA-F]{16}$/)
+                    .optional()
+                    .describe("Scope the score to one span instead of the whole trace"),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+        }, async (input) => {
+            try {
+                const { traceId, ...score } = input;
+                const stored = await backend.addScore(traceId, score);
+                return text(`Added score ${stored.name}=${JSON.stringify(stored.value)} (${stored.id}) to trace ${traceId}.`, { ...stored });
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+        server.registerTool("patch_trace_metadata", {
+            title: "Patch trace metadata",
+            description: "Shallow-merge keys into a stored trace's metadata for free-form facts that only exist after the run (a business outcome, a link to a ticket). For ratings, verdicts and eval results prefer add_score, which is indexed. A key in the patch replaces that top-level key outright; keys not mentioned are left alone; concurrent writers on one key are last-writer-wins. Everything else about the trace, spans included, stays immutable. Metadata is not indexed, so it cannot be searched or filtered by.",
+            inputSchema: {
+                traceId: TRACE_ID,
+                metadata: z
+                    .record(z.string(), z.unknown())
+                    .describe("Keys to merge into the trace's existing metadata"),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+        }, async (input) => {
+            try {
+                const result = await backend.patchTraceMetadata(input.traceId, input.metadata);
+                const verb = result.changed ? "Merged into" : "Already matched";
+                return text(`${verb} the metadata of trace ${input.traceId}; it now has ${Object.keys(result.metadata).length} keys.`, { ...result });
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+    }
+    if (canDelete) {
+        server.registerTool("delete_trace", {
+            title: "Delete trace",
+            description: "Permanently delete one trace and all of its spans. Irreversible. Requires confirm=true.",
+            inputSchema: {
+                traceId: TRACE_ID,
+                confirm: z.literal(true).describe("Must be true; guards against accidental deletion"),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+        }, async (input) => {
+            try {
+                await backend.deleteTrace(input.traceId);
+                return text(`Deleted trace ${input.traceId}.`, { ok: true, traceId: input.traceId });
+            }
+            catch (err) {
+                return failure(err);
+            }
+        });
+    }
+    return server;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@firetrace/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for FireTrace: lets AI agents list, read, record, and delete traces through a scoped API key.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "firetrace-mcp": "./bin/firetrace-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.1.13"
+  },
+  "keywords": [
+    "firetrace",
+    "mcp",
+    "model-context-protocol",
+    "llm",
+    "tracing"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export {
+  BackendError,
+  hasScope,
+  type KeyScope,
+  type ListScoresQuery,
+  type ListTracesQuery,
+  type MetadataPatchResult,
+  type ProjectLike,
+  type RecordResult,
+  type ScoreInputLike,
+  type ScoreLike,
+  type ScorePageLike,
+  type SpanLike,
+  type TraceBackend,
+  type TraceDetailLike,
+  type TracePageLike,
+  type TraceSummaryLike,
+  type UsageLike,
+} from "./backend.ts";
+export { HttpBackend, type HttpBackendOptions } from "./http-backend.ts";
+export { createFireTraceMcpServer, truncateDeep, type FireTraceMcpOptions } from "./server.ts";