Servidor MCP de mcpPaylocity

Un servidor de Protocolo de contexto de modelo (MCP) para obtener datos de los puntos finales de la API de Paylocity.

Componentes

Recursos

El servidor implementa recursos de API de Paylocity con:

• Esquema de URI paylocity:// personalizado para acceder a los datos de Paylocity

• Los siguientes recursos están disponibles:

  • paylocity://employees/{company_id} - Lista todos los empleados de una empresa

  • paylocity://employees/{company_id}/{employee_id} - Obtener detalles de un empleado específico

  • paylocity://earnings/{company_id}/{employee_id} - Obtener datos de ganancias de un empleado específico

  • paylocity://codes/{company_id}/{code_resource} - Obtener códigos de empresa para un recurso específico

  • paylocity://localtaxes/{company_id}/{employee_id} - Obtener los impuestos locales de un empleado específico

  • paylocity://paystatement/{company_id}/{employee_id}/{year}/{check_date} - Obtener detalles del estado de pago para una fecha específica

Herramientas

El servidor implementa las siguientes herramientas:

• fetch_employees : obtiene todos los empleados de una empresa

  • Toma el parámetro company_id opcional

• fetch_employee_details : obtiene detalles de un empleado específico

  • Toma los parámetros requeridos employee_id y opcionales company_id

• fetch_employee_earnings : obtiene datos de ganancias de un empleado específico

  • Toma los parámetros requeridos employee_id y opcionales company_id

• fetch_company_codes : obtiene códigos de empresa para un recurso específico

  • Toma los parámetros obligatorios code_resource y company_id opcionales

• fetch_employee_local_taxes : obtiene los impuestos locales de un empleado específico

  • Toma los parámetros requeridos employee_id y opcionales company_id

• fetch_employee_paystatement_details : obtiene los detalles del extracto de pago para una fecha específica

  • Toma los parámetros obligatorios employee_id , year , check_date y company_id opcional.

Implementaciones futuras

Los siguientes puntos finales se implementarán en futuras actualizaciones:

• [ ] Información de nivel superior (por ejemplo, tasa de rotación, plantilla por departamento, comparación de tarifas, etc.)

Configuración

El servidor requiere que se configuren las siguientes variables de entorno:

• PAYLOCITY_CLIENT_ID - Su ID de cliente de la API de Paylocity

• PAYLOCITY_CLIENT_SECRET - Su secreto de cliente de la API de Paylocity

• PAYLOCITY_COMPANY_IDS - Lista separada por comas de identificaciones de empresas para usar

• PAYLOCITY_ENVIRONMENT - Entorno API a utilizar ( production o testing )

Estos se pueden configurar en un archivo .env en el directorio raíz del proyecto.

Seguridad

⚠️ IMPORTANTE : Esta aplicación almacena en caché los tokens de autenticación en el directorio src/mcppaylocity/access_token/ . Estos archivos contienen credenciales confidenciales y nunca deben enviarse al control de versiones.

El repositorio incluye estas rutas en .gitignore , pero verifique que los archivos de token no se confirmen accidentalmente al enviar cambios.

Si ha enviado archivos de token accidentalmente, siga estos pasos:

1. Eliminar los archivos del repositorio: git rm --cached src/mcppaylocity/access_token/token.json src/mcppaylocity/access_token/token_info.txt

2. Confirmar la eliminación: git commit -m "Remove accidentally committed token files"

3. Considere rotar sus credenciales de API de Paylocity, ya que podrían haber sido comprometidas

Inicio rápido

Instalar

Escritorio de Claude

En MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json

Desarrollo

Construcción y publicación

Para preparar el paquete para su distribución:

1. Sincronizar dependencias y actualizar archivo de bloqueo:

2. Distribuciones de paquetes de compilación:

Esto creará distribuciones de origen y de rueda en el directorio dist/ .

3. Publicar en PyPI:

Nota: Deberás configurar las credenciales de PyPI a través de variables de entorno o indicadores de comando:

• Token: --token o UV_PUBLISH_TOKEN

• O nombre de usuario/contraseña: --username / UV_PUBLISH_USERNAME y --password / UV_PUBLISH_PASSWORD

Depuración

Dado que los servidores MCP se ejecutan en stdio, la depuración puede ser complicada. Para una experiencia óptima, recomendamos usar el Inspector MCP .

Puede iniciar el Inspector MCP a través de npm con este comando:

Al iniciarse, el Inspector mostrará una URL a la que podrá acceder en su navegador para comenzar a depurar.

Arquitectura

El servidor está construido con los siguientes componentes:

1. PaylocityClient : gestiona la comunicación con la API de Paylocity

2. TokenManager : administra tokens de autenticación, incluido el almacenamiento en caché y la renovación.

3. Servidor FastMCP : expone datos de Paylocity a través de recursos y herramientas de MCP

Licencia

Licencia MIT

Copyright (c) 2024 MJ Zou ( @mjzou )

Por la presente se concede permiso, sin cargo, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricción, incluyendo, sin limitación, los derechos a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir que las personas a quienes se les proporciona el Software lo hagan, sujeto a las siguientes condiciones:

El aviso de derechos de autor anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑOS U OTRAS RESPONSABILIDADES, YA SEA EN ACCIÓN CONTRACTUAL, EXTRACONTRACTUAL O DE OTRO TIPO, QUE SURJA DE, SE DERIVE DE O EN RELACIÓN CON EL SOFTWARE O EL USO U OTRAS RELACIONES CON EL MISMO.