Troubleshooter

MCP服务器故障排除

一种模型上下文协议（MCP）服务器，为开发人员和系统管理员提供全面的系统故障排除和诊断工具。此服务器使LLM能够帮助诊断系统问题、监视资源、检查日志、测试连接等。

版本： 1.0.0 | 许可证： 麻省理工学院| python 3.10+

______________________________________________________________________

📋 目录

• 特性
• 项目结构
• 快速开始
• 安装方法
• 可用工具
• 配置
• 安全
• 发展
• 文档

______________________________________________________________________

✨ 特性

🖥️ 系统信息

获取有关操作系统、硬件规格、CPU架构、内存容量和已安装软件版本的全面详细信息。

📊 资源监控

实时监控系统资源，包括：

• CPU使用率（总体和每个内核）
• 内存利用率（RAM和交换）
• 磁盘I/O统计信息
• 网络I/O指标

📋 日志文件访问

使用以下工具读取和分析系统日志文件：

• 读取最后N行的尾部功能
• 基于模式的过滤（类似于grep）
• 常见日志位置发现
• 支持多种日志格式

🌐 网络诊断

使用以下工具测试网络连接：

• DNS解析测试
• TCP端口连接检查
• 连接定时测量
• 超时配置

⚙️ 流程管理

搜索和监视正在运行的进程：

• 基于模式的流程搜索
• 每个进程的CPU和内存使用率
• 进程状态和命令行详细信息
• 按资源使用情况排序

🔧 环境分析

检查系统环境，包括：

• 环境变量（带模式过滤）
• 已安装的开发工具和版本
• PATH配置
• 常用工具版本检查（git、docker、python、node等）

🛡️ 安全命令执行

使用以下命令执行白名单诊断命令：

• 严格的安全命令白名单
• 超时保护
• 仅限安全诊断操作
• 实时输出捕获

______________________________________________________________________

📁 项目结构

troubleshooting_mcp/
├── src/
│   └── troubleshooting_mcp/          # Main package
│       ├── __init__.py               # Package initialization
│       ├── server.py                 # MCP server entry point
│       ├── constants.py              # Shared constants
│       ├── models.py                 # Pydantic input validation models
│       ├── utils.py                  # Utility functions
│       └── tools/                    # Individual diagnostic tools
│           ├── __init__.py           # Tool registration
│           ├── system_info.py        # System information tool
│           ├── resource_monitor.py   # Resource monitoring tool
│           ├── log_reader.py         # Log file reader tool
│           ├── network_diagnostic.py # Network diagnostic tool
│           ├── process_search.py     # Process search tool
│           ├── environment_inspect.py # Environment inspection tool
│           └── safe_command.py       # Safe command execution tool
│
├── tests/                            # Test suite
│   ├── __init__.py
│   └── test_server.py                # Server validation tests
│
├── docs/                             # Documentation
│   ├── QUICKSTART.md                 # Quick start guide
│   ├── EXAMPLES.md                   # Detailed usage examples
│   └── CHANGELOG.md                  # Version history
│
├── config/                           # Configuration files
│   └── claude_desktop_config.example.json # Claude Desktop example config
│
├── troubleshooting_mcp.py            # Backward compatibility entry point
├── setup.py                          # Package setup script
├── pyproject.toml                    # Modern Python project configuration
├── requirements.txt                  # Python dependencies
├── .gitignore                        # Git ignore rules
├── LICENSE                           # MIT License
└── README.md                         # This file

🎯 关键设计原则

1. 模块化架构：每个诊断工具都有自己的模块，便于维护和测试
2. 明确分离：为了清楚起见，常量、模型、实用程序和工具是分开的
3. 向后兼容：根 troubleshooting_mcp.py 保持与现有配置的兼容性
4. 可安装包：可以安装 pip install -e . 用于全系统访问
5. 类型安全：使用Pydantic v2进行全面的输入验证
6. 安全第一：严格的白名单、超时保护和输入验证贯穿始终

______________________________________________________________________

🚀 快速开始

1.️⃣ 安装依赖项（1分钟）

# Navigate to the project directory
cd troubleshooting_mcp

# Install required packages
pip install -r requirements.txt

# Or install as a package (recommended)
pip install -e .

2.️⃣ 测试服务器（1分钟）

# Method 1: Run directly (backward compatible)
python troubleshooting_mcp.py --help

# Method 2: Run as module
python -m troubleshooting_mcp.server --help

# Method 3: If installed as package
troubleshooting-mcp --help

# Run validation tests
python tests/test_server.py

3.️⃣ 配置Claude桌面（2分钟）

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "troubleshooting": {
      "command": "python",
      "args": ["/absolute/path/to/troubleshooting_mcp.py"]
    }
  }
}

替代方案（如果作为软件包安装）：

{
  "mcpServers": {
    "troubleshooting": {
      "command": "troubleshooting-mcp"
    }
  }
}

4.️⃣ 重新启动克劳德桌面

1. 完全退出克劳德桌面
2. 重新启动克劳德桌面
3. 寻找🔌 指示MCP服务器已连接的图标

______________________________________________________________________

📦 安装方法

方法1：直接使用（无需安装）

python troubleshooting_mcp.py

优点：简单，无需安装 缺点：系统范围内无法访问

方法2：可编辑安装（开发）

pip install -e .
troubleshooting-mcp

优点：全系统访问，易于修改，自动更新 缺点：需要安装pip

方法3：标准安装（生产）

pip install .
troubleshooting-mcp

优点：清洁安装，全系统访问 缺点：更改后需要重新安装

方法4：模块执行

python -m troubleshooting_mcp.server

优点：无需安装，Python模块语法正确 缺点：需要位于父目录中

______________________________________________________________________

🛠 可用工具

有关详细的工具文档和示例，请参阅 docs/EXAMPLES.md.

______________________________________________________________________

⚙️ 配置

依赖项

• mcp>=1.0.0 -带FastMCP框架的MCP Python SDK
• psutil>=5.9.0 -系统和过程监控
• pydantic>=2.0.0 -输入验证

环境变量

服务器遵循标准的Python环境变量：

• PYTHONPATH -用于模块分辨率
• PATH -用于定位诊断命令

定制

日志路径： 编辑 src/troubleshooting_mcp/constants.py:

COMMON_LOG_PATHS = [
    "/var/log/syslog",
    "/custom/app/logs/error.log",
    # Add your custom paths
]

安全命令： 编辑 src/troubleshooting_mcp/constants.py:

SAFE_COMMANDS = {
    "ping", "traceroute", "netstat",
    # Add approved commands only
}

字符限制： 编辑 src/troubleshooting_mcp/constants.py:

CHARACTER_LIMIT = 25000  # Adjust as needed

______________________________________________________________________

🔒 安全

命令白名单

只能执行预先批准的诊断命令。白名单包括常见的故障排除工具，但不包括任何可能：

• 修改系统状态
• 删除或覆盖文件
• 更改权限
• 安装软件
• 执行任意代码

默认白名单： ping, traceroute, nslookup, dig, netstat, ss, ip, ifconfig, df, du, free, uptime, uname, lsblk, lsof, whoami, hostname

超时保护

所有长时间运行的操作都有可配置的超时：

• 命令执行：默认30秒，最长300秒
• 网络测试：默认5秒，最多30秒

权限处理

• 无特权升级
• 清除拒绝权限场景的错误消息
• 在可能的情况下进行只读操作

输入验证

所有输入均使用Pydantic模型进行验证，该模型具有：

• 类型检查
• 范围限制
• 模式验证
• 白名单验证

______________________________________________________________________

💻 发展

设置开发环境

# Clone the repository
git clone 
cd troubleshooting_mcp

# Create virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e .

# Run tests
python tests/test_server.py

添加新工具

1. 创建新工具模块 在 src/troubleshooting_mcp/tools/:

# src/troubleshooting_mcp/tools/my_tool.py
def register_my_tool(mcp):
    @mcp.tool(name="troubleshooting_my_tool", annotations={...})
    async def troubleshooting_my_tool(params: MyInput) -> str:
        # Implementation
        pass

1. 添加输入模型 在 src/troubleshooting_mcp/models.py:

class MyInput(BaseModel):
    model_config = ConfigDict(str_strip_whitespace=True)
    param: str = Field(..., description="...")

1. 在工具包中注册 src/troubleshooting_mcp/tools/__init__.py:

from .my_tool import register_my_tool

def register_all_tools(mcp):
    # ... existing registrations ...
    register_my_tool(mcp)

代码的风格

• 遵循PEP 8风格指南
• 在适当的情况下使用类型提示
• 为所有函数添加全面的文档字符串
• 保持工具模块化和专注
• 使用共享实用程序功能

测试

# Run all tests
python tests/test_server.py

# Test specific functionality
python -c "from src.troubleshooting_mcp import mcp; print('Import successful')"

______________________________________________________________________

📚 文档

______________________________________________________________________

🎯 示例用法

在Claude Desktop中配置后，请尝试以下提示：

系统诊断

"What operating system and hardware does this machine have?"
"Show me current CPU and memory usage"

日志分析

"What log files are available on this system?"
"Search nginx error logs for 500 errors in the last 200 lines"

网络测试

"Can this server reach google.com?"
"Test if port 443 is open on api.example.com"

流程管理

"Is docker running on this system?"
"Show me the top 10 processes by CPU usage"

环境检查

"What development tools are installed?"
"Show me all AWS-related environment variables"

______________________________________________________________________

🐛 故障排除

服务器未出现在Claude桌面中

1. 检查配置中的文件路径是否为绝对路径
2. 验证JSON语法（无尾随逗号）
3. 检查克劳德桌面日志：

- macOS： ~/Library/Logs/Claude/mcp*.log - 窗户： %APPDATA%\Claude\logs\mcp*.log

“找不到模块”错误

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e .

“找不到命令”错误

# Check Python is in PATH
which python  # macOS/Linux
where python  # Windows

# Or use full path in config
# "command": "/usr/bin/python3"  # macOS/Linux
# "command": "C:/Python310/python.exe"  # Windows

______________________________________________________________________

🤝 贡献

欢迎投稿！贡献时：

1. 遵循现有的代码风格和模块化架构
2. 添加全面的文档字符串和类型提示
3. 包括使用Pydantic进行输入验证
4. 实施适当的错误处理
5. 更新文档
6. 在多个平台（Linux、macOS、Windows）上进行测试

______________________________________________________________________

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

构建使用：

• 模型上下文协议（MCP） 通过Anthropic
• FastMCP -Python MCP SDK
• psutil -系统监控库
• 派丹蒂克 -数据验证

______________________________________________________________________

📞 支持

对于问题、疑问或建议：

• 查看上面的故障排除部分
• 检查 快速启动指南
• 审查 示例文档
• 检查MCP文件：https://modelcontextprotocol.io/

______________________________________________________________________

专为开发人员和系统管理员设计

*最后更新时间：2025-11-05 |版本：1.0.0*