Ambivo Claude MCP 서버

이 Claude MCP(Model Context Protocol) 서버는 Claude AI와 함께 엔티티 데이터를 자연어로 조회할 수 있도록 Ambivo API 엔드포인트에 대한 액세스를 제공합니다.

기능

• 자연어 쿼리: /entity/natural_query 엔드포인트를 사용하여 엔티티 데이터에 대한 자연어 쿼리를 실행합니다.

• JWT 인증: Bearer 토큰 인증을 사용한 보안 액세스

• 속도 제한: API 남용을 방지하기 위한 내장 속도 제한

• 토큰 캐싱: 효율적인 토큰 검증을 위한 캐싱

• 오류 처리: 상세한 오류 메시지를 제공하는 포괄적인 오류 처리

• 재시도 로직: 실패한 요청에 대한 지수 백오프를 사용한 자동 재시도

도구

1. set_auth_token

Ambivo API 인증을 위한 JWT Bearer 토큰을 설정합니다.

매개변수:

• token (문자열, 필수): JWT Bearer 토큰

사용법:

{
  "token": "your-jwt-token-here"
}

2. natural_query

Ambivo 엔티티 데이터에 대한 자연어 쿼리를 실행합니다.

매개변수:

• query (문자열, 필수): 원하는 데이터를 설명하는 자연어 쿼리

• response_format (문자열, 선택): 응답 형식 - "table", "natural" 또는 "both" (기본값: "both")

예제 쿼리:

• "이번 주에 생성된 리드를 보여줘"

• "Gmail 주소를 가진 연락처를 찾아줘"

• "$10,000 이상의 기회를 나열해줘"

• "지난 7일 동안의 attribution_source google_ads 리드를 보여줘"

사용법:

{
  "query": "Show me leads created this week with attribution_source google_ads",
  "response_format": "both"
}

소개

이것은 Ambivo API를 위한 순수 Claude 기반 MCP 서버 구현으로, Claude Desktop 및 기타 Claude 호환 MCP 클라이언트와 원활하게 작동하도록 설계되었습니다. Claude의 강력한 언어 이해 기능을 통해 Ambivo CRM 데이터와 자연어로 상호작용할 수 있습니다.

설치

옵션 1: PyPI에서 설치 (권장)

pip install ambivo-mcp-server

옵션 2: 소스에서 설치

git clone https://github.com/ambivo-corp/ambivo-mcp-server.git
cd ambivo-mcp-server
pip install -e .

서버 실행

# If installed via pip
ambivo-mcp-server

# Or using Python module
python -m ambivo_mcp_server.server

구성

서버는 다음과 같은 기본 구성을 사용합니다:

• 기본 URL: https://goferapi.ambivo.com

• 시간 제한: 30초

• 콘텐츠 유형: application/json

필요한 경우 AmbivoAPIClient 클래스에서 이러한 설정을 수정할 수 있습니다.

인증

1. 먼저 set_auth_token 도구를 사용하여 인증 토큰을 설정합니다.

2. 토큰은 이후 모든 API 요청에 Bearer 토큰으로 포함됩니다.

3. 토큰은 Ambivo API 인증에서 발급된 유효한 JWT 토큰이어야 합니다.

오류 처리

서버는 포괄적인 오류 처리를 제공합니다:

• 인증 오류: 토큰이 없거나 유효하지 않은 경우 명확한 메시지

• HTTP 오류: 상세한 HTTP 상태 코드 및 응답 메시지

• 검증 오류: 도움이 되는 오류 메시지를 제공하는 매개변수 검증

• 네트워크 오류: 시간 제한 및 연결 오류 처리

API 엔드포인트

이 MCP 서버는 다음 Ambivo API 엔드포인트와 인터페이스합니다:

/entity/natural_query

• 메서드: POST

• 목적: 엔티티 데이터 검색을 위한 자연어 쿼리 처리

• 인증: 필수 (JWT Bearer 토큰)

• 콘텐츠 유형: application/json

/entity/data

• 메서드: POST

• 목적: 구조화된 매개변수를 사용한 직접 엔티티 데이터 액세스

• 인증: 필수 (JWT Bearer 토큰)

• 콘텐츠 유형: application/json

예제 워크플로우

1. 인증 설정:

   {
     "tool": "set_auth_token",
     "arguments": {
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
     }
   }

2. 자연어 쿼리:

   {
     "tool": "natural_query", 
     "arguments": {
       "query": "Show me all leads created in the last 30 days with phone numbers",
       "response_format": "both"
     }
   }

3. 직접 엔티티 쿼리:

   {
     "tool": "entity_data",
     "arguments": {
       "entity_type": "contact",
       "filters": {"email": {"$regex": "@gmail.com$"}},
       "limit": 100,
       "sort": {"created_date": -1}
     }
   }

개발

이 MCP 서버를 확장하려면:

1. 새 도구 추가: handle_list_tools() 및 handle_call_tool() 함수에 추가 도구 구현

2. API 클라이언트 수정: AmbivoAPIClient 클래스를 확장하여 추가 엔드포인트 지원

3. 구성 업데이트: 구성 섹션에서 기본 설정 수정

문제 해결

일반적인 문제:

1. "인증 필요" 오류: set_auth_token을 먼저 호출했는지 확인하세요.

2. HTTP 401/403 오류: JWT 토큰이 유효하고 만료되지 않았는지 확인하세요.

3. 연결 시간 초과: 네트워크 연결 및 API 엔드포인트 가용성을 확인하세요.

4. 잘못된 매개변수: 필수 및 선택 매개변수에 대한 도구 스키마를 검토하세요.

로깅:

서버는 중요한 이벤트와 오류를 기록합니다. 디버깅 정보는 콘솔 출력을 확인하세요.