Linux 诊断 MCP 服务器 - 讲座演示

这是原始 MCPDemo 教学仓库的 Python/Linux 适配版本。该仓库现已达到公共教学流程的 Milestone 7 同步：紧凑的系统检查、Linux 进程深入分析、作为资源的日志快照、工作流提示、基于 /mcp 的 HTTP 认证 MCP、进程终止前的显式征询、采样辅助的 Linux 诊断，以及允许的 root 级 /proc 和 /sys 快照。

此演示展示的内容

此讲座演示现包含：

• ✅ 工具：用于 get_system_info、get_process_list、get_process_by_id、get_process_by_name 以及受征询保护的 kill_process 的 Linux 诊断工具

• ✅ 资源：分页的 syslog://snapshot/... 日志快照资源

• ✅ 提示：用于错误分析、CPU 调查、安全审查和健康诊断的 MCP 工作流提示

• ✅ HTTP 传输：基于 http://127.0.0.1:5000/mcp 的可流式传输 MCP

• ✅ API 密钥认证：X-API-Key 请求头或 ?apiKey=secure-mcp-key

• ✅ AI 聊天客户端：一个 Python Azure OpenAI 客户端，它启动本地 HTTP 服务器，允许模型调用 MCP 工具、提示和资源，并在终端处理本地表单征询

• ✅ Python 3.12 实现，使用官方 MCP Python SDK

• ✅ 多种测试方法

• ✅ Milestone 5：针对 kill_process 的征询功能

• ✅ Milestone 6：采样辅助的 Linux 诊断

• ✅ Milestone 7：用于只读 /proc 和 /sys 快照的根目录

Related MCP server: Linux MCP Server

快速入门

1. 安装

仅服务器安装：

python3 -m pip install --user --break-system-packages -e .

安装讲座聊天客户端扩展：

python3 -m pip install --user --break-system-packages -e '.[llm]'

2. 快速冒烟测试（无 LLM）

python3 scripts/smoke_test.py

此脚本：

1. 启动本地 HTTP MCP 服务器

2. 验证没有 API 密钥时返回 401 Unauthorized

3. 在 /mcp 上执行 MCP 初始化握手

4. 确认 mcp-session-id 流程在请求间正常工作

5. 发现工具、提示和资源模板

6. 练习系统、进程、日志快照、proc 快照和采样辅助诊断流程

7. 验证当客户端未声明支持征询时，kill_process 能安全失败

8. 验证当缺少 Azure OpenAI 设置时，讲座聊天客户端能安全失败

3. 手动运行服务器

python3 -m mcp_linux_diag_server

服务器监听地址：

• 端点：http://127.0.0.1:5000/mcp

• 演示 API 密钥：secure-mcp-key

4. 使用 MCP Inspector 或 VS Code MCP 配置进行测试

在一个终端中启动服务器，然后使用上述 HTTP 端点进行连接。

此仓库包含带有必需请求头的 .vscode/mcp.json：

{
  "servers": {
    "linux-diag-demo": {
      "url": "http://127.0.0.1:5000/mcp",
      "headers": {
        "X-API-Key": "secure-mcp-key"
      }
    }
  }
}

如果您的 inspector 直接接受 URL，这种查询字符串形式也适用：

http://127.0.0.1:5000/mcp?apiKey=secure-mcp-key

5. 使用讲座聊天客户端

复制示例环境文件并填入您的本地 Azure OpenAI 设置：

cp .env.example .env.local
$EDITOR .env.local
python3 -m mcp_linux_diag_server.client --prompt "Summarize this machine."

要更紧密地模拟原始 .NET 凭据流程，请设置：

MCP_DEMO_AZURE_OPENAI_USE_DEFAULT_CREDENTIAL=true

并省略 API 密钥。

运行交互式聊天：

python3 -m mcp_linux_diag_server.client

或运行单个提示：

python3 -m mcp_linux_diag_server.client --prompt "What is the system information?"

工具

系统信息

• get_system_info - 返回紧凑的 Linux 或 WSL 系统快照

  • 主机名

  • 当前用户

  • Linux 发行版描述

  • 内核版本

  • 架构

  • 逻辑 CPU 数量

  • Python 运行时

  • 当前工作目录

  • 运行时间

  • 平均负载

  • 内存摘要

  • WSL 检测标志

进程检查

• get_process_list - 返回包含名称和 PID 的轻量级运行进程列表

• get_process_by_id - 返回单个 PID 的详细 Linux 进程信息

• get_process_by_name - 返回进程名称的分页详细进程信息

  • 默认 page_number=1

  • 默认 page_size=5

  • 保留了原始演示中“先列表，后详情”的教学流程

• kill_process - 仅在明确征询后终止 Linux 进程

  • 如果省略 process_id，服务器会采样 CPU 占用最高的进程并要求客户端选择一个

  • 服务器始终要求输入确认短语 CONFIRM PID {pid}

  • 当 stdin/stdout 为交互式时，讲座客户端会在终端本地处理这些提示

• troubleshoot_linux_diagnostics - 使用采样将自然语言 Linux 诊断问题转换为经过验证的 /proc 或 /sys 读取操作

  • 服务器在读取任何内容之前，会根据允许列表验证采样的路径和字段

  • 精确的 Python 适配：采样的查询是单个安全的 PATH 或 PATH | grep FIELD 行，而不是 WQL

  • 服务器随后再次采样，将观察结果总结反馈给用户

• create_proc_snapshot - 从允许的 /proc 或 /sys 路径创建不可变的只读快照，并返回资源 URI

  • 文件快照逐行分页内容

  • 目录快照在不跟踪符号链接的情况下分页确定性的子项元数据

  • 在读取任何内容之前强制执行明确的允许根目录

• request_proc_access - 使用征询来请求对额外的 /proc 或 /sys 根目录的只读访问权限

  • 将批准的根目录添加到服务器的内存允许列表中

  • 允许模型在尝试被阻止的快照操作之前主动请求访问权限

日志快照

• create_log_snapshot - 从常见的 Linux 日志文件创建不可变快照，并返回资源 URI

  • 支持 system、security、kernel 和 package 日志组

  • 可选的 filter_text 将快照缩小到匹配的行

  • 返回基础资源 URI 加上分页资源模板

资源

• syslog://snapshot/{snapshot_id} - 读取带有默认分页的存储 Linux 日志快照

• syslog://snapshot/{snapshot_id}?limit={limit}&offset={offset} - 读取存储快照的特定页面

• proc://snapshot/{snapshot_id} - 读取带有默认分页的存储 proc/sys 快照

• proc://snapshot/{snapshot_id}?limit={limit}&offset={offset} - 读取存储 proc/sys 快照的特定页面

每个资源读取都会返回：

• 快照元数据

• 捕获的条目

• 分页元数据 (total_count, returned_count, limit, offset, has_more, next_offset)

提示

• AnalyzeRecentApplicationErrors - 以错误为中心的日志分析工作流

• ExplainHighCpu - 将高 CPU 占用进程与 Linux 日志关联

• DetectSecurityAnomalies - 审查可疑进程以及身份验证/安全日志证据

• DiagnoseSystemHealth - 端到端系统健康工作流

• TroubleshootLinuxComponent - 引导代理使用 troubleshoot_linux_diagnostics 的深度分析工作流

项目

src/mcp_linux_diag_server/server.py

经过身份验证的 HTTP MCP 服务器，公开了 Milestone 1-7 的诊断工具、资源和工作流提示。

src/mcp_linux_diag_server/client.py

讲座聊天客户端，它：

• 启动本地 HTTP 服务器

• 使用演示 API 密钥通过可流式传输的 HTTP 进行连接

• 将 MCP 提示/资源 API 作为模型的辅助工具公开

• 当模型触发 kill_process 时，在本地终端完成 MCP 表单征询

• 完成 MCP 采样请求，以便服务器可以合成安全的 Linux 诊断查询和摘要

• 教导模型在对被阻止的路径进行快照之前请求 proc/sys 访问权限

• 执行工具调用回合

测试方法

有关仍支撑基础讲座流程的 Milestone 1 验证清单，请参阅 M1_VALIDATION_GUIDE.md。

项目结构

MCPPythonDemo/
├── README.md
├── LICENSE.txt
├── pyproject.toml
├── .env.example
├── .vscode/
│   └── mcp.json
├── scripts/
│   └── smoke_test.py
├── src/
│   └── mcp_linux_diag_server/
│       ├── __main__.py
│       ├── client.py
│       ├── http_config.py
│       ├── server.py
│       └── tools/
│           ├── log_snapshots.py
│           ├── proc_snapshots.py
│           ├── processes.py
│           └── system_info.py
├── tests/
│   ├── http_harness.py
│   ├── test_client.py
│   ├── test_m1_smoke.py
│   ├── test_m2_smoke.py
│   ├── test_m3_smoke.py
│   ├── test_m4_http.py
│   ├── test_log_snapshots.py
│   ├── test_processes.py
│   └── test_system_info.py

要求

• Python 3.12+

• mcp[cli]

• 仅在需要运行讲座聊天客户端时需要 Azure OpenAI

里程碑

✅ Milestone 1 - 基于 stdio 的最小诊断工具及讲座聊天客户端 ✅ Milestone 2 - 进程检查 ✅ Milestone 3 - 日志快照资源和提示 ✅ Milestone 4 - HTTP 传输和安全性 ✅ Milestone 5 - 基于征询的 kill_process ✅ Milestone 6 - 采样辅助的 Linux 诊断 ✅ Milestone 7 - 根目录和 proc/sys 快照

许可证

MIT。请参阅 LICENSE.txt。

资源

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• 原始 C# MCPDemo