Umami Analytics MCP 서버

Umami의 웹사이트 분석 데이터에 대한 접근을 제공하여 Claude의 역량을 강화하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 Claude는 사용자 행동을 분석하고, 웹사이트 성능을 추적하고, 데이터 기반 인사이트를 제공할 수 있습니다.

코드베이스는 처음부터 끝까지 Claude Sonnet 3.5와 Cursor를 사용하여 생성되었습니다.

그것이 하는 일

이 서버는 Claude를 Umami 분석 플랫폼에 연결하여 다음을 수행할 수 있도록 합니다.

• 사용자 여정 및 행동 패턴 분석
• 웹사이트 성능 지표 추적
• 실시간 방문자 활동 모니터링
• 웹페이지 콘텐츠 캡처 및 분석
• 과거 분석 데이터로부터 통찰력 생성

작동 원리

서버는 Claude에게 웹사이트 데이터를 분석하기 위한 다음과 같은 도구를 제공합니다.

사용 가능한 도구

• get_websites : Umami 계정에서 웹사이트 목록과 해당 ID를 검색합니다.
• get_website_stats : 웹사이트의 페이지뷰, 방문자, 이탈률과 같은 주요 지표를 가져옵니다.
• get_website_metrics : URL, 참조자, 브라우저, 국가와 같은 특정 지표를 분석합니다.
• get_pageview_series : 사용자 정의 가능한 간격으로 시계열 페이지뷰 데이터를 가져옵니다.
• get_active_visitors : 웹사이트의 현재 활성 방문자 수를 모니터링합니다.
• get_session_ids : 특정 이벤트 또는 기간의 세션 ID를 검색합니다.
• get_tracking_data : 특정 세션 ID에 대한 자세한 활동 데이터를 가져옵니다.
• get_docs : 여러 사용자 여정에 대한 의미 검색을 수행하여 주어진 질문에 가장 관련성 있는 청크를 반환합니다.
• get_screenshot : 웹페이지의 시각적 스냅샷을 캡처합니다.
• get_html : 웹페이지 HTML 소스코드를 검색하고 분석합니다.

각 도구에는 설명과 전달 가능한 인수 목록이 있습니다. 이러한 인수는 Claude가 작업에 적합한 도구를 효과적으로 선택하고 올바른 매개변수를 제공할 수 있도록 컨텍스트와 정보를 제공하는 데 사용됩니다.

이러한 도구 대부분은 Umami API에서 Claude Desktop으로 직접 데이터를 가져오지만, get_docs는 Claude와의 컨텍스트 창 문제를 방지하고 토큰 사용량을 절약하기 위해 의미 검색 단계를 추가합니다. 특정 이벤트에 대한 모든 사용자 여정은 Umami API를 사용하여 검색된 후, 더 작은 섹션으로 분할되어 huging face의 오픈 소스 문장 변환기 모델을 사용하여 임베딩됩니다. 그런 다음 질문을 기반으로 가장 관련성 높은 청크를 검색하여 Claude로 반환하여 웹사이트에서 사용자가 수행한 특정 동작 및 행동을 분석할 수 있습니다. 이는 기존 데이터 시각화 도구로는 재현하기 어렵습니다. 이러한 임베딩 및 의미 검색은 src/analytics_service/embeddings.py 파일에 구현되어 있습니다.

또한, get_screenshot 및 get_html 도구는 오픈 소스 Crawl4AI 웹 크롤러를 사용하여 특정 웹사이트의 HTML 소스 코드와 스크린샷을 검색합니다. Claude와의 컨텍스트 창 문제를 방지하기 위해 스크린샷 크기를 줄이기 위해 다운샘플링해야 합니다. 이를 통해 Claude에게 웹사이트의 구조와 디자인에 대한 맥락을 제공하여 사이트 성능 개선에 대한 더욱 정확하고 관련성 있는 권장 사항을 제공할 수 있습니다. 웹 크롤러 구현은 src/analytics_service/crawler.py 파일에 있습니다.

설정 가이드

필수 조건

• uv 설치: pip install uv

1. 클로드 데스크톱 구성Claude Desktop 구성 파일에 다음을 추가하세요.
   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • 윈도우: %APPDATA%/Claude/claude_desktop_config.json

   지엑스피1

   /path/to/analytics_service 실제 analytics_service 디렉토리 경로로 바꾸세요.

   UMAMI_API_URL의 경우 https://example.com 사용 중인 Umami 버전(자체 호스팅 또는 Umami Cloud 호스팅)의 URL로 변경하세요. UMAMI_USERNAME 및 UMAMI_PASSWORD의 경우 yourUmamiUsername 및 yourUmamiPassword Umami 계정 사용자 인증 정보로 변경하세요. UMAMI_TEAM_ID의 경우 yourUmamiTeamId 분석하려는 팀의 ID로 변경하세요.

2. 클로드 데스크탑 열기

Claude Desktop을 열면 자동으로 분석 서비스 MCP 서버에 연결됩니다. 서버가 초기화되고 올바른 패키지가 설치될 때까지 최대 몇 분 정도 기다려 주세요. 서버가 준비되면 채팅 창 오른쪽 하단에 사용 가능한 MCP 도구 10개가 표시됩니다. 작은 망치 아이콘과 그 옆에 숫자 10이 표시됩니다.

또한, 아직 활성화하지 않으셨다면 Claude Desktop의 기능 미리보기에서 "분석 도구"를 활성화하는 것을 강력히 권장합니다. 이렇게 하면 Claude가 대시보드 및 기타 데이터 시각화를 구축할 수 있습니다. 이를 위해 왼쪽 패널에서 "기능 미리보기" 탭을 찾아 "분석 도구"를 활성화하세요. LaTeX 렌더링도 같은 섹션에서 활성화할 수 있습니다.

서버 사용 방법

시작하기

가장 간단한 시작 방법은 서버에서 제공하는 대시보드 프롬프트 생성 기능을 사용하는 것입니다. 채팅 창 왼쪽 하단에 있는 "MCP에서 첨부" 첨부 파일 버튼을 클릭하여 대시보드 프롬프트 생성 기능을 선택합니다. 그런 다음 "구현 선택"을 선택하고 "대시보드 프롬프트 생성"을 선택합니다.

이는 귀하의 웹사이트 대시보드를 만드는 과정을 안내하며, 다음 사항을 묻습니다.

1. 분석하려는 웹사이트의 이름
2. 분석 시작 및 종료 날짜
3. 웹사이트의 시간대

이 정보를 제공하면 서버에서 Claude에게 대시보드를 만드는 방법을 알려주는 txt 파일을 생성합니다. 채팅 창에서 Enter 키를 누르면 Claude가 나머지 작업을 처리합니다. 그런 다음 Claude에게 대시보드를 변경하거나 다른 시각화 기능을 추가해 달라고 요청할 수 있습니다.

자연어 사용

더욱 맞춤화된 경험을 원하시면 Claude와 직접 상담하여 대시보드에 표시할 데이터, 사용할 시각화 도구 등 원하는 요구 사항을 구체적으로 지정하실 수 있습니다. 또한 사용자 여정을 분석하여 특정 문제점을 파악하고, 사이트 스크린샷을 추가하여 Claude에게 추가적인 맥락을 제공할 수 있습니다.

요청 완료에 필요한 도구는 Claude가 자동으로 사용합니다. 자연어로 요청하시면 Claude가 사용할 도구를 자동으로 선택합니다. 사용 가능한 모든 도구 목록을 보려면 Claude에게 목록을 요청하거나 채팅 창 오른쪽 하단에 있는 망치 아이콘을 클릭하세요.

나만의 프롬프트를 만들어보세요

정기적으로 사용하는 워크플로에 대한 프롬프트를 직접 만들 수도 있습니다. 이를 위해서는 다음이 필요합니다.

1. 프롬프트 구조 정의 다음을 포함하는 프롬프트 정의를 만듭니다.
   • name : 프롬프트에 대한 고유 식별자
   • description : 프롬프트가 무엇을 하는지에 대한 명확한 설명
   • arguments : 프롬프트에 필요한 입력 매개변수 목록

   src/analytics_service/server.py 의 list_prompts() 함수에 다음을 추가하세요.

   구조의 예:

   @app.list_prompts() async def list_prompts(): return [ # ... existing prompts ... { "name": "Your Prompt Name", "description": "Your prompt description", "arguments": [ { "name": "Parameter Name 1", "description": "Parameter description", "required": True/False }, { "name": "Parameter Name 2", "description": "Parameter description", "required": True/False } ] } ]
2. 프롬프트 구현 src/analytics_service/server.py 의 get_prompt() 함수에 프롬프트 처리 논리를 추가합니다.
   @app.get_prompt() async def get_prompt(name: str, arguments: Any): # ... existing prompts ... if name == "Your Prompt Name": return { "messages": [ { "role": "user", "content": { "type": "text", "text": f"Your prompt template with {arguments['Parameter Name']}" } } ] }
   프롬프트에서 메시지를 정의할 때 role 필드는 대화를 구성하는 데 중요합니다.
   • 사용자 입력이나 질문을 시뮬레이션하는 메시지에는 "role": "user" 사용하세요.
   • Claude의 응답이나 지시를 나타내는 메시지에는 "role": "assistant" 사용하세요.
   • 컨텍스트를 설정하거나 고급 지침을 제공하는 메시지의 경우 "role": "system" 사용하세요.

   각 메시지의 content 필드에는 type 지정해야 합니다. 사용 가능한 유형은 다음과 같습니다.

   • "type": "text" - 일반 텍스트 콘텐츠의 경우
   • "type": "resource" - 파일, 로그 또는 기타 데이터와 같은 외부 리소스를 포함합니다. 다음을 포함하는 resource 객체를 포함해야 합니다.
     • uri : 리소스 식별자
     • text : 실제 내용
     • mimeType : 콘텐츠의 MIME 유형(예: "text/plain", "text/x-python")

   리소스에는 text 필드에 콘텐츠가 포함되어 있지만 resource 유형을 사용하면 여러 가지 중요한 이점이 있습니다.

   1. 콘텐츠 유형 인식 : mimeType 필드는 Claude에게 콘텐츠를 해석하는 방법(예: Python 코드, 일반 텍스트 또는 기타 형식)을 알려줍니다.
   2. 소스 추적 : uri 필드는 콘텐츠가 어디에서 왔는지에 대한 참조를 유지하며, 이는 다음과 같은 경우에 유용할 수 있습니다.
      • 데이터 출처 추적
      • 소스가 변경되면 업데이트 활성화
      • 리소스의 위치와 목적에 대한 맥락 제공
   3. 구조화된 데이터 처리 : 리소스 형식을 사용하면 각 리소스에 대한 메타데이터를 유지하면서 다양한 유형의 콘텐츠를 일관되게 처리할 수 있습니다.

   다음은 다양한 역할과 콘텐츠 유형을 보여주는 예입니다.

   "messages": [ { "role": "system", "content": { "type": "text", "text": "Analyze the following log file and code for potential issues." } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "logs://recent", "text": "[2024-03-14 15:32:11] ERROR: Connection timeout", "mimeType": "text/plain" } } }, { "role": "assistant", "content": { "type": "text", "text": "I notice a connection timeout error. Let me examine the related code." } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "file:///code.py", "text": "def example():\n pass", "mimeType": "text/x-python" } } } ]

   대부분의 프롬프트에서는 사용자 역할이 있는 텍스트 유형만으로도 충분하며, 클로드가 응답을 더욱 자유롭게 제어하고 창의적으로 처리할 수 있도록 합니다. 그러나 더 복잡한 워크플로에서는 역할과 유형이 서로 다른 여러 메시지를 통해 더욱 체계적인 대화 흐름을 제공하고 사용자가 응답을 더욱 효과적으로 제어할 수 있습니다.

3. 프롬프트 생성을 위한 모범 사례
   • 프롬프트를 집중적이고 구체적으로 만드십시오.
   • 인수에 대한 명확한 검증 요구 사항을 포함합니다.
   • 매개변수에 설명적 이름을 사용하세요
   • 매개변수 설명에 예시 값을 포함합니다.
   • Claude를 효과적으로 안내하기 위해 프롬프트 템플릿을 구성하세요.
   • 오류 처리 및 예외 상황을 고려하세요
   • 다양한 입력으로 프롬프트 테스트