# AntBot MCP Server
**AntBot MCP Server**는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 기반의 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 # 상수 정의
```
### 핵심 컴포넌트
1. **McpServer 클래스** (`index.ts`)
- MCP 서버 인스턴스 관리
- 요청 핸들러 설정
- 에러 처리 및 로깅
2. **ProjectService 클래스** (`projectService.ts`)
- 프로젝트 목록 조회
- 프로젝트 정보 파싱 (antConf.xml)
- 프로젝트 다운로드 및 실행
- 실행 중 프로세스 감지 (Windows tasklist)
- 캐싱 시스템
3. **LogService 클래스** (`logService.ts`)
- mcprun 로그 파일 조회
- 최신 로그 tail 기능
4. **설정 관리** (`config.ts`)
- AntBot Robot 설정 파일 자동 로드
- 필수 설정 검증
- 동적 설정 관리
## 🛠️ 설치 및 빌드
### 전제 조건
- **Node.js** v16 이상 (권장: LTS 버전)
- **Windows 환경** (AntBot Runner 프로세스 감지 기능)
- **AntBot Robot** 설치 및 매니저 연동 완료
- **AntBot Robot 설정 파일** 존재: `%APPDATA%\Roaming\AntBotRobot\AntBot_Robot.exe.config`
### 설치
```bash
# 프로젝트 클론
git clone <repository-url>
cd antbot-mcp-server
# 의존성 설치
npm install
# 빌드
npm run build
# 또는 클린 빌드 (기존 빌드 파일 삭제 후 재빌드)
npm run cleanbuild
```
## 🧩 MCP 도구 구성
### 1. Get_AntBot_Project_List
AntBot 매니저에서 사용 가능한 프로젝트 목록을 조회합니다.
```json
{
"name": "Get_AntBot_Project_List",
"description": "Returns a list of antbot projects.",
"inputSchema": {
"type": "object",
"properties": {},
"required": []
}
}
```
**응답 예시:**
```json
{
"projects": [
{
"projectId": "PR000000298",
"projectName": "웹 스크래핑 프로젝트",
"description": "웹사이트에서 데이터를 수집하는 프로젝트"
}
]
}
```
### 2. Get_AntBot_Project_Info
특정 프로젝트의 상세 정보와 실행에 필요한 매개변수를 조회합니다.
```json
{
"name": "Get_AntBot_Project_Info",
"description": "Get project information including required parameters",
"inputSchema": {
"type": "object",
"properties": {
"projectId": { "type": "string" }
},
"required": ["projectId"]
}
}
```
**응답 예시:**
```json
{
"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`를 호출하여 프로젝트 정보를 확인해야 합니다.
```json
{
"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"]
}
}
```
**사용 예시:**
```json
{
"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줄을 조회합니다.
```json
{
"name": "Get_Last_Mcprun_Log",
"description": "Returns the last 100 lines of the latest mcprun log.",
"inputSchema": {
"type": "object",
"properties": {},
"required": []
}
}
```
**응답 예시:**
```json
{
"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 사용
```bash
# MCP Inspector 설치
npm install -g @modelcontextprotocol/inspector
# 서버 테스트
npm run inspector
```
### 2. 테스트 시나리오
1. **프로젝트 목록 조회**: `Get_AntBot_Project_List` 호출
2. **프로젝트 정보 조회**: `Get_AntBot_Project_Info` 호출 (projectId 필요)
3. **프로젝트 실행**: `Run_AntBot_Project` 호출 (projectId, projectPath, parameters 필요)
4. **로그 조회**: `Get_Last_Mcprun_Log` 호출
## 🧠 Claude Desktop 연동
### 전제 조건
- Claude Desktop 설치 완료
- AntBot Robot 매니저 연동 완료
- MCP Inspector로 서버 정상 동작 확인
### 등록 방법
#### 방법 1: Claude Desktop GUI
1. Claude Desktop 실행
2. 설정 → 개발자 → 설정편집
3. `%APPDATA%\Roaming\Claude\claude_desktop_config.json` 파일 편집
#### 방법 2: 직접 설정
```json
{
"mcpServers": {
"antbot-mcp-server": {
"command": "node",
"args": ["C:\\path\\to\\antbot-mcp-server\\build\\index.js"]
}
}
}
```
### ⚠️ 중요: Claude Desktop 재시작
설정 변경 후 **반드시 Claude Desktop을 완전히 종료하고 재시작**해야 합니다:
1. 시스템 트레이에서 Claude 아이콘 우클릭
2. **종료** 선택 (완전히 종료)
3. 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 공식 문서](https://modelcontextprotocol.io/docs)
- **이슈 리포트**: GitHub Issues
## 📄 라이선스
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
