Cursor MCP Monitor

Cursor MCP 监视器

一个用于监视 Cursor AI 编辑器中 Model Context Protocol（MCP）交互的 .NET 控制台应用程序。此工具通过实时监视日志文件，帮助开发者调试和分析 MCP 服务与客户端之间的通信。

什么是 MCP？

Model Context Protocol（MCP）是一种开放协议，用于标准化应用程序向大模型提供上下文的方式。它采用客户端-服务端架构，其中：

• MCP 主机（如 Cursor）连接到多个服务
• MCP 客户端与服务保持一对一连接
• MCP 服务通过标准化协议提供特定功能
• 本地数据源和远程服务通过 MCP 服务安全访问

功能

• 实时监视 Cursor 中 MCP 客户端与服务之间的交互：
  • 客户端创建和连接事件
  • 服务提供项列表和功能
  • 协议错误和警告
  • 客户端生命周期状态转换
• 监视 Cursor 日志目录中的新 MCP 日志文件
• 解析不同类型的消息并为其添加颜色标识：
  • 绿色：客户端创建和成功连接
  • 黄色：服务提供项列表
  • 红色：协议错误和客户端关闭
  • 灰色：常规信息消息
• 支持日志轮换和文件截断
• 支持跨平台（Windows、macOS、Linux）
• 采用指数退避和重试逻辑，实现智能错误处理
• 可配置轮询间隔和日志文件模式
• 提供命令行界面，便于自定义
• 使用 Serilog 进行结构化日志记录，提升可观测性：
  • 格式化的控制台日志
  • 按日轮换的文件日志
  • 上下文属性（计算机名称、线程 ID 等）
  • 日志级别筛选和输出自定义

交互式仪表板

应用程序包含一个用于监视和分析的 Web 仪表板，应用程序运行时可通过 http://localhost:5050 访问。仪表板通过 WebSocket 连接实时流式传输事件，支持自动重新连接，并监视事件速率。

终端显示会以毫秒精度显示时间戳，并通过颜色标识不同类型的消息，方便识别各类事件。高级搜索功能支持基于文本的搜索、高亮显示和键盘快捷键。

命令面板（Ctrl/Cmd + P）可快速访问常用操作：

• 清除日志（Ctrl/Cmd + K）
• 复制可见条目（Ctrl/Cmd + C）
• 切换自动滚动（Ctrl/Cmd + S）
• 聚焦搜索框（/）

仪表板包含 WebSocket 连接状态、活跃客户端数量和每秒事件数的状态指示器。支持深色和浅色主题，并可检测系统主题。

安装

你可以使用 .NET CLI 全局安装此工具：

# Install from NuGet.org
dotnet tool install --global CursorMCPMonitor

# Or install from GitHub Packages
dotnet nuget add source --name github "https://nuget.pkg.github.com/willibrandon/index.json"
dotnet tool install --global CursorMCPMonitor --add-source github

安装后，可以在任意位置运行此工具：

cursor-mcp --help

更新到最新版本：

dotnet tool update --global CursorMCPMonitor

卸载：

dotnet tool uninstall --global CursorMCPMonitor

配置

可以通过 appsettings.json 配置应用程序：

{
  "LogsRoot": null,
  "PollIntervalMs": 1000,
  "LogPattern": "Cursor MCP.log",
  "Verbosity": "Debug",
  "Filter": null,
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug",
      "Override": {
        "Microsoft": "Warning",
        "System": "Warning"
      }
    },
    "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
    "Properties": {
      "Application": "CursorMCPMonitor"
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "Microsoft": "Warning"
    }
  }
}

• LogsRoot：要监视的 Cursor MCP 日志根目录。如果为 null，默认值如下：
  • Windows：%AppData%/Cursor/logs
  • macOS：~/Library/Application Support/Cursor/logs
  • Linux：~/.config/Cursor/logs
• PollIntervalMs：检查新日志行的频率（以毫秒为单位）
• LogPattern：要监视的日志文件模式（支持 "Cursor MCP*.log" 之类的 glob 模式）
• Verbosity：详细级别（Debug、Information、Warning、Error）。默认值为 Debug，以显示所有消息。
• Filter：可选的文本模式，用于筛选日志内容（仅显示包含此文本的行）
• Serilog：结构化日志记录配置（参见 Serilog 配置）

你也可以使用环境变量覆盖设置：

# Windows
set LogsRoot=C:\CustomPath\Cursor\logs
set PollIntervalMs=500
# Linux/macOS
export LogsRoot=/custom/path/cursor/logs
export PollIntervalMs=500

Serilog 配置

应用使用 Serilog 进行结构化日志记录，可在 appsettings.json 文件中配置：

• Serilog:MinimumLevel:Default：默认最低日志级别
• Serilog:MinimumLevel:Override：为特定命名空间覆盖最低日志级别
• Serilog:Enrich：用于为日志添加上下文信息的丰富器
• Serilog:Properties：要包含在所有日志事件中的自定义属性

默认情况下，日志写入以下位置：

• 控制台：采用便于阅读的格式
• 文件：存储在 logs 目录中，每日轮换，文件名为 cursormonitor-YYYYMMDD.log

命令行选项

可以使用命令行选项覆盖配置设置：

# Specify a custom logs directory
dotnet run -- --logs-root "C:\Users\username\AppData\Roaming\Cursor\logs"

# Set a custom polling interval (500ms)
dotnet run -- --poll-interval 500

# Use a different log pattern (glob pattern support)
dotnet run -- --log-pattern "Cursor MCP*.log"

# Set verbosity level
dotnet run -- --verbosity debug

# Filter logs to only show lines containing specific text
dotnet run -- --filter "CreateClient"

# Combine multiple options
dotnet run -- --logs-root "/path/to/logs" --poll-interval 500 --verbosity error --filter "Error in MCP"

构建和运行

先决条件

• .NET 9.0 SDK 或更高版本

构建

dotnet build

运行

dotnet run

Docker 支持

应用支持 Docker。使用 Docker 构建和运行：

# Make sure you're in the repository root directory
cd /path/to/CursorMCPMonitor

# Build the image (note the -f flag to specify Dockerfile location)
docker build -t cursor-mcp-monitor -f src/CursorMCPMonitor/Dockerfile .

# Run the container with volume mapping for logs
# For Windows PowerShell:
docker run -it --rm -v "$env:APPDATA\Cursor\logs:/app/logs" -e LogsRoot=/app/logs cursor-mcp-monitor

# For Windows CMD:
docker run -it --rm -v "%APPDATA%\Cursor\logs:/app/logs" -e LogsRoot=/app/logs cursor-mcp-monitor

# For macOS/Linux:
docker run -it --rm -v "$HOME/Library/Application Support/Cursor/logs:/app/logs" -e LogsRoot=/app/logs cursor-mcp-monitor

重要提示：

• 始终从仓库根目录而非项目目录运行 Docker 构建命令。这样可以确保所有必需文件都包含在构建上下文中。
• 运行 Docker 容器时，需要将本地 Cursor 日志目录映射到容器中，并将 LogsRoot 环境变量设置为映射后的目录路径。

日志记录与可观测性

应用使用 Serilog 实现结构化日志记录，具有以下优势：

• 上下文信息：每条日志都包含机器名称、线程 ID 和源上下文等上下文属性
• 多种输出格式：日志以格式化的形式同时写入控制台和文件
• 日志级别：不同的日志级别（Debug、Information、Warning、Error、Fatal）有助于筛选最相关的信息
• 结构化数据：日志事件包含可供查询和分析的结构化数据
• 日志文件：日志文件存储在应用的 logs 目录中，每日轮换

控制台日志格式示例：

[2025-03-03 12:34:56.789] [INF] [CursorMCPMonitor.Services.LogProcessorService] CreateClient detected: Cursor MCP.log 2025-03-03 12:34:56.123 [info] a602: Handling CreateClient action

文件日志格式示例：

2025-03-03 12:34:56.789 +00:00 [INF] [CursorMCPMonitor.Services.LogProcessorService] CreateClient detected: Cursor MCP.log 2025-03-03 12:34:56.123 [info] a602: Handling CreateClient action

错误处理

应用包含高级错误处理功能：

• 文件访问错误采用带抖动的指数退避策略
• 自动从瞬时问题中恢复
• 使用颜色编码的控制台输出提供详细错误报告
• 检测文件轮换和截断
• 使用上下文信息进行结构化错误日志记录

用例

• 通过监控客户端与服务端的交互，调试 MCP 服务实现
• 分析协议消息和错误模式
• 跟踪客户端生命周期和连接状态
• 监控服务端功能和提供的内容
• 验证协议实现是否正确
• 通过结构化日志跟踪应用性能和错误率

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE.txt 文件。