🚀 MCP Paylocity 服务器
MCP Paylocity 服务器是一个模型上下文协议 (MCP) 服务器，主要用于从 Paylocity API 端点获取数据，为数据获取和管理提供了便捷的解决方案。
🚀 快速开始
安装配置
在终端中运行以下命令安装并启动服务器：
cd /path/to/mcpPaylocity
npm install
npm start
Claude Desktop 配置
根据环境选择以下配置方式：
开发环境配置
{
"development": {
"command": "uv --directory . run mcppaylocity",
"args": []
}
}
发布环境配置
{
"production": {
"command": "uv --directory . run mcppaylocity",
"args": []
}
}
✨ 主要特性
资源访问
- 自定义 URI 方案：使用
paylocity://自定义 URI 方案，通过以下路径访问 Paylocity 数据：/employees：获取员工信息。/departments：获取部门信息。/jobs：获取职位信息。/salary-slips：获取工资单信息。
工具实现
- 数据获取工具：
fetch_employees：根据过滤条件（如部门、职位）获取员工列表。fetch_departments：获取所有部门信息。fetch_jobs：获取所有职位信息。fetch_salary_slips：根据员工 ID 获取工资单详情。
- 未来计划：增加高级功能，如绩效数据、考勤记录等，目前仍在开发中。
📦 安装指南
环境变量配置
为使服务器正常运行，请设置以下环境变量并存入 .env 文件：
| 变量名 | 描述 | 示例值 |
|---|---|---|
PAYLOCITY_CLIENT_ID |
Paylocity API 客户端 ID | "your_client_id" |
PAYLOCITY_CLIENT_SECRET |
Paylocity API 客户端密钥 | "your_client_secret" |
PAYLOCITY_COMPANY_IDS |
要访问的公司 ID 列表（逗号分隔） | "123,456,789" |
PAYLOCITY_ENVIRONMENT |
环境类型（开发/生产） | "development"或"production" |
注意事项
⚠️ 重要提示
- 认证令牌会缓存到本地文件，确保服务器运行环境的安全性。
- 不要将包含敏感信息的
.env文件提交到代码仓库。
💻 使用示例
基础用法
由于文档未提供基础使用的代码示例，暂无法展示。
📚 详细文档
构建与发布
- 构建：
npm run build
- 打包：
npm run package
- 发布：
npm run publish
请确保设置好 npm 用户令牌或使用环境变量进行认证。
调试技巧
由于 MCP 服务器通过标准输入输出运行，调试较为困难。推荐使用 MCP 检查器 进行调试：
npx @modelcontextprotocol/inspector uv --directory /path/to/mcpPaylocity run mcppaylocity
运行后，检查器会显示浏览器访问地址，帮助您进行调试。
🔧 技术细节
组件结构
PaylocityClient：负责与 Paylocity API 进行通信。TokenManager：管理认证令牌的缓存和自动刷新功能。FastMCP 服务器：将 Paylocity 数据通过 MCP 资源和工具对外暴露。
📄 许可证
MIT License
版权所有 (c) 2024 MJ Zou (@mjzou)
许可条款：
允许任何人免费使用、复制、修改、合并、发布、分发、 sublicensing 和/或出售本软件及其关联的文档文件，前提是遵守以下条件：
- 保留版权声明：无论以任何形式复制或分发，必须包含版权声明。
- 限制责任声明：对于因使用或无法使用本软件而导致的任何损害（包括但不限于直接、间接、附带、特殊、衍生或后果性损害），版权所有者不承担任何责任。