Splunk MCP(모델 컨텍스트 프로토콜) 도구

자연어를 통해 Splunk Enterprise/Cloud와 상호 작용하는 FastMCP 기반 도구입니다. 이 도구는 직관적인 인터페이스를 통해 Splunk 데이터 검색, KV 저장소 관리, Splunk 리소스 접근 등의 기능을 제공합니다.

작동 모드

이 도구는 세 가지 모드로 작동합니다.

1. SSE 모드 (기본값)
   • 서버에서 보낸 이벤트 기반 통신
   • 실시간 양방향 상호작용
   • 웹 기반 MCP 클라이언트에 적합
   • 인수가 제공되지 않을 경우 기본 모드
   • /sse 엔드포인트를 통해 액세스
2. API 모드
   • RESTful API 엔드포인트
   • /api/v1 엔드포인트 접두사를 통해 액세스
   • python splunk_mcp.py api 로 시작하세요
3. STDIO 모드
   • 표준 입출력 기반 통신
   • Claude Desktop 및 기타 MCP 클라이언트와 호환 가능
   • AI 어시스턴트와의 직접 통합에 이상적
   • python splunk_mcp.py stdio 로 시작하세요

특징

• Splunk 검색 : 자연어 쿼리로 Splunk 검색 실행
• 인덱스 관리 : Splunk 인덱스 나열 및 검사
• 사용자 관리 : Splunk 사용자를 보고 관리합니다.
• KV 매장 운영 : KV 매장 컬렉션을 생성, 나열 및 관리합니다.
• 비동기 지원 : 더 나은 성능을 위해 비동기/대기 패턴으로 구축됨
• 상세 로깅 : 더 나은 가시성을 위한 이모티콘 표시기가 포함된 포괄적인 로깅
• SSL 구성 : 다양한 보안 요구 사항에 맞는 유연한 SSL 검증 옵션
• 향상된 디버깅 : 문제 해결을 위한 자세한 연결 및 오류 로깅
• 종합 테스트 : 모든 주요 기능을 포괄하는 단위 테스트
• 오류 처리 : 적절한 상태 코드를 사용한 강력한 오류 처리
• SSE 준수 : MCP SSE 사양을 완벽하게 준수합니다.

사용 가능한 MCP 도구

다음 도구는 MCP 인터페이스를 통해 사용할 수 있습니다.

도구 관리

• 목록_도구
  • 사용 가능한 모든 MCP 도구와 해당 설명 및 매개변수를 나열합니다.

건강 검진

• 건강 검진
  • 연결을 확인하기 위해 사용 가능한 Splunk 앱 목록을 반환합니다.
• 핑
  • MCP 서버가 활성 상태인지 확인하기 위한 간단한 ping 엔드포인트

사용자 관리

• 현재 사용자
  • 현재 인증된 사용자에 대한 정보를 반환합니다.
• 사용자 목록
  • 모든 사용자와 해당 역할의 목록을 반환합니다.

인덱스 관리

• 리스트_인덱스
  • 접근 가능한 모든 Splunk 인덱스 목록을 반환합니다.
• 인덱스 정보 가져오기
  • 특정 인덱스에 대한 자세한 정보를 반환합니다.
  • 매개변수: index_name(문자열)
• 인덱스 및 소스 유형
  • 인덱스와 해당 소스 유형의 포괄적인 목록을 반환합니다.

찾다

• 검색_스플렁크
  • Splunk 검색 쿼리를 실행합니다.
  • 매개변수:
    • search_query(문자열): Splunk 검색 문자열
    • earliest_time(문자열, 선택 사항): 검색 창의 시작 시간
    • latest_time(문자열, 선택 사항): 검색 창의 종료 시간
    • max_results(정수, 선택 사항): 반환할 최대 결과 수
• 저장된 검색 목록
  • Splunk 인스턴스에 저장된 검색 목록을 반환합니다.

KV 스토어

• 목록_kvstore_collections
  • 모든 KV 매장 컬렉션을 나열합니다
• create_kvstore_collection
  • 새로운 KV 매장 컬렉션을 만듭니다.
  • 매개변수: collection_name(문자열)
• 삭제_kvstore_collection
  • 기존 KV 스토어 컬렉션을 삭제합니다.
  • 매개변수: collection_name(문자열)

SSE 엔드포인트

SSE 모드에서 실행할 경우 다음 엔드포인트를 사용할 수 있습니다.

• /sse : SSE 연결 정보를 텍스트/이벤트 스트림 형식으로 반환합니다.
  • SSE 연결에 대한 메타데이터를 제공합니다.
  • 메시지 엔드포인트에 대한 URL이 포함됩니다.
  • 프로토콜 및 기능 정보를 제공합니다.
• /sse/messages : 주요 SSE 스트림 엔드포인트
  • 하트비트와 같은 스트림 시스템 이벤트
  • 지속적인 연결을 유지합니다
  • 올바르게 포맷된 SSE 이벤트를 보냅니다.
• /sse/health : SSE 모드에 대한 상태 점검 엔드포인트
  • SSE 형식으로 상태 및 버전 정보를 반환합니다.

오류 처리

MCP 구현에는 일관된 오류 처리가 포함됩니다.

• 잘못된 검색 명령 또는 잘못된 요청
• 권한이 부족합니다
• 리소스를 찾을 수 없습니다
• 잘못된 입력 검증
• 예상치 못한 서버 오류
• Splunk 서버 연결 문제

모든 오류 응답에는 오류를 설명하는 자세한 메시지가 포함됩니다.

필수 조건

• Python 3.10 이상
• 의존성 관리를 위한 시
• Splunk Enterprise/Cloud 인스턴스
• 필요한 권한이 있는 적절한 Splunk 자격 증명

설치

옵션 1: 로컬 설치

1. 저장소를 복제합니다.

지엑스피1

2. Poetry를 사용하여 종속성을 설치합니다.

3. 예제 환경 파일을 복사하고 설정을 구성하세요.

4. Splunk 자격 증명으로 .env 파일을 업데이트합니다.

옵션 2: Docker 설치

1. 최신 이미지를 가져옵니다.

2. 위와 같이 .env 파일을 만들거나 환경 변수를 직접 사용하세요.
3. Docker Compose를 사용하여 실행:

또는 Docker를 직접 사용하는 방법:

용법

지역 사용

이 도구는 세 가지 모드로 실행될 수 있습니다.

1. SSE 모드(MCP 클라이언트의 기본값):

3. STDIO 모드:

Docker 사용법

이 프로젝트는 새로운 docker compose (V2)와 기존 docker-compose (V1) 명령을 모두 지원합니다. 아래 예시에서는 V2 구문을 사용하지만, 두 명령 모두 지원됩니다.

1. SSE 모드(기본값):

2. API 모드:

3. STDIO 모드:

Docker로 테스트하기

이 프로젝트에는 Docker의 전용 테스트 환경이 포함되어 있습니다.

1. 모든 테스트를 실행합니다.

2. 특정 테스트 구성 요소를 실행합니다.

테스트 결과는 ./test-results 디렉토리에서 확인할 수 있습니다.

Docker 개발 팁

1. 건물 이미지 :

2. 로그 보기 :

3. 디버깅 :

참고: Docker Compose V1을 사용하는 경우 위 명령에서 docker compose docker-compose 로 바꾸세요.

보안 참고 사항

1. 환경 변수 :

• .env 파일을 커밋하지 마세요
• .env.example 템플릿으로 사용하세요
• 프로덕션에 Docker 비밀을 사용하는 것을 고려하세요

2. SSL 검증 :

• 프로덕션에는 VERIFY_SSL=true 권장됩니다.
• 개발/테스트를 위해 비활성화할 수 있습니다.
• 환경 변수를 통해 구성

3. 포트 노출 :

• 필요한 포트만 노출하세요
• 가능하면 내부 Docker 네트워크를 사용하세요
• 프로덕션에서 네트워크 보안을 고려하세요

환경 변수

다음 환경 변수를 구성하세요.

• SPLUNK_HOST : Splunk 호스트 주소
• SPLUNK_PORT : Splunk 관리 포트(기본값: 8089)
• SPLUNK_USERNAME : Splunk 사용자 이름
• SPLUNK_PASSWORD : Splunk 비밀번호
• SPLUNK_SCHEME : 연결 방식(기본값: https)
• VERIFY_SSL : SSL 검증을 활성화/비활성화합니다(기본값: true)
• FASTMCP_LOG_LEVEL : 로깅 수준(기본값: INFO)
• SERVER_MODE : uvicorn을 사용할 때의 서버 모드(sse, api, stdio)

SSL 구성

이 도구는 유연한 SSL 검증 옵션을 제공합니다.

1. 기본(보안) 모드 :

• 전체 SSL 인증서 검증
• 호스트 이름 확인이 활성화되었습니다.
• 프로덕션 환경에 권장됨

2. 편안한 모드 :

• SSL 인증서 검증이 비활성화되었습니다.
• 호스트 이름 확인이 비활성화되었습니다.
• 테스트 또는 자체 서명 인증서에 유용합니다.

테스트

이 프로젝트에는 pytest를 사용한 포괄적인 테스트 범위와 사용자 정의 MCP 클라이언트를 사용한 종단 간 테스트가 포함됩니다.

테스트 실행

기본 테스트 실행:

보도 보고를 통해:

자세한 출력:

종단 간 SSE 테스트

이 프로젝트에는 라이브 SSE 엔드포인트에 연결하고 모든 도구를 테스트하는 사용자 지정 MCP 클라이언트 테스트 스크립트가 포함되어 있습니다.

이 스크립트는 다음과 같은 MCP 클라이언트 역할을 합니다.

1. /sse 엔드포인트에 연결하여 메시지 URL을 가져옵니다.
2. 메시지 엔드포인트에 도구 호출 보내기
3. SSE 이벤트를 처리하여 도구 결과 추출
4. 예상 형식에 대한 결과 검증

이는 실제 MCP 클라이언트에서 사용되는 SSE 인터페이스에 대한 실제 테스트를 제공합니다.

테스트 구조

이 프로젝트에서는 세 가지 상호 보완적인 테스트 접근 방식을 사용합니다.

1. MCP 통합 테스트 ( tests/test_api.py ) :
   • mcp.call_tool() 을 통해 MCP 도구 인터페이스를 테스트합니다.
   • FastMCP로 적절한 도구 등록을 확인합니다.
   • 올바른 응답 형식과 데이터 구조를 보장합니다.
   • MCP 인터페이스 수준에서 오류 처리를 검증합니다.
   • 참고: 이 파일은 목적을 더 잘 반영하기 위해 이상적으로 test_mcp.py 로 이름을 바꾸는 것이 좋습니다.
2. 직접 기능 테스트 ( tests/test_endpoints_pytest.py ) :
   • Splunk 기능을 직접 테스트합니다(MCP 계층을 우회)
   • 함수 구현 세부 사항에 대한 보다 포괄적인 적용 범위 제공
   • 테스트 에지 케이스, 매개변수 변형 및 오류 처리
   • SSL 구성, 연결 매개변수 및 시간 초과에 대한 테스트가 포함됩니다.
   • 효율적인 테스트 적용을 위해 매개변수화된 테스트를 사용합니다.
3. 종단간 MCP 클라이언트 테스트 ( test_endpoints.py ) :
   • SSE 엔드포인트에 연결하는 실제 MCP 클라이언트처럼 동작합니다.
   • 연결에서 도구 호출, 응답 구문 분석까지의 전체 흐름을 테스트합니다.
   • 실제 SSE 프로토콜 구현을 검증합니다.
   • 실제 매개변수를 사용하여 라이브 서버에 대한 테스트 도구
4. 구성 테스트 ( tests/test_config.py ) :
   • 환경 변수 구문 분석 테스트
   • SSL 검증 설정
   • 연결 매개변수 검증

테스트 도구

테스트는 다음을 지원합니다.

• pytest-asyncio를 사용한 비동기 테스트
• pytest-cov를 사용한 커버리지 보고
• pytest-mock으로 모킹하기
• 매개변수화된 테스트
• 연결 시간 초과 테스트

문제 해결

연결 문제

1. 기본 연결성 :

• 이제 도구는 기본 TCP 연결 테스트를 수행합니다.
• 포트 8089에 접근 가능한지 확인하세요
• 네트워크 라우팅 및 방화벽 확인

2. SSL 문제 :

• SSL 오류가 표시되면 VERIFY_SSL=false 설정해보세요.
• 인증서 유효성 및 신뢰 체인 확인
• 호스트 이름이 인증서와 일치하는지 확인하세요

3. 인증 문제 :

• Splunk 자격 증명 확인
• 사용자 권한 확인
• 계정이 잠기지 않았는지 확인하세요

4. 디버깅 :

• 자세한 로그를 보려면 FASTMCP_LOG_LEVEL=DEBUG 설정하세요.
• 특정 오류 메시지에 대한 연결 로그를 확인하세요.
• SSL 구성 메시지 검토

5. SSE 연결 문제 :

• /sse 를 통해 SSE 엔드포인트에 액세스할 수 있는지 확인하세요.
• 적절한 콘텐츠 유형 헤더를 확인하세요
• 브라우저 개발자 도구를 사용하여 SSE 연결을 검사합니다.

클로드 통합

클로드 데스크톱 구성

Splunk MCP를 Claude Desktop과 통합하려면 SSE 또는 STDIO 모드를 사용하도록 설정하세요. claude_desktop_config.json 파일에 다음 설정을 추가하세요.

STDIO 모드(데스크톱에 권장)

SSE 모드

Claude와 함께 사용

구성이 완료되면 Claude를 통해 자연어를 사용하여 Splunk와 상호 작용할 수 있습니다. 예:

1. 사용 가능한 인덱스 나열:

2. Splunk 데이터 검색:

3. 시스템 상태 확인:

4. KV 매장 관리:

MCP 도구는 Claude에게 자동으로 제공되어 자연어 명령을 통해 이러한 작업을 실행할 수 있습니다.

특허

[여기에 라이센스가 있습니다]

감사의 말

• FastMCP 프레임워크
• Python용 Splunk SDK
• 구성 관리를 위한 Python 분리
• SSE 구현을 위한 SSE Starlette