opik-mcp 2.0.0 → 2.0.2

package/README.md

@@ -1,20 +1,34 @@
+<!--
+  This README is preserved from the v2.0.1 release for historical reference.
+  The authoritative deprecation notice lives in DEPRECATED.md next to this file.
+-->
+
+> ## ⚠️ Deprecated — migrate to the Python server
+>
+> This TypeScript MCP server (npm `opik-mcp`) is **deprecated** and will stop
+> serving MCP requests on **2026-11-15**.
+>
+> In your MCP client config, replace `npx -y opik-mcp` with
+> **`uvx opik-mcp@latest`**.
+> Full migration guide: [`MIGRATION.md`](./MIGRATION.md)
+> · Deprecation policy: [`DEPRECATED.md`](./DEPRECATED.md)
+
 <h1 align="center" style="border-bottom: none">
-    <div>
-        <a href="https://www.comet.com/site/products/opik/?from=llm&utm_source=opik&utm_medium=github&utm_content=header_img&utm_campaign=opik-mcp">
-            <picture>
-                <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/comet-ml/opik-mcp/refs/heads/main/docs/assets/logo-dark-mode.svg">
-                <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/comet-ml/opik-mcp/refs/heads/main/docs/assets/logo-light-mode.svg">
-                <img alt="Comet Opik logo" src="docs/assets/logo-light-mode.svg" width="200" />
-            </picture>
-        </a>
-        <br>
-        Opik MCP Server
-    </div>
-    (Model Context Protocol)<br>
+  <div>
+    <a href="https://www.comet.com/site/products/opik/?from=llm&utm_source=opik&utm_medium=github&utm_content=header_img&utm_campaign=opik-mcp">
+      <picture>
+        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/comet-ml/opik-mcp/refs/heads/main/legacy/typescript/docs/assets/logo-dark-mode.svg">
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/comet-ml/opik-mcp/refs/heads/main/legacy/typescript/docs/assets/logo-light-mode.svg">
+        <img alt="Comet Opik logo" src="docs/assets/logo-light-mode.svg" width="200" />
+      </picture>
+    </a>
+    <br />
+    Opik MCP Server
+  </div>
 </h1>
 
 <p align="center">
-A Model Context Protocol (MCP) implementation for the <a href="https://github.com/comet-ml/opik/">Opik platform</a> with support for multiple transport mechanisms, enabling seamless integration with IDEs and providing a unified interface for Opik's capabilities.
+Model Context Protocol (MCP) server for <a href="https://github.com/comet-ml/opik/">Opik</a>, with both local stdio and remote streamable-http transports.
 </p>
 
 <div align="center">
@@ -22,278 +36,202 @@ A Model Context Protocol (MCP) implementation for the <a href="https://github.co
 [![License](https://img.shields.io/github/license/comet-ml/opik-mcp)](https://github.com/comet-ml/opik-mcp/blob/main/LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.11.0-brightgreen)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/typescript-%5E5.8.2-blue)](https://www.typescriptlang.org/)
-<img src="https://badge.mcpx.dev?status=on" title="MCP Enabled"/>
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15411156.svg)](https://doi.org/10.5281/zenodo.15411156)
+<a href="https://www.comet.com/docs/opik/prompt_engineering/mcp_server"><img src="https://badge.mcpx.dev?status=on" title="MCP Enabled" alt="MCP Enabled" /></a>
+<a href="https://doi.org/10.5281/zenodo.15411156"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.15411156.svg" alt="DOI" /></a>
 
 </div>
 
 <p align="center">
-    <a href="https://www.comet.com/site/products/opik/?from=llm&utm_source=opik&utm_medium=github&utm_content=website_button&utm_campaign=opik"><b>Website</b></a> •
-    <a href="https://chat.comet.com"><b>Slack community</b></a> •
-    <a href="https://x.com/Cometml"><b>Twitter</b></a> •
-    <a href="https://www.comet.com/docs/opik/?from=llm&utm_source=opik&utm_medium=github&utm_content=docs_button&utm_campaign=opik"><b>Documentation</b></a>
+  <a href="https://www.comet.com/site/products/opik/?from=llm&utm_source=opik&utm_medium=github&utm_content=website_button&utm_campaign=opik"><b>Website</b></a> •
+  <a href="https://chat.comet.com"><b>Slack community</b></a> •
+  <a href="https://x.com/Cometml"><b>Twitter</b></a> •
+  <a href="https://www.comet.com/docs/opik/?from=llm&utm_source=opik&utm_medium=github&utm_content=docs_button&utm_campaign=opik"><b>Documentation</b></a>
 </p>
 
-<p align="center">
-    <a href="https://glama.ai/mcp/servers/@comet-ml/opik-mcp" rel="nofollow" target="_blank">
-      <img width="380" height="200" src="https://glama.ai/mcp/servers/@comet-ml/opik-mcp/badge" alt="Opik Server MCP server" />
-    </a>
-</p>
-
-> **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?
+> [!IMPORTANT]
+> This repository ships the MCP server implementation only. We do not currently provide a hosted remote MCP service for Opik.
+> If you run `streamable-http` remotely, authentication is fail-closed by default.
 
-Opik MCP Server is an open-source implementation of the Model Context Protocol for the Opik platform. It provides a unified interface for interacting with Opik's capabilities, supporting multiple transport mechanisms for flexible integration into various environments.
+## Why this server
 
-<br>
+Opik MCP Server gives MCP-compatible clients one interface for:
 
-You can use Opik MCP Server for:
-* **IDE Integration:**
-  * Seamlessly integrate with Cursor, VS Code, Windsurf and other compatible IDEs
-  * Provide direct access to Opik's capabilities from your development environment
+- Prompt lifecycle management
+- Workspace, project, and trace exploration
+- Metrics and dataset operations
+- MCP resources and resource templates for metadata-aware flows
 
-* **Unified API Access:**
-  * Access all Opik features through a standardized protocol
-  * Leverage multiple transport options (stdio, streamable-http) for different integration scenarios
+## Quickstart
 
-* **Platform Management:**
-  * Manage prompts, projects, traces, and metrics through a consistent interface
-  * Organize and monitor your LLM applications efficiently
+### 1. Run with npx
 
-## Features
-
-- **Prompts Management**: Create, list, update, and delete prompts
-- **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
-
-### Installation
-
-#### Cursor Integration
+```bash
+# Opik Cloud
+npx -y opik-mcp --apiKey YOUR_API_KEY
+```
 
-To integrate with Cursor IDE, open to the Cursor settings page and navigate
-to the Features tab. If you scroll down to the MCP section you will see the
-button `+ Add new MCP server` that will allow you to add the Opik MCP server.
+For self-hosted Opik, pass `--apiUrl` (for example `http://localhost:5173/api`) and use your local auth strategy.
 
-Once the `New MCP server` modal is open, select `command` as the server type and
-enter the command: `npx -y opik-mcp --apiKey YOUR_API_KEY`.
+### 2. Add to your MCP client
 
-Alternatively, you can create a `.cursor/mcp.json` in your project and add:
+Cursor (`.cursor/mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "opik": {
       "command": "npx",
-      "args": [
-        "-y",
-        "opik-mcp",
-        "--apiKey",
-        "YOUR_API_KEY"
-      ]
+      "args": ["-y", "opik-mcp", "--apiKey", "YOUR_API_KEY"]
     }
   }
 }
 ```
 
-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:
+VS Code / GitHub Copilot (`.vscode/mcp.json`):
 
 ```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}"
-            ]
-        }
+  "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
-and navigate to the MCP section. From there, click on `View raw config` and update
-the configuration object to be:
+Windsurf (raw config):
 
 ```json
 {
-    "mcpServers": {
-      "opik": {
-        "command": "npx",
-        "args": [
-          "-y",
-          "opik-mcp",
-          "--apiKey",
-          "YOUR_API_KEY"
-        ]
-      }
+  "mcpServers": {
+    "opik": {
+      "command": "npx",
+      "args": ["-y", "opik-mcp", "--apiKey", "YOUR_API_KEY"]
     }
   }
+}
 ```
 
-Note: If you are using the Open-Source version of Opik, you will need to specify
-the `apiBaseUrl` parameter as `http://localhost:5173/api`.
+More client-specific examples: [docs/ide-integration.md](docs/ide-integration.md)
+
+## Run from source
 
-#### Manual Installation
 ```bash
-# Clone the repository
 git clone https://github.com/comet-ml/opik-mcp.git
 cd opik-mcp
-
-# Install dependencies and build
 npm install
 npm run build
 ```
 
-**Configuration**
-
-Create a `.env` file based on the example:
+Optional local config:
 
 ```bash
 cp .env.example .env
-# Edit .env with your specific configuration
 ```
 
-**Starting the Server**
+Start the server:
 
 ```bash
-# Start with stdio transport (default)
 npm run start:stdio
-
-# Start with streamable-http transport for remote/self-hosted access
 npm run start:http
 ```
 
-## Transport Options
+## Transport modes
 
-### Standard Input/Output
+| Transport | Use case | Command |
+| --- | --- | --- |
+| `stdio` | Local MCP integration (same machine as client) | `npm run start:stdio` |
+| `streamable-http` | Remote/self-hosted MCP endpoint (`/mcp`) | `npm run start:http` |
 
-Ideal for local integration where the client and server run on the same machine.
+### Remote auth defaults (`streamable-http`)
 
-```bash
-make start-stdio
-```
+- `Authorization: Bearer <OPIK_API_KEY>` or `x-api-key` is required by default.
+- Workspace is resolved server-side (token map recommended); workspace headers are not trusted by default.
+- In remote mode, request-context workspace takes precedence over tool `workspaceName`.
+- Missing or invalid auth returns HTTP `401`.
 
-### Streamable HTTP
+Key environment flags:
 
-Enables remote/self-hosted MCP over the standard Streamable HTTP endpoint (`/mcp`).
+- `STREAMABLE_HTTP_REQUIRE_AUTH` (default `true`)
+- `STREAMABLE_HTTP_VALIDATE_REMOTE_AUTH` (default `true`, except test env)
+- `REMOTE_TOKEN_WORKSPACE_MAP` (JSON token-to-workspace map)
+- `STREAMABLE_HTTP_TRUST_WORKSPACE_HEADERS` (default `false`)
 
-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`.
+Deep dive: [docs/streamable-http-transport.md](docs/streamable-http-transport.md)
 
-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.
+## Toolsets
 
-```bash
-npm run start:http
-```
+Toolsets let you narrow which capabilities are enabled:
 
-For detailed information about streamable-http transport, see [docs/streamable-http-transport.md](docs/streamable-http-transport.md).
+- `core`
+- `integration`
+- `expert-prompts`
+- `expert-datasets`
+- `expert-trace-actions`
+- `expert-project-actions`
+- `metrics`
+- `all` (enables all modern toolsets)
 
-## Resources and Prompts Capabilities
+Configure via:
 
-- `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`).
+- CLI: `--toolsets all`
+- Env: `OPIK_TOOLSETS=core,expert-prompts,metrics`
 
-## Development
+Details: [docs/configuration.md](docs/configuration.md)
 
-### Testing
+## MCP resources and prompts
 
-```bash
-# Run all tests
-npm test
+- `resources/list` exposes static URIs (for example `opik://workspace-info`)
+- `resources/templates/list` exposes dynamic URI templates (for example `opik://projects/{page}/{size}`)
+- `resources/read` supports static and templated URIs
+- `prompts/list` and `prompts/get` expose workflow prompts
 
-# Run specific test suite
-npm test -- tests/transports/streamable-http-transport.test.ts
-```
+## Development
 
-### Pre-commit Hooks
+```bash
+# Lint
+npm run lint
 
-This project uses pre-commit hooks to ensure code quality:
+# Test
+npm test
 
-```bash
-# Run pre-commit checks manually
+# Build
+npm run build
+
+# Run precommit checks
 make precommit
 ```
 
 ## Documentation
 
-- [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
+- [API Reference](docs/api-reference.md)
+- [Configuration](docs/configuration.md)
+- [IDE Integration](docs/ide-integration.md)
+- [Streamable HTTP Transport](docs/streamable-http-transport.md)
+
+## Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
 
 ## Citation
 
-If you use this project in your research, please cite it as follows:
+If you use this project in research, cite:
 
 ```
 Comet ML, Inc, Koc, V., & Boiko, Y. (2025). Opik MCP Server. Github. https://doi.org/10.5281/zenodo.15411156
 ```
 
-Or use the following BibTeX entry:
+BibTeX:
 
 ```bibtex
 @software{CometML_Opik_MCP_Server_2025,
@@ -306,7 +244,7 @@ Or use the following BibTeX entry:
 }
 ```
 
-You can also find citation information in the `CITATION.cff` file in this repository.
+Citation metadata is also available in [CITATION.cff](CITATION.cff).
 
 ## License
 

package/build/cli.js

@@ -2,6 +2,14 @@
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import configImport from './config.js';
+import { main } from './index.js';
+import { DEPRECATION_NOTICE } from './utils/deprecation.js';
+// Deprecation banner — stderr only, so stdio transport framing stays
+// clean. Note: this does NOT appear on ``--help`` because ``config.ts``
+// runs ``loadConfig()`` at module-load (ESM import ordering) and yargs
+// inside it calls ``process.exit(0)`` on --help before this line ever
+// executes. Accepted limitation — see commit message and OPIK-6713.
+process.stderr.write(`${DEPRECATION_NOTICE.full}\n`);
 // Parse command line arguments
 const argv = yargs(hideBin(process.argv))
     .scriptName('opik-mcp')
@@ -30,5 +38,15 @@ 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';
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+// Start the server after applying CLI overrides.
+main().catch((error) => {
+    const message = toErrorMessage(error);
+    console.error(`Failed to start Opik MCP server: ${message}`);
+    process.exit(1);
+});

package/build/config.js

@@ -58,7 +58,9 @@ const ALL_TOOLSET_CHOICES = [
 ];
 export function normalizeToolsets(values) {
     const normalized = new Set();
-    for (const value of values.flatMap(v => v.split(',')).map(v => v.trim())) {
+    for (const value of values
+        .flatMap((v) => v.split(','))
+        .map((v) => v.trim())) {
         const toolset = value;
         switch (toolset) {
             case 'all':
@@ -116,7 +118,9 @@ function loadOpikConfigFile() {
         for (const line of lines) {
             const trimmedLine = line.trim();
             // Skip empty lines and comments
-            if (!trimmedLine || trimmedLine.startsWith('#') || trimmedLine.startsWith(';')) {
+            if (!trimmedLine ||
+                trimmedLine.startsWith('#') ||
+                trimmedLine.startsWith(';')) {
                 continue;
             }
             // Check for section headers
@@ -253,20 +257,32 @@ export function loadConfig() {
         isSelfHosted: args.selfHosted !== undefined
             ? args.selfHosted
             : process.env.OPIK_SELF_HOSTED === 'true' || false,
-        debugMode: args.debug !== undefined ? args.debug : process.env.DEBUG_MODE === 'true' || false,
+        debugMode: args.debug !== undefined
+            ? args.debug
+            : process.env.DEBUG_MODE === 'true' || false,
         // Transport configuration
         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',
+            (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'),
+            (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 || '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',
+        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',
         // Toolset configuration with fallbacks
         enabledToolsets: (() => {
             // Command line takes precedence

package/build/debug-log.js

@@ -21,8 +21,8 @@ export function initDebugLog() {
     // Log environment variables
     logDebug('Environment Variables:');
     Object.keys(process.env)
-        .filter(key => key.startsWith('OPIK_'))
-        .forEach(key => {
+        .filter((key) => key.startsWith('OPIK_'))
+        .forEach((key) => {
         let value = process.env[key];
         // Mask sensitive information
         if (key === 'OPIK_API_KEY')
@@ -35,7 +35,7 @@ export function initDebugLog() {
         logDebug(`  ${index}: ${arg}`);
     });
     // Set up uncaught exception handler
-    process.on('uncaughtException', error => {
+    process.on('uncaughtException', (error) => {
         logDebug(`UNCAUGHT EXCEPTION: ${error.message}`);
         logDebug(error.stack || 'No stack trace available');
     });
@@ -44,7 +44,7 @@ export function initDebugLog() {
         logDebug(`UNHANDLED REJECTION: ${reason}`);
     });
     // Set up exit handler
-    process.on('exit', code => {
+    process.on('exit', (code) => {
         logDebug(`Process exiting with code: ${code}`);
     });
 }
@@ -52,7 +52,7 @@ export function logDebug(message) {
     const logPath = '/tmp/opik-mcp-debug.log';
     const timestamp = new Date().toISOString();
     const logMessage = `[${timestamp}] ${message}\n`;
-    return new Promise(resolve => {
+    return new Promise((resolve) => {
         try {
             fs.appendFileSync(logPath, logMessage);
         }