MCP Pulse

🔴 mcp脉冲

模型上下文协议（MCP）服务器的实时监控和可观察性仪表板。 全面了解您的AI工作流程——在漂亮的实时仪表板中跟踪工具调用、延迟、错误和使用模式。

](https://www.npmjs.com/package/mcp-pulse)   ](https://nodejs.org/)

______________________________________________________________________

*带有实时指标、呼叫跟踪和警报的实时仪表板*

______________________________________________________________________

✨ 特性

📊 实时仪表板

• 实时通话记录 --观察每次MCP工具调用
• 延迟跟踪 --每次呼叫、每台服务器和滚动平均直方图
• 错误率监控 --带有堆栈痕迹的表面故障工具
• 请求量 --通话/分钟，时间窗口可配置

🔍 深度可观察性

• 结构化日志记录 --每个请求/响应都有完整的JSON有效负载检查
• 工具使用排行榜 --知道你的人工智能最常调用哪些工具
• 会话重放 --从头到尾重播任何捕获的会话
• 筛选和搜索 --按服务器、工具名称、状态、延迟或时间范围

🚨 智能警报

• 阈值警报 --当错误率或延迟超过限制时通知
• 异常检测 --自动标记异常图案
• Webhook+log+CSV --灵活的警报传递

🧩 MCP生态系统整合

• 适用于任何SSE传输 --所有官方MCP服务器（文件系统、GitHub、Slack等）
• 零代码集成 --通行证 --mcp-pulse 标记到任何兼容的服务器
• 协议感知 --理解 initialize, tools/list, tools/call, sampling/create, roots/list

💻 开发者体验

• WebSocket+HTTP --将仪表板连接到本地或远程服务器
• 默认情况下为暗模式 --OLED友好的深色主题
• 导出为CSV/JSON --完整的原始数据导出以供分析
• 健康检查端点 — /health 用于容器编排

______________________________________________________________________

⚡ 快速开始

1--安装

npm install -g mcp-pulse

2--启动仪表板

mcp-pulse dashboard
# → Opens at http://localhost:3000

3--代理任何MCP服务器

在一个 新终端，代理任何基于SSE的MCP服务器：

# Wrap the official filesystem server
npx @modelcontextprotocol/server-filesystem ./projects \
  --mcp-pulse \
  --mcp-pulse-port 3100

# Or wrap via stdio with the pulse proxy
cat my_server_output.json | mcp-pulse proxy --protocol sse --port 3100

4--打开浏览器

http://localhost:3000

______________________________________________________________________

🐳 码头工人

# Run dashboard
docker run -p 3000:3000 -p 3100:3100 \
  --env MCP_PULSE_PORT=3100 \
  SergiuPogor/mcp-pulse:latest

# Proxy an MCP server inside Docker
docker run -p 3100:3100 \
  --env MCP_PULSE_TARGET=http://your-server:3001 \
  SergiuPogor/mcp-pulse:latest proxy

______________________________________________________________________

📐 建筑

┌──────────────┐      ┌──────────────┐      ┌──────────────────────┐
│  MCP Client  │──────│  MCP Server  │──────│   mcp-pulse Proxy     │
│  (Claude,    │ SSE  │  (official   │──────│  (intercepts all      │
│   Cursor,    │      │   servers)   │      │   JSON-RPC messages) │
│   etc.)      │      │              │      │                      │
└──────────────┘      └──────────────┘      └──────────┬───────────┘
                                                        │ HTTP/WS
                                                        ▼
                                              ┌──────────────────┐
                                              │  mcp-pulse       │
                                              │  Dashboard       │
                                              │  (Express + WS)  │
                                              └──────────────────┘

代理如何工作

1. 客户端启动与MCP服务器的SSE连接
2. mcp-pulse proxy 拦截JSON-RPC流量
3. 每条消息都会被实时记录、计时和转发
4. Dashboard通过WebSocket接收实时流
5. 指标在内存中聚合，具有可配置的保留期

______________________________________________________________________

🛠️ CLI参考

mcp-pulse [command]

Commands:
  dashboard          Start the web dashboard (default port 3000)
  proxy              Start a proxy server that intercepts MCP traffic
  proxy:stdio        Wrap a stdio-based MCP server ( Pipes JSON-RPC)
  alert              Run the alert engine (reads from dashboard API)
  export             Export captured data to CSV or JSON

Options:
  --port, -p         Port for dashboard or proxy        [default: 3000]
  --target, -t       Target MCP server URL (for proxy)  [required]
  --protocol         Transport: sse | stdio | stream   [default: sse]
  --retention        How many hours to keep data         [default: 24]
  --alert-threshold  Error rate % to trigger alert      [default: 10]
  --json             Output raw JSON (for scripting)
  --verbose          Enable verbose logging
  --help             Show help

示例

# Start dashboard on port 8080
mcp-pulse dashboard --port 8080

# Proxy an SSE server
mcp-pulse proxy --target http://localhost:3001 --port 3100

# Proxy a stdio server and stream its output
mcp-pulse proxy:stdio -- npx @modelcontextprotocol/server-github

# Run alerting engine
mcp-pulse alert --threshold 5 --webhook https://hooks.example.com/alert

# Export last 1 hour to CSV
mcp-pulse export --format csv --hours 1 --output ./report.csv

______________________________________________________________________

🔌 MCP服务器集成

官方服务器（SSE传输）

这些服务器与 mcp-pulse proxy 开箱即用：

Stdio服务器

对于基于stdio的服务器，请使用 proxy:stdio:

mcp-pulse proxy:stdio -- python /path/to/your/mcp_server.py

自定义服务器

要检测自定义MCP服务器，请添加脉冲中间件：

import { createPulseMiddleware } from 'mcp-pulse/middleware';

// In your MCP server setup:
server.addMiddleware(createPulseMiddleware({
  endpoint: 'http://localhost:3000/pulse',
  quiet: false,          // suppress pulse logging
  samplingRate: 1.0,     // capture 100% of calls (0.0–1.0)
  excludeTools: ['internal/debug'], // tools to skip
}));

______________________________________________________________________

📡 仪表板API

仪表板公开了REST+WebSocket API。

REST端点

WebSocket事件

// Connect to live stream
const ws = new WebSocket('ws://localhost:3000/live');

ws.on('message', (data) => {
  const event = JSON.parse(data);
  
  switch (event.type) {
    case 'call:start':    // MCP call initiated
    case 'call:end':      // MCP call completed (includes latency + status)
    case 'call:error':    // MCP call failed
    case 'metrics:update': // Aggregated metrics (every 5s)
    case 'alert:trigger':  // Alert fired
    case 'heartbeat':     // Connection keepalive
  }
});

事件有效载荷

// call:end payload
{
  id: 'call_abc123',
  serverId: 'server_filesystem',
  tool: 'filesystem.read_file',
  duration: 42,          // ms
  status: 'success',    // 'success' | 'error' | 'timeout'
  request: {            // Sanitized request (secrets removed)
    method: 'tools/call',
    params: { name: 'read_file', arguments: { path: '/projects/README.md' } }
  },
  response: {
    content: [{ type: 'text', text: '...' }]
  },
  timestamp: '2026-03-21T14:30:00.000Z'
}

// alert:trigger payload
{
  id: 'alert_001',
  serverId: 'server_filesystem',
  metric: 'error_rate',
  value: 15.3,          // percentage
  threshold: 10.0,
  window: '5m',
  firedAt: '2026-03-21T14:30:00.000Z'
}

______________________________________________________________________

⚙️ 配置

环境变量

MCP_PULSE_PORT=3000          # Dashboard port
MCP_PULSE_PROXY_PORT=3100   # Proxy port
MCP_PULSE_RETENTION=24       # Hours of data to keep
MCP_PULSE_TARGET=            # Target MCP server URL (for proxy mode)
MCP_PULSE_SAMPLING=1.0       # Capture rate (0.0–1.0)
MCP_PULSE_AUTH_TOKEN=        # Optional: require token for API
MCP_PULSE_WEBHOOK_URL=       # Alert webhook URL

config.json

放在项目根目录中或 ~/.mcp-pulse/config.json:

{
  "dashboard": {
    "port": 3000,
    "auth": {
      "enabled": false,
      "token": "your-secret-token"
    },
    "retention": {
      "hours": 24,
      "maxCalls": 100000
    }
  },
  "proxy": {
    "port": 3100,
    "target": "http://localhost:3001",
    "protocol": "sse",
    "sampling": 1.0
  },
  "alerts": [
    {
      "name": "High Error Rate",
      "metric": "error_rate",
      "threshold": 10,
      "window": "5m",
      "severity": "critical",
      "actions": ["log", "webhook"]
    },
    {
      "name": "High Latency",
      "metric": "latency_p99",
      "threshold": 2000,
      "window": "5m",
      "severity": "warning",
      "actions": ["log"]
    }
  ],
  "export": {
    "defaultFormat": "csv",
    "includePayloads": false
  }
}

______________________________________________________________________

🧪 示例

示例1——监视文件系统MCP服务器

# Terminal 1: Start dashboard
mcp-pulse dashboard

# Terminal 2: Start filesystem MCP server via proxy
npx @modelcontextprotocol/server-filesystem $HOME/projects \
  --mcp-pulse \
  --mcp-pulse-port 3100 \
  --mcp-pulse-target http://localhost:3100

# Terminal 3: Use the server (e.g. in Claude Desktop)
claude

# Open http://localhost:3000 to watch all file operations

示例2-GitHub服务器故障警报

# Set webhook (e.g. Discord or Slack incoming webhook)
export MCP_PULSE_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/yyy

# Start alert engine
mcp-pulse alert --threshold 5 --webhook $MCP_PULSE_WEBHOOK_URL

# Start GitHub MCP server
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx
npx @modelcontextprotocol/server-github \
  --mcp-pulse \
  --mcp-pulse-port 3100

示例3——自定义仪表板嵌入

// Embed real-time mcp-pulse data into your own app
import { MCP PulseClient } from 'mcp-pulse/client';

const client = new MCP PulseClient({
  dashboardUrl: 'http://localhost:3000',
  apiKey: 'optional-token',
});

client.on('call:end', (call) => {
  if (call.tool.includes('github') && call.status === 'error') {
    console.error(`GitHub tool failed: ${call.tool}`, call.response);
  }
});

await client.connect();

______________________________________________________________________

🔒 安全

• 日志中没有秘密 --请求参数在存储之前会被扫描和编辑
• 有效载荷截断 --大响应被截断（可配置，默认10KB）
• 默认情况下仅限本地 --仪表板绑定到 127.0.0.1 除非 --public 使用标志
• 可选身份验证 --set MCP_PULSE_AUTH_TOKEN 保护API
• GDPR注释 --mcp脉冲在本地存储数据；除非导出，否则任何数据都不会离开您的机器

______________________________________________________________________

🤝 贡献

欢迎投稿！请阅读我们的 贡献指南 在提交PR之前。

# Development setup
git clone https://github.com/SergiuPogor/mcp-pulse.git
cd mcp-pulse
npm install
npm run dev          # Watch mode + hot reload
npm run test         # Run tests
npm run lint         # Lint + format

报告问题

请通过以下方式报告错误和功能请求 .包括：

• mcp脉冲版本(mcp-pulse --version)
• Node.js版本(node --version)
• MCP服务器名称和版本
• 重现步骤

______________________________________________________________________

📄 许可证

麻省理工学院©2026 Sergiu Pogor

______________________________________________________________________

如果你觉得有用，就把它标上。