使用说明

`MCP-logger` -日志系统+MCP服务器+浏览器集成

一个轻量级的日志记录系统，可以捕获前端控制台日志，并通过MCP（模型上下文协议）进行访问。非常适合使用AI助手的开发和调试环境。

📋 系统概述

浏览器日志系统由三个主要组件组成：

前端记录器 (mcp-logger.js)-捕获控制台日志并发送到后端
后端服务器 (logger-server.js)-从前端接收和存储日志
MCP服务器 (mcp-server.js)-提供MCP对存储日志的访问

🏗️ 架构概述

系统上下文（C4级别1）

graph TB
    subgraph "Your Applications"
        app1["Web App"]
        app2["Mobile App"]
        app3["Backend API"]
    end

    subgraph "Browser Logger System"
        logger["Logging System"]
    end

    dev["Developer"]
    ai["AI Assistant"]

    %% Your apps send logs to the system
    app1 -->|"logs"| logger
    app2 -->|"logs"| logger
    app3 -->|"logs"| logger

    %% You interact with AI to get insights
    dev -->|"asks about issues"| ai
    ai -->|"fetches logs"| logger
    ai -->|"provides insights"| dev

    classDef yourApp fill:#e8f5e8,stroke:#2e7d32
    classDef logger fill:#e1f5fe,stroke:#01579b
    classDef person fill:#fff3e0,stroke:#f57c00

    class app1,app2,app3 yourApp
    class logger logger
    class dev,ai person

它是如何工作的：

您的应用程序将日志发送到集中式日志系统
你向你的人工智能助手询问问题或难题
AI从您的任何应用程序中检索和分析日志
您可以从AI助手那里获得可操作的见解

🚀 快速启动（5分钟设置）

步骤1：安装依赖项

cd mcp-logger
npm install

步骤2：配置（可选）

# Copy the example configuration file
cp .env.example .env

# Edit .env to customize settings (optional):
# PORT=3000
# HOST=0.0.0.0
# MAX_LOG_ENTRIES=500

步骤3：启动后端服务器

# Terminal 1
node logger-server.js
# Expected: 🚀 Browser Logger Server running on http://localhost:22345

步骤4：配置MCP客户端

MCP服务器使用STDIO传输，由LLM客户端自动启动：

# Show quick setup with Claude Code CLI
node mcp-server.js mcp-help

使用默认应用程序 my-app （AI客户端将使用MCP FE-logs 仅适用于应用程序 my-app):

claude mcp add FE-logs node $(pwd)/mcp-server.js \
    --scope local --env FILTER_APP=my-app

或者使用基本设置（在get_logs调用中需要app参数）：

claude mcp add FE-logs node $(pwd)/mcp-server.js

与MCP检查员一起测试：

npx @modelcontextprotocol/inspector --cli node $(pwd)/mcp-server.js \
  -e FILTER_APP=my-app --method tools/call --tool-name 'get_logs'

步骤5：添加到前端应用程序

将此单个脚本添加到HTML文件中-它会自动处理在线和离线情况：

<script>
window.MCP_LOGGING_ENABLED = true;
window.MCP_LOGGING_APP_NAME = 'my-app';  // REQUIRED: Set your app name
window.MCP_LOGGING_BACKEND_URL = 'http://localhost:22345';
(function() {
    // Try to load from server first, fallback to local file
    var script = document.createElement('script');
    script.src = window.MCP_LOGGING_BACKEND_URL + '/mcp-logger.js';
    script.onerror = function() {
        // Server is down, create a simple fallback logger
        console.log('MCP Logger server offline, using local fallback');
        window.logger = {
            log: function(namespace, data) {
                console.debug('[' + namespace + ']', data);
            }
        };
    };
    document.head.appendChild(script);
})();
</script>

步骤6：测试您的设置

使用 get_logs() MCP客户端中的工具，用于从前端应用程序检索日志。

不带FILTER_APP（需要应用程序参数）：

get_logs(app="my-app")
get_logs(app="my-app", filter="error", lines=50)

设置了过滤器_APP（应用程序参数可选）：

get_logs()                                    // Uses default app
get_logs(filter="error", lines=50)            // Uses default app
get_logs(app="other-app")                     // Override default app

🔧 配置

环境变量（.env文件）

创建一个 .env 文件来自 .env.example 要自定义设置，请执行以下操作：

# Copy the example configuration
cp .env.example .env

后端服务器配置：

PORT=22345                              # Server port
HOST=localhost                          # Server host (use 0.0.0.0 for external access)
MAX_LOG_ENTRIES=500                     # Max log entries per namespace

MCP服务器配置：

BACKEND_HOST=localhost                  # Host where MCP server can reach backend
BACKEND_PORT=22345                      # Port where MCP server can reach backend
FILTER_APP=my-app                       # Default app name for get_logs tool

自定义主机/端口示例

不同端口：

# .env file
PORT=3000
HOST=localhost

# Frontend script
window.MCP_LOGGING_BACKEND_URL = 'http://localhost:3000';

外部访问：

# .env file
PORT=22345
HOST=0.0.0.0
BACKEND_HOST=192.168.1.100

# Frontend script
window.MCP_LOGGING_BACKEND_URL = 'http://192.168.1.100:22345';

完成远程设置：

# .env file
PORT=3000
HOST=0.0.0.0
BACKEND_HOST=192.168.1.100
BACKEND_PORT=3000
FILTER_APP=dashboard

🔌 API终点

主要终点：

POST /api/logs/submit -从前端提交日志
GET /api/logs/status -获取所有应用程序、主机和命名空间
GET /api/health -健康检查
GET / -Web日志查看器界面
GET /mcp-logger.js -前端记录器脚本

📖 使用示例

控制台日志记录（自动）

// All console methods are automatically captured
console.log('Application started');
console.info('User logged in');
console.warn('Deprecated API used');
console.error('Network request failed');

应用程序日志记录（结构化）

// User interaction logging
logger.log('user-actions', {
    action: 'click',
    target: 'submit-button',
    page: '/checkout',
    timestamp: Date.now()
});

// API call logging
logger.log('api-calls', {
    method: 'POST',
    url: '/api/users',
    status: 200,
    duration: 150
});

// Error logging
logger.log('errors', {
    type: 'validation',
    message: 'Invalid email format',
    field: 'email'
});

Shell命令日志记录

# First argument is app name, rest is command
./shell-log.sh my-app npm run build
./shell-log.sh api-test curl -s http://api.example.com/health
./shell-log.sh markdown-ticket bash start.sh

# View logs in web interface at http://localhost:22345
# App: my-app, Namespace: npm (auto-generated from command)

MCP工具使用

// Basic log retrieval
// auto-selects single host
// use app=unknown-app or defined in app=${FILTER_APP} env variable
get_logs()

// Retrieve with filtering
get_logs(filter="error", lines=10)

// Specific host and namespace
get_logs(frontend_host="localhost:3000", namespace="user-actions")

🖥️ Web日志查看器

访问web界面 http://localhost:22345 当后端服务器正在运行时。

特征：

实时日志流
按文本、日志级别或源进行筛选
暗/亮主题
将日志导出到剪贴板
暂停/恢复流媒体播放

# Start backend and open viewer
npm run start-backend
open http://localhost:22345

🧪 测试和验证

基本连接测试

# Test backend health
curl http://localhost:22345/api/health

邮差API测试

全面的Postman系列提供了完整的API测试覆盖范围：

# Import the collection
1. Open Postman → Import → File → sandbox/MCP-Logger-API.postman_collection.json
2. Run individual requests or use Collection Runner for bulk testing
3. View detailed guide: sandbox/POSTMAN_API_GUIDE.md

测试覆盖范围：

✅ 系统健康和状态端点
✅ 日志提交（浏览器、应用程序、shell格式）
✅ 具有过滤和分页功能的日志检索
✅ 实时SSE流媒体
✅ 前端资产服务
✅ 负载测试和并发请求
✅ 错误处理和边缘情况

前端集成测试

打开 test/test-front.html 在浏览器中测试日志功能。

🔧 前端配置

// Set before loading mcp-logger.js
window.MCP_LOGGING_ENABLED = true;                    // Enable/disable logging
window.MCP_LOGGING_APP_NAME = 'my-app';               // REQUIRED: Your app name
window.MCP_LOGGING_BACKEND_URL = 'http://localhost:22345'; // Backend URL
window.MCP_LOGGING_BUFFER_SIZE = 100;                 // Log buffer size

注：后端配置通过 .env 文件（请参阅上面的配置部分）。

🐛 故障排除

常见问题

后端服务器无法启动：

# Check if port is in use
lsof -i :22345

# Check .env file configuration
cat .env

# Use different port if needed
PORT=3001 node logger-server.js

# Or use environment variables directly
HOST=0.0.0.0 PORT=3001 node logger-server.js

前端无法连接：

# Check backend health
curl http://localhost:22345/api/health

未出现在MCP中的日志：

检查浏览器控制台是否有错误
验证网络请求是否发送到 /api/logs/submit
确保后端服务器正在运行

MCP工具不可用：

验证AI客户端配置路径是否正确
检查args数组是否包含到的绝对路径 mcp-server.js

🔒 安全说明

此系统仅适用于开发环境。它使用HTTP通信，并假设本地网络是可信的。对于生产使用，请实施适当的身份验证并使用HTTPS。

📁 文件结构

mcp-logger/
├── mcp-logger.js                    # Frontend logger
├── inject-logger.js                 # Auto-loading script
├── logger-server.js                 # Backend HTTP server
├── mcp-server.js                     # MCP server (STDIO transport)
├── shell-log.sh                     # Bash wrapper for shell command logging
├── .env.example                     # Example configuration
├── .env                             # Your configuration (create from .env.example)
├── package.json                     # Dependencies and scripts
├── openapi.yaml                     # OpenAPI 3.1 specification
├── CLAUDE.md                        # Claude Code project instructions
├── assets/                          # Web viewer assets
│   ├── log-viewer.css               # Web viewer styles
│   └── log-viewer.js                # Web viewer functionality
├── templates/                       # HTML templates
│   └── log-viewer.html              # Web log viewer template
├── docs/                            # Documentation
│   ├── SHELL_LOGGING.md             # Comprehensive shell logging guide
│   └── CRs/                         # Change requests (gitignored)
│       ├── MCL-001-*.md             # Shell logging feature
│       └── MCL-002-*.md             # Web UI feature
├── sandbox/                         # Non-tracked files (gitignored)
│   ├── MCP-Logger-API.postman_collection.json  # Postman API testing collection
│   ├── POSTMAN_API_GUIDE.md         # Postman collection usage guide
│   ├── SSE_MONITORING.md            # SSE monitoring guide
│   └── *.sh, *.html                 # Various test scripts and files
├── test/                            # Test files
│   ├── test-frontend.html           # Full integration test
│   ├── test-frontend-simulation.js  # Backend test simulation
│   └── test-spam-protection.js      # Rate limiting test
├── test-log-viewer.html             # Standalone log viewer test
└── README.md                        # This file

📞 后端集成

Shell命令日志记录

使用带有进程替换的nohup实时捕获shell命令输出。

# Usage: ./shell-log.sh app-name command [args...]
./shell-log.sh my-app npm run build
./shell-log.sh api-test curl -s http://api.example.com/health
./shell-log.sh markdown-ticket bash start.sh

# With verbose output
MCP_LOGGING_VERBOSE=true ./shell-log.sh test-app your-command

主要特点：

第一个论点是 应用程序名称
命名空间为 自动生成 from命令（截断为30个字符）
后台进程捕获 使用nohup+过程替换
仅内存日志记录 （无磁盘文件）
实时流媒体 到web界面
标准输出/标准错误分离 具有日志/错误级别

环境变量：

MCP_LOGGING_BACKEND_URL -后端URL（默认值：http://localhost:22345)
MCP_LOGGING_VERBOSE -启用调试输出
HOSTNAME -主机标识符（默认值：系统主机名）

📖 详细指南：参见 docs/SHELL_LOGING.md 获取全面的shell日志记录文档。

后端系统日志记录

此记录器也可以从任何后端系统简单使用，只需使用 http://localhost:22345/api/logs/submit 端点与

POST /api/logs/submit
Content-Type: application/json

{
    "app": "my-backend-app",
    "host": "localhost:3000",
    "logs": {
        "{your namespace}": [  ]
    }
}

📞 支持

技术支持：

检查上面的故障排除部分
看 CLAUDE.md 用于项目设置指导
用详细信息创建问题

📚 文档

📖 API文档

📖 OpenAPI规范: openapi.yaml -完整的OpenAPI 3.1规范
📮 邮差收藏: 沙箱/MCP-记录器-API.postman_collection.json -完整的API测试集合
📮 邮递员指南: 沙箱/POSTMAN_API_GUIDE.md -全面的邮差使用指南
🌊 SSE监控: 沙盒/SSE_MONITOING.md -SSE监控指南

🏗️ 项目文档

🤖 Claude代码设置: CLAUDE.md -项目说明和开发指导

🧪 测试

🌐 前端集成: test/test-front.html -完全集成测试
⚡ 后端模拟: test/test前端模拟.js -直接测试后端API
🛡️ 速率限制: test/test-spam-protection.js -测试速率限制功能

使用说明

MCP-logger -日志系统+MCP服务器+浏览器集成

📋 系统概述

🏗️ 架构概述

系统上下文（C4级别1）

🚀 快速启动（5分钟设置）

步骤1：安装依赖项

步骤2：配置（可选）

步骤3：启动后端服务器

步骤4：配置MCP客户端

步骤5：添加到前端应用程序

步骤6：测试您的设置

🔧 配置

环境变量（.env文件）

自定义主机/端口示例

🔌 API终点

📖 使用示例

控制台日志记录（自动）

应用程序日志记录（结构化）

Shell命令日志记录

MCP工具使用

🖥️ Web日志查看器

🧪 测试和验证

基本连接测试

邮差API测试

前端集成测试

🔧 前端配置

🐛 故障排除

常见问题

🔒 安全说明

📁 文件结构

📞 后端集成

Shell命令日志记录

后端系统日志记录

📞 支持

📚 文档

📖 API文档

🏗️ 项目文档

🧪 测试

相关 MCP

Figma MCP服务器

Markdown转换服务

MCP 协议测试服务器

图像生成服务

代码安全扫描工具

网页内容抓取服务器

`MCP-logger` -日志系统+MCP服务器+浏览器集成