HRMS Tool

概要

HRMS ツール は、Model Context Protocol サーバーであり、中核となるHRワークフロー（オンボーディング、オフボーディング、休暇管理、会議スケジュール、ITチケット、メール）を、AIエージェントが直接呼び出せるツールに変換します。

HRポータルをクリックして操作する代わりに、MCP接続されたアシスタントに次のように尋ねることができます：

"マーカス・ウェッブをエレナ・クロスの新しい直属として、月曜日からオンボーディングして。" "ナオミ・スティールのチームで休暇が少なくなっているのは誰？" "ディエゴ・ラモスの未処理チケットをすべてクローズして、今後の会議をキャンセルして — 彼は金曜日に退職する。"

アシスタントは手順を計画し、適切なツールを適切な順序で呼び出し、結果を報告します — 複数ステップのワークフローには以下のガイド付きプロンプトを、単発の操作には個別のツールを使用します。

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（推奨）

• メールツールを機能させたい場合は、アプリパスワードを持つ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 でアプリパスワードを生成します（セキュリティ → 2段階認証 → アプリパスワード）。通常のGmailパスワードでは機能しません。

▶️ サーバーの実行

uv run mcp-server/server.py

これにより、MCPサーバーがstdio上で起動し、デモ用の従業員、休暇記録、会議、チケットがシードされます。

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() が一貫性のあるデモデータセットを生成します：2つのチームにわたる8人の組織図、ランダム化された休暇残高/履歴、従業員ごとに2〜6件の今後の会議、混合ステータスの8〜15件のチケット。

• 従業員IDは E001、E002、… の形式に従います。チケットIDは T0001、T0002、… の形式に従います。

• 新しい従業員は、特に指定がない限り、デフォルトで20日の休暇残高になります。

再起動後もデータを保持する必要がある場合は、各マネージャークラスのインメモリのdict/リストを実際のデータストアに置き換える必要があります。

⚠️ 既知の制限事項

• ツール呼び出しに対する認証や認可はありません — アクセス制御は完全にMCPクライアントに委ねられています。

• 永続化層はありません（上記参照）。

• メール送信はGmailのみで、SMTP + アプリパスワードを使用します。

• 会議の競合検出は正確なタイムスタンプの一致のみをチェックし、重複する範囲はチェックしません。

📄 ライセンス

このプロジェクトは MITライセンス の下でライセンスされています。