内容
# 人力资源系统 MCP 服务器
一个最小的[模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，作为一个工作示例，展示了如何构建 MCP 服务器。它通过一组小型工具公开本地 SQLite 合同/计费数据库（`PROJECT`、`CA_DETAIL`、`CA_BILL_PLAN`），范围从通用模式自省到特定领域的语义查询。
## 功能特点
- **模式自省工具** — 无需事先了解模式即可发现表和列
- **语义工具** — 为合同/计费领域（项目、合同行、计费计划）定制的查询
- **直接 SQL 工具** — 在了解模式后用于任意查询的逃生出口
- **直接数据库访问** — 通过 Python 标准库 `sqlite3`，在 `asyncio.to_thread` 中封装以实现异步兼容性
## 快速开始
### 前提条件
- Python 3.11+
- [uv](https://github.com/astral-sh/uv) 包管理器（推荐）
### 安装
```bash
# 克隆仓库
git clone <repo-url>
cd peoplesoft-mcp
# 安装依赖
uv sync
# 创建 finstg.db 并加载静态数据
uv run create_db.py
```
### 配置
1. 复制示例环境文件：
```bash
cp .env.example .env
```
2. 编辑 `.env` 以指向不同的 SQLite 文件（默认为仓库根目录下的 `finstg.db`）：
```bash
SQLITE_DB_PATH=finstg.db
```
3. 将 `.cursor/mcp.json.example` 复制到 `.cursor/mcp.json` 并更新到您的安装路径。
### 运行服务器
```bash
uv run peoplesoft_server.py
```
### Cursor IDE 集成
MCP 配置（`.cursor/mcp.json`，从 `.cursor/mcp.json.example` 复制）应如下所示：
```json
{
"mcpServers": {
"peoplesoft": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_ps/",
"run",
"peoplesoft_server.py"
]
}
}
}
```
## 可用工具
### 模式自省（2 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_tables` | 列出本地数据库中的表，可选按名称过滤 |
| `describe_table` | 获取表结构（列、类型、主键） |
### 合同与计费模块（4 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_projects` | 列出项目，可按业务单元/状态/类型过滤 |
| `get_project_contracts` | 获取项目及其合同行和计费计划 |
| `list_contracts` | 列出合同明细行及其计费计划信息 |
| `get_bill_plan` | 获取特定合同行的计费计划详情 |
### 计费分析（2 个工具）
| 工具 | 描述 |
|------|-------------|
| `check_project_billing_setup` | 检查每个项目的合同行、计费计划、计费计划类型和生效状态，以发现计费设置问题 |
| `cost_reimbursable_billable_transactions` | 汇总未分配的成本补偿可计费交易（总和、计数、日期范围）按项目 |
### 直接查询（1 个工具）
| 工具 | 描述 |
|------|-------------|
| `query_peoplesoft_db` | 对本地数据库执行自定义 SQL 查询 |
## 项目结构
```
peoplesoft-mcp/
├── peoplesoft_server.py # MCP 服务器主入口
├── db.py # SQLite 连接管理
├── create_db.py # 创建 finstg.db 并加载数据/*.csv
├── db_structure.txt # create_db.py 的模式定义源
├── data/ # 加载到 finstg.db 的静态 CSV 数据
│ ├── project.csv
│ ├── ca_detail.csv
│ ├── ca_bill_plan.csv
│ └── proj_resource.csv
├── finstg.db # 本地 SQLite 数据库（生成）
├── tools/ # 语义工具模块
│ ├── introspection.py # 模式发现工具
│ ├── contracts.py # 合同/计费工具
│ └── billing.py # 计费设置和成本补偿分析工具
├── tests/ # 测试套件
│ └── test_contracts.py
└── pyproject.toml # 项目配置
```
## 运行测试
```bash
uv run pytest tests/ -v -s
```
## 示例查询
- "列出业务单元 UCD 的所有活动项目"
- "哪些合同行和计费计划属于项目 25B1111？"
- "合同 FAKE4 行 2 的计费计划状态是什么？"
- "finstg.db 中有哪些表和列？"
## 开发
### 添加新工具
1. 在 `tools/` 中创建新模块或添加到现有模块
2. 定义使用 `db.execute_query()` 的异步函数
3. 添加 `register_tools(mcp)` 函数
4. 在 `peoplesoft_server.py` 中导入和注册
## 许可证
MIT
## 更新日志
### v0.3.0 (2026-07-15)
- 删除了旧 PeopleSoft HCM Oracle 工具模块（`hr.py`、`payroll.py`、`benefits.py`、`performance.py`、`peopletools.py`）、其文档、其门控/跳过测试以及围绕它们的 Cursor 代理/技能配置
- 删除了 4 个为已删除的 Oracle 模式文档提供服务的 MCP 资源
- 将仓库重新用作 MCP 服务器构造的独立工作示例（模式自省 + 语义工具 + 直接 SQL 出口）用于本地 SQLite 数据库
### v0.2.x (2026-03-02 – 早期)
- 将 Oracle (`oracledb`) 后端替换为本地 SQLite 数据库 (`finstg.db`)
- 重写模式自省以使用 SQLite 自己的元数据 (`sqlite_master`、`PRAGMA table_info`)
- 添加了 `tools/contracts.py`，包含用于本地 `PROJECT`/`CA_DETAIL`/`CA_BILL_PLAN` 模式的语义工具
