AI导哈

Paylocity数据获取服务

一个通过MCP协议从Paylocity API端点获取员工薪资、税务等数据的服务器。

  • by mz462
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 mz462/mcppaylocity

使用说明

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)
  • MODEL_COST_PRIORITY -模型选择的可选成本优先级
  • MODEL_SPEED_PRIORITY -可选的速度优先级用于型号选择
  • MODEL_INTELLIGENCE_PRIORITY -模型选择的可选智能优先级
  • MODEL_HINTS -可选逗号分隔的模型名称提示

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

MCP握手

启动时，服务器响应MCP initialize 带有握手数据的请求 包含其功能、指令、协议版本和服务器信息。这 说明字段描述了如何使用Paylocity资源和工具。

安全

⚠️ 重要：此应用程序将身份验证令牌缓存在 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

Development/Unpublished Servers Configuration 
"mcpServers": {
  "mcpPaylocity": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/mcpPaylocity",
      "run",
      "mcppaylocity"
    ]
  }
}
Published Servers Configuration 
"mcpServers": {
  "mcpPaylocity": {
    "command": "uvx",
    "args": [
      "mcppaylocity"
    ]
  }
}

发展

建筑与出版

准备分发包裹：

  1. 同步依赖关系并更新锁文件：
uv sync
  1. 构建包分发：
uv build

这将在 dist/ 目录。

  1. 发布到PyPI：
uv publish

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

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

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.

您可以通过以下方式启动MCP检查器 npm 使用此命令：

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

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

建筑

服务器由以下组件构建：

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

许可证

MIT许可证

版权所有（c）2024邹美杰(@梅祖)

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

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

软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。

相关 MCP