mcpPaylocity MCP 服务器

一个模型上下文协议 (MCP) 服务器，用于从 Paylocity API 端点获取数据。

组件

资源

该服务器实现了 Paylocity API 资源，具有：

• 用于访问 Paylocity 数据的自定义 paylocity:// URI 方案
• 以下资源可用：
  • paylocity://employees/{company_id} - 列出公司的所有员工
  • paylocity://employees/{company_id}/{employee_id} - 获取特定员工的详细信息
  • paylocity://earnings/{company_id}/{employee_id} - 获取特定员工的收入数据
  • paylocity://codes/{company_id}/{code_resource} - 获取特定资源的公司代码
  • paylocity://localtaxes/{company_id}/{employee_id} - 获取特定员工的本地税
  • paylocity://paystatement/{company_id}/{employee_id}/{year}/{check_date} - 获取特定日期的工资单详细信息

工具

该服务器实现了以下工具：

• fetch_employees - 获取公司的所有员工
  • 接受可选的 company_id 参数
• fetch_employee_details - 获取特定员工的详细信息
  • 接受必需的 employee_id 和可选的 company_id 参数
• fetch_employee_earnings - 获取特定员工的收入数据
  • 接受必需的 employee_id 和可选的 company_id 参数
• fetch_company_codes - 获取特定资源的公司代码
  • 接受必需的 code_resource 和可选的 company_id 参数
• fetch_employee_local_taxes - 获取特定员工的本地税
  • 接受必需的 employee_id 和可选的 company_id 参数
• fetch_employee_paystatement_details - 获取特定日期的工资单详细信息
  • 接受必需的 employee_id、year、check_date 和可选的 company_id 参数

未来实现

以下端点将在未来的更新中实现：

• [ ] 更高级别的见解（例如，离职率、按部门划分的员工人数、费率比较等）

配置

服务器需要设置以下环境变量：

• PAYLOCITY_CLIENT_ID - 您的 Paylocity API 客户端 ID
• PAYLOCITY_CLIENT_SECRET - 您的 Paylocity API 客户端密钥
• PAYLOCITY_COMPANY_IDS - 要使用的公司 ID 的逗号分隔列表
• PAYLOCITY_ENVIRONMENT - 要使用的 API 环境（production 或 testing）

这些可以在项目根目录中的 .env 文件中设置。

安全

⚠️ 重要提示：此应用程序将身份验证令牌缓存在 src/mcppaylocity/access_token/ 目录中。这些文件包含敏感凭据，绝不应提交到版本控制。

该存储库在 .gitignore 中包含这些路径，但请验证在推送更改时是否未意外提交令牌文件。

如果您不小心提交了令牌文件，请按照以下步骤操作：

1. 从存储库中删除文件：git rm --cached src/mcppaylocity/access_token/token.json src/mcppaylocity/access_token/token_info.txt
2. 提交删除：git commit -m "Remove accidentally committed token files"
3. 考虑轮换您的 Paylocity API 凭据，因为它们可能已泄露

快速入门

安装

Claude Desktop

在 MacOS 上：~/Library/Application\ Support/Claude/claude_desktop_config.json 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

<details> <summary>开发/未发布的服务器配置</summary>

"mcpServers": {
  "mcpPaylocity": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/mcpPaylocity",
      "run",
      "mcppaylocity"
    ]
  }
}

</details>

<details> <summary>已发布的服务器配置</summary>

"mcpServers": {
  "mcpPaylocity": {
    "command": "uvx",
    "args": [
      "mcppaylocity"
    ]
  }
}

</details>

开发

构建和发布

要准备用于分发的软件包：

1. 同步依赖项并更新锁定文件：

uv sync

2. 构建软件包分发：

uv build

这将在 dist/ 目录中创建源和 wheel 分发。

3. 发布到 PyPI：

uv publish

注意：您需要通过环境变量或命令标志设置 PyPI 凭据：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

调试

由于 MCP 服务器通过 stdio 运行，因此调试可能具有挑战性。 为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

您可以使用 npm 通过以下命令启动 MCP Inspector：

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

启动后，Inspector 将显示一个 URL，您可以在浏览器中访问该 URL 以开始调试。

架构

该服务器由以下组件构建：

1. PaylocityClient - 处理与 Paylocity API 的通信
2. TokenManager - 管理身份验证令牌，包括缓存和续订
3. FastMCP Server - 通过 MCP 资源和工具公开 Paylocity 数据

许可证

MIT 许可证

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

特此授予任何人免费获得本软件及其相关文档文件（“软件”）副本的许可，不受限制地处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利，并允许向其提供本软件的人员这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或主要部分中。

本软件按“原样”提供，不提供任何形式的明示或暗示的保证，包括但不限于适销性、特定用途适用性和不侵权的保证。 在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权诉讼或其他诉讼中，因本软件或本软件的使用或其他交易而引起或与之相关的。