HaloPSA MCP 도구

HaloPSA API와 상호 작용하기 위한 MCP(Model Context Protocol) 서버입니다.

개요

이 패키지는 Claude와 같은 AI 어시스턴트가 HaloPSA API와 상호 작용할 수 있도록 하는 모델 컨텍스트 프로토콜 서버 구현을 제공합니다. 다양한 구성으로 사용할 수 있습니다.

독립형 서버로서
Claude Desktop과 통합
Node.js 애플리케이션의 라이브러리로서

특징

다양한 전송 유형(stdio, http, tcp)을 지원하는 MCP 서버
티켓, 사용자, 자산 등과 상호 작용하기 위한 도구
Claude Desktop과의 원활한 통합
구성 가능한 로깅 및 오류 처리
강력한 보안 검사
MCP SDK와의 교차 버전 호환성

설치

NPM 글로벌 설치

지엑스피1

로컬 설치

npm install haloapi-mcp-tools

구성

다음 환경 변수를 사용하여 프로젝트 루트에 .env 파일을 만듭니다.

# Required HaloPSA API Configuration
HALO_API_URL=https://yourhalo.haloservicedesk.com/api
HALO_CLIENT_ID=your_client_id
HALO_CLIENT_SECRET=your_client_secret

# Optional Configuration
HALO_API_VERSION=v3
HALO_SCOPE=all
HALO_TENANT=your_tenant_id
TRANSPORT=stdio
PORT=3000
DEBUG=false

또는 도구가 Claude Desktop 통합으로 실행되는 경우 Claude Desktop의 구성을 사용할 수 있습니다.

용법

독립형 서버로 사용

# Start the server using stdio transport (default)
haloapi-mcp-server

# Start with HTTP transport
TRANSPORT=http PORT=3000 haloapi-mcp-server

# Start with debug mode
DEBUG=true haloapi-mcp-server

# Command-line options are also available
haloapi-mcp-server --transport http --port 3000 --debug

Claude Desktop과 함께 사용

Claude Desktop과 함께 사용하려면:

패키지를 전역으로 설치합니다.

npm install -g haloapi-mcp-tools

Claude Desktop 설정(설정 > 확장 프로그램 > MCP 서버 추가)에서 이 MCP 서버를 사용하도록 Claude Desktop을 구성하세요.
- 이름: HaloPSA
- 명령어: haloapi-desktop-mcp
- 환경 변수(선택 사항):
  - HALO_API_URL: HaloPSA API URL
  - HALO_CLIENT_ID: 클라이언트 ID
  - HALO_CLIENT_SECRET: 클라이언트 비밀번호
클로드와의 대화에서 HaloPSA 도구를 사용해 보세요!

또는 이 저장소를 복제한 경우 다음을 실행할 수 있습니다.

# Run the MCP server for Claude Desktop
npm run claude

# Run with debug logging
npm run claude:debug

# Or use the convenience script
./run-mcp.sh desktop

MCP 서버는 Claude Desktop 설정의 구성을 자동으로 감지하여 사용합니다.

도서관으로 활용하기

const { startServer } = require('haloapi-mcp-tools');

async function main() {
  const server = await startServer({
    transport: 'stdio', // or 'http', 'tcp'
    port: 3000,
    debug: true,
    haloBaseUrl: 'https://yourhalo.haloservicedesk.com/api',
    haloClientId: 'your_client_id',
    haloClientSecret: 'your_client_secret'
  });
  
  // Server is now running
  console.log('Server started successfully');
  
  // To shut down the server
  // await server.close();
}

main().catch(console.error);

구조

코드베이스는 다음과 같은 구조로 구성됩니다.

src/core/ - Core MCP 서버 구현
src/tools/ - HaloPSA API 작업을 위한 도구 정의
src/utils/ - 로깅, 검증 등을 위한 유틸리티 함수
src/services/ - HaloPSA API 작업을 위한 서비스 계층
src/api/ - HaloPSA용 API 클라이언트
bin/ - 실행 가능한 진입점
scripts/ - 개발 및 유지 관리를 위한 유틸리티 스크립트

MCP 도구

이 패키지는 HaloPSA와 상호 작용하기 위한 여러 도구를 제공하고 Claude Desktop에서 요구하는 표준 MCP 프로토콜 방법을 구현합니다.

티켓 도구

get-tickets : 선택적 필터링을 사용하여 티켓 목록을 가져옵니다.
get-ticket : 특정 티켓에 대한 자세한 정보를 가져옵니다.
create-ticket : 새로운 티켓을 생성합니다
update-ticket : 기존 티켓을 업데이트합니다
delete-ticket : 티켓 삭제
get-ticket-comments : 특정 티켓에 대한 코멘트를 가져옵니다
add-comment : 티켓에 댓글을 추가합니다

사용자 도구

get-users : 선택적 필터링을 사용하여 사용자 목록을 가져옵니다.
get-user : 특정 사용자에 대한 자세한 정보를 가져옵니다.
create-user : 새로운 사용자를 생성합니다
update-user : 기존 사용자 업데이트
delete-user : 사용자 삭제
get-agents : 에이전트 목록을 가져옵니다

자산 도구

get-assets : 선택적 필터링을 사용하여 자산 목록을 가져옵니다.
get-asset : 특정 자산에 대한 자세한 정보를 가져옵니다.
create-asset : 새로운 자산을 생성합니다
update-asset : 기존 자산을 업데이트합니다.
delete-asset : 자산 삭제
get-asset-types : 모든 자산 유형 목록을 가져옵니다.

표준 MCP 방법

resources/list : MCP 서버에서 사용 가능한 모든 리소스를 나열합니다.
prompts/list : Claude Desktop 통합을 위한 모든 사용 가능한 프롬프트를 나열합니다.
tools/list : MCP 서버에서 사용 가능한 모든 도구를 나열합니다.

Claude 데스크톱 통합

이 패키지에는 다양한 MCP SDK 버전에서 작동하는 Claude Desktop 통합을 위한 통합 구현이 포함되어 있습니다.

통합 구현의 주요 특징:

SDK 호환성 계층을 통한 교차 버전 호환성
Claude Desktop 설정에서 자동 구성 감지
강력한 오류 처리 및 대체 메커니즘
포괄적인 로깅 및 디버깅 지원

문제 해결

일반적인 문제

모듈 가져오기

가져오기 또는 모듈 시스템과 관련된 오류가 발생하는 경우:

SyntaxError: Cannot use import statement outside a module

해결 방법: 프로젝트 구성에 맞는 올바른 import 구문을 사용하고 있는지 확인하세요. 이 패키지는 주로 CommonJS를 사용하므로 require() 문을 사용하세요.

인증 오류

HaloPSA 인증과 관련된 오류가 표시되는 경우:

Error: Invalid client credentials

해결 방법: 환경 변수나 구성에서 클라이언트 ID와 클라이언트 비밀번호를 확인하세요.

운송 문제

서버가 특정 전송 유형으로 시작하지 못하는 경우:

Error: Unsupported transport

해결 방법: 지원되는 전송 유형인 'stdio', 'http' 또는 'tcp' 중 하나를 사용하고 있는지 확인하세요.

Claude Desktop 통합 문제

Claude Desktop이 MCP 서버에 연결할 수 없거나 지원되지 않는 방법에 대한 오류가 표시되는 경우:

Error: Method not supported: tools/list

해결 방법: MCP 프로토콜에 대한 강력한 지원과 통합 MCP 구현이 포함된 이 패키지의 최신 버전을 사용하고 있는지 확인하세요.

JSON 구문 분석 오류

MCP 서버 로그에 다음과 같은 JSON 구문 분석 오류가 표시되는 경우:

Error parsing JSON message: Unexpected non-whitespace character after JSON at position X

해결 방법: 최신 버전에는 잘못된 형식의 메시지와 관련된 일반적인 문제를 자동으로 해결하는 향상된 JSON 처리 기능이 포함되어 있습니다. 문제가 지속되면 디버그 모드를 활성화하여 자세한 내용을 확인하세요.

DEBUG=true haloapi-mcp-server

디버깅

자세한 디버깅 정보를 활성화하려면 DEBUG 환경 변수를 설정하세요.

DEBUG=true haloapi-mcp-server

더욱 자세한 정보를 얻으려면 로그 수준을 높일 수도 있습니다.

LOG_LEVEL=trace haloapi-mcp-server

Claude Desktop 통합의 경우 다음 위치에서 로그를 찾을 수 있습니다.

macOS: ~/Library/Logs/Claude/mcp-server-halopsa.log
Windows: %APPDATA%\Claude\Logs\mcp-server-halopsa.log
리눅스: ~/.local/share/claude/logs/mcp-server-halopsa.log

테스트

포함된 테스트 스크립트를 사용하여 MCP 서버를 테스트할 수 있습니다.

# Run the test script against a running server
npm run test:mcp

# Run the automated tests
npm test

대화형 테스트 스크립트를 사용하면 개별 도구를 테스트하고 응답을 검사할 수 있어 디버깅과 개발에 유용합니다.

개발 및 확장

코드베이스는 새로운 기능을 추가하거나 변경할 때 따라야 할 몇 가지 디자인 패턴과 관행을 따릅니다.

디자인 패턴

호환성 계층 패턴 : src/sdk-compat.js 에서 사용되어 다양한 SDK 버전에서 일관된 인터페이스를 제공합니다.
종속성 주입 : 코드베이스 전체에서 모듈에 대한 종속성을 제공하는 데 사용되어 테스트가 더 쉬워지고 모듈성이 높아집니다.
모듈 패턴 : 각 구성 요소는 명확한 책임과 인터페이스를 갖춘 모듈로 구성됩니다.
Facade 패턴 : 주요 진입점( desktop-mcp-unified.js , standalone-mcp.js )은 기본 기능에 대한 단순화된 인터페이스를 제공합니다.

새로운 기능 추가

코드베이스에 새로운 기능을 추가할 때는 다음 단계를 따르세요.

src/tools/ 의 적절한 모듈에 새로운 도구 정의를 추가합니다.
src/tools/index.js 에 새 도구를 등록합니다.
src/utils/ 에 있는 해당 모듈에 새로운 유틸리티 기능을 추가합니다.
tests/ 디렉토리에 새로운 기능에 대한 테스트를 작성하세요.
새로운 기능을 반영하도록 문서를 업데이트하세요.

특허

기여자

술레만 만지( @ssmanji89 )

HaloPSA MCP Tools

Integrations