@arizeai/phoenix-mcp 3.1.5 → 4.0.0

package/build/sessionTools.js

@@ -0,0 +1,126 @@
+import z from "zod";
+import { DEFAULT_TRACE_PAGE_SIZE, MAX_SESSION_PAGE_SIZE } from "./constants.js";
+import { requireIdentifier } from "./identifiers.js";
+import { fetchAllPages } from "./pagination.js";
+import { resolveProjectIdentifier } from "./projectUtils.js";
+import { getResponseData } from "./responseUtils.js";
+import { jsonResponse } from "./toolResults.js";
+// ---------------------------------------------------------------------------
+// Tool descriptions
+// ---------------------------------------------------------------------------
+const LIST_SESSIONS_DESCRIPTION = `List sessions for a project.
+
+Sessions represent conversation flows grouped across traces.
+
+Example usage:
+  Show me the last 10 sessions for project "default"
+
+Expected return:
+  Array of session objects ordered by the requested sort order.`;
+const GET_SESSION_DESCRIPTION = `Get a single session by GlobalID or user-provided session_id.
+
+Example usage:
+  Show me session "chat-123"
+
+Expected return:
+  A session object and, optionally, its annotations.`;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Fetch all annotations for a single session, paginating internally.
+ */
+async function fetchSessionAnnotations({ client, projectIdentifier, sessionId, }) {
+    const normalizedProjectIdentifier = requireIdentifier({
+        identifier: projectIdentifier,
+        label: "projectIdentifier",
+    });
+    return fetchAllPages({
+        limit: Infinity,
+        fetchPage: async (cursor, pageSize) => {
+            const query = {
+                session_ids: [sessionId],
+                limit: pageSize,
+            };
+            if (cursor) {
+                query.cursor = cursor;
+            }
+            const response = await client.GET("/v1/projects/{project_identifier}/session_annotations", {
+                params: {
+                    path: { project_identifier: normalizedProjectIdentifier },
+                    query,
+                },
+            });
+            const data = getResponseData({
+                response,
+                errorPrefix: `Failed to fetch annotations for session "${sessionId}"`,
+            });
+            return { data: data.data, nextCursor: data.next_cursor || undefined };
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+/**
+ * Register session-related MCP tools on the given server.
+ */
+export const initializeSessionTools = ({ client, server, defaultProject, }) => {
+    server.tool("list-sessions", LIST_SESSIONS_DESCRIPTION, {
+        project_identifier: z.string().optional(),
+        limit: z
+            .number()
+            .min(1)
+            .max(MAX_SESSION_PAGE_SIZE)
+            .default(DEFAULT_TRACE_PAGE_SIZE),
+        order: z.enum(["asc", "desc"]).default("desc").optional(),
+    }, async ({ project_identifier, limit, order = "desc" }) => {
+        const normalizedProjectIdentifier = resolveProjectIdentifier({
+            projectIdentifier: project_identifier,
+            defaultProjectIdentifier: defaultProject,
+        });
+        const sessions = await fetchAllPages({
+            limit,
+            fetchPage: async (cursor, pageSize) => {
+                const response = await client.GET("/v1/projects/{project_identifier}/sessions", {
+                    params: {
+                        path: { project_identifier: normalizedProjectIdentifier },
+                        query: { cursor, limit: pageSize, order },
+                    },
+                });
+                const data = getResponseData({
+                    response,
+                    errorPrefix: `Failed to fetch sessions for project "${normalizedProjectIdentifier}"`,
+                });
+                return { data: data.data, nextCursor: data.next_cursor || undefined };
+            },
+        });
+        return jsonResponse(sessions);
+    });
+    server.tool("get-session", GET_SESSION_DESCRIPTION, {
+        session_identifier: z.string(),
+        include_annotations: z.boolean().default(false).optional(),
+    }, async ({ session_identifier, include_annotations = false }) => {
+        const response = await client.GET("/v1/sessions/{session_identifier}", {
+            params: {
+                path: { session_identifier },
+            },
+        });
+        const session = getResponseData({
+            response,
+            errorPrefix: `Failed to fetch session "${session_identifier}"`,
+        }).data;
+        if (!include_annotations) {
+            return jsonResponse(session);
+        }
+        const annotations = await fetchSessionAnnotations({
+            client,
+            projectIdentifier: session.project_id,
+            sessionId: session.session_id,
+        });
+        return jsonResponse({
+            session,
+            annotations,
+        });
+    });
+};

package/build/spanTools.js

@@ -1,4 +1,12 @@
 import z from "zod";
+import { DEFAULT_PAGE_SIZE, MAX_SPAN_QUERY_LIMIT } from "./constants.js";
+import { resolveProjectIdentifier } from "./projectUtils.js";
+import { getResponseData } from "./responseUtils.js";
+import { attachAnnotationsToSpans, extractSpanIds, fetchProjectSpans, fetchSpanAnnotations, } from "./spanUtils.js";
+import { jsonResponse } from "./toolResults.js";
+// ---------------------------------------------------------------------------
+// Tool descriptions
+// ---------------------------------------------------------------------------
 const GET_SPANS_DESCRIPTION = `Get spans from a project with filtering criteria.
 
 Spans represent individual operations or units of work within a trace. They contain timing information,
@@ -59,89 +67,111 @@ Expected return:
     ],
     "nextCursor": "cursor_for_pagination"
   }`;
-export const initializeSpanTools = ({ client, server, }) => {
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+/**
+ * Register span-related MCP tools on the given server.
+ */
+export const initializeSpanTools = ({ client, server, defaultProject, }) => {
     server.tool("get-spans", GET_SPANS_DESCRIPTION, {
-        projectName: z.string(),
-        startTime: z.string().optional(),
-        endTime: z.string().optional(),
-        traceIds: z.array(z.string()).optional(),
+        project_identifier: z.string().optional(),
+        start_time: z.string().optional(),
+        end_time: z.string().optional(),
+        trace_ids: z.array(z.string()).optional(),
+        parent_id: z.string().nullable().optional(),
+        names: z.array(z.string()).optional(),
+        span_kinds: z.array(z.string()).optional(),
+        status_codes: z.array(z.enum(["OK", "ERROR", "UNSET"])).optional(),
         cursor: z.string().optional(),
-        limit: z.number().min(1).max(1000).default(100).optional(),
-    }, async ({ projectName, startTime, endTime, traceIds, cursor, limit = 100, }) => {
-        const params = {
-            limit,
-        };
-        if (cursor) {
-            params.cursor = cursor;
-        }
-        if (startTime) {
-            params.start_time = startTime;
-        }
-        if (endTime) {
-            params.end_time = endTime;
-        }
-        if (traceIds) {
-            params.trace_id = traceIds;
-        }
-        const response = await client.GET("/v1/projects/{project_identifier}/spans", {
-            params: {
-                path: {
-                    project_identifier: projectName,
-                },
-                query: params,
+        limit: z
+            .number()
+            .min(1)
+            .max(MAX_SPAN_QUERY_LIMIT)
+            .default(DEFAULT_PAGE_SIZE)
+            .optional(),
+        include_annotations: z.boolean().default(false).optional(),
+    }, async ({ project_identifier, start_time, end_time, trace_ids, parent_id, names, span_kinds, status_codes, cursor, limit = DEFAULT_PAGE_SIZE, include_annotations = false, }) => {
+        const resolvedProjectIdentifier = resolveProjectIdentifier({
+            projectIdentifier: project_identifier,
+            defaultProjectIdentifier: defaultProject,
+        });
+        const response = await fetchProjectSpans({
+            client,
+            projectIdentifier: resolvedProjectIdentifier,
+            filters: {
+                cursor,
+                limit,
+                startTime: start_time,
+                endTime: end_time,
+                traceIds: trace_ids,
+                parentId: parent_id,
+                names,
+                spanKinds: span_kinds,
+                statusCodes: status_codes,
             },
+            totalLimit: limit,
+        });
+        const spans = include_annotations
+            ? attachAnnotationsToSpans({
+                spans: response.spans,
+                annotations: await fetchSpanAnnotations({
+                    client,
+                    projectIdentifier: resolvedProjectIdentifier,
+                    spanIds: extractSpanIds(response.spans),
+                }),
+            })
+            : response.spans;
+        return jsonResponse({
+            spans,
+            nextCursor: response.nextCursor,
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        spans: response.data?.data ?? [],
-                        nextCursor: response.data?.next_cursor ?? null,
-                    }, null, 2),
-                },
-            ],
-        };
     });
     server.tool("get-span-annotations", GET_SPAN_ANNOTATIONS_DESCRIPTION, {
-        projectName: z.string(),
-        spanIds: z.array(z.string()),
-        includeAnnotationNames: z.array(z.string()).optional(),
-        excludeAnnotationNames: z.array(z.string()).optional(),
+        project_identifier: z.string().optional(),
+        span_ids: z.array(z.string()),
+        include_annotation_names: z.array(z.string()).optional(),
+        exclude_annotation_names: z.array(z.string()).optional(),
         cursor: z.string().optional(),
-        limit: z.number().min(1).max(1000).default(100).optional(),
-    }, async ({ projectName, spanIds, includeAnnotationNames, excludeAnnotationNames, cursor, limit = 100, }) => {
+        limit: z
+            .number()
+            .min(1)
+            .max(MAX_SPAN_QUERY_LIMIT)
+            .default(DEFAULT_PAGE_SIZE)
+            .optional(),
+    }, async ({ project_identifier, span_ids, include_annotation_names, exclude_annotation_names, cursor, limit = DEFAULT_PAGE_SIZE, }) => {
+        const resolvedProjectIdentifier = resolveProjectIdentifier({
+            projectIdentifier: project_identifier,
+            defaultProjectIdentifier: defaultProject,
+        });
         const params = {
-            span_ids: spanIds,
+            span_ids,
             limit,
         };
         if (cursor) {
             params.cursor = cursor;
         }
-        if (includeAnnotationNames) {
-            params.include_annotation_names = includeAnnotationNames;
+        if (include_annotation_names) {
+            params.include_annotation_names = include_annotation_names;
         }
-        if (excludeAnnotationNames) {
-            params.exclude_annotation_names = excludeAnnotationNames;
+        if (exclude_annotation_names) {
+            params.exclude_annotation_names = exclude_annotation_names;
         }
         const response = await client.GET("/v1/projects/{project_identifier}/span_annotations", {
             params: {
                 path: {
-                    project_identifier: projectName,
+                    project_identifier: resolvedProjectIdentifier,
                 },
                 query: params,
             },
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        annotations: response.data?.data ?? [],
-                        nextCursor: response.data?.next_cursor ?? null,
-                    }, null, 2),
-                },
-            ],
-        };
+        const data = getResponseData({
+            response,
+            errorPrefix: `Failed to fetch span annotations for project "${resolvedProjectIdentifier}"`,
+        });
+        return jsonResponse({
+            annotations: data.data,
+            nextCursor: data.next_cursor || null,
+        });
     });
 };

package/build/spanUtils.js

@@ -0,0 +1,232 @@
+import { getSpans, } from "@arizeai/phoenix-client/spans";
+import { ANNOTATION_CHUNK_SIZE, ANNOTATION_PAGE_SIZE, DEFAULT_PAGE_SIZE, MAX_CONCURRENT_ANNOTATION_REQUESTS, MAX_SPAN_QUERY_LIMIT, MS_PER_MINUTE, } from "./constants.js";
+import { requireIdentifier } from "./identifiers.js";
+import { getResponseData } from "./responseUtils.js";
+/**
+ * Extract span IDs from an array of spans, filtering out any without context.
+ */
+export function extractSpanIds(spans) {
+    return spans
+        .map((span) => span.context?.span_id)
+        .filter((spanId) => Boolean(spanId));
+}
+/**
+ * Translate MCP span filters into the phoenix-client `getSpans` parameter shape.
+ *
+ * The MCP layer uses plural field names (`names`, `spanKinds`, `statusCodes`)
+ * while phoenix-client uses singular (`name`, `spanKind`, `statusCode`).
+ */
+export function buildProjectSpansRequest({ cursor, limit, startTime, endTime, traceIds, parentId, names, spanKinds, statusCodes, }) {
+    const request = {};
+    if (cursor) {
+        request.cursor = cursor;
+    }
+    if (limit !== undefined) {
+        request.limit = limit;
+    }
+    if (startTime) {
+        request.startTime = startTime;
+    }
+    if (endTime) {
+        request.endTime = endTime;
+    }
+    if (traceIds && traceIds.length > 0) {
+        request.traceIds = traceIds;
+    }
+    if (parentId !== undefined) {
+        request.parentId = parentId;
+    }
+    if (names && names.length > 0) {
+        request.name = names;
+    }
+    if (spanKinds && spanKinds.length > 0) {
+        request.spanKind = spanKinds;
+    }
+    if (statusCodes && statusCodes.length > 0) {
+        request.statusCode = statusCodes;
+    }
+    return request;
+}
+/**
+ * Resolve the lower-bound start time for trace and span listing tools.
+ *
+ * An explicit `since` ISO timestamp takes precedence. When only `lastNMinutes`
+ * is provided the start time is computed relative to `now`.
+ *
+ * @returns An ISO 8601 timestamp string, or `undefined` if no time constraint was given.
+ */
+export function resolveStartTime({ since, lastNMinutes, now = new Date(), }) {
+    if (since) {
+        return since;
+    }
+    if (lastNMinutes === undefined) {
+        return undefined;
+    }
+    return new Date(now.getTime() - lastNMinutes * MS_PER_MINUTE).toISOString();
+}
+/**
+ * Fetch spans for a project, paginating internally until `totalLimit` is
+ * reached or all matching spans have been retrieved.
+ *
+ * @param options.client - The Phoenix REST client.
+ * @param options.projectIdentifier - Project name or Relay GlobalID.
+ * @param options.filters - Span filter criteria.
+ * @param options.totalLimit - Cap on the total number of spans returned.
+ * @returns The collected spans and an optional cursor for further pagination.
+ */
+export async function fetchProjectSpans({ client, projectIdentifier, filters, totalLimit, }) {
+    const normalizedProjectIdentifier = requireIdentifier({
+        identifier: projectIdentifier,
+        label: "projectIdentifier",
+    });
+    const collectedSpans = [];
+    let cursor = filters.cursor;
+    const pageLimit = Math.min(totalLimit || filters.limit || DEFAULT_PAGE_SIZE, MAX_SPAN_QUERY_LIMIT);
+    do {
+        const response = await getSpans({
+            client,
+            project: { project: normalizedProjectIdentifier },
+            ...buildProjectSpansRequest({
+                ...filters,
+                cursor,
+                limit: pageLimit,
+            }),
+        });
+        collectedSpans.push(...response.spans);
+        cursor = response.nextCursor || undefined;
+        if (totalLimit !== undefined && collectedSpans.length >= totalLimit) {
+            return {
+                spans: collectedSpans.slice(0, totalLimit),
+                nextCursor: cursor || null,
+            };
+        }
+    } while (cursor);
+    return {
+        spans: collectedSpans,
+        nextCursor: cursor || null,
+    };
+}
+/**
+ * Split an array into chunks of at most `size` elements.
+ */
+function chunkArray(values, size) {
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size) {
+        chunks.push(values.slice(index, index + size));
+    }
+    return chunks;
+}
+/**
+ * Fetch all span annotation pages for a single chunk of span IDs.
+ *
+ * Paginates internally until every annotation for the given span IDs
+ * has been collected.
+ */
+async function fetchSpanAnnotationsForChunk({ client, projectIdentifier, spanIds, includeAnnotationNames, excludeAnnotationNames, pageLimit, }) {
+    const annotations = [];
+    let cursor;
+    do {
+        const query = {
+            span_ids: spanIds,
+            limit: pageLimit,
+        };
+        if (cursor) {
+            query.cursor = cursor;
+        }
+        if (includeAnnotationNames && includeAnnotationNames.length > 0) {
+            query.include_annotation_names = includeAnnotationNames;
+        }
+        if (excludeAnnotationNames && excludeAnnotationNames.length > 0) {
+            query.exclude_annotation_names = excludeAnnotationNames;
+        }
+        const response = await client.GET("/v1/projects/{project_identifier}/span_annotations", {
+            params: {
+                path: {
+                    project_identifier: projectIdentifier,
+                },
+                query,
+            },
+        });
+        const data = getResponseData({
+            response,
+            errorPrefix: `Failed to fetch span annotations for project "${projectIdentifier}"`,
+        });
+        annotations.push(...data.data);
+        cursor = data.next_cursor || undefined;
+    } while (cursor);
+    return annotations;
+}
+/**
+ * Fetch span annotations in chunks to avoid overwhelming the annotations
+ * endpoint with very large span-ID lists.
+ *
+ * Span IDs are split into chunks of {@link ANNOTATION_CHUNK_SIZE} and
+ * fetched with a concurrency cap of {@link MAX_CONCURRENT_ANNOTATION_REQUESTS}.
+ *
+ * @param options.client - The Phoenix REST client.
+ * @param options.projectIdentifier - Project name or Relay GlobalID.
+ * @param options.spanIds - Span IDs to fetch annotations for.
+ * @param options.includeAnnotationNames - Only return annotations with these names.
+ * @param options.excludeAnnotationNames - Exclude annotations with these names.
+ * @param options.pageLimit - Per-page limit for annotation pagination.
+ * @param options.maxConcurrent - Maximum concurrent chunk requests.
+ */
+export async function fetchSpanAnnotations({ client, projectIdentifier, spanIds, includeAnnotationNames, excludeAnnotationNames, pageLimit = ANNOTATION_PAGE_SIZE, maxConcurrent = MAX_CONCURRENT_ANNOTATION_REQUESTS, }) {
+    if (spanIds.length === 0) {
+        return [];
+    }
+    const normalizedProjectIdentifier = requireIdentifier({
+        identifier: projectIdentifier,
+        label: "projectIdentifier",
+    });
+    const uniqueSpanIds = Array.from(new Set(spanIds));
+    const chunks = chunkArray(uniqueSpanIds, ANNOTATION_CHUNK_SIZE);
+    const allAnnotations = [];
+    for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += maxConcurrent) {
+        const batch = chunks.slice(chunkIndex, chunkIndex + maxConcurrent);
+        const batchResults = await Promise.all(batch.map((spanIdsChunk) => fetchSpanAnnotationsForChunk({
+            client,
+            projectIdentifier: normalizedProjectIdentifier,
+            spanIds: spanIdsChunk,
+            includeAnnotationNames,
+            excludeAnnotationNames,
+            pageLimit,
+        })));
+        for (const batchResult of batchResults) {
+            allAnnotations.push(...batchResult);
+        }
+    }
+    return allAnnotations;
+}
+/**
+ * Merge annotations onto their corresponding spans by `span_id`.
+ *
+ * Spans that have no matching annotations are returned unmodified.
+ * Spans with annotations gain an `annotations` property containing
+ * the full list.
+ */
+export function attachAnnotationsToSpans({ spans, annotations, }) {
+    const annotationsBySpanId = new Map();
+    for (const annotation of annotations) {
+        const spanAnnotations = annotationsBySpanId.get(annotation.span_id);
+        if (spanAnnotations) {
+            spanAnnotations.push(annotation);
+        }
+        else {
+            annotationsBySpanId.set(annotation.span_id, [annotation]);
+        }
+    }
+    return spans.map((span) => {
+        const spanId = span.context?.span_id;
+        const spanAnnotations = spanId
+            ? annotationsBySpanId.get(spanId)
+            : undefined;
+        if (!spanAnnotations || spanAnnotations.length === 0) {
+            return span;
+        }
+        return {
+            ...span,
+            annotations: spanAnnotations,
+        };
+    });
+}

package/build/supportTools.js

@@ -12,10 +12,16 @@ or best practices.
 
 Expected return:
   Expert guidance about how to use and integrate Phoenix`;
+/** Cached RunLLM MCP client, lazily created on first use. */
+let runLLMClient = null;
 /**
- * Creates an MCP client connected to the RunLLM server via HTTP
+ * Return a cached MCP client connected to the RunLLM server.
+ * Creates and connects the client on first call; subsequent calls reuse it.
  */
-async function createRunLLMClient() {
+async function getRunLLMClient() {
+    if (runLLMClient) {
+        return runLLMClient;
+    }
     const transport = new StreamableHTTPClientTransport(new URL("https://mcp.runllm.com/mcp"), {
         requestInit: {
             headers: {
@@ -28,21 +34,18 @@ async function createRunLLMClient() {
         version: "1.0.0",
     });
     await client.connect(transport);
+    runLLMClient = client;
     return client;
 }
 /**
- * Calls the chat tool on the RunLLM MCP server
+ * Calls the search tool on the RunLLM MCP server.
  */
 export async function callRunLLMQuery({ query, }) {
-    const client = await createRunLLMClient();
-    // Call the chat tool with the user's question
+    const client = await getRunLLMClient();
     const result = await client.callTool({
         name: "search",
-        arguments: {
-            query: query,
-        },
+        arguments: { query },
     });
-    // There's usually only one content item, but we'll handle multiple for safety
     if (result.content && Array.isArray(result.content)) {
         const textContent = result.content
             .filter((item) => item.type === "text")

package/build/toolResults.js

@@ -0,0 +1,32 @@
+/**
+ * Wrap an arbitrary payload as a JSON-formatted MCP text content response.
+ *
+ * @param payload - The value to serialize. Will be pretty-printed with 2-space indentation.
+ * @returns An MCP tool result containing one text content block.
+ */
+export function jsonResponse(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+/**
+ * Wrap a plain string as an MCP text content response.
+ *
+ * @param text - The plain text to return.
+ * @returns An MCP tool result containing one text content block.
+ */
+export function textResponse(text) {
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+    };
+}