@arizeai/phoenix-mcp 3.1.5 → 4.0.0

package/build/traceTools.js

@@ -0,0 +1,141 @@
+import { getTraces } from "@arizeai/phoenix-client/traces";
+import z from "zod";
+import { DEFAULT_TRACE_PAGE_SIZE, MAX_SPAN_QUERY_LIMIT, MAX_TRACE_PAGE_SIZE, } from "./constants.js";
+import { resolveProjectIdentifier } from "./projectUtils.js";
+import { attachAnnotationsToSpans, extractSpanIds, fetchProjectSpans, fetchSpanAnnotations, resolveStartTime, } from "./spanUtils.js";
+import { jsonResponse } from "./toolResults.js";
+import { buildTrace, groupSpansByTrace } from "./traceUtils.js";
+// ---------------------------------------------------------------------------
+// Tool descriptions
+// ---------------------------------------------------------------------------
+const LIST_TRACES_DESCRIPTION = `List traces for a project.
+
+This tool groups project spans into traces and returns the newest traces first.
+
+Example usage:
+  Show me the last 10 traces for project "default"
+  Show me recent traces from the last 30 minutes for project "checkout"
+
+Expected return:
+  Array of trace objects with grouped spans and summary timing information.`;
+const GET_TRACE_DESCRIPTION = `Get a single trace by its exact trace ID within a project.
+
+Example usage:
+  Show me trace "abc123def456" from project "default"
+
+Expected return:
+  A trace object with all spans that belong to the trace.`;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Fetch every span belonging to a single trace.
+ */
+async function fetchTraceSpans({ client, projectIdentifier, traceId, }) {
+    const response = await fetchProjectSpans({
+        client,
+        projectIdentifier,
+        filters: {
+            traceIds: [traceId],
+            limit: MAX_SPAN_QUERY_LIMIT,
+        },
+        totalLimit: undefined,
+    });
+    return response.spans;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+/**
+ * Register trace-related MCP tools on the given server.
+ */
+export const initializeTraceTools = ({ client, server, defaultProject, }) => {
+    server.tool("list-traces", LIST_TRACES_DESCRIPTION, {
+        project_identifier: z.string().optional(),
+        limit: z
+            .number()
+            .min(1)
+            .max(MAX_TRACE_PAGE_SIZE)
+            .default(DEFAULT_TRACE_PAGE_SIZE),
+        since: z.string().optional(),
+        last_n_minutes: z.number().min(1).optional(),
+        include_annotations: z.boolean().default(false).optional(),
+    }, async ({ project_identifier, limit, since, last_n_minutes, include_annotations = false, }) => {
+        const startTime = resolveStartTime({
+            since,
+            lastNMinutes: last_n_minutes,
+        });
+        const normalizedProjectIdentifier = resolveProjectIdentifier({
+            projectIdentifier: project_identifier,
+            defaultProjectIdentifier: defaultProject,
+        });
+        const tracePage = await getTraces({
+            client,
+            project: { project: normalizedProjectIdentifier },
+            startTime,
+            limit,
+            sort: "start_time",
+            order: "desc",
+        });
+        const traceIds = tracePage.traces.map((trace) => trace.trace_id);
+        if (traceIds.length === 0) {
+            return jsonResponse([]);
+        }
+        const response = await fetchProjectSpans({
+            client,
+            projectIdentifier: normalizedProjectIdentifier,
+            filters: {
+                traceIds,
+                limit: MAX_SPAN_QUERY_LIMIT,
+            },
+            totalLimit: undefined,
+        });
+        let spans = response.spans;
+        if (include_annotations) {
+            const annotations = await fetchSpanAnnotations({
+                client,
+                projectIdentifier: normalizedProjectIdentifier,
+                spanIds: extractSpanIds(spans),
+            });
+            spans = attachAnnotationsToSpans({ spans, annotations });
+        }
+        const spansByTraceId = groupSpansByTrace({ spans });
+        const traces = traceIds.flatMap((traceId) => {
+            const traceSpans = spansByTraceId.get(traceId);
+            if (!traceSpans || traceSpans.length === 0) {
+                return [];
+            }
+            return [buildTrace({ spans: traceSpans })];
+        });
+        return jsonResponse(traces);
+    });
+    server.tool("get-trace", GET_TRACE_DESCRIPTION, {
+        project_identifier: z.string().optional(),
+        trace_id: z.string(),
+        include_annotations: z.boolean().default(false).optional(),
+    }, async ({ project_identifier, trace_id, include_annotations = false }) => {
+        const normalizedProjectIdentifier = resolveProjectIdentifier({
+            projectIdentifier: project_identifier,
+            defaultProjectIdentifier: defaultProject,
+        });
+        const spans = await fetchTraceSpans({
+            client,
+            projectIdentifier: normalizedProjectIdentifier,
+            traceId: trace_id,
+        });
+        if (spans.length === 0) {
+            throw new Error(`Trace not found for project "${normalizedProjectIdentifier}": ${trace_id}`);
+        }
+        if (include_annotations) {
+            const annotations = await fetchSpanAnnotations({
+                client,
+                projectIdentifier: normalizedProjectIdentifier,
+                spanIds: extractSpanIds(spans),
+            });
+            return jsonResponse(buildTrace({
+                spans: attachAnnotationsToSpans({ spans, annotations }),
+            }));
+        }
+        return jsonResponse(buildTrace({ spans }));
+    });
+};

package/build/traceUtils.js

@@ -0,0 +1,57 @@
+/**
+ * Group an array of spans by their `trace_id`, returning a map
+ * from trace ID to the spans belonging to that trace.
+ */
+export function groupSpansByTrace({ spans, }) {
+    const traces = new Map();
+    for (const span of spans) {
+        const traceId = span.context.trace_id;
+        if (!traces.has(traceId)) {
+            traces.set(traceId, []);
+        }
+        traces.get(traceId).push(span);
+    }
+    return traces;
+}
+/**
+ * Build a {@link Trace} summary from a non-empty array of spans that share
+ * the same trace ID.
+ *
+ * The summary includes the root span, overall time range, duration, and a
+ * roll-up status that is `"ERROR"` when any span has an error.
+ *
+ * @throws When the spans array is empty.
+ */
+export function buildTrace({ spans }) {
+    if (spans.length === 0) {
+        throw new Error("Cannot build trace from empty spans array");
+    }
+    const traceId = spans[0].context.trace_id;
+    const rootSpan = spans.find((span) => !span.parent_id);
+    const startTimes = spans
+        .map((span) => new Date(span.start_time).getTime())
+        .filter((time) => !Number.isNaN(time));
+    const endTimes = spans
+        .map((span) => new Date(span.end_time).getTime())
+        .filter((time) => !Number.isNaN(time));
+    const startTime = startTimes.length > 0
+        ? new Date(Math.min(...startTimes)).toISOString()
+        : undefined;
+    const endTime = endTimes.length > 0
+        ? new Date(Math.max(...endTimes)).toISOString()
+        : undefined;
+    const duration = startTime && endTime
+        ? new Date(endTime).getTime() - new Date(startTime).getTime()
+        : undefined;
+    const hasErrors = spans.some((span) => span.status_code === "ERROR" ||
+        span.attributes?.error);
+    return {
+        traceId,
+        spans,
+        rootSpan,
+        startTime,
+        endTime,
+        duration,
+        status: hasErrors ? "ERROR" : "OK",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-mcp",
-  "version": "3.1.5",
+  "version": "4.0.0",
   "description": "A MCP server for Arize Phoenix",
   "keywords": [
     "arize-phoenix",
@@ -24,22 +24,25 @@
   ],
   "type": "module",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "glob": "^13.0.6",
     "minimist": "^1.2.8",
-    "zod": "^4.0.14",
-    "@arizeai/phoenix-client": "6.5.2"
+    "zod": "^4.3.6",
+    "@arizeai/phoenix-client": "6.5.3",
+    "@arizeai/phoenix-config": "0.1.2"
   },
   "devDependencies": {
-    "@types/glob": "^8.1.0",
+    "@types/glob": "^9.0.0",
     "@types/minimist": "^1.2.5",
     "@types/node": "^22.14.0",
-    "tsx": "^4.19.3"
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.10"
   },
   "scripts": {
     "build": "tsc && chmod 755 build/index.js",
     "dev": "source ./.env && tsx src/index.ts -- --apiKey $PHOENIX_API_KEY --baseUrl $PHOENIX_BASE_URL",
     "inspect": "pnpm run build && npx -y @modelcontextprotocol/inspector -- node build/index.js",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }