pnlcs-mcp

Un servidor de Model Context Protocol para PNLCS, el panel de facturación de código abierto. Conecta Claude Code, Claude Desktop, Cursor, VS Code o cualquier otro cliente MCP a tu instalación de PNLCS y trabaja con ella en lenguaje natural:

"¿Qué facturas están vencidas?" — "Muéstrame los servicios y dominios de este cliente." — "¿Hay algún pedido retenido como fraude hoy?" — "Abre un ticket para ada@example.com sobre la renovación de su dominio."

Cero dependencias. El servidor es un pequeño proceso de Node que se comunica con la API de administración de PNLCS que ya tienes. No se instala nada en el lado de PNLCS.

• npm: pnlcs-mcp

• Requiere: Node 18+ en la máquina donde se ejecuta tu cliente de IA

• Transporte: stdio (lanzado por tu cliente — sin puerto, nada que alojar)

1. Crea una credencial de API en PNLCS

1. Inicia sesión en el área de administración de tu instalación de PNLCS.

2. Ve a Configuración → Credenciales de API.

3. Haz clic en Crear, ponle un nombre como mcp y copia los dos valores que te muestra:

   • Identificador — el nombre de usuario de la credencial

   • Secreto — se muestra una sola vez; guárdalo en un lugar seguro

Ese par es todo lo que necesita el servidor, y se le pasa mediante tres variables de entorno:

Related MCP server: WHMCS MCP Server

2. Conecta tu cliente

Claude Code (CLI)

Un solo comando:

claude mcp add pnlcs \
  --env PNLCS_URL=https://billing.example.com \
  --env PNLCS_IDENTIFIER=your_identifier \
  --env PNLCS_SECRET=your_secret \
  -- npx -y pnlcs-mcp

Añade --env PNLCS_ALLOW_WRITES=1 si también quieres las herramientas de escritura. Usa --scope project para compartir la entrada con tu equipo mediante .mcp.json (pon el secreto en el entorno de tu shell, no en el archivo versionado). Compruébalo con claude mcp list; elimínalo con claude mcp remove pnlcs.

Claude Desktop

Edita claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "pnlcs": {
      "command": "npx",
      "args": ["-y", "pnlcs-mcp"],
      "env": {
        "PNLCS_URL": "https://billing.example.com",
        "PNLCS_IDENTIFIER": "your_identifier",
        "PNLCS_SECRET": "your_secret"
      }
    }
  }
}

Reinicia Claude Desktop; las herramientas aparecen bajo el icono del martillo.

Cursor

Configuración → MCP → Añadir nuevo servidor MCP global, o crea .cursor/mcp.json en tu proyecto (misma forma JSON que Claude Desktop arriba).

VS Code (modo agente de Copilot)

Crea .vscode/mcp.json:

{
  "servers": {
    "pnlcs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pnlcs-mcp"],
      "env": {
        "PNLCS_URL": "https://billing.example.com",
        "PNLCS_IDENTIFIER": "your_identifier",
        "PNLCS_SECRET": "your_secret"
      }
    }
  }
}

Cualquier otra cosa (Windsurf, Cline, Zed, ...)

Cada cliente MCP que pueda lanzar un servidor stdio usa las mismas tres piezas: comando npx, argumentos ["-y", "pnlcs-mcp"] y las variables de entorno anteriores. Desde un clon del repositorio, node mcp/server.js funciona de forma idéntica.

3. Herramientas

Herramientas de lectura — siempre disponibles

Herramientas de escritura — solo con PNLCS_ALLOW_WRITES=1

Sin el indicador, las herramientas de escritura no solo están ocultas: llamar a una de ellas se rechaza antes de que ocurra cualquier HTTP. Un asistente configurado para informes ni siquiera puede ver un botón de suspensión. Dale a una configuración de informes una vida de solo lectura simplemente no estableciendo el indicador.

4. Notas de seguridad

• El secreto solo viaja entre la máquina donde se ejecuta tu cliente de IA y tu instalación de PNLCS, a través de la misma API HTTPS que usan tus pantallas de administración. Nunca se envía al proveedor del modelo; el modelo ve los resultados de las herramientas.

• Prefiere una credencial de API dedicada para MCP, de modo que puedas revocarla de forma independiente.

• PNLCS limita la tasa de las credenciales de API (300 solicitudes/minuto por credencial), así que un agente descontrolado no puede saturar tu instalación.

• Mantén PNLCS_ALLOW_WRITES desactivado a menos que realmente quieras que el asistente actúe sobre tus registros, y lee lo que propone antes de aprobar llamadas a herramientas que creen o modifiquen cosas.

5. Solución de problemas

6. Pruebas

npm test ejecuta la suite sin conexión: lanza el proceso real del servidor, habla con él mediante el protocolo real y comprueba la forma HTTP de cada herramienta contra un stub local, además de la puerta de escritura en ambas direcciones, las solicitudes por lotes de revisiones de protocolo anteriores, la negociación de versiones, los tiempos de espera y el drenaje al apagar.

node test/live.mjs ejecuta todas las herramientas contra una instalación real: apúntalo a una demo, nunca a los registros de producción; crea datos desechables claramente nombrados para las herramientas de escritura e imprime una línea PASS/FAIL por herramienta.

Desarrollo

Este paquete se desarrolla dentro del monorepo de PNLCS en mcp/; este repositorio es su espejo de distribución independiente y siempre coincide con la versión publicada en npm.