@arizeai/phoenix-mcp 2.1.10 → 2.2.0

package/README.md

@@ -14,12 +14,14 @@
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/LICENSE)
 <img src="https://badge.mcpx.dev?status=on" title="MCP Enabled"/>
+<a href="https://cursor.com/install-mcp?name=phoenix&config=eyJjb21tYW5kIjoibnB4IC15IEBhcml6ZWFpL3Bob2VuaXgtbWNwQGxhdGVzdCAtLWJhc2VVcmwgaHR0cDovL2xvY2FsaG9zdDo2MDA2IC0tYXBpS2V5IHlvdXItYXBpLWtleSJ9"><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add Arize Phoenix MCP server to Cursor" height=20 /></a>
 
 Phoenix MCP Server is an implementation of the Model Context Protocol for the Arize Phoenix platform. It provides a unified interface to Phoenix's capabilites.
 
 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
@@ -45,6 +47,7 @@ This MCP server can be used using `npx` and can be directly integrated with clie
       ]
     }
   }
+}
 ```
 
 ## Development

package/build/index.js

@@ -8,7 +8,9 @@ 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";
+import { initializeSupportTools } from "./supportTools.js";
 const argv = minimist(process.argv.slice(2));
 const headers = argv.apiKey
     ? {
@@ -36,6 +38,8 @@ initializePromptTools({ client, server });
 initializeExperimentTools({ client, server });
 initializeDatasetTools({ client, server });
 initializeProjectTools({ client, server });
+initializeSpanTools({ client, server });
+initializeSupportTools({ 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/build/supportTools.js

@@ -0,0 +1,73 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import z from "zod";
+const PHOENIX_SUPPORT_DESCRIPTION = `Get help with Phoenix and OpenInference.
+
+- Tracing AI applications via OpenInference and OpenTelemetry
+- Phoenix datasets, experiments, and prompt management
+- Phoenix evals and annotations
+
+Use this tool when you need assistance with Phoenix features, troubleshooting,
+or best practices.
+
+Expected return:
+  Expert guidance about how to use and integrate Phoenix`;
+/**
+ * Creates an MCP client connected to the RunLLM server via HTTP
+ */
+async function createRunLLMClient() {
+    const transport = new StreamableHTTPClientTransport(new URL("https://mcp.runllm.com/mcp/"), {
+        requestInit: {
+            headers: {
+                "assistant-name": "arize-phoenix",
+            },
+        },
+    });
+    const client = new Client({
+        name: "runllm-client",
+        version: "1.0.0",
+    });
+    await client.connect(transport);
+    return client;
+}
+/**
+ * Calls the chat tool on the RunLLM MCP server
+ */
+export async function callRunLLMChat({ question, }) {
+    const client = await createRunLLMClient();
+    // Call the chat tool with the user's question
+    const result = await client.callTool({
+        name: "chat",
+        arguments: {
+            message: question,
+        },
+    });
+    // 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")
+            .map((item) => item.text)
+            .join("\n");
+        if (textContent) {
+            return textContent;
+        }
+    }
+    return "No response received from support";
+}
+export const initializeSupportTools = async ({ server, }) => {
+    server.tool("phoenix-support", PHOENIX_SUPPORT_DESCRIPTION, {
+        question: z
+            .string()
+            .describe("Your question about Arize Phoenix, OpenInference, or related topics"),
+    }, async ({ question }) => {
+        const result = await callRunLLMChat({ question });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result,
+                },
+            ],
+        };
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-mcp",
-  "version": "2.1.10",
+  "version": "2.2.0",
   "description": "A MCP server for Arize Phoenix",
   "bin": {
     "@arizeai/phoenix-mcp": "./build/index.js"
@@ -16,11 +16,11 @@
   "author": "oss@arize.com",
   "license": "Apache-2.0",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@modelcontextprotocol/sdk": "^1.13.3",
     "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",