项目简介

Kubiks CLI是一个命令行工具，旨在简化Next.js应用的调试流程。它通过配置OpenTelemetry自动收集应用的日志、追踪和指标数据，并将这些数据存储在本地SQLite数据库中。最核心的是，Kubiks CLI作为一个MCP（Model Context Protocol）服务器运行，允许AI代码编辑器（如Cursor）直接访问这些丰富的上下文数据，从而实现智能化的故障诊断和代码修复。

主要功能点

OpenTelemetry自动配置: 自动为Next.js项目设置OpenTelemetry环境变量，无需手动配置。
全面数据捕获: 实时捕获HTTP请求、SQL查询、AI SDK调用、服务器和客户端日志等遥测数据。
本地数据存储: 将所有收集到的数据高效存储在本地SQLite数据库中，方便快速查询。
MCP集成: 作为MCP服务器，提供标准化的接口供AI编辑器调用工具来查询应用运行时的上下文信息。
AI辅助调试: LLM（如Cursor）可以利用Kubiks CLI提供的上下文信息（通过MCP工具调用获取）来理解应用问题、定位根源并提出修复建议。
跨平台支持: 可在macOS, Linux, Windows上运行。

安装步骤

macOS / Linux (使用Homebrew):

brew install kubiks-inc/tap/kubiks

其他平台: 访问GitHub Releases页面下载适用于您操作系统的最新版本二进制文件。 ⬇️ Download from releases

服务器配置（供MCP客户端使用）

Kubiks CLI在启动时会自动将自身注册为一个名为 "kubiks" 的MCP服务器，其通信URL为 'http://localhost:7433/mcp/sse'。对于MCP客户端（例如Cursor AI编辑器），您通常无需手动配置，Kubiks CLI会自动管理位于用户主目录下的 '.cursor/mcp.json' 配置文件。如果您需要手动检查或配置，以下是MCP客户端可能使用的JSON配置示例（请勿直接将此代码复制到CLI或终端，这仅为配置格式示例和注释说明）：

{
  "mcpServers": {
    "kubiks": {
      "url": "http://localhost:7433/mcp/sse"
    }
  },
  "globalSettings": {
    "timeout": 60 // 可选：设置MCP请求的超时时间
  }
}

'mcpServers': 这是一个对象，其中包含注册的MCP服务器列表。
'kubiks': 这是Kubiks CLI服务器的名称，LLM客户端将使用此名称来识别和连接到Kubiks。
'url': 这是MCP服务器的通信地址。Kubiks CLI默认监听在 'http://localhost:7433'，并通过 'mcp/sse' 路径提供SSE（Server-Sent Events）传输协议的MCP服务。
'globalSettings': 可选的全局设置。
'timeout': (可选) LLM客户端与MCP服务器通信的超时时间（单位：秒）。

基本使用方法

在您的Next.js项目根目录中，打开终端。
运行Kubiks CLI启动遥测数据收集器和开发服务器：
```
kubiks
```
此命令会同时启动Next.js开发服务器（通过 'npm run dev'）、OpenTelemetry收集器和Kubiks MCP服务器。

启用浏览器日志（推荐）: 为了获得最佳调试体验，在您的 'next.config.js' 文件中添加以下配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    // Forward browser logs to the terminal for easier debugging
    browserDebugInfoInTerminal: true,
  },
}

module.exports = nextConfig

这将允许Kubiks收集并提供浏览器端的日志。

当您的Next.js应用出现问题时，在您的AI代码编辑器（如Cursor）中，直接向AI提问，例如：
- "我的 '/api/users' 接口为什么返回500错误？"
- "用户点击这个按钮时，有哪些SQL查询在运行？"
- "展示一下结账流程的完整请求追踪。" AI编辑器将通过MCP协议调用Kubiks CLI提供的工具，获取到精确的日志、追踪和请求负载数据，帮助您快速定位和解决问题。

关键词

项目简介

主要功能点

安装步骤

服务器配置（供MCP客户端使用）

基本使用方法

信息