Skip to main content
Glama
Sign In
enesjakozh

Inoyu Apache Unomi MCP Server

by sergehuber
npmGitHub
JavaScript
Apache 2.0
1
4
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Integrations

  • Integrates with Apache Unomi for user profile management and context storage, enabling Claude to maintain user context through Apache Unomi's profile management system

이노유 아파치 우노미 MCP 서버

Apache Unomi 프로필 관리를 통해 Claude가 사용자 컨텍스트를 유지 관리할 수 있도록 하는 모델 컨텍스트 프로토콜 서버입니다.

⚠️ 조기 구현 공지

이는 데모 목적으로 의도된 초기 구현입니다.

  • 프로덕션 용도로 검증되지 않음
  • 변경될 수 있음
  • 아직 공식적으로 지원되지 않음
  • 학습 및 실험용으로만 사용 가능

현재 범위

이 구현은 다음을 제공합니다.

  • 이메일을 이용한 프로필 조회 및 생성
  • 프로필 부동산 관리
  • 기본 세션 처리
  • 컨텍스트 격리를 위한 범위 관리

Unomi의 다른 기능(이벤트, 세그먼트, 세션 속성 등)은 현재 구현되지 않았습니다. 향후 개발 우선순위에 대한 커뮤니티의 의견을 환영합니다.

데모

MCP 서버가 Claude가 컨텍스트를 유지하고 사용자 프로필을 관리하는 방법을 살펴보세요.

설치

Claude Desktop과 함께 사용하려면 서버 구성 및 환경 변수를 추가하세요.

MacOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json Windows의 경우: %APPDATA%/Claude/claude_desktop_config.json

지엑스피1

설정 파일의 env 섹션에서 서버에 필요한 환경 변수를 설정할 수 있습니다. 해당 값을 실제 Unomi 서버 정보로 바꾸세요.

구성을 업데이트한 후에는 Claude Desktop을 다시 시작하세요. 채팅 창 오른쪽 하단에 있는 도구 아이콘을 클릭하여 서버에서 제공하는 모든 도구가 제대로 설치되었는지 확인할 수 있습니다.

특징

프로필 액세스

  • 자동 생성 기능이 있는 이메일 기반 프로필 조회
  • 프로필 속성, 세그먼트 및 점수 액세스
  • 모든 데이터 교환을 위한 JSON 형식
  • 날짜 기반 ID를 사용한 자동 세션 관리

도구

  • get_my_profile - 환경 변수를 사용하여 프로필 가져오기
    • 환경 또는 이메일 조회에서 UNOMI_PROFILE_ID를 사용합니다.
    • 현재 날짜를 기준으로 세션 ID를 자동으로 생성합니다.
    • 선택 매개변수:
      • requireSegments: 세그먼트 정보 포함
      • requireScores: 채점 정보 포함
  • update_my_profile - 프로필 속성 업데이트
    • 환경 또는 이메일 조회에서 UNOMI_PROFILE_ID를 사용합니다.
    • 키-값 쌍을 사용하여 업데이트할 속성 객체를 가져옵니다.
    • 문자열, 숫자, 부울 및 null 값을 지원합니다.
    • 예:
      { "properties": { "firstName": "John", "age": 30, "isSubscribed": true, "oldProperty": null } }
  • get_profile - ID로 특정 프로필 검색
    • 필수 매개변수로 profileId를 사용합니다.
    • Unomi에서 전체 프로필 데이터를 반환합니다.
  • search_profiles - 프로필 검색
    • 쿼리 문자열과 선택적 제한/오프셋 매개변수를 사용합니다.
    • 이름, 성 및 이메일 필드에서 검색
  • create_scope - 새로운 Unomi 범위를 만듭니다.
    • 범위 식별자와 선택적 이름/설명을 사용합니다.
    • 이벤트 추적 및 프로필 업데이트에 필요합니다.
    • 예:
      { "scope": "my-app", "name": "My Application", "description": "Scope for my application events" }

범위 관리

서버는 자동으로 범위를 관리합니다.

  1. 기본 범위:
    • 모든 작업에 기본 범위인 claude-desktop 사용됩니다.
    • 필요할 때 자동으로 생성됩니다
    • 프로필 업데이트 및 이벤트 추적에 사용됨
  2. 사용자 정의 범위:
    • create_scope 도구를 사용하여 생성할 수 있습니다.
    • 다양한 애플리케이션이나 컨텍스트를 분리하는 데 유용합니다.
    • 프로필 작업에서 사용하기 전에 존재해야 합니다.
  3. 자동 범위 생성:
    • 서버는 필요한 범위가 있는지 확인합니다.
    • 누락된 경우 자동으로 생성됩니다.
    • 범위 메타데이터에 대해 의미 있는 기본값을 사용합니다.

참고 : 범위는 필요할 때 자동으로 생성되지만 create_scope 도구를 사용하여 사용자 정의 이름과 설명으로 수동으로 생성할 수도 있습니다.

개요

이 MCP 서버를 통해 Claude는 Apache Unomi의 프로필 관리 시스템을 통해 사용자에 대한 컨텍스트를 관리할 수 있습니다. 이를 통해 다음과 같은 작업을 수행할 수 있습니다.

주요 역량

  1. 사용자 인식 :
    • 이메일 또는 프로필 ID를 사용하여 대화에서 사용자 식별
    • 세션 간에 일관된 사용자 컨텍스트 유지
    • 사용자 프로필을 자동으로 생성하고 관리합니다.
  2. 컨텍스트 관리 :
    • 사용자 기본 설정 저장 및 검색
  3. 통합 기능 :
    • 원활한 Claude Desktop 통합
    • 자동 세션 관리
    • 범위 기반 컨텍스트 격리

당신이 할 수 있는 일

  • Claude가 대화 전반에 걸쳐 사용자 기본 설정을 기억하도록 합니다.
  • 사용자별 정보 저장 및 검색
  • 일관된 사용자 컨텍스트 유지
  • 이메일 식별을 통해 여러 사용자 관리

필수 조건

  • Apache Unomi 서버 실행
  • Claude Desktop 설치
  • Unomi 서버에 대한 네트워크 액세스
  • 적절한 보안 구성
  • 필수 환경 변수

구성

환경 변수

서버에는 다음과 같은 환경 변수가 필요합니다.

UNOMI_BASE_URL=http://your-unomi-server:8181 UNOMI_USERNAME=your-username UNOMI_PASSWORD=your-password UNOMI_PROFILE_ID=your-profile-id UNOMI_SOURCE_ID=your-source-id UNOMI_KEY=your-unomi-key UNOMI_EMAIL=your-email

프로필 해상도

서버는 프로필 ID를 확인하기 위해 2단계 프로세스를 사용합니다.

  1. 이메일 조회( UNOMI_EMAIL 이 설정된 경우):
    • 이메일이 일치하는 프로필을 검색합니다.
    • 발견되면 해당 프로필의 ID를 사용합니다.
    • 세션 전반에 걸쳐 일관된 프로필을 유지하는 데 유용합니다.
  2. 대체 프로필 ID:
    • 이메일 조회에 실패하거나 UNOMI_EMAIL 설정되지 않은 경우
    • 환경에서 UNOMI_PROFILE_ID 사용합니다.
    • 프로필을 항상 사용할 수 있도록 보장합니다.

응답은 source 필드를 통해 어떤 방법이 사용되었는지 나타냅니다.

  • "email_lookup" : 이메일을 통해 찾은 프로필
  • "environment" : 대체 프로필 ID 사용

Unomi 서버 구성

  1. etc/org.apache.unomi.cluster.cfg 에서 보호된 이벤트를 구성합니다.
    # Required for protected events like property updates org.apache.unomi.cluster.authorization.key=your-unomi-key # Required to allow Claude Desktop to access Unomi # Replace your-claude-desktop-ip with your actual IP org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
  2. etc/org.apache.unomi.cors.cfg 에서 Unomi 서버의 CORS가 올바르게 구성되었는지 확인하세요.
    # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
  3. 변경 사항을 적용하려면 Unomi 서버를 다시 시작하세요.

중요 : Unomi 키는 Claude Desktop의 UNOMI_KEY 환경 변수와 서버 구성에서 정확히 일치해야 합니다.

구성

환경 변수

서버에는 다음과 같은 환경 변수가 필요합니다.

UNOMI_BASE_URL=http://your-unomi-server:8181 UNOMI_USERNAME=your-username UNOMI_PASSWORD=your-password UNOMI_PROFILE_ID=your-profile-id UNOMI_SOURCE_ID=your-source-id UNOMI_KEY=your-unomi-key UNOMI_EMAIL=your-email

프로필 해상도

서버는 프로필 ID를 확인하기 위해 2단계 프로세스를 사용합니다.

  1. 이메일 조회( UNOMI_EMAIL 이 설정된 경우):
    • 이메일이 일치하는 프로필을 검색합니다.
    • 발견되면 해당 프로필의 ID를 사용합니다.
    • 세션 전반에 걸쳐 일관된 프로필을 유지하는 데 유용합니다.
  2. 대체 프로필 ID:
    • 이메일 조회에 실패하거나 UNOMI_EMAIL 설정되지 않은 경우
    • 환경에서 UNOMI_PROFILE_ID 사용합니다.
    • 프로필을 항상 사용할 수 있도록 보장합니다.

응답은 source 필드를 통해 어떤 방법이 사용되었는지 나타냅니다.

  • "email_lookup" : 이메일을 통해 찾은 프로필
  • "environment" : 대체 프로필 ID 사용

Unomi 서버 구성

  1. etc/org.apache.unomi.cluster.cfg 에서 보호된 이벤트를 구성합니다.
    # Required for protected events like property updates org.apache.unomi.cluster.authorization.key=your-unomi-key # Required to allow Claude Desktop to access Unomi # Replace your-claude-desktop-ip with your actual IP org.apache.unomi.ip.ranges=127.0.0.1,::1,your-claude-desktop-ip
  2. etc/org.apache.unomi.cors.cfg 에서 Unomi 서버의 CORS가 올바르게 구성되었는지 확인하세요.
    # Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*
  3. 변경 사항을 적용하려면 Unomi 서버를 다시 시작하세요.

중요 : Unomi 키는 Claude Desktop의 UNOMI_KEY 환경 변수와 서버 구성에서 정확히 일치해야 합니다.

개발

종속성 설치:

npm install

서버를 빌드하세요:

npm run build

자동 재빌드를 사용한 개발의 경우:

npm run watch

디버깅

MCP 서버는 stdio를 통해 통신하므로 디버깅이 어려울 수 있습니다. 패키지 스크립트로 제공되는 MCP Inspector를 사용하는 것이 좋습니다.

npm run inspector

검사기는 브라우저에서 디버깅 도구에 액세스할 수 있는 URL을 제공합니다.

Claude Desktop 로그를 추적하여 MCP 요청과 응답을 확인할 수도 있습니다.

# Follow logs in real-time tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

세션 ID 형식

get_my_profile 사용하면 세션 ID는 다음 형식을 사용하여 자동 생성됩니다.

[profileId]-YYYYMMDD

예를 들어, 프로필 ID가 "user123"이고 오늘이 2024년 3월 15일인 경우 세션 ID는 다음과 같습니다.

user123-20240315

문제 해결

일반적인 문제

  1. 보호된 이벤트 실패
    • 두 구성 모두에서 Unomi 키가 정확히 일치하는지 확인하세요.
    • IP 주소가 올바르게 허용 목록에 등록되었는지 확인하세요
    • 속성을 업데이트하기 전에 범위가 있는지 확인하세요.
    • 필요한 경우 CORS 구성을 확인하세요
  2. 프로필을 찾을 수 없습니다
    • UNOMI_EMAIL이 올바르게 설정되었는지 확인하세요
    • 이메일 형식이 유효한지 확인하세요
    • Unomi에 프로필이 있는지 확인하세요
    • 폴백 UNOMI_PROFILE_ID가 유효한지 확인하세요
  3. 세션 문제
    • 세션은 날짜 기반임을 기억하세요
    • 하루에 프로필당 세션은 1개만 가능합니다.
    • 세션 ID 형식이 profileId-YYYYMMDD 와 일치하는지 확인하세요.
    • 세션에 대한 범위가 있는지 확인하세요
  4. 연결 문제
    • Unomi 서버가 실행 중인지 확인하세요
    • 네트워크 연결 확인
    • UNOMI_BASE_URL이 올바른지 확인하세요
    • 인증 자격 증명 확인

확인할 로그

  1. 클로드 데스크톱 로그 :
    # MacOS ~/Library/Logs/Claude/mcp*.log # Windows %APPDATA%\Claude\mcp*.log
  2. Unomi 서버 로그 :
    # Usually in $UNOMI_HOME/logs/karaf.log

빠른 수정

  1. 상태 재설정 :
    # Stop Claude Desktop # Clear logs rm ~/Library/Logs/Claude/mcp*.log # Restart Claude Desktop
  2. 구성 확인 :
    # Check Unomi connection curl -u username:password http://your-unomi-server:8181/cxs/cluster # Test scope exists curl -u username:password http://your-unomi-server:8181/cxs/scopes/claude-desktop

Claude Desktop 구성 옵션

  1. Claude Desktop 구성을 생성하거나 편집하세요.
    • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • 윈도우: %APPDATA%/Claude/claude_desktop_config.json
  2. NPX를 사용하여 서버 구성을 추가합니다.
    { "mcpServers": { "unomi-server": { "command": "npx", "args": ["@inoyu/mcp-unomi-server"], "env": { "UNOMI_BASE_URL": "http://your-unomi-server:8181", "UNOMI_USERNAME": "your-username", "UNOMI_PASSWORD": "your-password", "UNOMI_PROFILE_ID": "your-profile-id", "UNOMI_KEY": "your-unomi-key", "UNOMI_EMAIL": "your-email@example.com", "UNOMI_SOURCE_ID": "claude-desktop" } } } }

참고 : NPX를 사용하면 항상 최신 버전의 서버를 실행할 수 있습니다.

또는 특정 버전을 사용하려면 다음을 수행하세요.

{ "mcpServers": { "unomi-server": { "command": "npx", "args": ["@inoyu/mcp-unomi-server@0.1.0"], "env": { // ... environment variables ... } } } }

개발 또는 로컬 설치의 경우:

{ "mcpServers": { "unomi-server": { "command": "node", "args": ["/path/to/local/mcp-unomi-server/build/index.js"], "env": { // ... environment variables ... } } } }

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Apache Unomi 프로필 관리를 통해 Claude가 사용자 컨텍스트를 유지 관리할 수 있도록 하는 모델 컨텍스트 프로토콜 서버입니다.

  1. Current Scope
    1. Demo
      1. Installation
        1. Features
          1. Profile Access
          2. Tools
          3. Scope Management
        2. Overview
          1. Key Capabilities
          2. What You Can Do
          3. Prerequisites
        3. Configuration
          1. Environment Variables
          2. Profile Resolution
          3. Unomi Server Configuration
        4. Configuration
          1. Environment Variables
          2. Profile Resolution
          3. Unomi Server Configuration
        5. Development
          1. Debugging
          2. Session ID Format
        6. Troubleshooting
          1. Common Issues
          2. Logs to Check
          3. Quick Fixes
          4. Claude Desktop Configuration options

        Appeared in Searches

        ID: cot5p3ud7z