MCP Observer Server

mcp-observer-server

mcp-observer-server 파일 시스템 이벤트를 모니터링하고 MCP 클라이언트에 실시간 알림을 제공하는 MCP(Model Context Protocol) 서버입니다. 로컬 파일 시스템과 다음과 같은 AI 어시스턴트 간의 (양방향) 브리지 역할을 합니다. 클로드 검사기를 사용하면 파일 변경 사항에 자동으로 대응할 수 있습니다.

참고: 이 글은 제가 개발 중인 파일 모니터링 MCP 서버의 데모/POC입니다. 이와 관련된 많은 질문/의견/문제/토론이 올라오고 있어서, 제 접근 방식을 공유하고자 간단한 구현 예를 게시합니다.

문맥

MCP 프로토콜은 리소스 구독 개념을 정의합니다. 클라이언트는 리소스 변경 사항에 대한 알림을 요청할 수 있고, 서버는 알림을 보낼지 여부를 선택할 수 있습니다. 흐름도는 다음과 같습니다.

프로토콜에 따르면 클라이언트는 변경 사항을 읽기 위해 서버로 읽기 요청을 다시 보내야 합니다. (참고로 이 모든 것은 선택 사항입니다.) 하지만 저는 이 방식이 다소 번거롭고, 추가적인 작업이 필요하며, 리소스 업데이트 알림에 변경 사항도 함께 표시하는 것이 더 좋다고 생각합니다. 다행히 SDK는 meta / _meta 필드를 제공하여 원하는 대로 전송할 수 있습니다. 따라서 변경된 줄 수, 변경 사항의 차이점 등 무엇을 전송할지 알 수 없습니다. 이 데모에서는 구현하지 않았고, 지금은 타임스탬프만 전송하고 있습니다. (기본적으로 최소한의 POC를 제외한 모든 것을 서버에서 가져왔습니다.) 또한 stdio 전송 방식으로 실행되므로 특별한 내용은 없습니다.

참고!!! 아직 "실제" MCP 클라이언트에서 테스트해 보지 못했습니다. 제가 알기로는 대부분의 뷰 클라이언트가 리소스 구독을 지원하는 것으로 알고 있습니다. 어차피 선택 사항이니까요. 다행히 Inspector는 아주 좋은 클라이언트이므로 이 서버를 테스트하는 데 사용할 수 있습니다.

데모 지침:

1. 저장소를 복제합니다.
2. uv (또는 다른 방법)를 사용하여 종속성을 설치합니다.
3. make start ( uv 사용)를 사용하여 서버를 실행하거나 npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py 실행합니다.
4. Inspector 클라이언트를 열고 stdio를 사용하여 연결합니다. 구성이 필요하지 않습니다.
5. subscribe 도구를 사용하여 디렉토리나 파일을 모니터링합니다(또는 "리소스 목록"을 실행하고 리소스를 클릭한 다음 "구독" 버튼을 클릭하여 구독할 수도 있습니다).
6. 기본적으로 서버는 src/mcp_observer_server/watched.txt 에 watched.txt 라는 파일을 노출합니다(파일은 .gitignored 형식이므로 직접 생성해야 합니다). 하지만 다른 파일도 구독할 수 있습니다. subscribe_default 도구를 사용하여 이 파일을 구독할 수 있습니다.
7. watched.txt 파일(또는 구독한 파일)을 수정하면 Inspector 오른쪽 하단 패널에 서버 알림이 표시됩니다. 이것이 POC가 설정된 것입니다.

데모 시각화

1. 서버를 시작하고 Inspector에 연결합니다.
2. 기본 리소스를 나열하세요.
3. 도구 나열:
4. 기본 파일을 구독하세요:
5. 파일을 수정하세요:
6. 알림이 나타나는 것을 확인하세요:

🎉

서버 설명

MCP Observer 서버는 시스템의 파일 및 디렉터리 변경 사항을 추적하여 MCP 클라이언트가 이러한 이벤트를 구독하고 파일 생성, 수정, 삭제 또는 이동 시 조치를 취할 수 있도록 합니다(현재 데모에서는 수정 이벤트를 처리합니다). 이 서버는 전체 모델 컨텍스트 프로토콜(Model Context Protocol) 사양을 구현하여 다음을 제공합니다.

• 실시간 파일 모니터링 : 효율적인 파일 시스템 관찰을 위한 Watchdog 라이브러리 사용
• 구독 관리 : 모든 경로에 대한 모니터링 구독을 생성, 나열 및 취소합니다.
• 변경 내역 : 각 구독에 대한 최근 변경 사항 로그를 유지합니다(데모에서는 생략됨)
• 파일 및 디렉토리 액세스 : MCP 리소스를 통해 파일 내용 및 디렉토리 목록 읽기
• 상태 비저장 디자인 : 클라이언트가 파일 변경에 대한 응답으로 발생하는 일을 제어합니다.

주요 특징

• 특정 파일, 디렉토리 또는 전체 저장소의 변경 사항을 구독합니다.
• 파일 패턴 또는 이벤트 유형별로 이벤트 필터링(데모에서는 생략)
• 최근 변경 사항을 쿼리하여 어떤 파일이 영향을 받았는지 확인하세요(데모에서는 생략됨)
• 리소스 엔드포인트를 통해 파일 콘텐츠에 액세스
• 최소한의 종속성을 갖춘 가볍고 효율적인 구현
• 모든 MCP 호환 클라이언트(리소스 구독을 지원하는)와의 간단한 통합

실제 응용 프로그램

제가 해결하려는 가장 큰 문제는 클로드 코드(Claude Code)가 파일을 직접 수정하고 변경 사항을 직접 기록하지 않는 한, 저장소/프로젝트에서 무슨 일이 일어나고 있는지 전혀 알 수 없다는 것입니다. ("마지막으로 읽은 후 파일이 변경되었습니다"라는 알림 아시죠?) 프로젝트에서 실제로 진행 상황을 모니터링하는 클라이언트나 코딩 어시스턴트가 있으면, 모든 작업을 클로드에게 위임할 필요 없이, 단지 작업 진행 상황을 알 수 있다는 점이 매우 유용하다고 생각합니다. 몇 가지 실용적인 활용 사례는 다음과 같습니다.

• 자동 문서 업데이트 : 코드 변경 사항에 맞춰 문서를 동기화합니다. 코드를 업데이트하면 Claude에게 변경 사항이 알려지고, Claude는 문서 문자열 등을 사전에 확인하거나 업데이트합니다.
• 실시간 코드 검토 : 작업하는 동안 코드 변경 사항에 대한 실시간 피드백을 받고, 철자 오류, 유형 오류 등을 찾아내고 조언을 제공하는 진정한 쌍 프로그래밍입니다.
• 테스트 자동화 : 관련 파일이 수정되면 테스트를 실행합니다.
• AI 지원 : AI 도구가 파일 변경 사항에 자동으로 대응할 수 있도록 합니다.
• Git 커밋 자동화 : 커밋하는 것을 자주 잊어버리시나요? Claude가 변경 사항을 모니터링하고 커밋 작업을 더 자주 제안(또는 수행)해 드립니다.

현재 구현 설계

서버 구현은 단순성, 안정성, 유지 관리를 우선시하는 간소화된 아키텍처를 특징으로 합니다.

건축 하이라이트

1. 단순화된 구조
   • 집중된 구현(약 170줄의 코드)
   • 핵심 구성요소의 작은 세트로 통합된 기능
   • MCP SDK를 직접 활용하는 깔끔한 기능 기반 디자인
   • 높은 가독성과 유지관리성
2. 효율적인 상태 관리
   • 간단한 사전 구조는 클라이언트 세션에 대한 경로를 매핑합니다.
   • 세션 경로 직접 매핑을 위해 watched 사전을 사용합니다.
   • 명확한 데이터 흐름을 통한 최소한의 상태 추적
   • 중복된 데이터 구조를 방지합니다
3. MCP 프로토콜 통합
   • MCP SDK 함수 데코레이터의 직접 사용
   • 깨끗한 리소스 URI 처리
   • 적절한 기능 구성을 통한 간소화된 서버 초기화
   • 직접 알림 전달 시스템
4. 이벤트 처리
   • 간소화된 Watchdog 이벤트 핸들러 구현
   • 이벤트-알림 직접 경로
   • call_soon_threadsafe 통한 스레드 안전 통신
   • 효율적인 이벤트 필터링
5. 알림 시스템
   • MCP 알림 기본 요소의 직접 사용
   • 적절한 오류 처리를 통한 안정적인 전달
   • 정확한 UTC 타임스탬프 처리
   • 깔끔한 URI 포맷

핵심 구성 요소

1. 데이터 구조
   • 단일 글로벌 사전 watched 맵 Path 객체는 ServerSession 객체 세트로 변환됩니다.
   • 각 경로 항목에는 해당 경로에 구독된 세션 세트가 포함되어 있습니다.
2. 도구 API
   • 두 가지 필수 도구: subscribe 및 unsubscribe
   • 간단한 구독 관리를 위한 간단한 경로 매개변수
   • 깔끔한 오류 처리 및 경로 검증
3. 리소스 처리
   • 리소스 목록을 통해 직접 노출되는 파일 URI
   • 경로 확인 및 검증
   • 파일의 텍스트 콘텐츠 읽기
4. 이벤트 처리
   • Watcher 클래스는 FileSystemEventHandler를 확장합니다.
   • 수정된 이벤트를 직접 처리합니다.
   • 스레드 안전 알림 전송
   • 중첩된 경로에 대한 경로 상대성 처리
5. 알림 전달
   • ServerNotification 생성 및 전송
   • 타임스탬프가 포함된 이벤트 메타데이터
   • 깔끔한 URI 포맷

이 구현은 기능성과 단순성 사이에서 좋은 균형을 이루었으며, 그 결과 안정적이고 유지 관리가 쉬운 코드베이스가 만들어졌습니다.