MCP Triage Helper

🧩 小型问题分类助手

这是一个探索使用（某技术/方法）的原型项目 模型上下文协议（MCP） 协助QA工程师进行日志分类处理。

• 本地FastMCP服务器将解析日志（最后200行，错误模式）。
• Hugging Face MCP服务器（LLaMA 3.1）将分析解析错误。
• MCP 主机将协调流程，并返回根本原因及建议的质量保证步骤。

🧪 本项目展示了人工智能如何通过解析真实世界的日志并自动生成分类见解来辅助质量保证（QA）工程师。

📦 安装

克隆仓库并设置环境：

# Clone the project
git clone https://github.com/Elena-Scherbinina/mcp-triage-helper.git
cd mcp-triage-helper

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate   # (Mac/Linux)
# or on Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
# If not using requirements.txt, install manually:
pip install fastmcp "huggingface_hub[mcp]" uvicorn fastapi

快速概览

📁 项目结构

mcp-triage-helper/
├── fastmcp_server/
│   ├── parser.py         ← Parses log files and extracts error data
│   └── server.py         ← Runs both the FastMCP and REST servers
│
├── logs/
│   ├── sample.log        ← Example log file with mixed INFO/WARN/ERROR messages
│   └── sample_small.log  ← Smaller test log for quick verification
│
├── scripts/
│   └── run_py.sh         ← Start the Hugging Face MCP host and load config.json
│
├── config.json           ← Configuration file - connects local FastMCP server to Hugging Face MCP
│
├── requirements.txt      ← Lists all Python dependencies 
│
├── .gitignore            ← Excludes local files (.env, venv, logs) from being committed to Git
│
└── README.md             ← documentation

🧾 日志

这个（或“该”） logs/ 文件夹包含 示例日志文件 用于测试Mini QA分类助手：

• sample.log 翻译成中文是“示例日志文件” – 一个包含混合INFO、WARN以及多条ERROR行（如SQLTimeout、NullPointerException、ConnectException）的日志文件，用于测试完整的解析和AI摘要功能。
• sample_small.log 翻译为中文是：“小样本日志文件” – 一个非常短的日志（5-6行），仅包含一个错误，适用于快速运行或演示。

这些文件被 Git 忽略（参见 .gitignore）且仅用于本地开发和测试目的。

⚙️ 本地FastMCP工具

• 姓名： parse_log(file_path)
• 目的：从日志文件中提取最后N行和错误模式。
• 输出：包含错误类型和计数的结构化JSON。

🧩 架构

• fastmcp_server/parser.py将日志文件解析为结构化的错误摘要。
• fastmcp_server/server.py运行一个本地FastMCP兼容的服务，该服务提供（或暴露） parse_log。
• config.json配置MCP主机连接到本地FastMCP服务器（以及可选地连接到Hugging Face MCP主机）。

🚀 如何运行迷你问答分类助手

🧠 步骤0 — 登录Hugging Face

在运行MCP主机之前，请确保您已通过Hugging Face的身份验证：

huggingface-cli login

系统会提示您粘贴您的 Hugging Face 访问令牌（以 hf\_ 开头）。 登录信息会安全地存储在您的设备上——您只需进行一次此操作。

1️⃣ 启动本地FastMCP + REST服务器

该项目包含两个层次：

• MCP服务器 — 暴露；揭露 parse_log_tool(file_path) 用于大型语言模型（LLM）或主机连接。
• REST服务器 — 可选的测试终端在 http://localhost:8080/parse_log。

#To start the MCP server:
python -m fastmcp_server.server

#Expected output:
🖥️  Server name: MCP Log Parser Server
📦 Transport:    Streamable-HTTP
🔗 Server URL:   http://localhost:8000/mcp

2️⃣ 测试REST终端点

   curl -X POST http://localhost:8080/parse_log \
  -H "Content-Type: application/json" \
  -d '{"file_path": "./logs/sample.log"}'

#Expected response:
{
  "errors": [
    {"type": "java.sql.SQLTimeoutException", "count": 1, "examples": ["Timeout waiting for connection from pool"]},
    {"type": "com.retailapp.db.ConnectionManager", "count": 1, "examples": ["- Failed to connect to database"]}
  ]
}

3️⃣ 运行Hugging Face MCP主机

FastMCP服务器运行后，您可以使用以下命令启动Hugging Face MCP主机（客户端代理）：

bash scripts/run_py.sh

# Expected Output:
🤖 Starting Hugging Face MCP host ...
Agent loaded with 1 tools:
 • parse_log_tool
»

现在您可以直接与主持人互动，例如：

Analyze errors in ./logs/sample.log and summarize what they mean.

💬 示例输出

# Prompt:
Analyze errors in ./logs/sample.log and summarize what they mean.

# Response:
Several connection and null-pointer issues detected:
• Timeout waiting for connection from pool
• Failed to connect to database
• NullPointerException in OrderService
• Connection refused to PaymentGateway

Suggested fixes:
• Review DB connection pool settings
• Check database reachability
• Fix null handling in OrderService
• Verify payment gateway connectivity

📊 当前状态

• ✅ FastMCP服务器 本地运行于 http://localhost:8000/mcp，暴露 parse_log_tool(file_path)。

• ✅ REST 端点 (http://localhost:8080/parse_log) 可用于通过curl或Postman进行快速测试。

• ✅ Hugging Face MCP 主机 通过 config.json 成功连接到本地服务器。

• ✅ 日志解析模块 从样本日志中返回结构化的JSON摘要。

• ⚙️（齿轮图标，常用于表示机械、设置、调整等含义） 下一步： 扩展管道，加入模型推理（LLaMA / Claude）功能，以实现自动根本原因建议。

• 📁 代表文件夹（File Folder）的符号。 回购协议准备延期 — 包括虚拟环境设置、配置模板和测试数据。

🧭 下一步行动

• 🤝 未来的改进可能包括更丰富的错误上下文、多步骤分析以及一个简洁的网页用户界面。