이노유 아파치 우노미 MCP 서버
Apache Unomi 프로필 관리를 통해 Claude가 사용자 컨텍스트를 유지 관리할 수 있도록 하는 모델 컨텍스트 프로토콜 서버입니다.
⚠️ 조기 구현 공지
이는 데모 목적으로 의도된 초기 구현입니다.
프로덕션 용도로 검증되지 않음
변경될 수 있음
아직 공식적으로 지원되지 않음
학습 및 실험용으로만 사용 가능
현재 범위
이 구현은 다음을 제공합니다.
이메일을 이용한 프로필 조회 및 생성
프로필 부동산 관리
기본 세션 처리
컨텍스트 격리를 위한 범위 관리
Unomi의 다른 기능(이벤트, 세그먼트, 세션 속성 등)은 현재 구현되지 않았습니다. 향후 개발 우선순위에 대한 커뮤니티의 의견을 환영합니다.
Related MCP server: ConnectWise Manage MCP Server
데모
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" }
범위 관리
서버는 자동으로 범위를 관리합니다.
기본 범위:
모든 작업에 기본 범위인
claude-desktop사용됩니다.필요할 때 자동으로 생성됩니다
프로필 업데이트 및 이벤트 추적에 사용됨
사용자 정의 범위:
create_scope도구를 사용하여 생성할 수 있습니다.다양한 애플리케이션이나 컨텍스트를 분리하는 데 유용합니다.
프로필 작업에서 사용하기 전에 존재해야 합니다.
자동 범위 생성:
서버는 필요한 범위가 있는지 확인합니다.
누락된 경우 자동으로 생성됩니다.
범위 메타데이터에 대해 의미 있는 기본값을 사용합니다.
참고 : 범위는 필요할 때 자동으로 생성되지만
create_scope도구를 사용하여 사용자 정의 이름과 설명으로 수동으로 생성할 수도 있습니다.
개요
이 MCP 서버를 통해 Claude는 Apache Unomi의 프로필 관리 시스템을 통해 사용자에 대한 컨텍스트를 관리할 수 있습니다. 이를 통해 다음과 같은 작업을 수행할 수 있습니다.
주요 역량
사용자 인식 :
이메일 또는 프로필 ID를 사용하여 대화에서 사용자 식별
세션 간에 일관된 사용자 컨텍스트 유지
사용자 프로필을 자동으로 생성하고 관리합니다.
컨텍스트 관리 :
사용자 기본 설정 저장 및 검색
통합 기능 :
원활한 Claude Desktop 통합
자동 세션 관리
범위 기반 컨텍스트 격리
당신이 할 수 있는 일
Claude가 대화 전반에 걸쳐 사용자 기본 설정을 기억하도록 합니다.
사용자별 정보 저장 및 검색
일관된 사용자 컨텍스트 유지
이메일 식별을 통해 여러 사용자 관리
필수 조건
Apache Unomi 서버 실행
Claude Desktop 설치
Unomi 서버에 대한 네트워크 액세스
적절한 보안 구성
필수 환경 변수
구성
환경 변수
서버에는 다음과 같은 환경 변수가 필요합니다.
프로필 해상도
서버는 프로필 ID를 확인하기 위해 2단계 프로세스를 사용합니다.
이메일 조회(
UNOMI_EMAIL이 설정된 경우):이메일이 일치하는 프로필을 검색합니다.
발견되면 해당 프로필의 ID를 사용합니다.
세션 전반에 걸쳐 일관된 프로필을 유지하는 데 유용합니다.
대체 프로필 ID:
이메일 조회에 실패하거나
UNOMI_EMAIL설정되지 않은 경우환경에서
UNOMI_PROFILE_ID사용합니다.프로필을 항상 사용할 수 있도록 보장합니다.
응답은 source 필드를 통해 어떤 방법이 사용되었는지 나타냅니다.
"email_lookup": 이메일을 통해 찾은 프로필"environment": 대체 프로필 ID 사용
Unomi 서버 구성
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-ipetc/org.apache.unomi.cors.cfg에서 Unomi 서버의 CORS가 올바르게 구성되었는지 확인하세요.# Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*변경 사항을 적용하려면 Unomi 서버를 다시 시작하세요.
중요 : Unomi 키는 Claude Desktop의 UNOMI_KEY 환경 변수와 서버 구성에서 정확히 일치해야 합니다.
구성
환경 변수
서버에는 다음과 같은 환경 변수가 필요합니다.
프로필 해상도
서버는 프로필 ID를 확인하기 위해 2단계 프로세스를 사용합니다.
이메일 조회(
UNOMI_EMAIL이 설정된 경우):이메일이 일치하는 프로필을 검색합니다.
발견되면 해당 프로필의 ID를 사용합니다.
세션 전반에 걸쳐 일관된 프로필을 유지하는 데 유용합니다.
대체 프로필 ID:
이메일 조회에 실패하거나
UNOMI_EMAIL설정되지 않은 경우환경에서
UNOMI_PROFILE_ID사용합니다.프로필을 항상 사용할 수 있도록 보장합니다.
응답은 source 필드를 통해 어떤 방법이 사용되었는지 나타냅니다.
"email_lookup": 이메일을 통해 찾은 프로필"environment": 대체 프로필 ID 사용
Unomi 서버 구성
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-ipetc/org.apache.unomi.cors.cfg에서 Unomi 서버의 CORS가 올바르게 구성되었는지 확인하세요.# Add your Claude Desktop origin if needed org.apache.unomi.cors.allowed.origins=http://localhost:*변경 사항을 적용하려면 Unomi 서버를 다시 시작하세요.
중요 : Unomi 키는 Claude Desktop의 UNOMI_KEY 환경 변수와 서버 구성에서 정확히 일치해야 합니다.
개발
종속성 설치:
서버를 빌드하세요:
자동 재빌드를 사용한 개발의 경우:
디버깅
MCP 서버는 stdio를 통해 통신하므로 디버깅이 어려울 수 있습니다. 패키지 스크립트로 제공되는 MCP Inspector를 사용하는 것이 좋습니다.
검사기는 브라우저에서 디버깅 도구에 액세스할 수 있는 URL을 제공합니다.
Claude Desktop 로그를 추적하여 MCP 요청과 응답을 확인할 수도 있습니다.
세션 ID 형식
get_my_profile 사용하면 세션 ID는 다음 형식을 사용하여 자동 생성됩니다.
예를 들어, 프로필 ID가 "user123"이고 오늘이 2024년 3월 15일인 경우 세션 ID는 다음과 같습니다.
문제 해결
일반적인 문제
보호된 이벤트 실패
두 구성 모두에서 Unomi 키가 정확히 일치하는지 확인하세요.
IP 주소가 올바르게 허용 목록에 등록되었는지 확인하세요
속성을 업데이트하기 전에 범위가 있는지 확인하세요.
필요한 경우 CORS 구성을 확인하세요
프로필을 찾을 수 없습니다
UNOMI_EMAIL이 올바르게 설정되었는지 확인하세요
이메일 형식이 유효한지 확인하세요
Unomi에 프로필이 있는지 확인하세요
폴백 UNOMI_PROFILE_ID가 유효한지 확인하세요
세션 문제
세션은 날짜 기반임을 기억하세요
하루에 프로필당 세션은 1개만 가능합니다.
세션 ID 형식이
profileId-YYYYMMDD와 일치하는지 확인하세요.세션에 대한 범위가 있는지 확인하세요
연결 문제
Unomi 서버가 실행 중인지 확인하세요
네트워크 연결 확인
UNOMI_BASE_URL이 올바른지 확인하세요
인증 자격 증명 확인
확인할 로그
클로드 데스크톱 로그 :
# MacOS ~/Library/Logs/Claude/mcp*.log # Windows %APPDATA%\Claude\mcp*.logUnomi 서버 로그 :
# Usually in $UNOMI_HOME/logs/karaf.log
빠른 수정
상태 재설정 :
# Stop Claude Desktop # Clear logs rm ~/Library/Logs/Claude/mcp*.log # Restart Claude Desktop구성 확인 :
# 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 구성 옵션
Claude Desktop 구성을 생성하거나 편집하세요.
MacOS:
~/Library/Application Support/Claude/claude_desktop_config.json윈도우:
%APPDATA%/Claude/claude_desktop_config.json
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를 사용하면 항상 최신 버전의 서버를 실행할 수 있습니다.
또는 특정 버전을 사용하려면 다음을 수행하세요.
개발 또는 로컬 설치의 경우: