hrb lms MCP

HRB休假管理系统MCP服务器（HRB_lms_MCP）

版本： 1.0\ 状态： 生产\ 技术栈： Java Spring Boot、PostgreSQL、MCP协议（JSON-RPC 2.0）

______________________________________________________________________

目录

1. 业务背景
2. 建筑
3. 环境
4. 设置和运行
5. MCP协议实现
6. 所有权和运营
7. 第一任务清单
8. 跨项目依赖关系

______________________________________________________________________

业务背景

问题陈述

HRB员工助理(hrb_emp_assist)需要访问后端系统中的实时运营数据（休假余额、休假历史、待批准）。这些数据无法从政策文件（RAG）中检索，需要与休假管理系统直接集成。

目标用户

• 主要的，重要的: hrb_emp_assist 应用程序（MCP客户端）
• 次要的：API直接消费者（如果暴露）
• 管理员：管理MCP服务器的系统管理员

核心工作流

1. 休假余额查询

- 检索员工的当前假期余额 - 支持多种休假类型（PTO、病假、FMLA等） - 从数据库返回实时数据

1. 离开历史查询

- 检索历史休假申请 - 按日期范围、休假类型、状态筛选 - 支持对大型结果集进行分页

1. 请假申请提交

- 提交新的休假申请 - 验证休假资格 - 启动审批工作流

1. 审批管理

- 检查经理的待定审批 - 检索员工的审批状态 - 支持批准/拒绝操作

1. HITL（Human in the Loop）请求

- 为复杂场景创建升级请求 - 跟踪HITL请求状态 - 支持完成轮询

成功标准

• 可用性：>99.9%正常运行时间
• 响应时间：简单查询\ .

2. Build project

mvn clean install

3. Set up database

Create PostgreSQL database: leave_management_db

Run migration scripts from src/main/resources/db/migration/

4. Configure application

cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml

Edit application-local.yml with database connection and API key

5. Run application

mvn spring-boot:run

Or with specific profile

mvn spring-boot:run -Dspring-boot.run.profiles=local

### 配置文件

- **`application.yml`**：基本配置
- **`application-local.yml`**：地方发展优先
- **`application-dev.yml`**：开发环境
- **`application-staging.yml`**：暂存环境
- **`application-prod.yml`**：生产环境

### 测试

Run all tests

mvn test

Run unit tests only

mvn test -Dtest=*Test

Run integration tests

mvn verify -Dtest=*IT

Run with coverage

mvn test jacoco:report

### 掉毛

Format code (if using Spotless)

mvn spotless:apply

Check code style

mvn checkstyle:check

Static analysis

mvn pmd:check

### 在本地运行

Development mode (with auto-reload)

mvn spring-boot:run -Dspring-boot.run.profiles=local

Production mode

java -jar target/hrb-lms-mcp-1.0.0.jar --spring.profiles.active=local

With specific port

mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=8080

### 健康检查

Application health (Spring Boot Actuator)

curl http://localhost:8080/actuator/health

MCP Protocol endpoint

curl -X POST http://localhost:8080/api/hrb/lms/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

______________________________________________________________________

## MCP协议实现

### MCP协议概述

**协议**：基于HTTP/REST的JSON-RPC 2.0

**端点**: `POST /api/hrb/lms/mcp`

**认证**：API密钥通过 `X-API-Key` 头球

### 可用工具

1. **`get_leave_balance`**

   - **描述**：检索员工当前的休假余额
   - **参数**: `{"employee_id": "string"}`
   - **退货**：按类型（PTO、病假、FMLA等）列出的休假余额

1. **`get_leave_history`**

   - **描述**：检索员工的休假申请历史记录
   - **参数**: `{"employee_id": "string", "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD"}`
   - **退货**：带状态、日期、类型的休假申请列表

1. **`submit_leave_request`**

   - **描述**：提交新的休假申请
   - **参数**: `{"employee_id": "string", "leave_type": "string", "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD", "reason": "string"}`
   - **退货**：请求ID和状态

1. **`check_pending_approvals`**

   - **描述**：检查经理的待批准休假
   - **参数**: `{"employee_id": "string"}` （经理的员工id）
   - **退货**：待批准请求列表

1. **`create_hitl_request`**

   - **描述**：创建人在循环升级请求
   - **参数**: `{"request_type": "string", "query": "string", "employee_id": "string"}`
   - **退货**：HITL请求ID和状态

### 工具选择策略

- 工具通过MCP协议公开 `tools/list` 方法
- MCP客户端(`hrb_emp_assist`)在运行时发现可用工具
- 工具说明指导LLM选择工具
- 工具执行通过 `tools/call` 方法

### 错误处理

- **无效参数**：返回JSON-RPC错误，代码为-32602
- **未找到工具**：返回JSON-RPC错误，代码为-32601
- **数据库错误**：返回JSON-RPC错误，代码为-32000
- **超时**：默认30秒，可配置

### 速率限制

- **每客户端**：每个API密钥100个请求/分钟
- **每个工具**：每个客户每个工具每分钟50个请求
- **退避**：速率限制的指数回退（429响应）

______________________________________________________________________

## 所有权和运营

### 基础设施所有权

- **AWS基础架构**：DevOps/平台团队

  - ECS集群、RDS实例、ALB、VPC、安全组
  - 机密管理器，参数存储
  - CloudWatch日志和指标

- **应用程序代码**：开发团队

  - 功能开发、错误修复
  - MCP工具实现
  - 数据库架构更改

### 变更管理

- **代码更改**:

  - 功能分支→ PR → 代码审查→ 合并到 `main`
  - 自动化测试必须通过
  - 通过GitHub Actions部署到dev/ststage/prod

- **基础设施变更**:

  - 地形/CDK更改需要平台团队批准
  - 生产变更需要变更请求

- **数据库更改**:

  - 中的迁移脚本 `src/main/resources/db/migration/`
  - 生产前在开发/测试阶段测试迁移

### 支持和Runbook

**入口点**:

- **应用问题**：检查CloudWatch日志(`/ecs/hrb-lms-mcp`)
- **数据库问题**：检查RDS指标、连接池状态
- **MCP协议问题**：验证JSON-RPC合规性，检查请求/响应日志

**常用跑步指南**:

- **服务不健康**：检查健康端点、查看日志、验证数据库连接
- **高延迟**：检查数据库查询性能、连接池耗尽
- **MCP协议错误**：验证JSON-RPC格式，检查工具实现
- **数据库连接问题**：检查RDS端点、安全组、连接池设置

**随叫随到轮换**：开发团队（初级）、平台团队（升级）

______________________________________________________________________

## 第一任务清单

对于加入项目的新代理/开发人员：

### 1.营造当地环境

- \[\]克隆存储库： `git clone  C:\workspace\poc\2026\hrb_lms_mcp`
- \[\]安装Java 17+和Maven 3.9+
- \[\]设置本地PostgreSQL数据库
- \[\]运行 `mvn clean install` 建设项目
- \[\]复制 `application-local.yml.example` 到 `application-local.yml`
- \[\]在中配置数据库连接和API密钥 `application-local.yml`
- \[\]运行数据库迁移： `mvn flyway:migrate` （如果使用Flyway）

### 2.运行测试

- \[\]运行 `mvn test` -所有测试都应该通过
- \[\]检查测试输出是否存在任何故障
- \[\]运行 `mvn test -Dtest=*Test` -单元测试
- \[\]运行 `mvn verify -Dtest=*IT` -集成测试

### 3.进行烟雾测试

- \[\]启动应用程序： `mvn spring-boot:run -Dspring-boot.run.profiles=local`
- \[\]测试健康终点： `curl http://localhost:8080/actuator/health`
- \[\]测试MCP协议端点：

curl -X POST http://localhost:8080/api/hrb/lms/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

- \[\]测试工具执行：

curl -X POST http://localhost:8080/api/hrb/lms/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: your-api-key" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_leave_balance", "arguments": {"employee_id": "EMP001"} }, "id": 2 }'

- \[\]验证是否成功返回响应

### 4.审查日志和健康检查

- \[\]检查应用程序日志（控制台输出或日志文件）
- \[\]验证启动日志中没有错误
- \[\]测试健康终点：
  - \[ \] `/actuator/health` -应用程序健康状况
  - \[ \] `/actuator/health/db` -数据库连接（如果已配置）
- \[\]查看日志结构和相关ID

### 5.探索代码库

- \[\]审查 `src/main/java/.../mcp/` -MCP协议处理程序
- \[\]审查 `src/main/java/.../tools/` -工具实现
- \[\]审查 `src/main/java/.../repository/` -数据访问层
- \[\]审查 `src/main/resources/db/migration/` -数据库迁移
- \[\]审查 `src/test/` -测试结构和示例

______________________________________________________________________

## 跨项目依赖关系

### 共享组件

1. **MCP协议**：这两个项目都使用MCP（模型上下文协议）进行服务通信

   - **位置**:
     - `hrb_lms_mcp` （C:\\workspace\\poc\\2026\\hrb_lms_mcp）：实现mcp服务器（Java Spring Boot）- **这个项目**
     - `hrb_emp_assist` （C:\\workspace\\poc\\2026\\hrb_amp_assist）：实现MCP客户端（Python）
   - **接口**：基于HTTP/REST的JSON-RPC 2.0
   - **协议端点**: `/api/hrb/lms/mcp` （由该服务器公开）
   - **沟通**: `hrb_emp_assist` → HTTP POST→ `hrb_lms_mcp` （此服务器）
   - **规格**：遵循MCP协议规范

1. **公用库** （如有）：

   - 共享实用程序、日志记录、配置模式
   - 位置：待定（可能位于单独的共享库中 `C:\workspace\poc\2026\hrb_shared`)

1. **基础设施模块**:

   - 用于共享AWS资源的共享Terraform/CDK模块
   - 位置：TBD（基础设施存储库。， `C:\workspace\poc\2026\hrb_infrastructure`)
   - 共享资源：VPC、安全组、IAM角色、KMS密钥

1. **共享AWS资源**:

   - **垂直路径计算机**: `hrb-services-vpc` （与分享 `hrb_emp_assist`)
   - **ECS集群**: `hrb-services-cluster` （共享）
   - **KMS密钥**：数据库加密、机密加密（共享）
   - **CloudWatch日志组**：每个项目单独，但保留政策相同

### 版本控制和发布约定

**语义版本控制**: `MAJOR.MINOR.PATCH`

- **重大**：中断对MCP协议或API的更改
- **次要的**：新工具，向后兼容的更改
- **补丁**：Bug修复，向后兼容

**分支策略**:

- **`main`**：生产就绪代码
- **`develop`**：功能集成分支
- **`feature/*`**：功能开发分支
- **`hotfix/*`**：生产修补程序

**标签策略**:

- **发布标签**: `v1.0.0`, `v1.1.0`等等。
- **预发布标签**: `v1.1.0-rc1`, `v1.1.0-beta1`

**发布过程**:

1. 功能开发 `feature/*` 分支
1. 合并到 `develop` 代码审查后
1. 从以下位置创建发布分支 `develop`
1. 标签发布： `v1.1.0`
1. 合并到 `main` 并部署到生产中

**MCP协议版本控制**:

- MCP协议版本：1.0（当前）
- 工具版本控制：工具独立进行版本控制
- 重大变化：需要重大版本升级

**跨项目协调**:

- **MCP协议变更**：需要与 `hrb_emp_assist` （MCP客户端）
- **重大变更**：MCP协议更改需要在两个项目中进行重大版本升级
- **展开命令**：部署 `hrb_lms_mcp` 首先（阶段0），然后 `hrb_emp_assist` （第1-8阶段）
- **API兼容性**：保持至少2个次要版本的向后兼容性

______________________________________________________________________

## 其他资源

- **MCP协议规范**: `docs/MCP-PROTOCOL.md`
- **API 文档**: `docs/api/`
- **部署指导**: `resources/aws_platforming/readme-aws-platforming.md`
- **数据库模式**: `docs/database-schema.md`
- **工具文档**: `docs/tools/`

______________________________________________________________________

**最后更新**: 2026-01-18\
**维护者**：开发团队\
**问题**：联系团队负责人或在存储库中创建问题