SUNGMYEONGGI/ninehire-mcp-server

나인하이어 MCP 서버

나인하이어(NineHire) HR 자동화 플랫폼을 위한 MCP(Model Context Protocol) 서버입니다. 이 서버를 통해 자연어로 채용 워크플로우를 자동화할 수 있습니다.

🚀 주요 기능

• 채용 공고 관리: 채용 공고 목록 조회, 검색, 상세 정보 조회
• 자연어 인터페이스: MCP를 통한 자연어 기반 상호작용
• 실시간 API 연동: 나인하이어 공식 API와 실시간 연동
• 유연한 필터링: 직군, 고용형태, 태그 등 다양한 조건으로 검색
• 비동기 처리: 고성능 비동기 API 호출

📋 요구사항

• Python: 3.8 이상
• 나인하이어 API 키: 엔터프라이즈 요금제 필요
• 운영체제: Windows, macOS, Linux 지원

🛠️ 설치 및 설정

1. 프로젝트 클론

git clone <repository-url>
cd ninehire-mcp

2. 패키지 설치

# pip 사용
pip install -e .

# 또는 개발 의존성까지 설치
pip install -e ".[dev]"

3. 환경 변수 설정

.env 파일을 생성하고 나인하이어 API 키를 설정합니다:

cp env.example .env

.env 파일 내용:

# 나인하이어 API 설정 (필수)
NINEHIRE_API_KEY=your_ninehire_api_key_here
NINEHIRE_API_BASE_URL=https://api.ninehire.com/api/v1

# MCP 서버 설정 (선택사항)
MCP_SERVER_NAME=ninehire-mcp-server
MCP_SERVER_VERSION=1.0.0

# 로깅 설정 (선택사항)
LOG_LEVEL=INFO
DEBUG=False

4. API 연결 테스트

python test_client.py

성공 시 다음과 같은 출력을 확인할 수 있습니다:

🚀 나인하이어 MCP 서버 테스트 시작

🔧 설정 정보:
  - API 베이스 URL: https://api.ninehire.com/api/v1
  - 디버그 모드: False

▶️  API 연결 테스트 시작
🔍 나인하이어 API 연결 테스트 중...
✅ API 연결 성공!
✅ API 연결 테스트 완료

📊 테스트 결과: 4/4 통과
🎉 모든 테스트가 성공했습니다!

🎯 MCP 서버 실행

직접 실행

python -m ninehire_mcp.server

CLI 명령어 실행

ninehire-mcp-server

스크립트 실행

# 개발 모드로 실행
DEBUG=True python -m ninehire_mcp.server

# 로그 레벨 변경하여 실행
LOG_LEVEL=DEBUG python -m ninehire_mcp.server

서버가 성공적으로 시작되면 다음과 같은 메시지가 출력됩니다:

INFO - 나인하이어 MCP 서버 초기화 시작
INFO - 나인하이어 API 연결 테스트 성공
INFO - 나인하이어 MCP 서버 초기화 완료
INFO - 나인하이어 MCP 서버 시작: ninehire-mcp-server v1.0.0

🔧 사용 가능한 MCP 도구

1. ninehire_get_jobs - 채용 공고 목록 조회

채용 공고 목록을 조회합니다.

파라미터:

• page (선택사항): 페이지 번호 (기본값: 1)
• limit (선택사항): 페이지당 결과 수 (기본값: 10, 최대: 100)
• title (선택사항): 채용 공고 제목으로 검색
• tags (선택사항): 태그 목록으로 필터링
• job_group (선택사항): 직군으로 필터링
• employment_type (선택사항): 고용 형태로 필터링
• include_unpublished (선택사항): 마감된 공고 포함 여부
• include_private (선택사항): 비공개 공고 포함 여부

사용 예시:

{
  "page": 1,
  "limit": 20,
  "job_group": "개발",
  "employment_type": "full_time"
}

2. ninehire_get_job_detail - 채용 공고 상세 조회

특정 채용 공고의 상세 정보를 조회합니다.

파라미터:

• job_id (필수): 조회할 채용 공고 ID
• language (선택사항): 언어 설정 ("korean" 또는 "english")

사용 예시:

{
  "job_id": "job_12345",
  "language": "korean"
}

3. ninehire_search_jobs - 채용 공고 검색

키워드와 조건으로 채용 공고를 검색합니다.

파라미터:

• keyword (선택사항): 검색 키워드
• job_group (선택사항): 직군
• employment_type (선택사항): 고용 형태
• tags (선택사항): 태그 목록
• affiliation (선택사항): 소속
• page (선택사항): 페이지 번호
• limit (선택사항): 결과 수 제한

사용 예시:

{
  "keyword": "백엔드 개발자",
  "job_group": "개발",
  "employment_type": "full_time",
  "tags": ["Python", "Django"],
  "limit": 10
}

🎪 자연어 사용 예시

MCP 클라이언트(Claude, ChatGPT 등)에서 다음과 같이 자연어로 요청할 수 있습니다:

채용 공고 조회

• "나인하이어에서 최신 채용 공고 10개를 보여줘"
• "개발 직군의 정규직 채용 공고를 찾아줘"
• "Python 태그가 있는 채용 공고를 검색해줘"

상세 정보 조회

• "채용 공고 ID job_12345의 상세 정보를 알려줘"
• "첫 번째 채용 공고의 자세한 내용을 보여줘"

조건별 검색

• "백엔드 개발자 채용 공고를 찾아줘"
• "스타트업에서 프리랜서로 일할 수 있는 공고가 있나?"
• "마감일이 임박한 채용 공고를 보여줘"

🐛 문제 해결

API 키 관련 오류

❌ 나인하이어 API 키가 설정되지 않았습니다.

해결방법:

1. .env 파일에 NINEHIRE_API_KEY 설정 확인
2. 나인하이어 관리자 페이지에서 API 키 발급 확인
3. 엔터프라이즈 요금제 가입 여부 확인

API 연결 실패

❌ 나인하이어 API 연결 실패!

해결방법:

1. 인터넷 연결 상태 확인
2. API 키 유효성 확인
3. 방화벽 설정 확인
4. API 베이스 URL 확인 (https://api.ninehire.com/api/v1)

의존성 오류

ModuleNotFoundError: No module named 'mcp'

해결방법:

pip install -e ".[dev]"

📚 개발자 가이드

코드 구조

ninehire_mcp/
├── __init__.py                 # 패키지 초기화
├── config.py                   # 설정 관리
├── server.py                   # MCP 서버 메인 코드
├── api/                        # API 클라이언트
│   ├── __init__.py
│   ├── client.py              # 나인하이어 API 클라이언트
│   └── types.py               # API 타입 정의
└── tools/                      # MCP 도구들
    ├── __init__.py
    ├── base.py                # 도구 베이스 클래스
    └── jobs.py                # 채용 공고 관련 도구

새로운 도구 추가

1. ninehire_mcp/tools/ 디렉토리에 새 파일 생성
2. BaseTool 클래스를 상속받는 도구 클래스 구현
3. schema 속성과 execute 메서드 구현
4. tools/__init__.py에 새 도구 추가

테스트 실행

# 기본 테스트
python test_client.py

# 특정 기능만 테스트
python -c "
import asyncio
from test_client import test_api_connection
asyncio.run(test_api_connection())
"

로깅 설정

import logging

# 디버그 모드 활성화
logging.getLogger('ninehire_mcp').setLevel(logging.DEBUG)

# 또는 환경변수로 설정
DEBUG=True LOG_LEVEL=DEBUG python -m ninehire_mcp.server

🔄 WebHook 연동 (향후 예정)

나인하이어 웹훅 이벤트를 처리하여 실시간 워크플로우 자동화를 지원할 예정입니다.

지원 예정 이벤트:

• 지원자 합격/불합격 상태 변경
• 새로운 지원서 접수
• 면접 일정 변경
• 채용 공고 상태 변경

📄 라이선스

MIT License

🤝 기여하기

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 지원

• 이슈 리포트: GitHub Issues
• 문의사항: [your.email@example.com]
• 나인하이어 문서: https://guide.ninehire.com

Happy Hiring with NineHire MCP! 🎉