ConnectWise API Gateway MCP 서버

이 모델 컨텍스트 프로토콜(MCP) 서버는 ConnectWise Manage API와 상호 작용하기 위한 포괄적인 인터페이스를 제공합니다. 개발자와 AI 비서 모두의 API 검색, 실행 및 관리를 간소화합니다.

핵심 역량

• API 검색: 키워드 또는 자연어를 사용하여 ConnectWise API 엔드포인트를 검색하고 탐색합니다.

• 간소화된 API 실행: 사용자 친화적인 매개변수 처리 및 자동 오류 관리를 통해 API 호출을 실행합니다.

• 빠른 메모리 시스템: 보다 효율적인 워크플로를 위해 자주 사용되는 API 쿼리를 저장하고 검색합니다.

• 원시 API 액세스: 엔드포인트, 메서드 및 매개변수에 대한 완벽한 제어를 통해 사용자 지정 API 요청을 보냅니다.

주요 특징

• 데이터베이스 지원 API 검색: 빠르고 효율적인 엔드포인트 조회를 위해 ConnectWise API 정의 JSON에서 구축된 SQLite 데이터베이스를 사용합니다.

• 자연어 검색: 필요한 내용에 대한 대화형 설명을 사용하여 관련 API 엔드포인트를 찾습니다.

• 분류된 API 탐색: 기능 범주별로 구성된 API 엔드포인트를 탐색합니다.

• 자세한 문서 액세스: 매개변수, 스키마, 응답 형식을 포함한 API 엔드포인트에 대한 포괄적인 정보를 확인하세요.

• 적응형 학습: 시스템은 사용 추적을 통해 어떤 API 호출이 사용자에게 가장 가치 있는지 학습합니다.

설치 및 설정

필수 조건

• Python 3.10 이상

• ConnectWise Manage API 자격 증명에 대한 액세스

• ConnectWise API 정의 파일( manage.json ) - 저장소에 포함됨

설치 단계

옵션 1: GitHub NPM 패키지 사용(권장)

GitHub에서 직접 패키지를 설치할 수 있습니다.

지엑스피1

이 방법은 모든 종속성을 자동으로 처리하고 Claude Desktop에 대한 더 간단한 구성을 제공합니다.

옵션 2: 수동 설치

윈도우

1. 저장소를 복제하거나 다운로드하세요.

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP

2. 패키지를 설치하세요:

   pip install -e .

맥OS

NPM 설치 방법을 사용하려면 다음을 실행하세요.

수동 설치의 경우:

1. Python 3.10 이상이 아직 설치되지 않았다면 설치하세요.

   # Using Homebrew brew install python@3.10 # Or using pyenv brew install pyenv pyenv install 3.10.0 pyenv global 3.10.0

2. 저장소를 복제합니다.

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP

3. 가상 환경 설정(권장):

   python3 -m venv venv source venv/bin/activate

4. 패키지를 설치하세요:

   pip install -e .

리눅스(우분투/데비안)

NPM 설치 방법을 사용하려면 다음을 실행하세요.

수동 설치의 경우:

1. Python 3.10 이상이 아직 설치되지 않았다면 설치하세요.

   # For Ubuntu 22.04+ sudo apt update sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip # For older versions of Ubuntu/Debian sudo add-apt-repository ppa:deadsnakes/ppa sudo apt update sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip

2. 저장소를 복제합니다.

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP

3. 가상 환경 설정(권장):

   python3.10 -m venv venv source venv/bin/activate

4. 패키지를 설치하세요:

   pip install -e .

설치 후 단계

Windows, macOS, Linux 등 어떤 플랫폼에 설치하든 다음 단계를 완료하세요.

1. (선택 사항) API 데이터베이스 구축

이 저장소에는 이미 미리 빌드된 데이터베이스가 포함되어 있으므로 이 단계는 선택 사항입니다. 최신 ConnectWise API 정의 파일을 사용해야 하는 경우에만 실행하세요.

이 단계는 한 번만 수행하면 되며, ConnectWise API 정의가 변경될 때마다 수행하면 됩니다.

2. API 자격 증명 구성

ConnectWise 자격 증명으로 다음 환경 변수를 설정하세요.

이러한 자격 증명은 인증 프로세스에서 다음과 같이 사용됩니다.

• CONNECTWISE_API_URL : ConnectWise 인스턴스에 대한 모든 API 요청의 기본 URL입니다.

  url = f"{API_URL}{endpoint}" # e.g., https://na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets

• CONNECTWISE_COMPANY_ID : 회사를 식별하기 위해 각 요청의 'clientId' 헤더에 포함됩니다.

  headers = {'clientId': COMPANY_ID, ...}

• CONNECTWISE_PUBLIC_KEY 및 CONNECTWISE_PRIVATE_KEY : AUTH_PREFIX와 함께 사용되어 기본 인증 자격 증명을 생성합니다.

  username = f"{AUTH_PREFIX}{PUBLIC_KEY}" # e.g., "yourprefix+your_public_key" password = PRIVATE_KEY credentials = f"{username}:{password}" # Combined into "yourprefix+your_public_key:your_private_key"

• CONNECTWISE_AUTH_PREFIX : 인증 사용자 이름에서 공개 키 앞에 추가되는 필수 접두사입니다. ConnectWise API는 통합 유형을 식별하기 위해 이 접두사를 필요로 합니다(예: "api+", "integration+" 등).

모든 요청과 함께 전송되는 최종 HTTP 헤더는 다음과 같습니다.

Claude Desktop 구성

Claude Desktop과 통합하는 방법은 두 가지가 있습니다.

방법 1: NPM 패키지 사용(권장)

NPM을 사용하여 패키지를 설치하세요:

그런 다음 Claude Desktop( claude_desktop_config.json )을 구성합니다.

방법 2: Node.js 스크립트 사용(대체 방법)

저장소를 복제하고 종속성을 설치한 경우 포함된 Node.js 스크립트를 사용할 수 있습니다.

방법 3: 직접 Python 스크립트 경로 사용

Python 스크립트를 직접 사용하려면 다음을 따르세요.

macOS 및 Linux의 경우 적절한 경로 형식을 사용하세요.

테스트를 위해 명령줄에서 직접 서버를 실행할 수 있습니다.

사용 가능한 도구

API Gateway MCP 서버는 ConnectWise API 작업을 위한 여러 도구를 제공합니다.

API 검색 도구

API 실행 도구

빠른 메모리 도구

사용 예

티켓 관련 엔드포인트 검색

자연어를 사용한 검색

GET 요청 실행

새 서비스 티켓 만들기

원시 API 요청 보내기

빠른 메모리 내용 보기

유용한 쿼리를 빠른 메모리에 저장

빠른 메모리 이해

빠른 메모리 기능을 사용하면 자주 사용되는 API 쿼리를 저장하고 검색하여 여러 가지 방법으로 워크플로를 최적화할 수 있습니다.

이익

• 시간 절약: 정확한 엔드포인트나 매개변수를 기억하지 않고도 복잡한 API 호출을 빠르게 실행합니다.

• 오류 감소: 성공적인 API 호출을 재사용하여 잠재적 오류를 최소화합니다.

• 적응형 학습: 시스템은 어떤 API 호출이 사용자에게 가장 가치 있는지 학습합니다.

• 매개변수 지속성: 매개변수와 요청 본문은 향후 사용을 위해 저장됩니다.

작동 원리

1. 자동 학습: 성공적인 API 호출을 실행하면 빠른 메모리에 저장하라는 메시지가 표시됩니다.

2. 지능형 검색: 다음에 동일한 API 엔드포인트를 사용할 때 시스템은 먼저 빠른 메모리를 확인합니다.

3. 매개변수 재사용: 호출에 대한 매개변수를 제공하지 않으면 시스템은 자동으로 빠른 메모리에 저장된 매개변수를 사용합니다.

4. 사용 추적: 시스템은 각 쿼리가 얼마나 자주 사용되는지 추적하고 자주 사용되는 쿼리를 우선 순위로 지정합니다.

빠른 메모리 기능

• 자동 매개변수 제안: 매개변수가 제공되지 않으면 시스템은 Fast Memory에서 매개변수를 제안합니다.

• 사용 카운터: Fast Memory의 쿼리가 사용될 때마다 사용 횟수가 증가합니다.

• 검색 기능: 설명 또는 엔드포인트 경로를 기준으로 저장된 쿼리를 검색합니다.

• 우선순위: 쿼리는 사용 빈도 순으로 표시되며 가장 자주 사용되는 쿼리가 맨 위에 표시됩니다.

빠른 메모리 관리

• 저장된 쿼리 보기: list_fast_memory()

• 특정 쿼리 검색: list_fast_memory("search term")

• 쿼리 삭제: delete_from_fast_memory(query_id)

• 모든 쿼리 지우기: clear_fast_memory()

빠른 메모리 기술 세부 사항

Fast Memory 시스템은 다음을 저장하는 SQLite 데이터베이스( fast_memory_api.db )로 구동됩니다.

• 쿼리 경로 및 메서드

• JSON 형태의 매개변수와 요청 본문

• 사용 지표 및 타임스탬프

• 사용자 친화적인 설명

데이터베이스 구조는 다음과 같습니다.

• id : 저장된 각 쿼리에 대한 고유 식별자

• description : 쿼리가 수행하는 작업에 대한 사용자 제공 설명

• path : API 엔드포인트 경로

• method : HTTP 메서드(GET, POST, PUT 등)

• params : JSON 형식의 쿼리 매개변수

• data : JSON 형식의 요청 본문

• timestamp : 쿼리가 마지막으로 사용된 시간

• usage_count : 쿼리가 사용된 횟수

문제 해결

일반적인 문제

데이터베이스를 찾을 수 없음 오류

해결 방법: ConnectWise API 정의 파일 경로로 build_database.py 스크립트를 실행합니다.

API 인증 문제

해결 방법: 모든 ConnectWise 자격 증명이 올바른지 확인하려면 환경 변수를 확인하세요.

• CONNECTWISE_COMPANY_ID , CONNECTWISE_PUBLIC_KEY 및 CONNECTWISE_PRIVATE_KEY 확인하세요.

• ConnectWise에서 API 키에 필요한 권한이 있는지 확인하세요.

• CONNECTWISE_AUTH_PREFIX 사용자 환경에 맞게 올바르게 설정되었는지 확인하세요.

API 호출 시 시간 초과

해결책:

• 인터넷 연결을 확인하세요

• ConnectWise API가 높은 부하를 겪고 있을 수 있습니다.

• 대용량 데이터 요청의 경우 쿼리에 보다 구체적인 필터를 추가하는 것을 고려하세요.

로그 및 진단

로그 위치

• 메인 로그 파일: api_gateway/api_gateway.log

• SQLite 데이터베이스:

  • API 데이터베이스: api_gateway/connectwise_api.db

  • 빠른 메모리 데이터베이스: api_gateway/fast_memory_api.db

데이터베이스 테스트

데이터베이스가 올바르게 구축되었고 접근 가능한지 확인하세요.

이렇게 하면 데이터베이스에 대한 통계가 표시되고 제대로 쿼리할 수 있는지 확인됩니다.

고급 사용법

API 쿼리 최적화

ConnectWise API를 사용하여 더 나은 성능을 얻으려면:

1. 특정 조건 사용: 정확한 조건으로 쿼리 범위를 좁히세요

   execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]" })

2. 필드 선택 제한: 필요한 필드만 요청하세요

   execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "fields": "id,summary,status,priority" })

3. 큰 결과 페이지 나누기: 페이지 및 페이지 크기 매개변수 사용

   execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "page": 1, "pageSize": 50 })

특허

본 소프트웨어는 독점적이며 기밀입니다. 무단 복제, 배포 또는 사용을 금지합니다.

감사의 말

• MCP(Model Context Protocol) 프레임워크를 사용하여 구축됨

• ConnectWise Manage API 지원