Linux 诊断 MCP 服务器 - 课程演示

这是原始 MCPDemo 教学仓库的 Python/Linux 适配版本。该仓库现已达到公共教学流程的 Milestone 4 同步：紧凑的系统检查、Linux 进程深入分析、作为资源的日志快照、工作流提示，以及通过 /mcp 进行的 HTTP 认证 MCP 通信。

本演示展示的内容

本课程演示现包含：

• ✅ 工具：用于 get_system_info、get_process_list、get_process_by_id 和 get_process_by_name 的只读 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

• ✅ 多种测试方法

• ⏳ 启发、采样和根节点：计划在后续版本中加入

快速入门

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. 运行系统、进程和日志快照流程

7. 验证当缺少 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

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

日志快照

• 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} - 读取存储快照中的特定页面

每次资源读取都会返回：

• 快照元数据

• 捕获的行

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

提示

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

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

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

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

项目

src/mcp_linux_diag_server/server.py

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

src/mcp_linux_diag_server/client.py

课程聊天客户端，它：

• 启动本地 HTTP 服务器

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

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

• 执行工具调用回合

测试方法

有关作为基础教学流程支撑的 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
│           ├── 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+ - 启发、采样和根节点

许可证

MIT。请参阅 LICENSE.txt。

资源

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• 原始 C# MCPDemo