JinDaGe - opik-mcp MCP Details

article

README

🚀 Opik MCP 服务器

Opik MCP 服务器是 Opik 平台的模型上下文协议（Model Context Protocol, MCP）的开源实现。它提供了一个统一接口，用于访问 Opik 的各项功能，并且支持多种传输机制，既适用于本地集成，也适用于远程集成。

🚀 快速开始

📦 安装指南

# 克隆仓库
git clone /path/to/opik-mcp
cd opik-mcp

# 运行 npm 构建
npm install

⚙️ 配置

创建项目根目录下的 .env 文件：

OPIK_API_BASE_URL=https://www.comet.com/opik/api
OPIK_API_KEY=YOUR_API_KEY
OPIK_WORKSPACE_NAME=default

🚀 启动服务器

标准输入输出模式（推荐用于本地开发）

# 运行 npm 脚本启动服务
npm start

服务器发送事件模式（适用于远程访问）

# 安装依赖
npm install

# 启动 SSE 传输服务器
make start-sse

✨ 主要特性

多传输支持：支持标准输入输出（stdio）和服务器发送事件（SSE）
IDE 集成：可与 Cursor 等 IDE 工具无缝集成
灵活配置：通过命令行参数和环境变量实现灵活配置
文档完善：提供详细的 API 文档和技术说明

💻 使用示例

IDE 集成

要在 Cursor 中使用 Opik MCP，创建项目根目录下的 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "opik": {
      "command": "/usr/local/bin/node",
      "args": [
        "./build/index.js",
        "--apiUrl",
        "https://www.comet.com/opik/api",
        "--apiKey",
        "YOUR_API_KEY",
        "--workspace",
        "default",
        "--debug",
        "true"
      ],
      "env": {
        "OPIK_API_BASE_URL": "https://www.comet.com/opik/api",
        "OPIK_API_KEY": "YOUR_API_KEY",
        "OPIK_WORKSPACE_NAME": "default"
      }
    }
  }
}

🔧 技术细节

可用命令

项目提供 Makefile 脚本简化操作：

# 查看所有可用命令
make help

# 运行测试
make test

# 启动 SSE 模式服务（实验性）
make start-sse

# 启动 stdio 模式服务
make start-stdio

传输选项

标准输入输出（stdio）

适用于本地环境，服务器与客户端在同一台机器上运行。

make start-stdio

服务器发送事件（SSE）

支持远程访问和多个客户端同时连接。此传输方式目前处于实验阶段。

make start-sse

更多关于 SSE 传输的详细信息，请参阅 docs/sse-transport.md。

开发

测试

# 运行所有测试用例
npm test

# 运行指定测试套件
npm test -- tests/transports/sse-transport.test.ts

预提交钩子

项目使用 pre-commit 钩子确保代码质量：

# 手动运行预提交检查
make precommit

📚 详细文档

SSE 传输 - SSE 传输方式的详细说明
API 参考 - 完整 API 文档
配置选项 - 高级配置指南
IDE 集成 - IDE 集成详解

📄 许可证

本项目遵循 Apache 2.0 协议开源。

opik-mcp