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参数

Related MCP server: Paylocity MCP Server by CData

未来实施

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

• [ ] 更高层次的洞察（例如离职率、部门员工人数、费率比较等）

配置

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

• 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 凭证，因为它们可能已被泄露

快速入门

安装

克劳德桌面

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

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

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

发展

构建和发布

准备分发包：

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

uv sync

2. 构建软件包分发版：

uv build

这将在dist/目录中创建源和轮子分布。

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

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

建筑学

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

1. PaylocityClient - 处理与 Paylocity API 的通信

2. TokenManager - 管理身份验证令牌，包括缓存和更新

3. FastMCP 服务器- 通过 MCP 资源和工具公开 Paylocity 数据

执照

MIT 许可证

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

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

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

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