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-285397596138AWS_REGION=us-east-1HR_KB_ID=OLRJAOAVCZ
注： 可能有.env为了方便起见，将文件保存在仓库中，但当前的实现不会在运行时自动加载它。如果你想重新启用.env加载后，您可以安全地重新引入dotenv在src/index.ts只要它不向stdout打印任何内容（这将与MCP的JSON over stdio协议冲突）。
安装、构建和运行
1.安装依赖项
从repo根目录：
npm install2.构建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调试和探索该工具。
让检查器启动服务器
- 构建项目：
npm run build- 发射检查器：
npx @modelcontextprotocol/inspector- 在检查器UI中，配置新连接：
- 运输类型： 工作室 - 命令： node - 论据： build/index.js - 工作目录： 您计算机上此仓库的路径\ （例如。， C:\Users\\Desktop\Career\ESI\EAAP - 31\esi-hr-mcp) - 环境变量： - AWS_PROFILE = AdministratorAccess-285397596138 - AWS_REGION = us-east-1 - HR_KB_ID = OLRJAOAVCZ
- 点击“连接”
检查员应显示：
- 成功连接
- 可用工具，包括
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响应，其中包含以下字段：
queryhitCountresults[]（每个排名块一个）
每个结果包括：
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接线