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

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

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

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

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

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

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

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

• ✅ Множественные методы тестирования

• ✅ Подтверждение Milestone 5 для kill_process

• ✅ Диагностика Linux с помощью сэмплирования (Milestone 6)

• ✅ Корневые пути Milestone 7 для снимков /proc и /sys только для чтения

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

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

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

  • Сохраняет учебный поток «сначала список, потом детали» из оригинальной демонстрации

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

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

• 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-сервер

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

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

• выполняет подтверждение форм MCP в локальном терминале, когда модель запускает kill_process

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

Вехи (Milestones)

✅ 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