AI导哈

HR知识库检索服务

一个连接HR知识库（基于AWS Bedrock和Aurora pgvector）与MCP兼容客户端的服务，提供HR政策检索功能。

  • by Dimotai
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Dimotai/esi-eaap-31-lightweight-mcp

使用说明

ESI HR知识库MCP服务器

此存储库包含MCP服务器，该服务器将ESI的人力资源知识库（由Aurora pgvector支持的AWS基岩知识库）连接到MCP兼容客户端（例如ChatGPT/MCP Inspector/内部代理）。

服务器公开单个工具， retrieve_hr_policy，它允许人力资源代理和内部工具查询人力资源知识库，并接收排名块和元数据（S3路径、页码、分数等）。

高级体系结构

数据管道

人力资源文件（手册、PTO/休假、福利、Unanet指南、州通知等）存储在S3中的以下位置：

s3://esi-hr-docs/...

AWS基岩知识库将此桶编入索引：

  • 姓名： esi-hr-kb-dev
  • 知识库ID: OLRJAOAVCZ
  • 地区： us-east-1
  • 嵌入模型： Titan文本嵌入v2（或类似版本）
  • 矢量存储： 亚马逊极光PostgreSQL（pgvector）

已计划的Lambda+EventBridge作业(hr-kb-scheduled-sync)跑步 StartIngestionJob 为了 OLRJAOAVCZ 及其S3数据源(XY5AQACOZ8)以保持KB与S3同步。

MCP集成

  • 此仓库托管Node.js/TypeScript MCP服务器
  • 服务器使用Bedrock Agent Runtime客户端调用 Retrieve 对照人力资源知识库
  • MCP兼容客户端调用 retrieve_hr_policy 工具和接收：
    • 检索到的内容块
    • S3源位置
    • 相关性得分
    • 杂项。基岩知识库元数据

项目结构

esi-hr-mcp/
├─ src/
│  └─ index.ts          # MCP server + retrieve_hr_policy implementation
├─ build/               # Compiled JS output from npm run build
├─ .env                 # Optional local env vars (NOT committed)
├─ package.json
├─ tsconfig.json
└─ README.md            # This file

先决条件

  • Node.js 18+ 和npm
  • AWS-CLI 配置有可以访问的配置文件：
    • 基岩知识库 OLRJAOAVCZ
    • 基岩代理运行时 us-east-1
  • 无论此MCP服务器在何处运行，都可以通过网络访问AWS Bedrock端点

MCP服务器使用标准的AWS SDK凭据解析（环境变量、配置/凭据文件、SSO配置文件等）。它不公开HTTP服务器；它通过stdio与MCP通信。

环境变量

服务器在运行时需要这些环境变量：

  • AWS_REGION –KB所在的AWS区域（例如。， us-east-1)
  • AWS_PROFILE –（可选）用于凭据的AWS CLI配置文件
  • HR_KB_ID –基岩知识库ID（例如。， OLRJAOAVCZ)

选项1：通过外壳/过程环境（建议本地开发）

PowerShell示例：

$env:AWS_PROFILE = "AdministratorAccess-285397596138"
$env:AWS_REGION  = "us-east-1"
$env:HR_KB_ID    = "OLRJAOAVCZ"

npm start

选项2：通过MCP检查器配置

在Inspector的连接配置（环境变量部分）中，设置：

  • AWS_PROFILE = AdministratorAccess-285397596138
  • AWS_REGION = us-east-1
  • HR_KB_ID = OLRJAOAVCZ

注： 可能有 .env 为了方便起见，将文件保存在仓库中，但当前的实现不会在运行时自动加载它。如果你想重新启用 .env 加载后，您可以安全地重新引入 dotenv 在 src/index.ts 只要它不向stdout打印任何内容（这将与MCP的JSON over stdio协议冲突）。

安装、构建和运行

1.安装依赖项

从repo根目录：

npm install

2.构建TypeScript

npm run build

这编译 src/index.ts 到 build/index.js.

3.运行MCP服务器（独立）

设置环境变量（如上所述），然后：

npm start

您应该看到类似于以下内容的日志行：

esi-hr-kb-server MCP up on stdio
Starting esi-hr-kb-server with KB ID=OLRJAOAVCZ, region=us-east-1, profile=AdministratorAccess-285397596138

此时，进程正在通过stdio等待MCP客户端。它不绑定到HTTP端口（没有 http://localhost:3000).

与MCP检查器一起使用

您可以使用MCP Inspector调试和探索该工具。

让检查器启动服务器

  1. 构建项目：

    npm run build

  2. 发射检查器：

    npx @modelcontextprotocol/inspector

  3. 在检查器UI中，配置新连接：

    • 运输类型： 工作室
    • 命令： node
    • 论据： build/index.js
    • 工作目录： 您计算机上此仓库的路径
      （例如。， C:\Users\<you>\Desktop\Career\ESI\EAAP - 31\esi-hr-mcp)
    • 环境变量：
      • AWS_PROFILE = AdministratorAccess-285397596138
      • AWS_REGION = us-east-1
      • HR_KB_ID = OLRJAOAVCZ

  4. 点击“连接”

检查员应显示：

  • 成功连接
  • 可用工具，包括 retrieve_hr_policy

测试工具

在“工具”选项卡中，选择 retrieve_hr_policy 并运行测试查询：

查询示例：

How do I submit a leave request in Unanet?

JSON输入示例：

{
  "query": "How do I submit a leave request in Unanet?",
  "topK": 5,
  "scoreThreshold": 0.3
}

您应该看到一个JSON响应，其中包含以下字段：

  • query
  • hitCount
  • results[] （每个排名块一个）

每个结果包括：

  • rank –基于1的排名
  • score –基岩相似性评分
  • text –人力资源内容片段
  • location.s3Location.uri –源文档的S3路径
  • metadata –包括页码、数据源ID等。

然后，客户端（ChatGPT、内部应用程序）可以生成友好的答案，并使用此信息显示链接或引用。

工具： retrieve_hr_policy

目的

查询ESI人力资源基岩知识库，了解人力资源政策、程序和工作流程（Unanet、PTO、福利等），并返回包含元数据和分数的原始检索块。下游客户可以使用这些来生成人性化的答案和引用。

输入

MCP模式在中定义 src/index.ts，但从逻辑上讲，该工具预期：

  • query （字符串，必填）
    自然语言问题（例如，“我如何在Unanet中提交休假申请？”）

  • topK （数字，可选）
    要返回的最大块数。如果没有提供，默认值通常为5。

  • scoreThreshold （数字，可选）
    最小相似性得分。得分低于此值的块可能会被过滤掉或标记为低置信度。

输出形状

该工具的典型响应如下：

  • query –回应用户查询
  • hitCount –检索到的块数
  • results[] –排名结果列表；每个都包含：
    • rank –排名顺序（1为最高）
    • score –基岩的相关性得分
    • text –从HR文档中提取文本块
    • location -文本来自哪里（S3 URI等）
    • metadata –其他密钥，例如：
      • x-amz-bedrock-kb-source-uri
      • x-amz-bedrock-kb-document-page-number
      • x-amz-bedrock-kb-data-source-id

客户可以使用 location 和 metadata 提供“查看源代码”链接和文档引用。

维护知识库（Infra Notes）

这些组件不在此仓库中，但对开发人员来说是重要的上下文。

S3和人力资源文件

  • 水桶： esi-hr-docs
  • 文件夹结构（示例）：
    • handbook/
    • benefits/
    • leave-and-pto/
    • systems-guides/
    • state-notices/
    • timekeeping/
    • travel-and-expense/

新的或更新的文档应上传到以下位置的正确子文件夹中 esi-hr-docs.

基岩知识库

  • 姓名： esi-hr-kb-dev
  • 身份证件： OLRJAOAVCZ
  • 地区： us-east-1
  • 数据来源： S3（ID XY5AQACOZ8)指向 s3://esi-hr-docs/
  • 嵌入模型： Titan文本嵌入v2（或同等版本）
  • 矢量存储： 带pgvector的Aurora PostgreSQL

同步和刷新选项

知识库需要摄取/同步作业来合并新的或更改的文档。

手动同步

使用AWS控制台：Bedrock→ 知识库→ esi-hr-kb-dev → 数据源→ “同步”

自动同步（已实现）

  • Lambda函数： hr-kb-scheduled-sync
  • 环境变量：
    • HR_KB_ID = OLRJAOAVCZ
    • HR_KB_DATASOURCE_ID = XY5AQACOZ8
    • AWS_REGION = us-east-1
  • 行为：
    • 呼叫 StartIngestionJob 用于HR知识库和数据源
    • 记录摄取作业ID、状态和基本统计信息
  • EventBridge时间表：
    • 规则定位 hr-kb-scheduled-sync 拉姆达
    • 时间表表达式，例如 rate(1 day) （可根据需要进行调整）

中的新文档或更新文档 s3://esi-hr-docs/... 将在下一个成功的摄取作业完成后被拾取并索引。

开发说明和未来工作

TypeScript和构建

  • tsconfig.json 配置有：
    • target: "ES2020"
    • module: "Node16"
    • moduleResolution: "Node16"
    • strict: true
  • npm run build 将TypeScript编译为 build/index.js

日志记录

MCP服务器日志：

  • 启动信息（KB ID、地区、AWS配置文件）
  • 基岩代理运行时调用错误

Lambda(hr-kb-scheduled-sync)日志：

  • 摄入作业开始事件
  • 摄入作业ID和初始状态

未来可能的增强功能

  • 添加第二个工具。， answer_hr_question，即：
    • 用途 RetrieveAndGenerate 而不是 Retrieve
    • 返回一个组合的自然语言答案和引用，而不仅仅是原始块
  • 在内部添加简单的重新排名/过滤规则 retrieve_hr_policy例如：
    • 更喜欢 leave-and-pto/ 或 systems-guides/ Unanet或休假相关查询的S3前缀
  • 将自动化测试（Jest/Vitest）添加到：
    • 验证MCP工具模式
    • 模拟基岩试剂运行时间，确保有效载荷和结果形状正确
  • 添加“健康检查”/ping工具，使操作监控更容易

所有权/联系方式

  • 主要所有者： EAAP/AI平台团队
  • 主要消费者： 需要通过AWS Bedrock和MCP结构化访问ESI HR内容的人力资源支持代理和内部工具

如果以下任何更改，则应更新此README和相关运行手册：

  • 知识库名称/ID或地区
  • S3桶或文件夹结构
  • MCP工具名称或请求/响应模式
  • 同步策略（手动与计划）或Lambda/EventBridge接线

相关 MCP