MCP-сервер диагностики Linux — Демонстрация лекции

Адаптация оригинального учебного репозитория MCPDemo для Python/Linux. Этот репозиторий теперь достигает паритета с Milestone 4 для публичного учебного потока: компактная проверка системы, детальный анализ процессов Linux, снимки журналов в качестве ресурсов, рабочие процессы и аутентифицированный MCP по HTTP на /mcp.

Что показывает эта демонстрация

Эта лекционная демонстрация теперь включает:

• ✅ Инструменты: инструменты диагностики Linux только для чтения для get_system_info, get_process_list, get_process_by_id и get_process_by_name

• ✅ Ресурсы: постраничные ресурсы снимков журналов syslog://snapshot/...

• ✅ Подсказки (Prompts): рабочие процессы MCP для анализа ошибок, исследования загрузки ЦП, проверки безопасности и диагностики состояния системы

• ✅ HTTP-транспорт: потоковый MCP через http://127.0.0.1:5000/mcp

• ✅ Аутентификация по API-ключу: заголовок X-API-Key или ?apiKey=secure-mcp-key

• ✅ Клиент чата с ИИ: клиент Python Azure OpenAI, который запускает локальный HTTP-сервер и позволяет модели вызывать инструменты, подсказки и ресурсы MCP

• ✅ Реализация на Python 3.12 с использованием официального SDK MCP для Python

• ✅ Несколько методов тестирования

• ⏳ Выявление (Elicitation), выборка (sampling) и корни (roots) запланированы на будущее

Быстрый старт

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. Проверяет 401 Unauthorized без API-ключа

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"
      }
    }
  }
}

Если ваш инспектор принимает 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

  • Версия ядра

  • Архитектура

  • Количество логических процессоров

  • Среда выполнения Python

  • Текущая рабочая директория

  • Время работы (uptime)

  • Средняя нагрузка

  • Сводка по памяти

  • Флаг обнаружения WSL

Инспекция процессов

• get_process_list — Возвращает облегченный список запущенных процессов с именами и PID

• get_process_by_id — Возвращает подробную информацию о процессе Linux для одного PID

• 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)

Подсказки (Prompts)

• AnalyzeRecentApplicationErrors — Рабочий процесс анализа журналов, сфокусированный на ошибках

• ExplainHighCpu — Сопоставление процессов с высокой нагрузкой на ЦП с журналами Linux

• DetectSecurityAnomalies — Проверка подозрительных процессов плюс доказательства из журналов аутентификации/безопасности

• DiagnoseSystemHealth — Сквозной рабочий процесс диагностики состояния системы

Проекты

src/mcp_linux_diag_server/server.py

Аутентифицированный HTTP-сервер MCP, предоставляющий инструменты диагностики Milestone 1-4, ресурсы журналов и рабочие процессы.

src/mcp_linux_diag_server/client.py

Клиент чата для лекции, который:

• запускает локальный HTTP-сервер

• подключается через потоковый HTTP с демонстрационным API-ключом

• предоставляет API подсказок/ресурсов MCP в качестве вспомогательных инструментов для модели

• выполняет вызовы инструментов

Методы тестирования

Для контрольного списка проверки 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 только если вы хотите запустить клиент чата для лекции

Этапы (Milestones)

✅ Milestone 1 - Минимальный инструмент диагностики через stdio плюс клиент чата для лекции
✅ Milestone 2 - Инспекция процессов
✅ Milestone 3 - Ресурсы снимков журналов и подсказки
✅ Milestone 4 - HTTP-транспорт и безопасность
⏳ Milestone 5+ - Выявление, выборка и корни

Лицензия

MIT. См. LICENSE.txt.

Ресурсы

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• Оригинальный C# MCPDemo