Keap MCP 서버

HTTP/2 지원, 포괄적인 진단, 대량 작업 등 고급 기능을 포함하여 Keap CRM 데이터와 상호 작용하기 위한 고성능 MCP(Model Context Protocol) 서버입니다.

기능

핵심 연락처 및 태그 관리

• 포괄적인 연락처 관리 - 연락처 목록 조회, 검색, 필터링 및 상세 정보 가져오기

• 고급 태그 작업 - 생성, 쿼리, 배치 작업을 포함한 전체 태그 수명 주기 관리

• 배치 태그 작업 - 여러 연락처에 여러 태그를 효율적으로 적용하거나 제거

• 사용자 지정 필드 작업 - 사용자 지정 필드 값으로 연락처 검색 및 사용자 지정 필드 대량 업데이트

• 복합 논리 필터링 - 중첩된 조건을 포함한 AND, OR, NOT 연산자 지원

성능 및 최적화

• HTTP/2 지원 - 연결 풀링을 통한 향상된 연결 성능

• 지능형 속도 제한 - 적응형 백오프 전략을 사용한 일일 요청 제한

• 쿼리 최적화 - 성능 분석을 통한 지능형 서버 측 대 클라이언트 측 필터링

• 성능 모니터링 - 실시간 쿼리 분석 및 최적화 제안

• 영구 캐싱 - API 호출을 줄이고 성능을 향상하기 위한 SQLite 기반 캐싱

고급 기능

• 포괄적인 진단 - API 성능 지표, 시스템 모니터링 및 상태 확인

• 향상된 오류 처리 - 다양한 오류 유형에 대한 지수 백오프를 포함한 강력한 재시도 로직

• 대량 사용자 지정 필드 업데이트 - 여러 연락처에 걸쳐 사용자 지정 필드 값을 효율적으로 설정

• 고급 필터 연산자 - BETWEEN, IN, SINCE, STARTS_WITH 등을 포함한 15개 이상의 연산자

• ID 목록 작업 - 연락처 및 태그 ID 세트 작업을 위한 유틸리티 함수

Related MCP server: claude-cli-mcp

아키텍처

Keap MCP 서버는 간소화된 고성능 아키텍처를 사용합니다:

• API 클라이언트 (src/api/client.py) - HTTP/2, 속도 제한 및 진단을 포함한 향상된 Keap API 통신

• MCP 도구 (src/mcp/) - 최적화가 포함된 포괄적인 MCP 프로토콜 구현

• 캐시 관리자 (src/cache/) - 지능형 무효화 기능을 갖춘 SQLite 기반 영구 캐싱

• 최적화 엔진 (src/mcp/optimization/) - 쿼리 최적화 및 성능 분석

• 스키마 (src/schemas/) - 데이터 유효성 검사 및 모델

• 유틸리티 (src/utils/) - 연락처 처리 및 필터링을 위한 공유 유틸리티

MCP 도구

이 서버는 17개의 포괄적인 MCP 도구를 제공합니다:

연락처 작업

1. list_contacts - 필터링 및 페이지 매김을 통한 연락처 목록 조회 (최적화됨)

2. search_contacts_by_email - 이메일 주소로 연락처 찾기

3. search_contacts_by_name - 이름으로 연락처 찾기

4. get_contact_details - 특정 연락처에 대한 상세 정보 가져오기

5. query_contacts_by_custom_field - 사용자 지정 필드 값으로 연락처 쿼리

태그 작업

6. get_tags - 선택적 필터링을 사용하여 태그 검색

7. get_tag_details - 특정 태그에 대한 상세 정보 가져오기

8. get_contacts_with_tag - 특정 태그가 있는 연락처 가져오기

9. create_tag - 새 태그 생성

태그 관리 (배치 작업)

10. modify_tags - 연락처에서 태그 추가 또는 제거

11. apply_tags_to_contacts - 배치 작업을 사용하여 여러 연락처에 여러 태그 적용

12. remove_tags_from_contacts - 여러 연락처에서 여러 태그 제거

사용자 지정 필드 관리

13. set_custom_field_values - 여러 연락처에 걸쳐 사용자 지정 필드 값을 대량 업데이트

고급 쿼리 및 성능 작업

14. query_contacts_optimized - 최적화 및 성능 분석을 포함한 고급 연락처 쿼리

15. analyze_query_performance - 쿼리 성능 및 최적화 잠재력 분석

시스템 작업

16. get_api_diagnostics - 포괄적인 API 진단 및 성능 지표

유틸리티 작업

17. intersect_id_lists - 여러 ID 목록의 교집합 찾기

시작하기

사전 요구 사항

• Python 3.9 이상

• Keap API 자격 증명

설치

1. 저장소 복제:

   git clone https://github.com/yourusername/keapmcp.git
   cd keapmcp

2. 종속성 설치:

   pip install -r requirements.txt

3. Keap API 자격 증명 구성:

   • 애플리케이션은 구성을 위해 .env 파일을 사용합니다.

   • API 키는 keapsync에서 복사되었지만 필요한 경우 수정할 수 있습니다.

   • 구성에는 다음이 포함됩니다:

     KEAP_API_KEY=your_api_key_here
     KEAP_API_BASE_URL=https://api.infusionsoft.com/crm/rest/v1
     KEAP_MCP_HOST=127.0.0.1
     KEAP_MCP_PORT=5000
     KEAP_MCP_LOG_LEVEL=INFO
     KEAP_MCP_LOG_FILE=keap_mcp_server.log
     KEAP_MCP_CACHE_ENABLED=true
     KEAP_MCP_CACHE_TTL=3600

서버 실행

python run.py --host 127.0.0.1 --port 5000

명령줄 옵션:

• --host - 바인딩할 호스트 (기본값: 127.0.0.1)

• --port - 수신할 포트 (기본값: 5000)

• --log-level - 로깅 수준 (기본값: INFO)

• --log-file - 로그 파일 경로 (기본값: keap_mcp_server.log)

• --no-console-log - 콘솔 로깅 비활성화

테스트 및 커버리지

Keap MCP 서버는 전체 CI/CD 파이프라인 통합을 통해 신뢰성과 올바른 작동을 보장하는 포괄적인 테스트 제품군을 포함합니다.

빠른 테스트

간편한 테스트 실행을 위해 Makefile을 사용하세요:

# Run all unit tests
make test

# Run tests with coverage reporting  
make coverage

# Generate HTML coverage report
make coverage-html

# Run service-specific tests
make test-services
make test-models

# Full development workflow
make dev-test

CI/CD 통합

이 프로젝트에는 자동화된 테스트 및 커버리지 보고가 포함되어 있습니다:

• 지속적 통합: Python 3.9, 3.10, 3.11에서 테스트 실행

• 커버리지 추적: 최소 60% 커버리지 강제 적용

• 커밋 전 검사: 코드 서식 지정, 린팅 및 보안 검사

• 커버리지 배지: 메인 브랜치에서 자동 업데이트

테스트 범주

• 단위 테스트 (tests/unit/) - 포괄적인 모킹을 통한 개별 구성 요소 테스트

• 통합 테스트 (tests/integration/) - 종단 간 기능 검증

• 성능 테스트 (tests/performance/) - 로드 및 최적화 검증

• API 검증 - Keap API 응답 형식 검증

커버리지 요구 사항

• 현재 커버리지: 55% 통합 커버리지 (구성 요소별로 다름)

• API 클라이언트: 포괄적인 모킹을 통해 핵심 기능 테스트 완료

• MCP 도구: 모의 종속성을 사용한 통합 테스트

• 캐시 시스템: 포괄적인 지속성 및 성능 테스트

• 유틸리티: 연락처 처리 및 필터링 기능 테스트 완료

• 최적화: 성능 분석 및 쿼리 최적화 포함

특정 테스트 실행

# Run all tests
python -m pytest tests/ -v

# With coverage reporting
python -m pytest tests/ --cov=src --cov-fail-under=90

# Integration tests (requires running server)
python -m pytest tests/integration/ -v

MCP 서버 사용

예시: 연락처 목록 조회 (최적화됨)

{
  "function": "list_contacts",
  "params": {
    "filters": [
      { "field": "email", "operator": "contains", "value": "@company.com" }
    ],
    "limit": 50,
    "include": ["id", "given_name", "family_name", "email"]
  }
}

참고: list_contacts는 이제 더 나은 성능을 위해 내부적으로 최적화 엔진을 사용합니다. 자세한 성능 지표는 query_contacts_optimized를 직접 사용하세요.

예시: 이메일로 검색

{
  "function": "search_contacts_by_email",
  "params": {
    "email": "john.doe@company.com",
    "include": ["id", "given_name", "family_name", "email", "tags"]
  }
}

예시: 태그 가져오기

{
  "function": "get_tags",
  "params": {
    "include_categories": true,
    "limit": 100
  }
}

예시: 배치 태그 작업

{
  "function": "apply_tags_to_contacts",
  "params": {
    "tag_ids": ["123", "456"],
    "contact_ids": ["1001", "1002", "1003"]
  }
}

예시: 사용자 지정 필드 쿼리

{
  "function": "query_contacts_by_custom_field",
  "params": {
    "field_id": "7",
    "field_value": "Engineering",
    "operator": "contains",
    "include": ["id", "given_name", "family_name", "email"]
  }
}

예시: 새 태그 생성

{
  "function": "create_tag",
  "params": {
    "name": "VIP Customer",
    "description": "High-value customer segment",
    "category_id": "2"
  }
}

예시: 대량 사용자 지정 필드 업데이트

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_ids": ["1001", "1002", "1003"],
    "common_value": "VIP Customer"
  }
}

또는 연락처별 개별 값 사용:

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_values": {
      "1001": "Gold Tier",
      "1002": "Silver Tier", 
      "1003": "Bronze Tier"
    }
  }
}

예시: API 진단

{
  "function": "get_api_diagnostics",
  "params": {}
}

예시: ID 목록 교집합

{
  "function": "intersect_id_lists",
  "params": {
    "lists": [
      {"list_id": "active_contacts", "item_ids": ["1", "2", "3", "4"]},
      {"list_id": "newsletter_subscribers", "item_ids": ["2", "3", "5", "6"]}
    ],
    "id_field": "item_ids"
  }
}

성능 기능

HTTP/2 지원

서버는 연결 풀링 및 keepalive 연결을 통해 향상된 성능을 위해 HTTP/2를 사용합니다.

속도 제한

• 일일 요청 제한 (기본적으로 하루 25,000건)

• 지능형 백오프 전략

• 속도 제한 모니터링 및 진단

캐싱 전략

• SQLite 기반 영구 캐싱

• 지능형 캐시 무효화

• TTL 기반 만료

• 캐시 적중/미적중 추적

오류 처리

• 재시도를 위한 지수 백오프

• 시간 초과, 네트워크 및 HTTP 오류에 대한 다양한 전략

• 포괄적인 오류 추적 및 진단

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.