Linux 진단 MCP 서버 - 강의 데모

기존 MCPDemo 교육용 저장소를 Python/Linux 환경에 맞게 개조한 버전입니다. 이 저장소는 공개 교육 흐름을 위한 Milestone 7 패리티에 도달했습니다: 간결한 시스템 검사, Linux 프로세스 상세 분석, 리소스 형태의 로그 스냅샷, 워크플로우 프롬프트, /mcp 경로를 통한 HTTP 기반 인증된 MCP, 프로세스 종료 전 명시적 확인 절차, 샘플링 지원 Linux 진단, 그리고 허용된 루트에 대한 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 채팅 클라이언트: 로컬 HTTP 서버를 실행하고, 모델이 MCP 도구, 프롬프트 및 리소스를 호출하도록 하며, 터미널에서 로컬 폼 확인 절차를 처리하는 Python Azure OpenAI 클라이언트

• ✅ Python 3.12 구현: 공식 MCP Python SDK 사용

• ✅ 다양한 테스트 방법

• ✅ Milestone 5: kill_process를 위한 확인 절차

• ✅ Milestone 6: 샘플링 지원 Linux 진단

• ✅ 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. 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 적용: 샘플링된 쿼리는 WQL 대신 단일 안전 PATH 또는 PATH | grep FIELD 라인임

  • 서버는 다시 샘플링하여 관찰 결과를 사용자에게 요약

• 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

Milestone 1-7 진단 도구, 리소스 및 워크플로우 프롬프트를 노출하는 인증된 HTTP MCP 서버.

src/mcp_linux_diag_server/client.py

다음 기능을 수행하는 강의용 채팅 클라이언트:

• 로컬 HTTP 서버 실행

• 데모 API 키를 사용하여 스트리밍 가능한 HTTP로 연결

• 모델을 위한 도구로서 MCP 프롬프트/리소스 API 노출

• 모델이 kill_process를 트리거할 때 로컬 터미널에서 MCP 폼 확인 절차 수행

• 서버가 안전한 Linux 진단 쿼리 및 요약을 합성할 수 있도록 MCP 샘플링 요청 수행

• 차단된 경로를 스냅샷으로 찍기 전에 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