# mcp_monitor

**Repository Path**: hephec321/mcp_monitor

## Basic Information

- **Project Name**: mcp_monitor
- **Description**: 本项目是一个演示原型，展示了 AI Agent 如何调用各种数据 MCP (Model Context Protocol) 工具，并详细记录交互过程中的溯源信息。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 溯源可视化演示 (MCP Traceability Monitor)

本项目是一个演示原型，展示了 AI Agent 如何调用各种数据 MCP (Model Context Protocol) 工具，并详细记录交互过程中的全链路溯源信息。

项目包含一个模拟的 AI Agent、多个模拟 MCP 数据工具（用户库、订单库、日志库），以及一个实时 Web 仪表盘，用于可视化监控 Agent 的决策过程、工具调用耗时和执行结果。

## 🚀 功能特性

1.  **智能体模拟 (AI Agent Simulation)**
    *   模拟 Agent 的思考 (`Thinking`)、规划 (`Plan`) 和决策 (`Decision`) 过程。
    *   随机生成三种任务场景：用户审计、订单检查、安全扫描。
    *   模拟 AI 元数据，包括 Token 消耗 (`tokens_used`) 和置信度 (`confidence`)。

2.  **MCP 工具模拟 (Mock MCP Tools)**
    *   实现了标准化的工具调用接口。
    *   **用户服务**: `get_user_info`, `get_user_orders`
    *   **日志服务**: `search_logs`
    *   模拟网络延迟、数据源标识和缓存命中状态。

3.  **全链路溯源 (Full-Link Traceability)**
    *   **Trace ID & Span ID**: 为每个任务和操作生成唯一标识，构建完整的调用链。
    *   **精准耗时**: 记录毫秒级的操作耗时，区分 Agent 思考时间和工具执行时间。
    *   **状态追踪**: 明确区分 `running` (进行中), `success` (成功), `error` (异常), `info` (信息)。

4.  **实时可视化仪表盘 (Real-time Dashboard)**
    *   **监控面板**: 实时展示总事件数、完成任务数、平均延迟和错误率。
    *   **日志流**: 类似控制台的实时日志流，支持自动刷新。
    *   **详情查看**: 支持展开查看完整的 JSON Payload，带语法高亮。
    *   **可视化增强**: 使用不同颜色区分 Actor (Agent/System/MCP/Tool)，直观展示调用关系。

## 🛠️ 安装与运行

### 前置要求
*   Node.js (v14 或更高版本)

### 启动步骤

1.  **安装依赖**
    ```bash
    npm install
    ```

2.  **启动服务**
    ```bash
    npm start
    ```
    启动后，控制台将显示 Agent 的运行日志。

3.  **访问仪表盘**
    打开浏览器访问: [http://localhost:3000](http://localhost:3000)

## 📊 溯源数据结构

系统生成的日志记录包含以下关键字段，存储于 `trace_log.json`：

```json
{
  "traceId": "d78d9d5c-...",       // 整个任务周期的唯一标识
  "spanId": "8eb31048-...",        // 当前原子操作的唯一标识
  "parentSpanId": "...",           // 父级操作 ID (用于构建树状调用链)
  "timestamp": "2023-10-27T...",   // ISO 时间戳
  "actor": "AuditBot_v1",          // 执行主体 (Agent / System / MCP_Server / ToolName)
  "action": "Decision",            // 动作类型 (Thinking / ToolCall / ToolResult / ...)
  "type": "end",                   // 记录类型 (start / end / info)
  "status": "success",             // 执行状态
  "duration": 306,                 // 耗时 (ms)
  "payload": {                     // 详细数据载荷
    "scenario": "audit_user",
    "ai_metadata": {
      "tokens_used": 103,
      "confidence": "0.83"
    }
  }
}
```

## 📂 项目结构

*   `src/agent.js`: 模拟 AI Agent 的逻辑，包含任务循环和决策状态机。
*   `src/mcp-server.js`: 模拟 MCP 工具服务器，提供数据查询接口。
*   `src/logger.js`: 核心日志模块，负责生成 Trace ID 并管理日志文件 IO。
*   `public/index.html`: 前端可视化仪表盘代码。
*   `index.js`: 项目入口，启动 Agent 和 Web Server。

## 📝 License

MIT