opik-mcp 0.1.2 → 2.0.0

package/README.md

@@ -40,7 +40,8 @@ A Model Context Protocol (MCP) implementation for the <a href="https://github.co
     </a>
 </p>
 
-> **⚠️ Notice:** SSE (Server-Sent Events) transport support is currently experimental and untested. For production use, we recommend using the direct process execution approach shown in the IDE integration examples.
+> **Note:** This repository provides the MCP server implementation. We do not currently provide a hosted remote MCP service for Opik.
+> If you run streamable-http remotely, authentication is fail-closed by default.
 
 ## 🚀 What is Opik MCP Server?
 
@@ -50,12 +51,12 @@ Opik MCP Server is an open-source implementation of the Model Context Protocol f
 
 You can use Opik MCP Server for:
 * **IDE Integration:**
-  * Seamlessly integrate with Cursor and other compatible IDEs
+  * Seamlessly integrate with Cursor, VS Code, Windsurf and other compatible IDEs
   * Provide direct access to Opik's capabilities from your development environment
 
 * **Unified API Access:**
   * Access all Opik features through a standardized protocol
-  * Leverage multiple transport options (stdio, SSE) for different integration scenarios
+  * Leverage multiple transport options (stdio, streamable-http) for different integration scenarios
 
 * **Platform Management:**
   * Manage prompts, projects, traces, and metrics through a consistent interface
@@ -67,6 +68,7 @@ You can use Opik MCP Server for:
 - **Projects/Workspaces Management**: Organize and manage projects
 - **Traces**: Track and analyze trace data
 - **Metrics**: Gather and query metrics data
+- **MCP Resources**: Read-only resources for workspace/project metadata plus resource templates for prompts, datasets, and traces
 
 ## Quick Start
 
@@ -102,6 +104,65 @@ Alternatively, you can create a `.cursor/mcp.json` in your project and add:
 Note: If you are using the Open-Source version of Opik, you will need to specify
 the `apiBaseUrl` parameter as `http://localhost:5173/api`.
 
+#### VS Code Integration (GitHub Copilot)
+
+To integrate Opik with VS Code (GitHub Copilot), you need to add the MCP server
+configuration to your workspace or user settings.
+
+1. Create or open the `.vscode/mcp.json` file in your workspace (or run the
+   **MCP: Open User Configuration** command to add it globally).
+
+2. Add the Opik MCP server configuration:
+
+```json
+{
+    "inputs": [
+        {
+            "type": "promptString",
+            "id": "opik-api-key",
+            "description": "Opik API Key",
+            "password": true
+        }
+    ],
+    "servers": {
+        "opik-mcp": {
+            "type": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "opik-mcp",
+                "--apiKey",
+                "${input:opik-api-key}"
+            ]
+        }
+    }
+}
+```
+
+3. When you start the MCP server for the first time, VS Code will prompt you
+   to enter your Opik API key. The value is securely stored for subsequent use.
+
+Note: If you are using the Open-Source version of Opik, add the `--apiBaseUrl`
+argument and remove the `--apiKey` argument:
+
+```json
+{
+    "servers": {
+        "opik-mcp": {
+            "type": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "opik-mcp",
+                "--apiBaseUrl",
+                "http://localhost:5173/api"
+            ]
+        }
+    },
+    "inputs": []
+}
+```
+
 #### Windsurf Installation
 
 To install the MCP server in Windsurf, you will need to open the Windsurf settings
@@ -153,8 +214,8 @@ cp .env.example .env
 # Start with stdio transport (default)
 npm run start:stdio
 
-# Start with SSE transport for network access (experimental)
-npm run start:sse
+# Start with streamable-http transport for remote/self-hosted access
+npm run start:http
 ```
 
 ## Transport Options
@@ -167,15 +228,34 @@ Ideal for local integration where the client and server run on the same machine.
 make start-stdio
 ```
 
-### Server-Sent Events (SSE)
+### Streamable HTTP
+
+Enables remote/self-hosted MCP over the standard Streamable HTTP endpoint (`/mcp`).
+
+Remote auth behavior:
+- `Authorization: Bearer <OPIK_API_KEY>` or `x-api-key` is required by default.
+- Workspace is resolved server-side (recommended via token mapping). Header workspaces are not trusted by default.
+- In remote mode, request-context workspace takes precedence over tool `workspaceName` args.
+- Missing/invalid auth returns HTTP `401`.
 
-Enables remote access and multiple simultaneous clients over HTTP. Note that this transport option is experimental.
+Remote auth environment flags:
+- `STREAMABLE_HTTP_REQUIRE_AUTH` (default `true`): require auth headers on `/mcp`.
+- `STREAMABLE_HTTP_VALIDATE_REMOTE_AUTH` (default `true`, except test env): validate bearer/API key against Opik before accepting requests.
+- `REMOTE_TOKEN_WORKSPACE_MAP`: JSON map of token -> workspace for server-side tenant routing.
+- `STREAMABLE_HTTP_TRUST_WORKSPACE_HEADERS` (default `false`): allow workspace headers when token map is not configured.
 
 ```bash
-make start-sse
+npm run start:http
 ```
 
-For detailed information about the SSE transport, see [docs/sse-transport.md](docs/sse-transport.md).
+For detailed information about streamable-http transport, see [docs/streamable-http-transport.md](docs/streamable-http-transport.md).
+
+## Resources and Prompts Capabilities
+
+- `resources/list` exposes static resources (for example, `opik://workspace-info`, `opik://projects-list`).
+- `resources/templates/list` exposes dynamic URI templates (for example, `opik://projects/{page}/{size}`, `opik://prompt/{name}`).
+- `resources/read` supports both static URIs and filled template URIs.
+- `prompts/list` and `prompts/get` expose workflow prompts (for example, `opik-triage-workflow`).
 
 ## Development
 
@@ -186,7 +266,7 @@ For detailed information about the SSE transport, see [docs/sse-transport.md](do
 npm test
 
 # Run specific test suite
-npm test -- tests/transports/sse-transport.test.ts
+npm test -- tests/transports/streamable-http-transport.test.ts
 ```
 
 ### Pre-commit Hooks
@@ -200,7 +280,7 @@ make precommit
 
 ## Documentation
 
-- [SSE Transport](docs/sse-transport.md) - Details on using the SSE transport
+- [Streamable HTTP Transport](docs/streamable-http-transport.md) - Details on remote transport
 - [API Reference](docs/api-reference.md) - Complete API documentation
 - [Configuration](docs/configuration.md) - Advanced configuration options
 - [IDE Integration](docs/ide-integration.md) - Integration with Cursor IDE

package/build/cli.js

@@ -8,25 +8,27 @@ const argv = yargs(hideBin(process.argv))
     .usage('$0 [args]')
     .option('transport', {
     alias: 't',
-    description: 'Transport to use (stdio or sse)',
+    description: 'Transport to use (stdio or streamable-http)',
     type: 'string',
-    default: 'stdio',
-    choices: ['stdio', 'sse'],
+    choices: ['stdio', 'streamable-http'],
 })
     .option('port', {
     alias: 'p',
-    description: 'Port to listen on (for sse transport)',
+    description: 'Port to listen on (for streamable-http transport)',
     type: 'number',
-    default: 3001,
 })
     .help()
     .alias('help', 'h')
     .strict(false) // Allow unknown options
     .parseSync();
 // Update config based on CLI arguments
-configImport.transport = argv.transport;
-if (argv.transport === 'sse') {
-    configImport.ssePort = argv.port;
+if (argv.transport) {
+    configImport.transport = argv.transport;
+    process.env.TRANSPORT = argv.transport;
+}
+if (argv.transport === 'streamable-http' && typeof argv.port === 'number') {
+    configImport.streamableHttpPort = argv.port;
+    process.env.STREAMABLE_HTTP_PORT = String(argv.port);
 }
 // Import and start the server (index.js will handle the main() call)
 import './index.js';

package/build/config.js

@@ -31,7 +31,74 @@ function writeToLogFile(message, forceWrite = false) {
         // Silently fail if we can't write to the log file
     }
 }
-export const DEFAULT_TOOLSETS = ['integration', 'prompts', 'projects', 'traces'];
+export const DEFAULT_TOOLSETS = ['core'];
+export const ALL_TOOLSETS = [
+    'core',
+    'expert-prompts',
+    'expert-datasets',
+    'expert-trace-actions',
+    'expert-project-actions',
+    'integration',
+    'metrics',
+];
+const ALL_TOOLSET_CHOICES = [
+    'all',
+    'core',
+    'expert-prompts',
+    'expert-datasets',
+    'expert-trace-actions',
+    'expert-project-actions',
+    'integration',
+    'metrics',
+    'capabilities',
+    'prompts',
+    'datasets',
+    'projects',
+    'traces',
+];
+export function normalizeToolsets(values) {
+    const normalized = new Set();
+    for (const value of values.flatMap(v => v.split(',')).map(v => v.trim())) {
+        const toolset = value;
+        switch (toolset) {
+            case 'all':
+                for (const item of ALL_TOOLSETS) {
+                    normalized.add(item);
+                }
+                break;
+            case 'core':
+            case 'expert-prompts':
+            case 'expert-datasets':
+            case 'expert-trace-actions':
+            case 'expert-project-actions':
+            case 'integration':
+            case 'metrics':
+                normalized.add(toolset);
+                break;
+            // Legacy aliases
+            case 'capabilities':
+                normalized.add('core');
+                break;
+            case 'prompts':
+                normalized.add('expert-prompts');
+                break;
+            case 'datasets':
+                normalized.add('expert-datasets');
+                break;
+            case 'projects':
+                normalized.add('core');
+                normalized.add('expert-project-actions');
+                break;
+            case 'traces':
+                normalized.add('core');
+                normalized.add('expert-trace-actions');
+                break;
+            default:
+                break;
+        }
+    }
+    return Array.from(normalized);
+}
 /**
  * Load configuration from ~/.opik.config file
  */
@@ -78,7 +145,7 @@ function loadOpikConfigFile() {
                 }
             }
         }
-        writeToLogFile(`Loaded config from ~/.opik.config: ${JSON.stringify(config)}`);
+        writeToLogFile(`Loaded config from ~/.opik.config with keys: ${Object.keys(config).join(', ') || '(none)'}`);
         return config;
     }
     catch (error) {
@@ -118,24 +185,20 @@ function parseCommandLineArgs() {
         // Transport Configuration
         .option('transport', {
         type: 'string',
-        description: 'Transport type (stdio or sse)',
-        choices: ['stdio', 'sse'],
-        default: 'stdio',
+        description: 'Transport type (stdio or streamable-http)',
+        choices: ['stdio', 'streamable-http'],
     })
-        .option('ssePort', {
+        .option('streamableHttpPort', {
         type: 'number',
-        description: 'Port for SSE transport',
-        default: 3001,
+        description: 'Port for streamable-http transport',
     })
-        .option('sseHost', {
+        .option('streamableHttpHost', {
         type: 'string',
-        description: 'Host for SSE transport',
-        default: 'localhost',
+        description: 'Host for streamable-http transport',
     })
-        .option('sseLogPath', {
+        .option('streamableHttpLogPath', {
         type: 'string',
-        description: 'Log file path for SSE transport',
-        default: '/tmp/opik-mcp-sse.log',
+        description: 'Log file path for streamable-http transport',
     })
         // MCP Configuration
         .option('mcpName', {
@@ -162,7 +225,7 @@ function parseCommandLineArgs() {
         .option('toolsets', {
         type: 'array',
         description: 'Comma-separated list of toolsets to enable',
-        choices: ['capabilities', 'integration', 'prompts', 'projects', 'traces', 'metrics'],
+        choices: ALL_TOOLSET_CHOICES,
     })
         .help()
         .parse();
@@ -192,13 +255,15 @@ export function loadConfig() {
             : process.env.OPIK_SELF_HOSTED === 'true' || false,
         debugMode: args.debug !== undefined ? args.debug : process.env.DEBUG_MODE === 'true' || false,
         // Transport configuration
-        transport: (args.transport || process.env.TRANSPORT || 'stdio'),
-        ssePort: args.ssePort || (process.env.SSE_PORT ? parseInt(process.env.SSE_PORT, 10) : 3001),
-        sseHost: args.sseHost || process.env.SSE_HOST || 'localhost',
-        sseLogPath: args.sseLogPath || process.env.SSE_LOG_PATH || '/tmp/opik-mcp-sse.log',
+        transport: (args.transport ?? process.env.TRANSPORT ?? 'stdio'),
+        streamableHttpPort: args.streamableHttpPort ??
+            (process.env.STREAMABLE_HTTP_PORT ? parseInt(process.env.STREAMABLE_HTTP_PORT, 10) : 3001),
+        streamableHttpHost: args.streamableHttpHost ?? process.env.STREAMABLE_HTTP_HOST ?? '127.0.0.1',
+        streamableHttpLogPath: args.streamableHttpLogPath ??
+            (process.env.STREAMABLE_HTTP_LOG_PATH || '/tmp/opik-mcp-streamable-http.log'),
         // MCP configuration with fallbacks
         mcpName: args.mcpName || process.env.MCP_NAME || 'opik-manager',
-        mcpVersion: args.mcpVersion || process.env.MCP_VERSION || '1.0.0',
+        mcpVersion: args.mcpVersion || process.env.MCP_VERSION || '2.0.0',
         mcpPort: args.mcpPort || (process.env.MCP_PORT ? parseInt(process.env.MCP_PORT, 10) : undefined),
         mcpLogging: args.mcpLogging !== undefined ? args.mcpLogging : process.env.MCP_LOGGING === 'true' || false,
         mcpDefaultWorkspace: args.mcpDefaultWorkspace || process.env.MCP_DEFAULT_WORKSPACE || 'default',
@@ -206,12 +271,11 @@ export function loadConfig() {
         enabledToolsets: (() => {
             // Command line takes precedence
             if (args.toolsets && args.toolsets.length > 0) {
-                return args.toolsets.filter((t) => ['integration', 'prompts', 'projects', 'traces', 'metrics'].includes(t));
+                return normalizeToolsets(args.toolsets);
             }
             // Environment variable fallback
             if (process.env.OPIK_TOOLSETS) {
-                const envToolsets = process.env.OPIK_TOOLSETS.split(',').map(t => t.trim());
-                return envToolsets.filter((t) => ['integration', 'prompts', 'projects', 'traces', 'metrics'].includes(t));
+                return normalizeToolsets(process.env.OPIK_TOOLSETS.split(','));
             }
             // Default toolsets
             return DEFAULT_TOOLSETS;
@@ -244,10 +308,10 @@ export function loadConfig() {
         // Log transport configuration
         writeToLogFile('\nTransport Configuration:');
         writeToLogFile(`- Transport: ${config.transport}`);
-        if (config.transport === 'sse') {
-            writeToLogFile(`- SSE Port: ${config.ssePort}`);
-            writeToLogFile(`- SSE Host: ${config.sseHost}`);
-            writeToLogFile(`- SSE Log Path: ${config.sseLogPath}`);
+        if (config.transport === 'streamable-http') {
+            writeToLogFile(`- Streamable HTTP Port: ${config.streamableHttpPort}`);
+            writeToLogFile(`- Streamable HTTP Host: ${config.streamableHttpHost}`);
+            writeToLogFile(`- Streamable HTTP Log Path: ${config.streamableHttpLogPath}`);
         }
         // Log MCP configuration
         writeToLogFile('\nMCP Configuration:');

package/build/index.js

@@ -2,9 +2,8 @@ import fs from 'fs';
 // Import other modules
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { makeApiRequest } from './utils/api.js';
 // Import custom transports
-import { SSEServerTransport } from './transports/sse-transport.js';
+import { StreamableHttpTransport } from './transports/streamable-http-transport.js';
 // Import environment variables loader - no console output
 import './utils/env.js';
 import { logToFile, logFile } from './utils/logging.js';
@@ -14,9 +13,19 @@ import { loadPromptTools } from './tools/prompt.js';
 import { loadProjectTools } from './tools/project.js';
 import { loadMetricTools } from './tools/metrics.js';
 import { loadIntegrationTools } from './tools/integration.js';
+import { loadCapabilitiesTools } from './tools/capabilities.js';
+import { loadDatasetTools } from './tools/dataset.js';
+import { loadCorePrompts } from './prompts/core-prompts.js';
+import { loadOpikResources } from './resources/opik-resources.js';
 // Import configuration
 import { loadConfig } from './config.js';
 const config = loadConfig();
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
 // Only initialize log file if debug mode is enabled
 if (config.debugMode) {
     try {
@@ -53,90 +62,57 @@ export let server = new McpServer({
 });
 // Load tools based on enabled toolsets
 logToFile(`Loading toolsets: ${config.enabledToolsets.join(', ')}`);
-if (config.enabledToolsets.includes('integration')) {
+const enabledToolsets = new Set(config.enabledToolsets);
+if (enabledToolsets.has('integration')) {
     server = loadIntegrationTools(server);
     logToFile('Loaded integration toolset');
 }
-if (config.enabledToolsets.includes('prompts')) {
+if (enabledToolsets.has('core')) {
+    server = loadCapabilitiesTools(server, config);
+    logToFile('Loaded core capabilities tools');
+    server = loadCorePrompts(server);
+    logToFile('Loaded core prompts');
+    server = loadProjectTools(server, { includeReadOps: true, includeMutations: false });
+    logToFile('Loaded core project read tools');
+    server = loadTraceTools(server, { includeCoreTools: true, includeExpertActions: false });
+    logToFile('Loaded core trace tools');
+}
+if (enabledToolsets.has('expert-prompts')) {
     server = loadPromptTools(server);
-    logToFile('Loaded prompts toolset');
+    logToFile('Loaded expert prompts toolset');
 }
-if (config.enabledToolsets.includes('projects')) {
-    server = loadProjectTools(server);
-    logToFile('Loaded projects toolset');
+if (enabledToolsets.has('expert-datasets')) {
+    server = loadDatasetTools(server);
+    logToFile('Loaded expert datasets toolset');
 }
-if (config.enabledToolsets.includes('traces')) {
-    server = loadTraceTools(server);
-    logToFile('Loaded traces toolset');
+if (enabledToolsets.has('expert-project-actions')) {
+    server = loadProjectTools(server, { includeReadOps: false, includeMutations: true });
+    logToFile('Loaded expert project actions toolset');
 }
-if (config.enabledToolsets.includes('metrics')) {
+if (enabledToolsets.has('expert-trace-actions')) {
+    server = loadTraceTools(server, { includeCoreTools: false, includeExpertActions: true });
+    logToFile('Loaded expert trace actions toolset');
+}
+if (enabledToolsets.has('metrics')) {
     server = loadMetricTools(server);
     logToFile('Loaded metrics toolset');
 }
 // Add resources to the MCP server
-if (config.workspaceName) {
-    // Define a workspace info resource
-    server.resource('workspace-info', 'opik://workspace-info', async () => ({
-        contents: [
-            {
-                uri: 'opik://workspace-info',
-                text: JSON.stringify({
-                    name: config.workspaceName,
-                    apiUrl: config.apiBaseUrl,
-                    selfHosted: config.isSelfHosted,
-                }, null, 2),
-            },
-        ],
-    }));
-    // Define a projects resource that provides the list of projects in the workspace
-    server.resource('projects-list', 'opik://projects-list', async () => {
-        try {
-            const response = await makeApiRequest('/v1/private/projects');
-            if (!response.data) {
-                return {
-                    contents: [
-                        {
-                            uri: 'opik://projects-list',
-                            text: `Error: ${response.error || 'Unknown error fetching projects'}`,
-                        },
-                    ],
-                };
-            }
-            return {
-                contents: [
-                    {
-                        uri: 'opik://projects-list',
-                        text: JSON.stringify(response.data, null, 2),
-                    },
-                ],
-            };
-        }
-        catch (error) {
-            logToFile(`Error fetching projects resource: ${error}`);
-            return {
-                contents: [
-                    {
-                        uri: 'opik://projects-list',
-                        text: `Error: Failed to fetch projects data`,
-                    },
-                ],
-            };
-        }
-    });
-}
+server = loadOpikResources(server, config);
 // ----------- SERVER CONFIGURATION TOOLS -----------
 // Main function to start the server
 export async function main() {
     logToFile('Starting main function');
     // Create the appropriate transport based on configuration
     let transport;
-    if (config.transport === 'sse') {
-        logToFile(`Creating SSEServerTransport on port ${config.ssePort}`);
-        transport = new SSEServerTransport({
-            port: config.ssePort || 3001,
+    if (config.transport === 'streamable-http') {
+        logToFile(`Creating Streamable HTTP transport on port ${config.streamableHttpPort}`);
+        transport = new StreamableHttpTransport({
+            port: config.streamableHttpPort || 3001,
+            host: config.streamableHttpHost || '127.0.0.1',
         });
-        // Explicitly start the SSE transport
-        logToFile('Starting SSE transport');
+        // Explicitly start the remote transport host
+        logToFile('Starting remote transport');
         await transport.start();
     }
     else {
@@ -145,23 +121,27 @@ export async function main() {
     }
     // Connect the server to the transport
     logToFile('Connecting server to transport');
-    server.connect(transport);
+    await server.connect(transport);
     logToFile('Transport connection established');
     // Log server status
-    if (config.transport === 'sse') {
-        logToFile(`Opik MCP Server running on SSE (port ${config.ssePort})`);
+    if (config.transport === 'streamable-http') {
+        logToFile(`Opik MCP Server running on Streamable HTTP (port ${config.streamableHttpPort})`);
     }
     else {
         logToFile('Opik MCP Server running on stdio');
     }
     logToFile('Main function completed successfully');
-    // Start heartbeat for keeping the process alive
-    setInterval(() => {
-        logToFile('Heartbeat ping');
-    }, 5000);
 }
 // Start the server
 main().catch(error => {
-    logToFile(`Error starting server: ${error}`);
+    const message = toErrorMessage(error);
+    logToFile(`Error starting server: ${message}`);
+    console.error(`Failed to start Opik MCP server: ${message}`);
+    if (error instanceof Error && error.stack) {
+        logToFile(error.stack);
+        if (config.debugMode) {
+            console.error(error.stack);
+        }
+    }
     process.exit(1);
 });

package/build/prompts/core-prompts.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { registerPrompt } from '../tools/registration.js';
+export function loadCorePrompts(server) {
+    registerPrompt(server, 'opik-triage-workflow', 'Guide for selecting the right Opik MCP toolset and first actions.', {
+        goal: z.string().describe('User goal to accomplish with Opik.'),
+        scope: z
+            .enum(['core', 'prompts', 'datasets', 'traces', 'projects', 'metrics'])
+            .default('core')
+            .describe('Primary domain for this task.'),
+    }, async ({ goal, scope }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        'You are operating the Opik MCP server.',
+                        `Goal: ${goal}`,
+                        `Scope: ${scope}`,
+                        'First, call get-server-info.',
+                        'Then propose a short 3-step action plan and execute only read operations before mutations.',
+                        'When mutating, confirm target IDs from read results.',
+                    ].join('\n'),
+                },
+            },
+        ],
+    }), { title: 'Opik Workflow Triage' });
+    registerPrompt(server, 'opik-dataset-maintenance', 'Workflow template for dataset curation and quality checks.', {
+        datasetName: z.string().describe('Dataset name to inspect or curate.'),
+        objective: z
+            .string()
+            .default('Find low-quality items and produce cleanup actions.')
+            .describe('Dataset maintenance objective.'),
+    }, async ({ datasetName, objective }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        `Dataset: ${datasetName}`,
+                        `Objective: ${objective}`,
+                        'Use list-datasets to locate the dataset ID.',
+                        'Use list-dataset-items with pagination to inspect records.',
+                        'Return a concise cleanup plan with explicit item IDs before delete-dataset-item.',
+                    ].join('\n'),
+                },
+            },
+        ],
+    }), { title: 'Dataset Maintenance' });
+    return server;
+}