mcp-human-resources

mcp-human-resources

专注于公开人力资源部门数据的 Spring Boot MCP 服务实现

本项目用于学习。请勿将其用作生产应用的模板。让大模型创建、更新和删除数据库行可能不是个好主意。

安装

假设已在 Linux 上安装 Java、Maven、node 和 npm

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 Key，更新配置文件并安装 Node 模块：
   https://github.com/modelcontextprotocol/servers-archived/tree/main/src/brave-search
   按照上述说明获取 API Key
   

export BRAVE_API_KEY=<YOUR_BRAVE_API_KEY>

**注意：**如果使用便捷脚本（start-run.sh 或 start-debug.sh），则无需手动运行此 export 命令。只需编辑脚本文件并在其中设置 API key。

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>
   

   将政策 PDF 文件上传至 ops/data/gcs，并使用 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，请在脚本文件中设置这些值（包括 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. 设置你偏好的大模型，已使用 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 的模型设置为辅助模型和评审模型/chatClients
   获取 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]
   首次测试出错，并显示了用于解决问题的网址链接。我需要打开该链接并启用 Vertex AI API
   
   

8. 设置 GMAIL 访问权限
   电子邮件配置，目前仅支持保存草稿功能。
   密码不是你常用的 Gmail 密码，而必须是应用专用密码：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
    
    我需要更新 .../mcp-human-resources/docker/prometheus.yml，将端口改为 8081，而不是 8080，因为此应用运行在 8081 端口。
    
    我还需要
    - 访问 http://localhost:3000/connections/datasources
    - 点击 Prometheus 数据源
    - 将名称从 'Prometheus' 改为 'prometheus'
    - 点击 'Save & Test'，确保 Grafana 可以连接到 Prometheus
    
    为了提高安全性，我还将 compose.yml 中 Grafana 的管理员密码从 'admin' 改为 'mysecretpassword'。
    如果 admin/mysecretpassword 不起作用，请改回 admin/admin

11. Policy 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 开发）

仓库中包含两个便捷脚本，可自动设置所有必需的环境变量并启动服务端：

步骤 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 从外部启动服务器，因此需要使用“attach”模式，将 VS Code 调试器连接到正在运行的进程

选项 B：永久设置环境变量

如果不想使用这些脚本，可以在 shell 配置中永久设置环境变量：

bash 用户（大多数 Linux 系统），将 export 语句添加到 ~/.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 默认 shell），将其添加到 ~/.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 脚本

将 run.sh 更新为你的 JDK 安装位置和环境变量，然后运行：

./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 获取详细说明
    
    

    收件箱监听器电子邮件测试用例（策略 + 员工流程）
    
    - 用于向受监控收件箱发送真实电子邮件的主题/正文示例内容位于 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

已知的无害启动警告

关于相同的检查清单，请参阅启动警告排查指南。