opik-mcp 0.1.2 → 2.0.0

package/build/tools/metrics.js

@@ -1,62 +1,66 @@
-import { makeApiRequest } from '../utils/api.js';
 import { z } from 'zod';
-import { logToFile } from '../utils/logging.js';
+import { callSdk, getOpikApi, getRequestOptions, mapMetricType, resolveProjectIdentifier, } from '../utils/opik-sdk.js';
+import { registerTool } from './registration.js';
+import { isoDateSchema, workspaceNameSchema } from './schema.js';
 export const loadMetricTools = (server) => {
-    server.tool('get-metrics', 'Get metrics data', {
-        metricName: z.string().optional().describe('Optional metric name to filter'),
-        projectId: z.string().optional().describe('Optional project ID to filter metrics'),
-        projectName: z.string().optional().describe('Optional project name to filter metrics'),
-        startDate: z.string().optional().describe('Start date in ISO format (YYYY-MM-DD)'),
-        endDate: z.string().optional().describe('End date in ISO format (YYYY-MM-DD)'),
+    registerTool(server, 'get-metrics', 'Get project metrics for a date range and optional metric type.', {
+        metricName: z
+            .string()
+            .optional()
+            .describe('Optional metric type/alias (TRACE_COUNT, TOKEN_USAGE, COST, DURATION, FEEDBACK).'),
+        projectId: z.string().optional().describe('Optional project ID.'),
+        projectName: z
+            .string()
+            .optional()
+            .describe('Optional project name (alternative to projectId).'),
+        startDate: isoDateSchema,
+        endDate: isoDateSchema,
+        workspaceName: workspaceNameSchema,
     }, async (args) => {
-        const { metricName, projectId, projectName, startDate, endDate } = args;
-        let url = `/v1/private/metrics`;
-        const queryParams = [];
-        if (metricName)
-            queryParams.push(`metric_name=${metricName}`);
-        // Add project filtering - API requires either project_id or project_name
-        if (projectId) {
-            queryParams.push(`project_id=${projectId}`);
-        }
-        else if (projectName) {
-            queryParams.push(`project_name=${encodeURIComponent(projectName)}`);
-        }
-        else {
-            // If no project specified, we need to find one for the API to work
-            const projectsResponse = await makeApiRequest(`/v1/private/projects?page=1&size=1`);
-            if (projectsResponse.data &&
-                projectsResponse.data.content &&
-                projectsResponse.data.content.length > 0) {
-                const firstProject = projectsResponse.data.content[0];
-                queryParams.push(`project_id=${firstProject.id}`);
-                logToFile(`No project specified, using first available: ${firstProject.name} (${firstProject.id})`);
-            }
-            else {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'Error: No project ID or name provided, and no projects found',
-                        },
-                    ],
-                };
-            }
+        const { metricName, projectId, projectName, startDate, endDate, workspaceName } = args;
+        const resolved = await resolveProjectIdentifier(projectId, projectName, workspaceName);
+        if (resolved.error || (!resolved.projectId && !resolved.projectName)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${resolved.error || 'No project available for metrics query'}`,
+                    },
+                ],
+            };
         }
-        if (startDate)
-            queryParams.push(`start_date=${startDate}`);
-        if (endDate)
-            queryParams.push(`end_date=${endDate}`);
-        if (queryParams.length > 0) {
-            url += `?${queryParams.join('&')}`;
+        if (!resolved.projectId) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Error: Metrics queries require a resolvable project ID',
+                    },
+                ],
+            };
         }
-        const response = await makeApiRequest(url);
+        const metricType = mapMetricType(metricName);
+        const api = getOpikApi();
+        const response = await callSdk(() => api.projects.getProjectMetrics(resolved.projectId, {
+            ...(metricType && { metricType }),
+            interval: 'DAILY',
+            ...(startDate && { intervalStart: new Date(startDate) }),
+            ...(endDate && { intervalEnd: new Date(endDate) }),
+        }, getRequestOptions(workspaceName)));
         if (!response.data) {
             return {
                 content: [{ type: 'text', text: response.error || 'Failed to fetch metrics' }],
             };
         }
+        const metricWarning = metricName && !metricType
+            ? `\nNote: metricName "${metricName}" is not a known metric type in the SDK and was ignored.`
+            : '';
         return {
             content: [
+                {
+                    type: 'text',
+                    text: `Metrics for project ${resolved.projectId}${metricWarning}`,
+                },
                 {
                     type: 'text',
                     text: JSON.stringify(response.data, null, 2),

package/build/tools/project.js

@@ -1,53 +1,74 @@
-import { makeApiRequest } from '../utils/api.js';
 import { z } from 'zod';
-export const loadProjectTools = (server) => {
-    server.tool('list-projects', 'Get a list of projects with optional filtering', {
-        page: z.number().optional().default(1).describe('Page number for pagination'),
-        size: z.number().optional().default(10).describe('Number of items per page'),
-        workspaceName: z.string().optional().describe('Workspace name to use instead of the default'),
-    }, async (args) => {
-        const { page, size, workspaceName } = args;
-        const url = `/v1/private/projects?page=${page}&size=${size}`;
-        const response = await makeApiRequest(url, {}, workspaceName);
-        if (!response.data) {
+import { callSdk, getOpikApi, getRequestOptions } from '../utils/opik-sdk.js';
+import { registerTool } from './registration.js';
+import { pageSchema, sizeSchema, workspaceNameSchema } from './schema.js';
+export const loadProjectTools = (server, options = {}) => {
+    const { includeReadOps = true, includeMutations = true } = options;
+    if (includeReadOps) {
+        registerTool(server, 'list-projects', 'List projects in the active workspace to find IDs for traces and metrics operations.', {
+            page: pageSchema,
+            size: sizeSchema(10),
+            workspaceName: workspaceNameSchema,
+        }, async (args) => {
+            const { page, size, workspaceName } = args;
+            const api = getOpikApi();
+            const response = await callSdk(() => api.projects.findProjects({ page, size }, getRequestOptions(workspaceName)));
+            if (!response.data) {
+                return {
+                    content: [{ type: 'text', text: response.error || 'Failed to fetch projects' }],
+                };
+            }
             return {
-                content: [{ type: 'text', text: response.error || 'Failed to fetch projects' }],
+                content: [
+                    {
+                        type: 'text',
+                        text: `Found ${response.data.total} projects (page ${response.data.page} of ${Math.ceil(response.data.total / response.data.size)})`,
+                    },
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response.data.content, null, 2),
+                    },
+                ],
             };
-        }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Found ${response.data.total} projects (page ${response.data.page} of ${Math.ceil(response.data.total / response.data.size)})`,
-                },
-                {
-                    type: 'text',
-                    text: JSON.stringify(response.data.content, null, 2),
-                },
-            ],
-        };
-    });
-    server.tool('create-project', 'Create a new project', {
-        name: z.string().min(1).describe('Name of the project'),
-        description: z.string().optional().describe('Description of the project'),
-        workspaceName: z.string().optional().describe('Workspace name to use instead of the default'),
-    }, async (args) => {
-        const { name, description, workspaceName } = args;
-        const requestBody = { name };
-        if (description)
-            requestBody.description = description;
-        const response = await makeApiRequest(`/v1/private/projects`, {
-            method: 'POST',
-            body: JSON.stringify(requestBody),
-        }, workspaceName);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: response.error || 'Successfully created project',
-                },
-            ],
-        };
-    });
+        }, {
+            title: 'List Projects',
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        });
+    }
+    if (includeMutations) {
+        registerTool(server, 'create-project', 'Create a new project for traces, prompts, and evaluation runs.', {
+            name: z.string().min(1).describe('Project name.'),
+            description: z.string().optional().describe('Optional project description.'),
+            workspaceName: workspaceNameSchema,
+        }, async (args) => {
+            const { name, description, workspaceName } = args;
+            const api = getOpikApi();
+            const response = await callSdk(() => api.projects.createProject({
+                name,
+                ...(description && { description }),
+            }, getRequestOptions(workspaceName)));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: response.error || 'Successfully created project',
+                    },
+                ],
+            };
+        }, {
+            title: 'Create Project',
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        });
+    }
     return server;
 };

package/build/tools/prompt.js

@@ -1,16 +1,16 @@
-import { makeApiRequest } from '../utils/api.js';
 import { z } from 'zod';
+import { callSdk, getOpikApi } from '../utils/opik-sdk.js';
+import { registerTool } from './registration.js';
+import { pageSchema, sizeSchema } from './schema.js';
 export const loadPromptTools = (server) => {
-    server.tool('get-prompts', 'Get a list of prompts with optional filtering', {
-        page: z.number().optional().default(1).describe('Page number for pagination'),
-        size: z.number().optional().default(10).describe('Number of items per page'),
-        name: z.string().optional().describe('Filter by prompt name'),
+    registerTool(server, 'get-prompts', 'List prompts with optional name filtering.', {
+        page: pageSchema,
+        size: sizeSchema(10),
+        name: z.string().optional().describe('Optional prompt name filter.'),
     }, async (args) => {
         const { page, size, name } = args;
-        let url = `/v1/private/prompts?page=${page}&size=${size}`;
-        if (name)
-            url += `&name=${encodeURIComponent(name)}`;
-        const response = await makeApiRequest(url);
+        const api = getOpikApi();
+        const response = await callSdk(() => api.prompts.getPrompts({ page, size, name }));
         if (!response.data) {
             return {
                 content: [{ type: 'text', text: response.error || 'Failed to fetch prompts' }],
@@ -29,21 +29,18 @@ export const loadPromptTools = (server) => {
             ],
         };
     });
-    server.tool('create-prompt', 'Create a new prompt', {
-        name: z.string().min(1).describe('Name of the prompt'),
-        description: z.string().optional().describe('Description of the prompt'),
-        tags: z.array(z.string()).optional().describe('List of tags for the prompt'),
+    registerTool(server, 'create-prompt', 'Create a prompt definition.', {
+        name: z.string().min(1).describe('Prompt name.'),
+        description: z.string().optional().describe('Optional prompt description.'),
+        tags: z.array(z.string().min(1)).optional().describe('Optional prompt tags.'),
     }, async (args) => {
         const { name, description, tags } = args;
-        const requestBody = { name };
-        if (description)
-            requestBody.description = description;
-        if (tags)
-            requestBody.tags = tags;
-        const response = await makeApiRequest(`/v1/private/prompts`, {
-            method: 'POST',
-            body: JSON.stringify(requestBody),
-        });
+        const api = getOpikApi();
+        const response = await callSdk(() => api.prompts.createPrompt({
+            name,
+            ...(description && { description }),
+            ...(tags && { metadata: { tags } }),
+        }));
         return {
             content: [
                 {
@@ -53,18 +50,36 @@ export const loadPromptTools = (server) => {
             ],
         };
     });
-    server.tool('get-prompt-version', 'Retrieve a specific version of a prompt', {
-        name: z.string().min(1).describe('Name of the prompt'),
-        commit: z.string().optional().describe('Specific commit/version to retrieve'),
+    registerTool(server, 'get-prompt-by-id', 'Get a prompt by ID.', {
+        promptId: z.string().min(1).describe('Prompt ID.'),
+    }, async (args) => {
+        const { promptId } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.prompts.getPromptById(promptId));
+        if (!response.data) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to fetch prompt' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    });
+    registerTool(server, 'get-prompt-version', 'Get a specific prompt version by name and optional commit.', {
+        name: z.string().min(1).describe('Prompt name.'),
+        commit: z.string().optional().describe('Optional commit/version identifier.'),
     }, async (args) => {
         const { name, commit } = args;
-        const requestBody = { name };
-        if (commit)
-            requestBody.commit = commit;
-        const response = await makeApiRequest(`/v1/private/prompts/versions/retrieve`, {
-            method: 'POST',
-            body: JSON.stringify(requestBody),
-        });
+        const api = getOpikApi();
+        const response = await callSdk(() => api.prompts.retrievePromptVersion({
+            name,
+            ...(commit && { commit }),
+        }));
         if (!response.data) {
             return {
                 content: [{ type: 'text', text: response.error || 'Failed to fetch prompt version' }],
@@ -79,25 +94,49 @@ export const loadPromptTools = (server) => {
             ],
         };
     });
-    server.tool('save-prompt-version', 'Save a new version of a prompt', {
-        name: z.string().min(1).describe('Name of the prompt'),
-        template: z.string().describe('Template content for the prompt version'),
-        change_description: z.string().optional().describe('Description of changes in this version'),
+    registerTool(server, 'delete-prompt', 'Delete a prompt by ID.', {
+        promptId: z.string().min(1).describe('Prompt ID.'),
+    }, async (args) => {
+        const { promptId } = args;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.prompts.deletePrompt(promptId));
+        if (response.error) {
+            return {
+                content: [{ type: 'text', text: response.error || 'Failed to delete prompt' }],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Successfully deleted prompt ${promptId}`,
+                },
+            ],
+        };
+    });
+    registerTool(server, 'save-prompt-version', 'Create a new prompt version.', {
+        name: z.string().min(1).describe('Prompt name.'),
+        template: z.string().min(1).describe('Prompt template body.'),
+        changeDescription: z
+            .string()
+            .optional()
+            .describe('Optional summary of changes in this version.'),
+        change_description: z.string().optional().describe('Deprecated alias for changeDescription.'),
         metadata: z.record(z.any()).optional().describe('Additional metadata for the prompt version'),
-        type: z.enum(['mustache', 'jinja2']).optional().describe('Template type'),
+        type: z.enum(['mustache', 'jinja2']).optional().describe('Template format.'),
     }, async (args) => {
-        const { name, template, change_description, metadata, type } = args;
-        const version = { template };
-        if (change_description)
-            version.change_description = change_description;
-        if (metadata)
-            version.metadata = metadata;
-        if (type)
-            version.type = type;
-        const response = await makeApiRequest(`/v1/private/prompts/versions`, {
-            method: 'POST',
-            body: JSON.stringify({ name, version }),
-        });
+        const { name, template, change_description, changeDescription, metadata, type } = args;
+        const resolvedChangeDescription = changeDescription ?? change_description;
+        const api = getOpikApi();
+        const response = await callSdk(() => api.prompts.createPromptVersion({
+            name,
+            version: {
+                template,
+                ...(resolvedChangeDescription && { changeDescription: resolvedChangeDescription }),
+                ...(metadata && { metadata }),
+                ...(type && { type }),
+            },
+        }));
         if (!response.data) {
             return {
                 content: [{ type: 'text', text: response.error || 'Failed to create prompt version' }],

package/build/tools/registration.js

@@ -0,0 +1,110 @@
+import { runWithRequestContext } from '../utils/request-context.js';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import config from '../config.js';
+const MISSING_API_KEY_MESSAGE = [
+    'This Opik MCP request requires an API key.',
+    'Set OPIK_API_KEY in the environment where the server runs,',
+    'or send Authorization: Bearer <token> with MCP requests.',
+    'If you are onboarding in a coding agent or MCP client, start with setup guidance tools',
+    'like get-opik-help or get-server-info, then add your key and retry.',
+].join(' ');
+function inferAnnotations(name) {
+    const readPrefixes = ['get-', 'list-', 'search-', 'read-'];
+    const mutatePrefixes = ['create-', 'delete-', 'update-', 'add-', 'save-'];
+    if (readPrefixes.some(prefix => name.startsWith(prefix))) {
+        return {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        };
+    }
+    if (mutatePrefixes.some(prefix => name.startsWith(prefix))) {
+        return {
+            readOnlyHint: false,
+            destructiveHint: name.startsWith('delete-'),
+            idempotentHint: false,
+            openWorldHint: false,
+        };
+    }
+    return undefined;
+}
+function withRequestContext(handler, requiresApiKey = true) {
+    return (...args) => {
+        const extra = [...args]
+            .reverse()
+            .find(arg => arg && typeof arg === 'object' && 'authInfo' in arg);
+        const authInfo = extra?.authInfo;
+        const context = {
+            apiKey: authInfo?.token,
+            workspaceName: authInfo?.extra?.workspaceName,
+        };
+        if (requiresApiKey && !(context.apiKey || config.apiKey)) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: MISSING_API_KEY_MESSAGE,
+                    },
+                ],
+            };
+        }
+        return runWithRequestContext(context, () => handler(...args));
+    };
+}
+export function registerTool(server, name, description, inputSchema, handler, options = {}) {
+    const wrappedHandler = withRequestContext(handler, options.requiresApiKey !== false);
+    if (typeof server.registerTool === 'function') {
+        const inferredAnnotations = inferAnnotations(name);
+        const mergedAnnotations = {
+            ...inferredAnnotations,
+            ...options.annotations,
+        };
+        server.registerTool(name, {
+            ...(options.title && { title: options.title }),
+            description,
+            inputSchema,
+            ...(Object.keys(mergedAnnotations).length > 0 && { annotations: mergedAnnotations }),
+            ...(options.outputSchema && { outputSchema: options.outputSchema }),
+            ...(options._meta && { _meta: options._meta }),
+        }, wrappedHandler);
+        return;
+    }
+    server.tool(name, description, inputSchema, wrappedHandler);
+}
+export function registerResource(server, name, uri, description, readCallback) {
+    const wrappedReadCallback = withRequestContext(readCallback);
+    if (typeof server.registerResource === 'function') {
+        server.registerResource(name, uri, {
+            description,
+        }, wrappedReadCallback);
+        return;
+    }
+    server.resource(name, uri, wrappedReadCallback);
+}
+export function registerResourceTemplate(server, name, uriTemplate, description, readCallback, listCallback) {
+    const wrappedReadCallback = withRequestContext(readCallback);
+    const wrappedListCallback = listCallback ? withRequestContext(listCallback) : undefined;
+    const template = new ResourceTemplate(uriTemplate, {
+        list: wrappedListCallback,
+    });
+    if (typeof server.registerResource === 'function') {
+        server.registerResource(name, template, {
+            description,
+        }, wrappedReadCallback);
+        return;
+    }
+    server.resource(name, template, wrappedReadCallback);
+}
+export function registerPrompt(server, name, description, argsSchema, handler, options = {}) {
+    const wrappedHandler = withRequestContext(handler);
+    if (typeof server.registerPrompt === 'function') {
+        server.registerPrompt(name, {
+            ...(options.title && { title: options.title }),
+            description,
+            argsSchema,
+        }, wrappedHandler);
+        return;
+    }
+    server.prompt(name, description, argsSchema, wrappedHandler);
+}

package/build/tools/schema.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export const pageSchema = z.number().int().min(1).default(1).describe('1-based page number.');
+export const sizeSchema = (defaultSize, max = 100) => z.number().int().min(1).max(max).default(defaultSize).describe(`Page size (1-${max}).`);
+export const workspaceNameSchema = z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Workspace override for local/stdio mode. Ignored when remote token-to-workspace mapping is enforced.');
+export const isoDateSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .optional()
+    .describe('Date in YYYY-MM-DD format.');