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: 수동 설치

윈도우

저장소를 복제하거나 다운로드하세요.
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
패키지를 설치하세요:
pip install -e .

맥OS

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

npm install -g jasondsmith72/CWM-API-Gateway-MCP

수동 설치의 경우:

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
저장소를 복제합니다.
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
가상 환경 설정(권장):
python3 -m venv venv source venv/bin/activate
패키지를 설치하세요:
pip install -e .

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

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

sudo npm install -g jasondsmith72/CWM-API-Gateway-MCP

수동 설치의 경우:

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
저장소를 복제합니다.
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
가상 환경 설정(권장):
python3.10 -m venv venv source venv/bin/activate
패키지를 설치하세요:
pip install -e .

설치 후 단계

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

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

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

# On Windows
python build_database.py path/to/manage.json

# On macOS/Linux
python3 build_database.py path/to/manage.json

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

2. API 자격 증명 구성

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

CONNECTWISE_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0
CONNECTWISE_COMPANY_ID=your_company_id
CONNECTWISE_PUBLIC_KEY=your_public_key
CONNECTWISE_PRIVATE_KEY=your_private_key
CONNECTWISE_AUTH_PREFIX=yourprefix+  # Prefix required by ConnectWise for API authentication

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

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 헤더는 다음과 같습니다.

'Authorization': 'Basic [base64 encoded credentials]'
'clientId': 'your_company_id'
'Content-Type': 'application/json'

Claude Desktop 구성

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

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

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

npm install -g jasondsmith72/CWM-API-Gateway-MCP

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

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "npx",
      "args": [
        "-y",
        "@jasondsmith72/CWM-API-Gateway-MCP"
      ],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

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

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

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "node",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/bin/server.js"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

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

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

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

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

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python3",
      "args": ["/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

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

# If installed via NPM
cwm-api-gateway-mcp

# If using the Node.js script (after cloning the repository)
node bin/server.js

# Or using the Python script directly
# On Windows
python api_gateway_server.py

# On macOS/Linux
python3 api_gateway_server.py

사용 가능한 도구

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

API 검색 도구

도구	설명
`search_api_endpoints`	쿼리 문자열로 API 엔드포인트 검색
`natural_language_api_search`	자연어 설명을 사용하여 엔드포인트 찾기
`list_api_categories`	사용 가능한 모든 API 카테고리 나열
`get_category_endpoints`	특정 카테고리의 모든 엔드포인트 나열
`get_api_endpoint_details`	특정 엔드포인트에 대한 자세한 정보를 얻으세요

API 실행 도구

도구	설명
`execute_api_call`	경로, 메서드, 매개변수 및 데이터를 사용하여 API 호출을 실행합니다.
`send_raw_api_request`	"METHOD /path [JSON body]" 형식으로 원시 API 요청을 보냅니다.

빠른 메모리 도구

도구	설명
`save_to_fast_memory`	API 쿼리를 Fast Memory에 수동으로 저장
`list_fast_memory`	Fast Memory에 저장된 모든 쿼리를 나열합니다.
`delete_from_fast_memory`	Fast Memory에서 특정 쿼리 삭제
`clear_fast_memory`	Fast Memory에서 모든 쿼리를 지웁니다.

사용 예

티켓 관련 엔드포인트 검색

search_api_endpoints("tickets")

자연어를 사용한 검색

natural_language_api_search("find all open service tickets that are high priority")

GET 요청 실행

execute_api_call(
    "/service/tickets", 
    "GET", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

새 서비스 티켓 만들기

execute_api_call(
    "/service/tickets", 
    "POST", 
    None,  # No query parameters 
    {
        "summary": "Server is down",
        "board": {"id": 1},
        "company": {"id": 2},
        "status": {"id": 1},
        "priority": {"id": 3}
    }
)

원시 API 요청 보내기

send_raw_api_request("GET /service/tickets?conditions=status/name='Open'")

빠른 메모리 내용 보기

list_fast_memory()

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

save_to_fast_memory(
    "/service/tickets", 
    "GET", 
    "Get all high priority open tickets", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

빠른 메모리 이해

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

이익

시간 절약: 정확한 엔드포인트나 매개변수를 기억하지 않고도 복잡한 API 호출을 빠르게 실행합니다.
오류 감소: 성공적인 API 호출을 재사용하여 잠재적 오류를 최소화합니다.
적응형 학습: 시스템은 어떤 API 호출이 사용자에게 가장 가치 있는지 학습합니다.
매개변수 지속성: 매개변수와 요청 본문은 향후 사용을 위해 저장됩니다.

작동 원리

자동 학습: 성공적인 API 호출을 실행하면 빠른 메모리에 저장하라는 메시지가 표시됩니다.
지능형 검색: 다음에 동일한 API 엔드포인트를 사용할 때 시스템은 먼저 빠른 메모리를 확인합니다.
매개변수 재사용: 호출에 대한 매개변수를 제공하지 않으면 시스템은 자동으로 빠른 메모리에 저장된 매개변수를 사용합니다.
사용 추적: 시스템은 각 쿼리가 얼마나 자주 사용되는지 추적하고 자주 사용되는 쿼리를 우선 순위로 지정합니다.

빠른 메모리 기능

자동 매개변수 제안: 매개변수가 제공되지 않으면 시스템은 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 : 쿼리가 사용된 횟수

문제 해결

일반적인 문제

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

Error: Database file not found at [path]
Please run build_database.py script first to generate the database

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

python build_database.py path/to/manage.json

API 인증 문제

HTTP error 401: Unauthorized

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

CONNECTWISE_COMPANY_ID , CONNECTWISE_PUBLIC_KEY 및 CONNECTWISE_PRIVATE_KEY 확인하세요.
ConnectWise에서 API 키에 필요한 권한이 있는지 확인하세요.
CONNECTWISE_AUTH_PREFIX 사용자 환경에 맞게 올바르게 설정되었는지 확인하세요.

API 호출 시 시간 초과

Request timed out. ConnectWise API may be slow to respond.

해결책:

인터넷 연결을 확인하세요
ConnectWise API가 높은 부하를 겪고 있을 수 있습니다.
대용량 데이터 요청의 경우 쿼리에 보다 구체적인 필터를 추가하는 것을 고려하세요.

로그 및 진단

로그 위치

메인 로그 파일: api_gateway/api_gateway.log
SQLite 데이터베이스:
- API 데이터베이스: api_gateway/connectwise_api.db
- 빠른 메모리 데이터베이스: api_gateway/fast_memory_api.db

데이터베이스 테스트

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

python test_database.py

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

고급 사용법

API 쿼리 최적화

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

특정 조건 사용: 정확한 조건으로 쿼리 범위를 좁히세요
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]" })
필드 선택 제한: 필요한 필드만 요청하세요
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "fields": "id,summary,status,priority" })
큰 결과 페이지 나누기: 페이지 및 페이지 크기 매개변수 사용
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "page": 1, "pageSize": 50 })

특허

감사의 말

MCP(Model Context Protocol) 프레임워크를 사용하여 구축됨
ConnectWise Manage API 지원

Integrations