Paylocity

🚀 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 文件：

注意事项

⚠️ 重要提示

• 认证令牌会缓存到本地文件，确保服务器运行环境的安全性。
• 不要将包含敏感信息的 .env 文件提交到代码仓库。

💻 使用示例

基础用法

由于文档未提供基础使用的代码示例，暂无法展示。

📚 详细文档

构建与发布

1. 构建：

npm run build

2. 打包：

npm run package

3. 发布：

npm run publish

请确保设置好 npm 用户令牌或使用环境变量进行认证。

调试技巧

由于 MCP 服务器通过标准输入输出运行，调试较为困难。推荐使用 MCP 检查器 进行调试：

npx @modelcontextprotocol/inspector uv --directory /path/to/mcpPaylocity run mcppaylocity

运行后，检查器会显示浏览器访问地址，帮助您进行调试。

🔧 技术细节

组件结构

1. PaylocityClient：负责与 Paylocity API 进行通信。
2. TokenManager：管理认证令牌的缓存和自动刷新功能。
3. FastMCP 服务器：将 Paylocity 数据通过 MCP 资源和工具对外暴露。

📄 许可证

MIT License

版权所有 (c) 2024 MJ Zou (@mjzou)

许可条款：

允许任何人免费使用、复制、修改、合并、发布、分发、 sublicensing 和/或出售本软件及其关联的文档文件，前提是遵守以下条件：

• 保留版权声明：无论以任何形式复制或分发，必须包含版权声明。
• 限制责任声明：对于因使用或无法使用本软件而导致的任何损害（包括但不限于直接、间接、附带、特殊、衍生或后果性损害），版权所有者不承担任何责任。