mcp-human-resources

mcp-human-resources

人事部門のデータを公開することに特化した Spring Boot MCP サーバーの実装です

これは学習用ツールとして作成されました。本番アプリケーションのテンプレートとして使用しないでください。LLM にデータベースの行の作成、更新、削除を許可するのは、おそらく良い考えではありません。

インストール

Java、Maven、node、npm がインストールされた Linux 環境を想定しています

1. リポジトリをクローンします：

git clone https://github.com/dbrown725/mcp-human-resources.git
cd mcp-human-resources

リポジトリのデータレイアウト

• 実行時クラスパスのアセットは src/main/resources に置きます。
• セットアップ／読み込みワークフローで使用する運用データファイルは ops/data 以下に置きます。
• 現在の配置場所：
  • DB シード CSV：ops/data/db/employee_data_load.csv
• 起動時の注意：data.sql は相対パスを使って DB シード CSV を読み込むため、リポジトリのルートからアプリを起動してください。

2. Brave Search をセットアップします：API キーを取得し、設定ファイルを更新して、Node モジュールをインストールします。
   https://github.com/modelcontextprotocol/servers-archived/tree/main/src/brave-search
   上記の手順に従って API キーを取得してください。
   

export BRAVE_API_KEY=<YOUR_BRAVE_API_KEY>

注記： 便利なスクリプト（start-run.sh または start-debug.sh）を使用する場合、この export コマンドを手動で実行する必要はありません。スクリプトファイルを編集して、そこで API キーを設定してください。

3. Google Cloud Storage をセットアップします： ガイドとして使用：https://github.com/sohamkamani/java-gcp-examples/blob/main/src/main/java/com/sohamkamani/storage/App.java // https://www.youtube.com/watch?v=FXiV4WPQveY

   export GEMINI_PROJECT_ID=<YOUR_GEMINI_PROJECT_ID>
   export STORAGE_BUCKET_NAME=<YOUR_STORAGE_BUCKET_NAME>
   

   ops/data/gcs のポリシー PDF ファイルをアップロードし、GCS オブジェクトパスには policies/<FILENAME>.pdf 形式を使用してください（例：policies/policies_Business Dress Code Policy.pdf）。

   署名付き URL： GCS ファイルの有効期限付き署名付き URL の生成（ブラウザー内での PDF 表示など）を有効にするには、GCP サービスアカウントを作成し、IAM 権限を設定して、環境変数 SIGNING_SERVICE_ACCOUNT を設定する必要があります。

   export SIGNING_SERVICE_ACCOUNT=<YOUR_SERVICE_ACCOUNT>@<YOUR_PROJECT_ID>.iam.gserviceaccount.com
   

   詳細なセットアップ手順については、SIGNED_URLS.md を参照してください。

注記： start-run.sh または start-debug.sh を使用する場合、手動で export するのではなく、これらの値（SIGNING_SERVICE_ACCOUNT を含む）をスクリプトファイルに設定してください。

4. Nano Banana の画像生成に必要です bash export GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>

注記： これらのスクリプトを使用する場合は、start-run.sh または start-debug.sh に設定してください。

5. Elastic Search をセットアップします：
Elastic Search MCP：https://github.com/elastic/mcp-server-elasticsearch

Elastic Search と Kibana をインストールします：https://www.elastic.co/docs/deploy-manage/deploy/self-managed/install-kibana
Kibana を使用して CSV ファイルを Elastic Search に読み込む手順。
https://www.elastic.co/blog/importing-csv-and-log-data-into-elasticsearch-with-file-data-visualizer

設定：src/main/resources/mcp-servers.json
ローカルの Elastic Index ではセキュリティが有効になっていないため、"ES_API_KEY": " " にスペースが必要でした。

後で Policy Vector RAG を取り込む際は、http://localhost:5601/app/dev_tools にアクセスして、次を実行します：
- `PUT /hr-policy-rag-index`
- マッピングの上書き（必要な場合のみ）：次元数 768 の dense_vector フィールドを設定します

npm i @elastic/mcp-server-elasticsearch

6. お好みの LLM をセットアップします。GROQ、OPENROUTER、Google Vertex AI でテスト済みです。画像検出は Google のみ、具体的には Gemini Flash 2.5 で動作します。
   Spring AI がサポートするモデル：https://docs.spring.io/spring-ai/reference/api/index.html
   現在のコードでは、Google Vertex AI をプライマリモデル／chatClient として、OpenAI 互換モデル 2 つをセカンダリモデルおよび評価用モデル／chatClient として設定しています。
   API KEY を取得します：https://console.groq.com/keys
   OPENROUTER KEY を取得します：https://openrouter.ai/settings/keys

export GROQ_API_KEY=<YOUR_GROQ_API_KEY>
export OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>

注記： 自動設定するには、これらの値を start-run.sh または start-debug.sh に設定してください。

7. Google Vertex AI に関する注意事項
   https://docs.spring.io/spring-ai/reference/api/chat/vertexai-gemini-chat.html
   ターミナルで実行し、spring-boot アプリも起動する次のコマンドを含みます。
   gcloud config set project <YOUR_PROJECT_ID> && gcloud auth application-default login <YOUR_ACCOUNT>
   
   ADC を設定する必要があります。（ブラウザーを使用できるマシンで実行する必要があります） ローカルでの ADC 設定に役立ちました。
   https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment https://www.youtube.com/watch?v=mEsC0BpEYGM
   gcloud auth application-default login
   ブラウザーでプロンプトが表示されたら、自分の Google ユーザーを選択し、すべてのアクセスオプションを選択しました。
   その後、ターミナルに次のように表示されました：Credentials saved to file: [/home/davidbrown/.config/gcloud/application_default_credentials.json]
   最初のテストではエラーが発生し、解決方法を示す URL リンクが表示されました。リンクを開いて Vertex AI API を有効にする必要がありました。
   
   

8. GMAIL アクセスの設定
   メール設定です。現在は下書きの保存機能のみがあります。
   パスワードは通常の Gmail パスワードではありません。APP パスワードを設定する必要があります：https://support.google.com/mail/answer/185833?hl=en

   export GMAIL_EMAIL_ADDRESS=<GMAIL_ADDRESSS>
   export GMAIL_EMAIL__APP_PASSWORD=<GMAIL_APP_PASSWORD>
   

注記： これらの値を start-run.sh または start-debug.sh に設定してください。これらのスクリプトですべての環境変数を設定できます。

9. ログディレクトリとファイルの設定

sudo mkdir /var/log/mcp-human-resources
sudo touch /var/log/mcp-human-resources/mcp-human-resources.log
sudo touch /var/log/mcp-human-resources/mcp-human-resources-call-advisor.log
sudo chmod -R 777 /var/log/mcp-human-resources

10. Docker での Prometheus と Grafana のセットアップと設定 メトリクスとトレースの設定です。https://github.com/danvega/spring-ai-metrics および https://youtu.be/FzLABAppJfM?t=17141 に基づいています
    
    Prometheus：http://localhost:9090
    Grafana：http://localhost:3000
    
    このアプリは 8081 で実行されるため、.../mcp-human-resources/docker/prometheus.yml のポートを 8080 から 8081 に変更する必要がありました。
    
    また、次の操作も必要でした。
    - http://localhost:3000/connections/datasources にアクセスする - Prometheus データソースをクリックする - 名前を「Prometheus」から「prometheus」に変更する - 「Save & Test」をクリックして、Grafana が Prometheus に接続できることを確認する
    
    セキュリティを強化するため、compose.yml の Grafana の管理者パスワードも「admin」から「mysecretpassword」に変更しました。
    admin/mysecretpassword が機能しない場合は、admin/admin に戻してください

11. ポリシー RAG Elasticsearch ベクターデータの読み込み。

    • GCS バケットの policies/ 配下にポリシー PDF があることを確認します。
    • POST /rag/policies/ingest-gcs?prefix=policies/ を呼び出して（src/test/http/rag.http を参照）、GCS の PDF を hr-policy-rag-index ベクターインデックスに取り込みます。
    • GET /rag/policies/query?question=... でクエリを実行し、根拠となるポリシーのコンテキストと、一致したポリシー添付ファイルのパスを取得します。

12. Maven Install を実行する
    

"./mvnw install"

13. サーバーを起動する
    

オプション A：便利なスクリプトを使用する（VS Code での開発に推奨）

このリポジトリには、必要な環境変数をすべて自動設定してサーバーを起動する便利なスクリプトが 2 つ含まれています。

ステップ 1：スクリプトを実行可能にする

プロジェクトのルートディレクトリに移動し、次を実行します：

cd /home/<YOUR_HOME_DIRECTORY>/Documents/projects/mcp-human-resources
chmod +x start-run.sh
chmod +x start-debug.sh

ステップ 2：適切なスクリプトを実行する

通常の開発の場合：

./start-run.sh

VS Code のブレークポイントを使用してデバッグする場合：

./start-debug.sh

スクリプトは、上記の環境変数（BRAVE_API_KEY、GEMINI_PROJECT_ID、STORAGE_BUCKET_NAME、GEMINI_API_KEY、GROQ_API_KEY、OPENROUTER_API_KEY、GMAIL_EMAIL_ADDRESS、GMAIL_EMAIL_APP_PASSWORD）をすべて自動的にエクスポートします。

重要： 実行する前に、start-run.sh と start-debug.sh を編集し、実際の API キーと認証情報を設定する必要があります。各ファイルを開き、プレースホルダーの値を実際のキーに置き換えてください。

ステップ 3：（デバッグモードのみ）VS Code デバッガーをアタッチする

./start-debug.sh を使用すると、サーバーはポート 5005 でリモートデバッグを有効にして起動します。VS Code でブレークポイントデバッグを有効にするには、次の手順に従います。

1. .vscode/launch.json にアタッチ構成が含まれていることを確認します。

{
    "type": "java",
    "name": "Attach to Debug Server (Port 5005)",
    "request": "attach",
    "hostName": "localhost",
    "port": 5005,
    "projectName": "humanresources"
}

2. VS Code で 実行とデバッグ パネルを開きます（Ctrl+Shift+D または Cmd+Shift+D）。

3. 上部のドロップダウンから 「Attach to Debug Server (Port 5005)」 を選択します。

4. 緑色の再生ボタンをクリックするか、F5 を押してデバッガーをアタッチします。

5. Java ファイルにブレークポイントを設定します。これでブレークポイントが機能します。

重要： ./start-debug.sh でサーバーを起動するたびに、「Attach to Debug Server」の手順を実行する必要があります。デバッガーをアタッチしない場合、VS Code は実行中の Java プロセスに接続されていないため、ブレークポイントを無視します。

違いについて：

• VS Code の 「launch」構成 は、新しい Java プロセスを起動します。
• 「attach」構成 は、すでに実行中の Java プロセスに接続します。
• スクリプトは Maven を使って外部からサーバーを起動するため、VS Code のデバッガーを実行中のプロセスに接続するには、「attach」モードを使用する必要があります。

オプション B：環境変数を永続的に設定する

スクリプトを使用しない場合は、シェルの設定ファイルで環境変数を永続的に設定できます。

bash ユーザーの場合（ほとんどの Linux システム）、エクスポート文を ~/.bashrc に追加します。

nano ~/.bashrc
# Add all the export statements from start-run.sh or start-debug.sh
# Save and exit (Ctrl+X, then Y, then Enter)
source ~/.bashrc

zsh ユーザーの場合（macOS のデフォルト）、エクスポート文を ~/.zshrc に追加します。

nano ~/.zshrc
# Add all the export statements from start-run.sh or start-debug.sh
# Save and exit (Ctrl+X, then Y, then Enter)
source ~/.zshrc

環境変数を永続的に設定したら、Maven でサーバーを直接起動できます。

./mvnw spring-boot:run

または、デバッグモードで起動します。

./mvnw spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"

オプション C：元の run.sh スクリプトを使用する

JDK のインストール先と環境変数を run.sh に設定してから、次のコマンドを実行します。

./run.sh

その他のドキュメント

• VS Code のセットアップとヒント - 必須の拡張機能、デバッグのヒント、ターミナルの操作
• トラブルシューティング - 環境変数、権限、ポートに関する一般的な問題の解決策

14. テスト

    単体テストを実行する
    
    プロジェクトのルートディレクトリに移動し、「./mvnw test」を実行します
    
    

    HTTP API テストを実行する
    
    推奨：src/test/http/ ディレクトリにある .http ファイルを使用します
    - VS Code 用の REST Client 拡張機能 をインストールします
    - または、IntelliJ IDEA の組み込み HTTP クライアントを使用します
    - 任意の .http ファイルを開き、各エンドポイントの上にある「Send Request」をクリックします
    - 詳しい手順については src/test/http/README.md を参照してください
    
    

    Inbox リスナーのメールテストケース（ポリシーおよび従業員のフロー）
    
    - 監視対象の受信トレイに実際のメールを送信するための件名と本文のサンプルは、ops/data/email-samples/ にあります
    - 利用可能な形式：
    - ops/data/email-samples/inbox_test_emails.md
    - ops/data/email-samples/inbox_test_emails.csv
    - ops/data/email-samples/inbox_test_emails.json
    
    

    **代替方法**：ブラウザー、curl、または Postman を使用します<br>
    - 例：http://localhost:8081/employees/5012<br>
    - 例：http://localhost:8081/ai?prompt=How%20many%20employees%20in%20IT%20are%20asian?<br><br>
    

    対応するクライアントアプリを使ってテストできます：
    https://github.com/dbrown725/mcp-human-resources-client

15. データベースとして H2 を使用しており、アプリケーションの起動時に読み込まれます。
    http://localhost:8081/h2-console
    パスワードは application.properties にあります。
    クエリの例：Select * from EMPLOYEE where AGE > 50;

16. 現在のログレベルを確認するには：
    http://localhost:8081/log

既知の無害な起動時警告

トラブルシューティングのドキュメントにある同じチェックリストについては、起動時の警告に関するガイダンスを参照してください。