opik-mcp 0.0.1

package/build/transports/sse-transport.js

@@ -0,0 +1,169 @@
+import express from 'express';
+import http from 'http';
+import fs from 'fs';
+import cors from 'cors';
+// Setup file-based logging
+const logFile = '/tmp/opik-mcp-sse.log';
+function logToFile(message) {
+    try {
+        const timestamp = new Date().toISOString();
+        fs.appendFileSync(logFile, `[${timestamp}] ${message}\n`);
+    }
+    catch (error) {
+        // Silently fail if we can't write to the log file
+    }
+}
+/**
+ * SSE (Server-Sent Events) transport for the MCP server
+ * This allows the server to be accessed over a network connection
+ * with a simple unidirectional streaming protocol
+ */
+export class SSEServerTransport {
+    app = express();
+    server = null;
+    port;
+    clients = new Map();
+    started = false;
+    onclose;
+    onerror;
+    onmessage;
+    constructor(options = {}) {
+        this.port = options.port || 3001;
+        // Setup Express server
+        this.app.use(cors());
+        this.app.use(express.json());
+        // Add health check endpoint
+        this.app.get('/health', (req, res) => {
+            const response = { status: 'ok' };
+            res.json(response);
+        });
+        // SSE endpoint for receiving MCP messages
+        this.app.get('/events', (req, res) => {
+            const clientId = req.query.clientId || Date.now().toString();
+            // Set headers for SSE
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+            });
+            // Send a welcome message
+            res.write(`data: ${JSON.stringify({ type: 'connection', clientId })}\n\n`);
+            // Add client to the list
+            this.clients.set(clientId, res);
+            logToFile(`SSE client connected: ${clientId}`);
+            // Handle client disconnect
+            req.on('close', () => {
+                this.clients.delete(clientId);
+                logToFile(`SSE client disconnected: ${clientId}`);
+            });
+        });
+        // Endpoint for sending messages to the MCP server
+        this.app.post('/send', (req, res) => {
+            const message = req.body;
+            if (this.onmessage) {
+                try {
+                    // Forward the message to the MCP connection handler
+                    this.onmessage(message);
+                    const response = { status: 'success' };
+                    res.status(200).json(response);
+                }
+                catch (error) {
+                    logToFile(`Error handling message: ${error}`);
+                    if (this.onerror) {
+                        this.onerror(error instanceof Error ? error : new Error(String(error)));
+                    }
+                    const errorResponse = {
+                        status: 'error',
+                        message: String(error),
+                    };
+                    res.status(500).json(errorResponse);
+                }
+            }
+            else {
+                const errorResponse = {
+                    status: 'error',
+                    message: 'Server not ready',
+                };
+                res.status(503).json(errorResponse);
+            }
+        });
+        // Create HTTP server
+        this.server = http.createServer(this.app);
+    }
+    /**
+     * Start listening for connections
+     */
+    async start() {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        return new Promise(resolve => {
+            if (!this.server) {
+                this.server = http.createServer(this.app);
+            }
+            this.server.listen(this.port, () => {
+                logToFile(`SSE transport listening on port ${this.port}`);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Send a message to all connected clients
+     */
+    async send(message) {
+        const messageStr = JSON.stringify(message);
+        // Broadcast the message to all connected clients
+        for (const [clientId, client] of this.clients.entries()) {
+            try {
+                client.write(`data: ${messageStr}\n\n`);
+            }
+            catch (error) {
+                logToFile(`Error sending message to client ${clientId}: ${error}`);
+                // Remove client if we can't send messages to it
+                this.clients.delete(clientId);
+            }
+        }
+    }
+    /**
+     * Close the transport
+     */
+    async close() {
+        if (!this.started) {
+            return;
+        }
+        this.started = false;
+        return new Promise((resolve, reject) => {
+            // Close all SSE connections
+            for (const [clientId, client] of this.clients.entries()) {
+                try {
+                    client.end();
+                }
+                catch (error) {
+                    logToFile(`Error closing connection to client ${clientId}: ${error}`);
+                }
+            }
+            // Clear the clients map
+            this.clients.clear();
+            // Close the HTTP server
+            if (this.server) {
+                this.server.close(err => {
+                    if (err) {
+                        logToFile(`Error closing SSE server: ${err}`);
+                        reject(err);
+                    }
+                    else {
+                        logToFile('SSE transport stopped');
+                        if (this.onclose)
+                            this.onclose();
+                        resolve();
+                    }
+                });
+                this.server = null;
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+}

package/build/transports/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for the transport layer of the MCP server
+ */
+export {};

package/build/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for the Opik API
+ */
+export {};

package/build/utils/capabilities.js

@@ -0,0 +1,303 @@
+/**
+ * Opik Comet API Capabilities
+ *
+ * This file defines the capabilities of the Opik Comet API to provide
+ * better context to the MCP about what it can and cannot do.
+ * Based on official Opik documentation: https://www.comet.com/docs/opik/
+ */
+/**
+ * Detailed capabilities of the Opik Comet API
+ * Based on official documentation: https://www.comet.com/docs/opik/
+ */
+export const opikCapabilities = {
+    prompts: {
+        available: true,
+        features: [
+            'Create and manage prompt templates',
+            'Version control for prompts',
+            'Prompt playground for testing different prompts and models',
+            'Managing prompts in code with the Python SDK',
+            'Retrieve prompt history',
+            'Update existing prompts',
+            'Delete prompts',
+        ],
+        limitations: [
+            'Limited prompt template variables support',
+            'No automatic prompt optimization',
+            'No A/B testing capabilities built-in',
+            'No automatic prompt performance metrics',
+        ],
+        examples: [
+            'Creating a prompt template for a specific use case',
+            'Versioning prompts to track changes over time',
+            'Testing different prompt variations in the playground',
+            'Managing prompts programmatically with the SDK',
+        ],
+        versionControl: true,
+        templateFormat: 'String with variable placeholders using {{variable}} syntax',
+        schema: {
+            prompt: {
+                id: 'string',
+                name: 'string',
+                description: 'string',
+                created_at: 'timestamp',
+                created_by: 'string',
+                last_updated_at: 'timestamp',
+                last_updated_by: 'string',
+                version_count: 'number',
+            },
+            promptVersion: {
+                id: 'string',
+                prompt_id: 'string',
+                version: 'number',
+                template: 'string',
+                created_at: 'timestamp',
+                created_by: 'string',
+                commit_message: 'string',
+            },
+        },
+    },
+    projects: {
+        available: true,
+        features: [
+            'Create and manage projects/workspaces',
+            'Organize traces by project',
+            'Project-level metrics and statistics',
+            'Update project metadata',
+            'Delete projects',
+            'Monitoring dashboards for projects',
+        ],
+        limitations: [
+            'No nested project hierarchies',
+            'Limited project sharing or collaboration features',
+            'No project templates or cloning',
+            'Limited metadata customization',
+        ],
+        examples: [
+            'Creating a project for a specific AI application',
+            'Organizing traces by customer or use case',
+            'Tracking metrics across different projects',
+            'Setting up monitoring dashboards for a project',
+        ],
+        hierarchySupport: false,
+        sharingSupport: false,
+        schema: {
+            project: {
+                id: 'string',
+                name: 'string',
+                description: 'string',
+                created_at: 'timestamp',
+                created_by: 'string',
+                last_updated_at: 'timestamp',
+                last_updated_by: 'string',
+                workspace: 'string',
+            },
+        },
+    },
+    traces: {
+        available: true,
+        features: [
+            'Record and retrieve LLM interactions (traces)',
+            'Log conversations and agent interactions',
+            'Log multimodal traces',
+            'Log distributed traces',
+            'Annotate traces with feedback scores',
+            'Track token usage and costs',
+            'Filter traces by project',
+            'Aggregate trace statistics',
+            'View trace metadata',
+            'Track latency and performance',
+            'Export trace data',
+            'OpenTelemetry integration',
+        ],
+        limitations: [
+            'No real-time trace streaming',
+            'Limited search capabilities within trace content',
+            'No built-in trace comparison tools',
+            'Limited custom trace tagging system',
+        ],
+        examples: [
+            'Recording a conversation with an AI assistant',
+            'Logging agent interactions in a complex workflow',
+            'Tracking distributed traces across multiple services',
+            'Annotating traces with feedback scores',
+            'Analyzing token usage patterns',
+            'Tracking costs across different models',
+        ],
+        dataRetention: 'Configurable, default varies by deployment',
+        searchCapabilities: [
+            'Filter by project',
+            'Filter by date range',
+            'Filter by trace name',
+            'Filter by trace type',
+            'Basic text search in trace names',
+        ],
+        filterOptions: ['project_id', 'project_name', 'start_date', 'end_date', 'name', 'type'],
+        schema: {
+            trace: {
+                id: 'string',
+                project_id: 'string',
+                name: 'string',
+                start_time: 'timestamp',
+                end_time: 'timestamp',
+                input: 'object',
+                output: 'object',
+                metadata: 'object',
+                usage: {
+                    completion_tokens: 'number',
+                    prompt_tokens: 'number',
+                    total_tokens: 'number',
+                },
+                created_at: 'timestamp',
+                last_updated_at: 'timestamp',
+                created_by: 'string',
+                last_updated_by: 'string',
+                total_estimated_cost: 'number',
+                duration: 'number',
+                tags: 'string[]',
+                spans: 'array',
+            },
+            span: {
+                id: 'string',
+                trace_id: 'string',
+                name: 'string',
+                type: 'string',
+                start_time: 'timestamp',
+                end_time: 'timestamp',
+                input: 'object',
+                output: 'object',
+                metadata: 'object',
+                usage: 'object',
+                duration: 'number',
+            },
+        },
+    },
+    metrics: {
+        available: true,
+        features: [
+            'Track token usage over time',
+            'Monitor costs and usage patterns',
+            'Filter metrics by project',
+            'Date range filtering',
+            'Aggregate metrics by day/week/month',
+            'LLM evaluation metrics (heuristic and LLM-as-judge)',
+            'Evaluation metrics for hallucination detection',
+            'Evaluation metrics for RAG evaluation',
+            'Evaluation metrics for moderation',
+            'Production monitoring dashboards',
+            'Rules and alerts for metrics',
+        ],
+        limitations: [
+            'Limited custom metric definitions',
+            'Limited visualization options through API',
+            'No real-time metrics streaming',
+            'Limited alerting capabilities',
+            'Limited export functionality',
+        ],
+        examples: [
+            'Tracking monthly token usage',
+            'Monitoring cost trends over time',
+            'Evaluating LLM outputs for hallucinations',
+            'Measuring RAG performance with context precision/recall',
+            'Setting up production monitoring dashboards',
+            'Creating rules for metric thresholds',
+        ],
+        availableMetrics: [
+            'total_tokens',
+            'prompt_tokens',
+            'completion_tokens',
+            'cost',
+            'latency',
+            'requests_count',
+            'error_rate',
+            'hallucination_score',
+            'answer_relevance',
+            'context_precision',
+            'context_recall',
+            'moderation_score',
+        ],
+        customMetricsSupport: true,
+        visualizationSupport: true,
+        schema: {
+            metric: {
+                name: 'string',
+                description: 'string',
+                value: 'number',
+                unit: 'string',
+                timestamp: 'timestamp',
+                project_id: 'string',
+            },
+            evaluation: {
+                id: 'string',
+                name: 'string',
+                metric: 'string',
+                score: 'number',
+                details: 'object',
+                timestamp: 'timestamp',
+            },
+        },
+    },
+    general: {
+        apiVersion: 'v1',
+        authentication: 'API Key via authorization header',
+        rateLimit: 'Configurable, high volume support (40+ million traces per day)',
+        supportedFormats: ['JSON'],
+    },
+};
+/**
+ * Get capabilities information based on configuration
+ * @param config The current configuration
+ * @returns Filtered capabilities based on what's enabled
+ */
+export function getEnabledCapabilities(config) {
+    return {
+        prompts: config.mcpEnablePromptTools
+            ? opikCapabilities.prompts
+            : { available: false, features: [], limitations: [] },
+        projects: config.mcpEnableProjectTools
+            ? opikCapabilities.projects
+            : { available: false, features: [], limitations: [] },
+        traces: config.mcpEnableTraceTools
+            ? opikCapabilities.traces
+            : { available: false, features: [], limitations: [] },
+        metrics: config.mcpEnableMetricTools
+            ? opikCapabilities.metrics
+            : { available: false, features: [], limitations: [] },
+        general: opikCapabilities.general,
+    };
+}
+/**
+ * Get a description of what Opik Comet can and cannot do
+ * @param config The current configuration
+ * @returns A string description of capabilities
+ */
+export function getCapabilitiesDescription(config) {
+    const capabilities = getEnabledCapabilities(config);
+    let description = 'Opik Comet Capabilities:\n\n';
+    // General capabilities
+    description += 'General:\n';
+    description += `- API Version: ${capabilities.general?.apiVersion || 'v1'}\n`;
+    description += `- Authentication: ${capabilities.general?.authentication || 'API Key'}\n`;
+    description += `- Rate Limit: ${capabilities.general?.rateLimit || 'Default'}\n\n`;
+    // Add each capability section
+    for (const [key, capability] of Object.entries(capabilities)) {
+        if (key === 'general')
+            continue;
+        const cap = capability;
+        if (!cap.available) {
+            description += `${key.charAt(0).toUpperCase() + key.slice(1)}: Not available\n\n`;
+            continue;
+        }
+        description += `${key.charAt(0).toUpperCase() + key.slice(1)}:\n`;
+        description += 'Features:\n';
+        cap.features.forEach(feature => {
+            description += `- ${feature}\n`;
+        });
+        description += '\nLimitations:\n';
+        cap.limitations.forEach(limitation => {
+            description += `- ${limitation}\n`;
+        });
+        description += '\n';
+    }
+    return description;
+}

package/build/utils/env.js

@@ -0,0 +1,52 @@
+/**
+ * Environment loading utility
+ * Loads variables from .env file
+ */
+import { config as dotenvConfig } from 'dotenv';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * File-based logger
+ * Only writes if debug mode is enabled
+ */
+function writeToLogFile(message) {
+    try {
+        // This uses sync functions which is acceptable during initialization
+        // The log file will only be written to if DEBUG_MODE=true
+        if (process.env.DEBUG_MODE === 'true') {
+            const logFile = '/tmp/opik-mcp.log';
+            if (!fs.existsSync(logFile)) {
+                fs.writeFileSync(logFile, `Opik MCP Server Started: ${new Date().toISOString()}\n`);
+            }
+            fs.appendFileSync(logFile, `[${new Date().toISOString()}] [env] ${message}\n`);
+        }
+    }
+    catch (error) {
+        // Silently fail if we can't write to the log file
+    }
+}
+/**
+ * Attempts to load environment variables from .env file
+ * Falls back to .env.example if .env doesn't exist
+ */
+export function loadEnv() {
+    const envPath = path.resolve(process.cwd(), '.env');
+    const examplePath = path.resolve(process.cwd(), '.env.example');
+    // Check if .env exists
+    if (fs.existsSync(envPath)) {
+        // Log this to file instead of console
+        writeToLogFile('Loading environment from .env file');
+        dotenvConfig({ path: envPath });
+    }
+    else if (fs.existsSync(examplePath)) {
+        // Fall back to .env.example if .env doesn't exist
+        writeToLogFile('Warning: .env file not found, using .env.example as fallback');
+        writeToLogFile('Please create a .env file with your actual configuration');
+        dotenvConfig({ path: examplePath });
+    }
+    else {
+        writeToLogFile('Warning: No .env or .env.example file found');
+    }
+}
+// Load environment variables when this module is imported
+loadEnv();