HRMS Tool

개요

HRMS Tool은 Model Context Protocol 서버로, 핵심 HR 워크플로 — 온보딩, 오프보딩, 휴가 추적, 회의 일정, IT 티켓, 이메일 — 를 AI 에이전트가 직접 호출할 수 있는 도구로 변환합니다.

HR 포털을 클릭하는 대신 MCP에 연결된 어시스턴트에게 다음과 같이 요청할 수 있습니다:

"월요일부터 엘레나 크로스(Elena Cross) 휘하의 새 직속 보고자로 마커스 웹(Marcus Webb)을 온보딩해 줘." "나오미 스틸(Naomi Steele) 팀 중에 휴가가 얼마 안 남은 사람은 누구야?" "디에고 라모스(Diego Ramos)의 열린 티켓을 모두 종결하고 예정된 회의를 취소해 줘 — 그는 금요일에 떠나."

어시스턴트는 단계를 계획하고 올바른 도구를 올바른 순서로 호출한 다음 보고합니다 — 다단계 워크플로에는 아래의 안내 프롬프트를, 일회성 작업에는 개별 도구를 사용합니다.

Related MCP server: HRizzle-HR-Assist

✨ 기능

• 👤 직원 관리 — 직원 추가, 업데이트, 조회, 검색; 매니저/보고자 관계 해결

• 🌴 휴가 관리 — 잔여 일수 확인, 휴가 신청, 기록 조회

• 📅 회의 일정 — 충돌 감지로 회의 예약, 목록, 취소

• 🎫 티켓 시스템 — 장비/리소스 요청 접수, 상태 추적, 티켓 필터링 및 조회

• 📧 이메일 — Gmail SMTP를 통한 트랜잭션 이메일 전송(일반 텍스트, HTML, 첨부 파일)

• 🧭 안내 프롬프트 — 온보딩, 오프보딩, 팀 휴가 보고를 위한 사전 구축된 다중 도구 워크플로

• 🌱 시드 데모 데이터 — 현실적인 조직도, 휴가 기록, 회의, 티켓으로 시작해 즉시 사용해볼 수 있습니다

🏗️ 아키텍처

flowchart LR
    Client(["MCP Client<br/>(Claude Desktop, etc.)"])

    subgraph MCPServer["mcp-server/"]
        Server["server.py<br/>MCPServer('HRMS Tool')"]
    end

    subgraph HRMSPkg["hrms/"]
        EM["EmployeeManager"]
        LM["LeaveManager"]
        MM["MeetingManager"]
        TM["TicketManager"]
        MAIL["EmailManager"]
    end

    subgraph UtilsPkg["utils/"]
        Seed["seed_services()"]
    end

    Client <-->|stdio| Server

    Server --> EM
    Server --> LM
    Server --> MM
    Server --> TM
    Server --> MAIL
    Server -->|once, at startup| Seed

    EM -->|holds a reference to| LM
    Seed --> EM
    Seed --> LM
    Seed --> MM
    Seed --> TM

    MAIL -->|SMTP| Gmail[(Gmail)]

hrms/schemas.py는 위에 별도로 표시되지 않았습니다. 이는 모든 매니저와 모든 도구 시그니처가 의존하는 Pydantic 모델 레이어입니다.

모든 데이터는 프로세스 수명 동안 메모리에 저장됩니다 — 데이터베이스가 없습니다. 다시 시작할 때마다 새롭고 무작위화된 데이터셋이 다시 시드됩니다(아래 데이터 및 지속성 참조).

📁 프로젝트 구조

hrms-claude-tool/
├── hrms/
│   ├── email_manager.py      # Gmail SMTP sender
│   ├── employee_manager.py   # employee CRUD, org chart, name search
│   ├── leave_manager.py      # leave balances & history
│   ├── meeting_manager.py    # meeting scheduling & cancellation
│   ├── schemas.py            # Pydantic models (Employee, Leave, Meeting, Ticket, Email)
│   └── ticket_manager.py     # ticket lifecycle
├── mcp-server/
│   └── server.py             # MCP server entrypoint: tools + prompts
├── utils/
│   └── utils.py              # seed_services() — dummy data generator
├── .env                       # Gmail credentials (not committed)
├── .gitignore
├── .python-version
├── pyproject.toml
├── README.md
└── uv.lock

⚙️ 사전 요구 사항

• Python 3.14+

• uv — 의존성 관리용(권장)

• 이메일 도구를 작동시키려면 **앱 비밀번호(App Password)**가 있는 Gmail 계정이 필요합니다(2단계 인증을 먼저 활성화해야 함)

🚀 설치

# Clone the repo
git clone <your-repo-url>
cd hrms-claude-tool

# Install dependencies
uv sync

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]>=2.0.0" "pydantic>=2.13.4" "requests>=2.34.2" python-dotenv

참고: email_manager.py는 .env를 로드하기 위해 python-dotenv를 가져오지만 현재 pyproject.toml의 의존성에 나열되어 있지 않습니다. uv sync를 사용한다면 여기에도 추가하세요.

🔐 환경 변수

이메일 전송에는 Gmail SMTP 자격 증명이 필요합니다. 프로젝트 루트의 .env 파일을 다음으로 채우세요:

GMAIL_SENDER_EMAIL=your-address@gmail.com
GMAIL_APP_PASSWORD=your-16-character-app-password

앱 비밀번호는 **myaccount.google.com/apppasswords**에서 생성하세요(보안(Security) → 2단계 인증(2-Step Verification) → 앱 비밀번호(App passwords)). 일반 Gmail 비밀번호로는 작동하지 않습니다.

▶️ 서버 실행

uv run mcp-server/server.py

이렇게 하면 stdio를 통해 MCP 서버가 시작되고 데모 직원, 휴가 기록, 회의, 티켓이 시드됩니다.

Claude Desktop / Claude Code에서 연결

MCP 클라이언트 구성(예: claude_desktop_config.json)에 항목을 추가하세요:

{
  "mcpServers": {
    "hrms-tool": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/hrms-claude-tool", "run", "mcp-server/server.py"]
    }
  }
}

클라이언트를 다시 시작하면 아래의 도구와 프롬프트를 대화에서 사용할 수 있습니다.

🛠️ 사용 가능한 도구

직원 및 조직도

휴가

회의

티켓

이메일

🧭 사용 가능한 프롬프트

프롬프트는 여러 도구를 하나의 완전한 워크플로로 연결합니다 — 이름을 하나 건네주면 에이전트가 알아서 진행합니다.

💾 데이터 및 지속성

• 모든 데이터는 메모리에 보관됩니다 — 서버를 다시 시작하면 아무것도 유지되지 않습니다.

• 시작할 때마다 seed_services()가 일관된 데모 데이터셋을 생성합니다: 두 팀에 걸친 8명 조직도, 무작위 휴가 잔여 일수/기록, 직원당 예정된 회의 26개, 혼합 상태의 티켓 815개.

• 직원 ID는 E001, E002, … 형식을 따르고, 티켓 ID는 T0001, T0002, … 형식을 따릅니다.

• 다른 시드가 없는 한 새 직원의 기본 휴가 잔여 일수는 20일입니다.

재시작 후에도 데이터가 유지되어야 한다면 각 매니저 클래스의 인메모리 dict/list를 실제 데이터 저장소로 교체해야 합니다.

⚠️ 알려진 제한 사항

• 도구 호출에 대한 인증 또는 권한 부여가 없습니다 — 접근 제어는 전적으로 MCP 클라이언트에 맡겨집니다.

• 영속성 계층이 없습니다(위 참조).

• 이메일 전송은 SMTP + 앱 비밀번호를 통한 Gmail 전용입니다.

• 회의 충돌 감지는 겹치는 범위가 아닌 정확한 타임스탬프 일치만 확인합니다.

📄 라이선스

이 프로젝트는 MIT License에 따라 라이선스가 부여됩니다.