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 채팅 클라이언트: 로컬 HTTP 서버를 실행하고 모델이 MCP 도구, 프롬프트 및 리소스를 호출할 수 있게 하는 Python Azure OpenAI 클라이언트

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

• ✅ 다양한 테스트 방법

• ⏳ 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. 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 런타임

  • 현재 작업 디렉토리

  • 가동 시간(Uptime)

  • 부하 평균(Load averages)

  • 메모리 요약

  • 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

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

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+ - Elicitation, sampling, roots

라이선스

MIT. LICENSE.txt를 참조하세요.

리소스

• Model Context Protocol

• MCP Inspector

• Azure OpenAI

• 기존 C# MCPDemo