opik-mcp 0.1.2 → 2.0.0

package/build/resources/opik-resources.js

@@ -0,0 +1,196 @@
+import { callSdk, getOpikApi, getRequestOptions } from '../utils/opik-sdk.js';
+import { registerResource, registerResourceTemplate } from '../tools/registration.js';
+const DEFAULT_PAGE = 1;
+const DEFAULT_SIZE = 10;
+const MAX_SIZE = 100;
+function parsePositiveInt(value, fallback, max = MAX_SIZE) {
+    const parsed = Number.parseInt(value || '', 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        return fallback;
+    }
+    return Math.min(parsed, max);
+}
+function toReadError(uri, message) {
+    return {
+        contents: [
+            {
+                uri,
+                text: JSON.stringify({ error: message }, null, 2),
+            },
+        ],
+    };
+}
+function includeToolset(enabled, toolset) {
+    return enabled.has(toolset);
+}
+export function loadOpikResources(server, config) {
+    const enabledToolsets = new Set(config.enabledToolsets);
+    const hasTraceRead = includeToolset(enabledToolsets, 'core') ||
+        includeToolset(enabledToolsets, 'expert-trace-actions');
+    const hasPromptRead = includeToolset(enabledToolsets, 'expert-prompts');
+    const hasDatasetRead = includeToolset(enabledToolsets, 'expert-datasets');
+    const hasProjectRead = includeToolset(enabledToolsets, 'core');
+    registerResource(server, 'workspace-info', 'opik://workspace-info', 'Workspace information for the configured Opik MCP server.', async () => ({
+        contents: [
+            {
+                uri: 'opik://workspace-info',
+                text: JSON.stringify({
+                    name: config.workspaceName,
+                    apiUrl: config.apiBaseUrl,
+                    selfHosted: config.isSelfHosted,
+                    enabledToolsets: config.enabledToolsets,
+                }, null, 2),
+            },
+        ],
+    }));
+    if (hasProjectRead) {
+        // Backward-compatible static URI while encouraging template usage for paging.
+        registerResource(server, 'projects-list', 'opik://projects-list', 'Project listing for the configured Opik workspace (first page only).', async () => {
+            const api = getOpikApi();
+            const response = await callSdk(() => api.projects.findProjects({ page: 1, size: 25 }));
+            if (!response.data) {
+                return toReadError('opik://projects-list', response.error || 'Failed to fetch projects');
+            }
+            return {
+                contents: [
+                    {
+                        uri: 'opik://projects-list',
+                        text: JSON.stringify(response.data, null, 2),
+                    },
+                ],
+            };
+        });
+        registerResourceTemplate(server, 'projects-page', 'opik://projects/{page}/{size}', 'Paginated project listing by page and size.', async (uri, variables) => {
+            const page = parsePositiveInt(variables.page, DEFAULT_PAGE);
+            const size = parsePositiveInt(variables.size, DEFAULT_SIZE);
+            const api = getOpikApi();
+            const response = await callSdk(() => api.projects.findProjects({ page, size }));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch projects');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+    }
+    if (hasPromptRead) {
+        registerResourceTemplate(server, 'prompts-page', 'opik://prompts/{page}/{size}', 'Paginated prompt listing by page and size.', async (uri, variables) => {
+            const page = parsePositiveInt(variables.page, DEFAULT_PAGE);
+            const size = parsePositiveInt(variables.size, DEFAULT_SIZE);
+            const api = getOpikApi();
+            const response = await callSdk(() => api.prompts.getPrompts({ page, size }));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch prompts');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+        registerResourceTemplate(server, 'prompt-latest', 'opik://prompt/{name}', 'Latest prompt version by prompt name.', async (uri, variables) => {
+            const name = decodeURIComponent(variables.name || '');
+            if (!name) {
+                return toReadError(uri.toString(), 'Prompt name is required');
+            }
+            const api = getOpikApi();
+            const response = await callSdk(() => api.prompts.retrievePromptVersion({ name }));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch prompt');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+        registerResourceTemplate(server, 'prompt-commit', 'opik://prompt/{name}/{commit}', 'Specific prompt version by prompt name and commit.', async (uri, variables) => {
+            const name = decodeURIComponent(variables.name || '');
+            const commit = decodeURIComponent(variables.commit || '');
+            if (!name || !commit) {
+                return toReadError(uri.toString(), 'Prompt name and commit are required');
+            }
+            const api = getOpikApi();
+            const response = await callSdk(() => api.prompts.retrievePromptVersion({ name, commit }));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch prompt version');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+    }
+    if (hasDatasetRead) {
+        registerResourceTemplate(server, 'datasets-page', 'opik://datasets/{page}/{size}', 'Paginated dataset listing by page and size.', async (uri, variables) => {
+            const page = parsePositiveInt(variables.page, DEFAULT_PAGE);
+            const size = parsePositiveInt(variables.size, DEFAULT_SIZE);
+            const api = getOpikApi();
+            const response = await callSdk(() => api.datasets.findDatasets({ page, size }));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch datasets');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+        registerResourceTemplate(server, 'dataset-by-id', 'opik://dataset/{datasetId}', 'Dataset details by dataset ID.', async (uri, variables) => {
+            const datasetId = decodeURIComponent(variables.datasetId || '');
+            if (!datasetId) {
+                return toReadError(uri.toString(), 'datasetId is required');
+            }
+            const api = getOpikApi();
+            const response = await callSdk(() => api.datasets.getDatasetById(datasetId));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch dataset');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+        registerResourceTemplate(server, 'dataset-items-page', 'opik://dataset/{datasetId}/items/{page}/{size}', 'Paginated dataset items by dataset ID, page, and size.', async (uri, variables) => {
+            const datasetId = decodeURIComponent(variables.datasetId || '');
+            const page = parsePositiveInt(variables.page, DEFAULT_PAGE);
+            const size = parsePositiveInt(variables.size, 25, 500);
+            if (!datasetId) {
+                return toReadError(uri.toString(), 'datasetId is required');
+            }
+            const api = getOpikApi();
+            const response = await callSdk(() => api.datasets.getDatasetItems(datasetId, { page, size }));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch dataset items');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+    }
+    if (hasTraceRead) {
+        registerResourceTemplate(server, 'trace-by-id', 'opik://trace/{traceId}', 'Trace details by trace ID.', async (uri, variables) => {
+            const traceId = decodeURIComponent(variables.traceId || '');
+            if (!traceId) {
+                return toReadError(uri.toString(), 'traceId is required');
+            }
+            const api = getOpikApi();
+            const response = await callSdk(() => api.traces.getTraceById(traceId, getRequestOptions()));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch trace');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+        registerResourceTemplate(server, 'traces-by-project-page', 'opik://traces/{projectId}/{page}/{size}', 'Paginated traces by project ID, page, and size.', async (uri, variables) => {
+            const projectId = decodeURIComponent(variables.projectId || '');
+            const page = parsePositiveInt(variables.page, DEFAULT_PAGE);
+            const size = parsePositiveInt(variables.size, DEFAULT_SIZE);
+            if (!projectId) {
+                return toReadError(uri.toString(), 'projectId is required');
+            }
+            const api = getOpikApi();
+            const response = await callSdk(() => api.traces.getTracesByProject({ projectId, page, size }, getRequestOptions()));
+            if (!response.data) {
+                return toReadError(uri.toString(), response.error || 'Failed to fetch traces');
+            }
+            return {
+                contents: [{ uri: uri.toString(), text: JSON.stringify(response.data, null, 2) }],
+            };
+        });
+    }
+    return server;
+}

package/build/test-client.js

@@ -397,11 +397,9 @@ async function main() {
     // Create the client
     const client = new Client({
         name: 'test-client',
-        version: '1.0.0',
+        version: '2.0.0',
     }, {
-        capabilities: {
-            tools: {}, // We're interested in tools
-        },
+        capabilities: {},
     });
     try {
         // Connect to the server

package/build/tools/capabilities.js

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+import { getCapabilitiesDescription, getEnabledCapabilities, opikCapabilities, } from '../utils/capabilities.js';
+import { getAllExampleTasks, getExampleForTask } from '../utils/examples.js';
+import { getAllMetricsInfo, getMetricInfo } from '../utils/metrics-info.js';
+import { getTracingInfo } from '../utils/tracing-info.js';
+import { registerTool } from './registration.js';
+function formatTopicHelp(topic) {
+    if (topic === 'general') {
+        const general = opikCapabilities.general;
+        return [
+            '# General API Information',
+            '',
+            `- API Version: ${general.apiVersion}`,
+            `- Authentication: ${general.authentication}`,
+            `- Rate Limit: ${general.rateLimit}`,
+            `- Supported Formats: ${general.supportedFormats.join(', ')}`,
+        ].join('\n');
+    }
+    const section = opikCapabilities[topic];
+    return [
+        `# ${topic.charAt(0).toUpperCase()}${topic.slice(1)}`,
+        '',
+        `Available: ${section.available ? 'Yes' : 'No'}`,
+        '',
+        '## Features',
+        ...section.features.map(feature => `- ${feature}`),
+        '',
+        '## Limitations',
+        ...section.limitations.map(limitation => `- ${limitation}`),
+    ].join('\n');
+}
+export const loadCapabilitiesTools = (server, config) => {
+    registerTool(server, 'get-server-info', 'Return server configuration and enabled Opik capabilities.', {}, async (_args) => {
+        const serverInfo = {
+            apiBaseUrl: config.apiBaseUrl,
+            isSelfHosted: config.isSelfHosted,
+            workspaceName: config.workspaceName,
+            transport: config.transport,
+            mcpName: config.mcpName,
+            mcpVersion: config.mcpVersion,
+            mcpDefaultWorkspace: config.mcpDefaultWorkspace,
+            enabledToolsets: config.enabledToolsets,
+            hasApiKey: Boolean(config.apiKey),
+            capabilities: getEnabledCapabilities(config),
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(serverInfo, null, 2),
+                },
+            ],
+        };
+    }, { requiresApiKey: false });
+    registerTool(server, 'get-opik-help', 'Return Opik capability documentation, optionally filtered by topic.', {
+        topic: z
+            .enum(['prompts', 'projects', 'traces', 'metrics', 'general'])
+            .optional()
+            .describe('Optional capability topic to describe'),
+    }, async (args) => {
+        if (args.topic) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: formatTopicHelp(args.topic),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: getCapabilitiesDescription(config),
+                },
+            ],
+        };
+    }, { requiresApiKey: false });
+    registerTool(server, 'get-opik-examples', 'Return Opik usage examples for a requested task.', {
+        task: z
+            .string()
+            .optional()
+            .describe('Optional task name, e.g. "create prompt", "log trace", "evaluate response"'),
+    }, async (args) => {
+        const tasks = getAllExampleTasks();
+        const example = getExampleForTask(args.task);
+        if (!example) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: args.task
+                            ? `No specific example found for task: ${args.task}. Available tasks: ${tasks.join(', ')}`
+                            : `Available tasks: ${tasks.join(', ')}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `# Example: ${example.title}`,
+                        '',
+                        '## Description',
+                        example.description,
+                        '',
+                        '## Steps',
+                        ...example.steps.map((step, index) => `${index + 1}. ${step}`),
+                        '',
+                        '## Code Example',
+                        example.codeExample.trim(),
+                    ].join('\n'),
+                },
+            ],
+        };
+    }, { requiresApiKey: false });
+    registerTool(server, 'get-opik-metrics-info', 'Return Opik metric definitions and usage guidance.', {
+        metric: z
+            .string()
+            .optional()
+            .describe('Optional metric name (e.g. hallucination, answerrelevance, moderation)'),
+    }, async (args) => {
+        if (args.metric) {
+            const metric = getMetricInfo(args.metric);
+            if (!metric) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Metric not found: ${args.metric}`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(metric, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(getAllMetricsInfo(), null, 2),
+                },
+            ],
+        };
+    }, { requiresApiKey: false });
+    registerTool(server, 'get-opik-tracing-info', 'Return tracing guidance for traces, spans, feedback, search, and visualization.', {
+        topic: z
+            .enum(['traces', 'spans', 'feedback', 'search', 'visualization'])
+            .optional()
+            .describe('Optional tracing topic'),
+    }, async (args) => {
+        const info = getTracingInfo(args.topic);
+        if (!info) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No tracing info found for topic: ${args.topic}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(info, null, 2),
+                },
+            ],
+        };
+    }, { requiresApiKey: false });
+    return server;
+};

package/build/tools/dataset.js

@@ -0,0 +1,172 @@
+import { z } from 'zod';
+import { callSdk, getOpikApi, getRequestOptions } from '../utils/opik-sdk.js';
+import { registerTool } from './registration.js';
+import { pageSchema, sizeSchema, workspaceNameSchema } from './schema.js';
+export const loadDatasetTools = (server) => {
+    registerTool(server, 'list-datasets', 'List datasets with optional name filtering.', {
+        page: pageSchema,
+        size: sizeSchema(10),
+        name: z.string().optional().describe('Optional dataset name filter.'),
+        workspaceName: workspaceNameSchema,
+    }, async (args) => {
+        const { page = 1, size = 10, name, workspaceName } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.datasets.findDatasets({ page, size, name }, getRequestOptions(workspaceName)));
+        if (!response.data) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to fetch datasets' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${response.data.total} datasets (page ${response.data.page} of ${Math.ceil(response.data.total / response.data.size)})`,
+                },
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data.content, null, 2),
+                },
+            ],
+        };
+    });
+    registerTool(server, 'get-dataset-by-id', 'Get full details for a dataset by ID.', {
+        datasetId: z.string().min(1).describe('Dataset ID.'),
+        workspaceName: workspaceNameSchema,
+    }, async (args) => {
+        const { datasetId, workspaceName } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.datasets.getDatasetById(datasetId, getRequestOptions(workspaceName)));
+        if (!response.data) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to fetch dataset' }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }],
+        };
+    });
+    registerTool(server, 'create-dataset', 'Create a dataset for evaluations and experiments.', {
+        name: z.string().min(1).describe('Dataset name.'),
+        description: z.string().optional().describe('Optional dataset description.'),
+        workspaceName: workspaceNameSchema,
+    }, async (args) => {
+        const { name, description, workspaceName } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.datasets.createDataset({
+            name,
+            ...(description && { description }),
+        }, getRequestOptions(workspaceName)));
+        if (response.error) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to create dataset' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Successfully created dataset: ${name}`,
+                },
+            ],
+        };
+    });
+    registerTool(server, 'delete-dataset', 'Delete a dataset by ID.', {
+        datasetId: z.string().min(1).describe('Dataset ID.'),
+        workspaceName: workspaceNameSchema,
+    }, async (args) => {
+        const { datasetId, workspaceName } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.datasets.deleteDataset(datasetId, getRequestOptions(workspaceName)));
+        if (response.error) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to delete dataset' }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Successfully deleted dataset ${datasetId}` }],
+        };
+    });
+    registerTool(server, 'list-dataset-items', 'List items in a dataset.', {
+        datasetId: z.string().min(1).describe('Dataset ID.'),
+        page: pageSchema,
+        size: sizeSchema(25, 500),
+        workspaceName: workspaceNameSchema,
+    }, async (args) => {
+        const { datasetId, page = 1, size = 25, workspaceName } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.datasets.getDatasetItems(datasetId, { page, size }, getRequestOptions(workspaceName)));
+        if (!response.data) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to fetch dataset items' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${response.data.total} dataset items (page ${response.data.page} of ${Math.ceil(response.data.total / response.data.size)})`,
+                },
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data.content, null, 2),
+                },
+            ],
+        };
+    });
+    registerTool(server, 'create-dataset-item', 'Create one dataset item with input, expected output, and metadata.', {
+        datasetId: z.string().min(1).describe('Dataset ID.'),
+        input: z.record(z.any()).describe('Input payload.'),
+        expectedOutput: z.record(z.any()).optional().describe('Optional expected output payload.'),
+        metadata: z.record(z.any()).optional().describe('Optional metadata payload.'),
+        workspaceName: workspaceNameSchema,
+    }, async (args) => {
+        const { datasetId, input, expectedOutput, metadata, workspaceName } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.datasets.createOrUpdateDatasetItems({
+            datasetId,
+            items: [
+                {
+                    source: 'manual',
+                    data: {
+                        input,
+                        ...(expectedOutput && { expected_output: expectedOutput }),
+                        ...(metadata && { metadata }),
+                    },
+                },
+            ],
+        }, getRequestOptions(workspaceName)));
+        if (response.error) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to create dataset item' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Successfully created dataset item in dataset ${datasetId}`,
+                },
+            ],
+        };
+    });
+    registerTool(server, 'delete-dataset-item', 'Delete a dataset item by ID.', {
+        itemId: z.string().min(1).describe('Dataset item ID.'),
+        workspaceName: workspaceNameSchema,
+    }, async (args) => {
+        const { itemId, workspaceName } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.datasets.deleteDatasetItems({
+            itemIds: [itemId],
+        }, getRequestOptions(workspaceName)));
+        if (response.error) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to delete dataset item' }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Successfully deleted dataset item ${itemId}` }],
+        };
+    });
+    return server;
+};

package/build/tools/integration.js

@@ -1,4 +1,4 @@
-// No imports needed for this simple documentation tool
+import { registerTool } from './registration.js';
 const integrationDocs = `
 # OPIK Agentic Onboarding
 
@@ -91,10 +91,10 @@ If issues are reported:
 4. Apply and revalidate.
 `;
 export const loadIntegrationTools = (server) => {
-    server.tool('opik-integration-docs', 'Provides detailed documentation on how to integrate Opik with your LLM application', {}, async (_args) => {
+    registerTool(server, 'opik-integration-docs', 'Provides detailed documentation on how to integrate Opik with your LLM application', {}, async (_args) => {
         return {
             content: [{ type: 'text', text: integrationDocs }],
         };
-    });
+    }, { requiresApiKey: false });
     return server;
 };