HaloPSA MCP 도구

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

개요

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

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

Related MCP server: Bluesky MCP Server

특징

다양한 전송 유형(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