Freshdesk API v2 통합을 위한 Model Context Protocol (MCP) 서버 구현체입니다. 이 서버는 MCP 인터페이스를 통해 티켓(tickets), 연락처(contacts), 에이전트(agents), 회사(companies) 및 대화(conversations)를 관리할 수 있는 도구를 제공합니다.

완전한 Freshdesk API v2 통합: 핵심 Freshdesk 리소스에 대한 전체 지원
내장 인증 (Built-in Authentication): 입력 검증을 포함한 보안 API 키 기반 인증
속도 제한 (Rate Limiting): 구성 가능한 제한을 통한 자동 속도 제한 처리
오류 처리 (Error Handling): 재시도 로직 및 지수 백오프 (exponential backoff)를 포함한 포괄적인 오류 처리
타입 안전성 (Type Safety): 엄격한 타이핑을 적용한 전체 TypeScript 구현
로깅 (Logging): Pino를 사용한 구조화된 로깅
보안 (Security): 입력 검증, 인젝션 방지 및 인증 보안 테스트

npm install
npm run build

프로젝트 루트에 다음과 같은 변수를 포함하는 .env 파일을 생성하세요:

# 필수 (Required)
FRESHDESK_DOMAIN=yourcompany.freshdesk.com # 또는 그냥 "yourcompany"
FRESHDESK_API_KEY=your_api_key_here
...

# 자동 재로드 기능이 포함된 개발 모드 (Development mode with auto-reload)
npm run dev
# 프로덕션 모드 (Production mode)
...

MCP 클라이언트 설정에 추가하세요:

{
"mcpServers": {
"freshdesk": {
...

Freshdesk 티켓 관리 - 티켓 생성, 업데이트, 목록 조회, 가져오기, 삭제 및 검색.

작업 (Actions):

create : 새 티켓 생성
update : 기존 티켓 업데이트
list : 필터를 사용한 티켓 목록 조회
get : 특정 티켓 가져오기
delete : 티켓 삭제
search : 쿼리로 티켓 검색

Freshdesk 연락처 관리 - 연락처 생성, 업데이트, 목록 조회, 가져오기, 삭제, 검색 및 병합.

작업 (Actions):

create : 새 연락처 생성
update : 기존 연락처 업데이트
list : 필터를 사용한 연락처 목록 조회
get : 특정 연락처 가져오기
delete : 연락처 삭제
search : 연락처 검색
merge : 여러 연락처 병합

Freshdesk 에이전트 관리 - 에이전트 목록 조회, 가져오기, 업데이트 및 에이전트의 그룹과 역할 확인.

작업 (Actions):

list : 모든 에이전트 목록 조회
get : 특정 에이전트 가져오기
update : 에이전트 상세 정보 업데이트
get_current

get_current : 현재 인증된 에이전트 가져오기
list_groups : 에이전트의 그룹 목록 조회
list_roles : 에이전트의 역할 (Roles) 목록 조회

Freshdesk 회사 관리 - 회사 생성, 업데이트, 목록 조회, 가져오기, 삭제, 검색 및 회사 연락처 목록 조회를 수행합니다.

Actions:

create : 새로운 회사 생성
update : 기존 회사 업데이트
list : 회사 목록 조회
get : 특정 회사 가져오기
delete : 회사 삭제
search : 회사 검색
list_contacts : 회사 내 연락처 목록 조회

Freshdesk 티켓 대화 (Ticket Conversations) 관리 - 답장 및 노트 생성, 대화 목록 조회, 가져오기, 업데이트 및 삭제를 수행합니다.

Actions:

create_reply : 티켓에 답장 추가
create_note : 티켓에 노트 추가
list : 티켓 대화 목록 조회
get : 특정 대화 가져오기
update : 대화 업데이트
delete : 대화 삭제

{
"tool": "tickets_manage",
"arguments": {
...

{
"tool": "contacts_manage",
"arguments": {
...

{
"tool": "conversations_manage",
"arguments": {
...

npm test
npm run test:watch
npm run test:coverage

npm run lint
npm run lint:fix
npm run format
...

npm run typecheck

src/
├── api/ # API 클라이언트 구현
├── auth/ # 인증 (Authentication) 로직
...

서버는 포괄적인 에러 핸들링 (Error Handling)을 구현합니다:

네트워크 에러 (Network Errors): 지수 백오프 (Exponential Backoff)를 통한 자동 재시도
속도 제한 (Rate Limiting): 자동 스로틀링 (Throttling)을 통해 Freshdesk API의 속도 제한을 준수
인증 에러 (Authentication Errors): 잘못된 API 키에 대한 명확한 에러 메시지 제공
유효성 검사 에러 (Validation Errors): 상세한 에러 메시지를 포함한 입력값 유효성 검사
API 에러 (API Errors): Freshdesk API 응답으로부터 적절한 에러 매핑

• API 키는 절대 로그에 남기거나 노출하지 않음
• 모든 입력값은 Zod 스키마를 사용하여 유효성 검사 수행
• Freshdesk API로의 보안 HTTPS 연결
• 환경 기반 설정 (Environment-based configuration)

MIT