@arizeai/phoenix-mcp 2.1.10 → 2.1.11

package/README.md

@@ -20,6 +20,7 @@ Phoenix MCP Server is an implementation of the Model Context Protocol for the Ar
 You can use Phoenix MCP Server for:
 
 - **Projects Management**: List and explore projects that organize your observability data
+- **Spans & Annotations**: Retrieve spans and their annotations for analysis and debugging
 - **Prompts Management**: Create, list, update, and iterate on prompts
 - **Datasets**: Explore datasets, and syntesize new examples
 - **Experiments**: Pull experiment results and visualize them with the help of an LLM

package/build/index.js

@@ -8,6 +8,7 @@ import { initializeDatasetTools } from "./datasetTools.js";
 import { initializeExperimentTools } from "./experimentTools.js";
 import { initializePromptTools } from "./promptTools.js";
 import { initializeProjectTools } from "./projectTools.js";
+import { initializeSpanTools } from "./spanTools.js";
 import { initializeReadmeResources } from "./readmeResource.js";
 const argv = minimist(process.argv.slice(2));
 const headers = argv.apiKey
@@ -36,6 +37,7 @@ initializePromptTools({ client, server });
 initializeExperimentTools({ client, server });
 initializeDatasetTools({ client, server });
 initializeProjectTools({ client, server });
+initializeSpanTools({ client, server });
 async function main() {
     // Initialize readme resources first
     if (process.env.DANGEROUSLY_READ_README_FILES === "true") {

package/build/spanTools.js

@@ -0,0 +1,143 @@
+import z from "zod";
+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,
+attributes, and context about the operation being performed.
+
+Example usage:
+  Get recent spans from project "my-project"
+  Get spans in a time range from project "my-project"
+
+Expected return:
+  Object containing spans array and optional next cursor for pagination.
+  Example: {
+    "spans": [
+      {
+        "id": "span123",
+        "name": "http_request",
+        "context": {
+          "trace_id": "trace456",
+          "span_id": "span123"
+        },
+        "start_time": "2024-01-01T12:00:00Z",
+        "end_time": "2024-01-01T12:00:01Z",
+        "attributes": {
+          "http.method": "GET",
+          "http.url": "/api/users"
+        }
+      }
+    ],
+    "nextCursor": "cursor_for_pagination"
+  }`;
+const GET_SPAN_ANNOTATIONS_DESCRIPTION = `Get span annotations for a list of span IDs.
+
+Span annotations provide additional metadata, scores, or labels for spans. They can be created
+by humans, LLMs, or code and help in analyzing and categorizing spans.
+
+Example usage:
+  Get annotations for spans ["span1", "span2"] from project "my-project"
+  Get quality score annotations for span "span1" from project "my-project"
+
+Expected return:
+  Object containing annotations array and optional next cursor for pagination.
+  Example: {
+    "annotations": [
+      {
+        "id": "annotation123",
+        "span_id": "span1",
+        "name": "quality_score",
+        "result": {
+          "label": "good",
+          "score": 0.95,
+          "explanation": null
+        },
+        "annotator_kind": "LLM",
+        "metadata": {
+          "model": "gpt-4"
+        }
+      }
+    ],
+    "nextCursor": "cursor_for_pagination"
+  }`;
+export const initializeSpanTools = ({ client, server, }) => {
+    server.tool("get-spans", GET_SPANS_DESCRIPTION, {
+        projectName: z.string(),
+        startTime: z.string().optional(),
+        endTime: z.string().optional(),
+        cursor: z.string().optional(),
+        limit: z.number().min(1).max(1000).default(100).optional(),
+    }, async ({ projectName, startTime, endTime, cursor, limit = 100 }) => {
+        const params = {
+            limit,
+        };
+        if (cursor) {
+            params.cursor = cursor;
+        }
+        if (startTime) {
+            params.start_time = startTime;
+        }
+        if (endTime) {
+            params.end_time = endTime;
+        }
+        const response = await client.GET("/v1/projects/{project_identifier}/spans", {
+            params: {
+                path: {
+                    project_identifier: projectName,
+                },
+                query: params,
+            },
+        });
+        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(),
+        cursor: z.string().optional(),
+        limit: z.number().min(1).max(1000).default(100).optional(),
+    }, async ({ projectName, spanIds, includeAnnotationNames, excludeAnnotationNames, cursor, limit = 100, }) => {
+        const params = {
+            span_ids: spanIds,
+            limit,
+        };
+        if (cursor) {
+            params.cursor = cursor;
+        }
+        if (includeAnnotationNames) {
+            params.include_annotation_names = includeAnnotationNames;
+        }
+        if (excludeAnnotationNames) {
+            params.exclude_annotation_names = excludeAnnotationNames;
+        }
+        const response = await client.GET("/v1/projects/{project_identifier}/span_annotations", {
+            params: {
+                path: {
+                    project_identifier: projectName,
+                },
+                query: params,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        annotations: response.data?.data ?? [],
+                        nextCursor: response.data?.next_cursor ?? null,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-mcp",
-  "version": "2.1.10",
+  "version": "2.1.11",
   "description": "A MCP server for Arize Phoenix",
   "bin": {
     "@arizeai/phoenix-mcp": "./build/index.js"
@@ -20,7 +20,7 @@
     "glob": "^11.0.1",
     "minimist": "^1.2.8",
     "zod": "^3.24.2",
-    "@arizeai/phoenix-client": "2.1.1"
+    "@arizeai/phoenix-client": "2.2.0"
   },
   "devDependencies": {
     "@types/glob": "^8.1.0",