AntBot MCP Server

AntBot MCP Server는 Model Context Protocol (MCP) 기반의 TypeScript 서버로, AI 기반 RPA 플랫폼인 AntBot과의 연동을 위해 설계되었습니다.
이 서버는 MCP 클라이언트와 상호작용하며, AntBot 프로젝트 관리 및 실행을 위한 도구들을 제공합니다.

✨ 주요 기능

MCP Tool 서버 인터페이스 구현
AntBot 프로젝트 목록 조회 (Get_AntBot_Project_List)
프로젝트 상세 정보 조회 (Get_AntBot_Project_Info) - 매개변수 정보 포함
프로젝트 실행 (Run_AntBot_Project) - 매개변수 전달 지원
실행 중 프로세스 감지 - 중복 실행 방지 (Windows 환경)
실행 로그 조회 (Get_Last_Mcprun_Log) - 최신 mcprun 로그 확인
자동 설정 관리 - AntBot Robot 설정 파일에서 자동으로 설정 로드
프로젝트 캐싱 - 성능 최적화를 위한 프로젝트 정보 캐싱
로깅 시스템 - 상세한 로그 기록 및 디버깅 지원
TypeScript 기반 모듈형 구조

🏗️ 아키텍처

프로젝트 구조

src/
├── index.ts              # MCP 서버 진입점 및 메인 클래스
├── projectService.ts     # 프로젝트 관리 비즈니스 로직
├── logService.ts         # 로그 조회 서비스
├── api.ts                # 외부 API 호출 유틸리티
├── config.ts             # 설정 관리 및 검증
├── fileUtils.ts          # 파일 처리 유틸리티 (ZIP, XML 파싱)
├── logger.ts             # 로깅 시스템
├── schema.ts             # Zod 기반 입력 검증 스키마
├── types.ts              # TypeScript 타입 정의
└── constants.ts          # 상수 정의

핵심 컴포넌트

McpServer 클래스 (index.ts)
- MCP 서버 인스턴스 관리
- 요청 핸들러 설정
- 에러 처리 및 로깅
ProjectService 클래스 (projectService.ts)
- 프로젝트 목록 조회
- 프로젝트 정보 파싱 (antConf.xml)
- 프로젝트 다운로드 및 실행
- 실행 중 프로세스 감지 (Windows tasklist)
- 캐싱 시스템
LogService 클래스 (logService.ts)
- mcprun 로그 파일 조회
- 최신 로그 tail 기능
설정 관리 (config.ts)
- AntBot Robot 설정 파일 자동 로드
- 필수 설정 검증
- 동적 설정 관리

🛠️ 설치 및 빌드

전제 조건

Node.js v16 이상 (권장: LTS 버전)
Windows 환경 (AntBot Runner 프로세스 감지 기능)
AntBot Robot 설치 및 매니저 연동 완료
AntBot Robot 설정 파일 존재: %APPDATA%\Roaming\AntBotRobot\AntBot_Robot.exe.config

설치

# 프로젝트 클론
git clone <repository-url>
cd antbot-mcp-server

# 의존성 설치
npm install

# 빌드
npm run build

# 또는 클린 빌드 (기존 빌드 파일 삭제 후 재빌드)
npm run cleanbuild

🧩 MCP 도구 구성

1. Get_AntBot_Project_List

AntBot 매니저에서 사용 가능한 프로젝트 목록을 조회합니다.

{
  "name": "Get_AntBot_Project_List",
  "description": "Returns a list of antbot projects.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

응답 예시:

{
  "projects": [
    {
      "projectId": "PR000000298",
      "projectName": "웹 스크래핑 프로젝트",
      "description": "웹사이트에서 데이터를 수집하는 프로젝트"
    }
  ]
}

2. Get_AntBot_Project_Info

특정 프로젝트의 상세 정보와 실행에 필요한 매개변수를 조회합니다.

{
  "name": "Get_AntBot_Project_Info",
  "description": "Get project information including required parameters",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectId": { "type": "string" }
    },
    "required": ["projectId"]
  }
}

응답 예시:

{
  "projectId": "PR000000298",
  "projectPath": "C:\\temp\\project_298\\antConf.xml",
  "name": "웹 스크래핑 프로젝트",
  "description": "웹사이트에서 데이터를 수집하는 프로젝트",
  "requiredParameters": [
    {
      "name": "url",
      "type": "string",
      "description": "스크래핑할 웹사이트 URL"
    }
  ],
  "optionalParameters": [
    {
      "name": "timeout",
      "type": "number",
      "description": "타임아웃 시간 (초)",
      "defaultValue": 30
    }
  ],
  "parameterSummary": "필수: url (string) | 선택: timeout (number, 기본값: 30)"
}

3. Run_AntBot_Project

프로젝트를 실행합니다. 먼저 Get_AntBot_Project_Info를 호출하여 프로젝트 정보를 확인해야 합니다.

{
  "name": "Run_AntBot_Project",
  "description": "Run the project with required parameters",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectId": { "type": "string" },
      "projectPath": { "type": "string" },
      "parameters": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "required": ["projectId", "projectPath"]
  }
}

사용 예시:

{
  "projectId": "PR000000298",
  "projectPath": "C:\\temp\\project_298\\antConf.xml",
  "parameters": {
    "url": "https://example.com",
    "timeout": 60
  }
}

중복 실행 방지:

실행 전 AntBot Runner 프로세스 상태 확인
이미 실행 중이면 "현재 AntBot이 다른 작업을 수행 중입니다." 메시지와 함께 오류 발생

4. Get_Last_Mcprun_Log

최신 mcprun 로그의 마지막 100줄을 조회합니다.

{
  "name": "Get_Last_Mcprun_Log",
  "description": "Returns the last 100 lines of the latest mcprun log.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

응답 예시:

{
  "fileName": "mcprun_20241201143022.log",
  "content": "2024-12-01 14:30:22 [INFO] 프로젝트 실행 시작\n2024-12-01 14:30:23 [INFO] 매개변수 로드 완료\n..."
}

🔧 주요 스크립트

명령어	설명
`npm run build`	TypeScript 컴파일 및 실행 권한 설정
`npm run clean`	빌드 디렉토리 삭제
`npm run cleanbuild`	클린 후 재빌드
`npm run watch`	파일 변경 감지 시 자동 빌드
`npm run inspector`	MCP Inspector로 테스트 실행

🧪 테스트 방법

1. MCP Inspector 사용

# MCP Inspector 설치
npm install -g @modelcontextprotocol/inspector

# 서버 테스트
npm run inspector

2. 테스트 시나리오

프로젝트 목록 조회: Get_AntBot_Project_List 호출
프로젝트 정보 조회: Get_AntBot_Project_Info 호출 (projectId 필요)
프로젝트 실행: Run_AntBot_Project 호출 (projectId, projectPath, parameters 필요)
로그 조회: Get_Last_Mcprun_Log 호출

🧠 Claude Desktop 연동

전제 조건

Claude Desktop 설치 완료
AntBot Robot 매니저 연동 완료
MCP Inspector로 서버 정상 동작 확인

등록 방법

방법 1: Claude Desktop GUI

Claude Desktop 실행
설정 → 개발자 → 설정편집
%APPDATA%\Roaming\Claude\claude_desktop_config.json 파일 편집

방법 2: 직접 설정

{
  "mcpServers": {
    "antbot-mcp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\antbot-mcp-server\\build\\index.js"]
    }
  }
}

⚠️ 중요: Claude Desktop 재시작

설정 변경 후 반드시 Claude Desktop을 완전히 종료하고 재시작해야 합니다:

시스템 트레이에서 Claude 아이콘 우클릭
종료 선택 (완전히 종료)
Claude Desktop 다시 실행

💡 참고: 단순히 창을 닫는 것이 아니라 트레이 아이콘을 통해 완전히 종료해야 설정이 적용됩니다.

사용 예시

Claude에게 다음과 같이 요청할 수 있습니다:

"AntBot 프로젝트 목록을 보여줘"
"PR000000298 프로젝트의 정보를 알려줘"
"PR000000298 프로젝트를 실행해줘"
"최신 실행 로그를 보여줘"

⚙️ 설정 관리

자동 설정 로드

서버는 다음 경로의 AntBot Robot 설정 파일을 자동으로 읽어옵니다:

%APPDATA%\Roaming\AntBotRobot\AntBot_Robot.exe.config

필수 설정 항목

MANAGER_USER: 매니저 사용자 ID
MANAGER_IP: 매니저 서버 IP
MANAGER_PORT: 매니저 서버 포트
AntBot Runner: AntBot Runner 실행 파일 경로

설정 검증

서버 시작 시 필수 설정이 누락된 경우 오류를 발생시킵니다:

AntBot Robot에서 매니저 연동을 먼저 진행해주세요.

🔍 로깅 및 디버깅

로그 위치

%USERPROFILE%\.AntBot\Log\Develop\

로그 레벨

INFO: 일반적인 작업 정보
DEBUG: 상세한 디버깅 정보
WARN: 경고 정보 (프로세스 감지 실패 등)
ERROR: 오류 정보

주요 로그 메시지

서버 초기화 및 시작
API 호출 결과
프로젝트 다운로드 및 실행 상태
설정 검증 결과
AntBot Runner 프로세스 상태 확인

mcprun 로그

파일명 형식: mcprun_YYYYMMDDHHMMSS.log
위치: %USERPROFILE%\.AntBot\Log\Develop\
MCP 도구를 통해 최신 로그 조회 가능

📦 의존성

핵심 의존성

@modelcontextprotocol/sdk: MCP 서버 구현
jsdom: XML 설정 파일 파싱
adm-zip: 프로젝트 ZIP 파일 처리
sudo-prompt: 관리자 권한 실행 (필요시)
xml2js: XML 파싱

개발 의존성

typescript: TypeScript 컴파일러
rimraf: 크로스 플랫폼 디렉토리 삭제
@types/*: 타입 정의

🚀 성능 최적화

캐싱 시스템

프로젝트 정보 캐싱 (5분)
중복 다운로드 방지
API 호출 최적화

에러 처리

상세한 에러 메시지
재시도 로직
Graceful degradation

프로세스 관리

Windows tasklist를 통한 프로세스 감지
중복 실행 방지로 리소스 보호
보수적 처리 (감지 실패 시 실행 허용)

🔒 보안 및 안정성

프로세스 감지

Windows 환경에서만 지원
tasklist 명령어를 통한 안전한 프로세스 확인
감지 실패 시에도 안정성 보장

권한 관리

sudo-prompt를 통한 관리자 권한 실행
필요한 경우에만 권한 상승

📞 지원 및 문의

AntBot 관련: ICT AX솔루션팀
MCP 관련: MCP 공식 문서
이슈 리포트: GitHub Issues

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

AntBot MCP Server

✨ 주요 기능

MCP Tool 서버 인터페이스 구현
AntBot 프로젝트 목록 조회 (Get_AntBot_Project_List)
프로젝트 상세 정보 조회 (Get_AntBot_Project_Info) - 매개변수 정보 포함
프로젝트 실행 (Run_AntBot_Project) - 매개변수 전달 지원
실행 중 프로세스 감지 - 중복 실행 방지 (Windows 환경)
실행 로그 조회 (Get_Last_Mcprun_Log) - 최신 mcprun 로그 확인
자동 설정 관리 - AntBot Robot 설정 파일에서 자동으로 설정 로드
프로젝트 캐싱 - 성능 최적화를 위한 프로젝트 정보 캐싱
로깅 시스템 - 상세한 로그 기록 및 디버깅 지원
TypeScript 기반 모듈형 구조

🏗️ 아키텍처

프로젝트 구조

src/
├── index.ts              # MCP 서버 진입점 및 메인 클래스
├── projectService.ts     # 프로젝트 관리 비즈니스 로직
├── logService.ts         # 로그 조회 서비스
├── api.ts                # 외부 API 호출 유틸리티
├── config.ts             # 설정 관리 및 검증
├── fileUtils.ts          # 파일 처리 유틸리티 (ZIP, XML 파싱)
├── logger.ts             # 로깅 시스템
├── schema.ts             # Zod 기반 입력 검증 스키마
├── types.ts              # TypeScript 타입 정의
└── constants.ts          # 상수 정의

핵심 컴포넌트

McpServer 클래스 (index.ts)
- MCP 서버 인스턴스 관리
- 요청 핸들러 설정
- 에러 처리 및 로깅
ProjectService 클래스 (projectService.ts)
- 프로젝트 목록 조회
- 프로젝트 정보 파싱 (antConf.xml)
- 프로젝트 다운로드 및 실행
- 실행 중 프로세스 감지 (Windows tasklist)
- 캐싱 시스템
LogService 클래스 (logService.ts)
- mcprun 로그 파일 조회
- 최신 로그 tail 기능
설정 관리 (config.ts)
- AntBot Robot 설정 파일 자동 로드
- 필수 설정 검증
- 동적 설정 관리

🛠️ 설치 및 빌드

전제 조건

Node.js v16 이상 (권장: LTS 버전)
Windows 환경 (AntBot Runner 프로세스 감지 기능)
AntBot Robot 설치 및 매니저 연동 완료
AntBot Robot 설정 파일 존재: %APPDATA%\Roaming\AntBotRobot\AntBot_Robot.exe.config

설치

# 프로젝트 클론
git clone <repository-url>
cd antbot-mcp-server

# 의존성 설치
npm install

# 빌드
npm run build

# 또는 클린 빌드 (기존 빌드 파일 삭제 후 재빌드)
npm run cleanbuild

🧩 MCP 도구 구성

1. Get_AntBot_Project_List

AntBot 매니저에서 사용 가능한 프로젝트 목록을 조회합니다.

{
  "name": "Get_AntBot_Project_List",
  "description": "Returns a list of antbot projects.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

응답 예시:

{
  "projects": [
    {
      "projectId": "PR000000298",
      "projectName": "웹 스크래핑 프로젝트",
      "description": "웹사이트에서 데이터를 수집하는 프로젝트"
    }
  ]
}

2. Get_AntBot_Project_Info

특정 프로젝트의 상세 정보와 실행에 필요한 매개변수를 조회합니다.

{
  "name": "Get_AntBot_Project_Info",
  "description": "Get project information including required parameters",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectId": { "type": "string" }
    },
    "required": ["projectId"]
  }
}

응답 예시:

{
  "projectId": "PR000000298",
  "projectPath": "C:\\temp\\project_298\\antConf.xml",
  "name": "웹 스크래핑 프로젝트",
  "description": "웹사이트에서 데이터를 수집하는 프로젝트",
  "requiredParameters": [
    {
      "name": "url",
      "type": "string",
      "description": "스크래핑할 웹사이트 URL"
    }
  ],
  "optionalParameters": [
    {
      "name": "timeout",
      "type": "number",
      "description": "타임아웃 시간 (초)",
      "defaultValue": 30
    }
  ],
  "parameterSummary": "필수: url (string) | 선택: timeout (number, 기본값: 30)"
}

3. Run_AntBot_Project

프로젝트를 실행합니다. 먼저 Get_AntBot_Project_Info를 호출하여 프로젝트 정보를 확인해야 합니다.

{
  "name": "Run_AntBot_Project",
  "description": "Run the project with required parameters",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectId": { "type": "string" },
      "projectPath": { "type": "string" },
      "parameters": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "required": ["projectId", "projectPath"]
  }
}

사용 예시:

{
  "projectId": "PR000000298",
  "projectPath": "C:\\temp\\project_298\\antConf.xml",
  "parameters": {
    "url": "https://example.com",
    "timeout": 60
  }
}

중복 실행 방지:

실행 전 AntBot Runner 프로세스 상태 확인
이미 실행 중이면 "현재 AntBot이 다른 작업을 수행 중입니다." 메시지와 함께 오류 발생

4. Get_Last_Mcprun_Log

최신 mcprun 로그의 마지막 100줄을 조회합니다.

{
  "name": "Get_Last_Mcprun_Log",
  "description": "Returns the last 100 lines of the latest mcprun log.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

응답 예시:

{
  "fileName": "mcprun_20241201143022.log",
  "content": "2024-12-01 14:30:22 [INFO] 프로젝트 실행 시작\n2024-12-01 14:30:23 [INFO] 매개변수 로드 완료\n..."
}

🔧 주요 스크립트

명령어	설명
`npm run build`	TypeScript 컴파일 및 실행 권한 설정
`npm run clean`	빌드 디렉토리 삭제
`npm run cleanbuild`	클린 후 재빌드
`npm run watch`	파일 변경 감지 시 자동 빌드
`npm run inspector`	MCP Inspector로 테스트 실행

🧪 테스트 방법

1. MCP Inspector 사용

# MCP Inspector 설치
npm install -g @modelcontextprotocol/inspector

# 서버 테스트
npm run inspector

2. 테스트 시나리오

프로젝트 목록 조회: Get_AntBot_Project_List 호출
프로젝트 정보 조회: Get_AntBot_Project_Info 호출 (projectId 필요)
프로젝트 실행: Run_AntBot_Project 호출 (projectId, projectPath, parameters 필요)
로그 조회: Get_Last_Mcprun_Log 호출

🧠 Claude Desktop 연동

전제 조건

Claude Desktop 설치 완료
AntBot Robot 매니저 연동 완료
MCP Inspector로 서버 정상 동작 확인

등록 방법

방법 1: Claude Desktop GUI

Claude Desktop 실행
설정 → 개발자 → 설정편집
%APPDATA%\Roaming\Claude\claude_desktop_config.json 파일 편집

방법 2: 직접 설정

{
  "mcpServers": {
    "antbot-mcp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\antbot-mcp-server\\build\\index.js"]
    }
  }
}

⚠️ 중요: Claude Desktop 재시작

설정 변경 후 반드시 Claude Desktop을 완전히 종료하고 재시작해야 합니다:

시스템 트레이에서 Claude 아이콘 우클릭
종료 선택 (완전히 종료)
Claude Desktop 다시 실행

💡 참고: 단순히 창을 닫는 것이 아니라 트레이 아이콘을 통해 완전히 종료해야 설정이 적용됩니다.

사용 예시

Claude에게 다음과 같이 요청할 수 있습니다:

"AntBot 프로젝트 목록을 보여줘"
"PR000000298 프로젝트의 정보를 알려줘"
"PR000000298 프로젝트를 실행해줘"
"최신 실행 로그를 보여줘"

⚙️ 설정 관리

자동 설정 로드

서버는 다음 경로의 AntBot Robot 설정 파일을 자동으로 읽어옵니다:

%APPDATA%\Roaming\AntBotRobot\AntBot_Robot.exe.config

필수 설정 항목

MANAGER_USER: 매니저 사용자 ID
MANAGER_IP: 매니저 서버 IP
MANAGER_PORT: 매니저 서버 포트
AntBot Runner: AntBot Runner 실행 파일 경로

설정 검증

서버 시작 시 필수 설정이 누락된 경우 오류를 발생시킵니다:

AntBot Robot에서 매니저 연동을 먼저 진행해주세요.

🔍 로깅 및 디버깅

로그 위치

%USERPROFILE%\.AntBot\Log\Develop\

로그 레벨

INFO: 일반적인 작업 정보
DEBUG: 상세한 디버깅 정보
WARN: 경고 정보 (프로세스 감지 실패 등)
ERROR: 오류 정보

주요 로그 메시지

서버 초기화 및 시작
API 호출 결과
프로젝트 다운로드 및 실행 상태
설정 검증 결과
AntBot Runner 프로세스 상태 확인

mcprun 로그

파일명 형식: mcprun_YYYYMMDDHHMMSS.log
위치: %USERPROFILE%\.AntBot\Log\Develop\
MCP 도구를 통해 최신 로그 조회 가능

📦 의존성

핵심 의존성

@modelcontextprotocol/sdk: MCP 서버 구현
jsdom: XML 설정 파일 파싱
adm-zip: 프로젝트 ZIP 파일 처리
sudo-prompt: 관리자 권한 실행 (필요시)
xml2js: XML 파싱

개발 의존성

typescript: TypeScript 컴파일러
rimraf: 크로스 플랫폼 디렉토리 삭제
@types/*: 타입 정의

🚀 성능 최적화

캐싱 시스템

프로젝트 정보 캐싱 (5분)
중복 다운로드 방지
API 호출 최적화

에러 처리

상세한 에러 메시지
재시도 로직
Graceful degradation

프로세스 관리

Windows tasklist를 통한 프로세스 감지
중복 실행 방지로 리소스 보호
보수적 처리 (감지 실패 시 실행 허용)

🔒 보안 및 안정성

프로세스 감지

Windows 환경에서만 지원
tasklist 명령어를 통한 안전한 프로세스 확인
감지 실패 시에도 안정성 보장

권한 관리

sudo-prompt를 통한 관리자 권한 실행
필요한 경우에만 권한 상승

📞 지원 및 문의

AntBot 관련: ICT AX솔루션팀
MCP 관련: MCP 공식 문서
이슈 리포트: GitHub Issues

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.