@mindops/zapsign-mcp

Servidor del Model Context Protocol que expone la API REST de ZapSign como herramientas MCP. Conéctalo a cualquier host compatible con MCP (Claude Desktop, VS Code, Cursor, tu propia aplicación SDK) y deja que un LLM gestione los flujos de trabajo de documentos: crear documentos, gestionar firmantes, rellenar plantillas DOCX, ejecutar verificaciones de antecedentes y gestionar webhooks.

Qué cubre

Las herramientas se agrupan por recurso de ZapSign. El conjunto sigue la API REST pública uno a uno; cada herramienta envuelve exactamente un endpoint.

• Documentos — crear desde URL de PDF / base64 / plantilla, listar, detalle, actualizar, eliminar, reordenar la visualización, colocar firmas, oneclick, documentos adicionales, registro de actividad de firmantes

• Firmantes — añadir, actualizar, detalle, eliminar, firmar en lote, rechazar, rechazar por usuario, restablecer intentos de autenticación, reenviar notificaciones, detalles de verificación, grupos de firmantes

• Plantillas — crear desde DOCX, actualizar campos de formulario, listar, detalle, actualizar, eliminar

• Usuarios — crear, listar, eliminar, información del plan

• Webhooks — crear, eliminar (los payloads de eventos son documentos de referencia, no endpoints de API)

• Autenticación (JWT) — obtener token, renovar token (alternativa al token de API estático)

• Verificaciones de antecedentes — crear verificación de persona/empresa, listar, detalle

• Marca de tiempo — aplicar marca de tiempo a un PDF firmado, o a un PDF arbitrario sin alterar las firmas

• Validación — verificar un PDF firmado

• Partner — gestión de empresas partner, actualizaciones de estado de pago, informe CSV de uso del plan

Instalación

Tras publicar en el registro:

npm install -g @mindops/zapsign-mcp
# or run on demand with npx (no global install):
npx -y @mindops/zapsign-mcp

Instalación local (antes de publicar)

cd /path/to/zapsign-mcp
npm install
npm run build
npm link            # exposes `zapsign-mcp` on $PATH globally

Publicación por primera vez

El paquete tiene como objetivo el ámbito @mindops en npmjs.org con acceso restricted. Para publicar:

npm login                      # authenticate against registry.npmjs.org
npm publish --access restricted   # or just `npm publish` — restricted is the publishConfig default

Si la organización @mindops aún no existe en npm, créala primero en https://www.npmjs.com/org/create.

Configuración

Crea un archivo .env (o define las variables de entorno en la configuración de tu host MCP):

ZAPSIGN_API_TOKEN=your-permanent-system-user-token
ZAPSIGN_ENV=production       # or 'sandbox' for the test environment

Recomendado: un token permanente de usuario del sistema (Configurações → API → Tokens en el panel de ZapSign). Los tokens vinculados a usuarios caducan y rompen la automatización.

Uso desde un host MCP

Claude Desktop / Claude Code

Añádelo a tu configuración de MCP (normalmente ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "zapsign": {
      "command": "npx",
      "args": ["-y", "@mindops/zapsign-mcp"],
      "env": {
        "ZAPSIGN_API_TOKEN": "...",
        "ZAPSIGN_ENV": "production"
      }
    }
  }
}

VS Code / Cursor

Misma estructura: colócalo en la sección de servidores MCP de tu configuración.

Localmente durante el desarrollo

npm install
npm run build
ZAPSIGN_API_TOKEN=... ZAPSIGN_ENV=sandbox node dist/index.js

El servidor usa stdio; conéctalo con cualquier cliente MCP para inspeccionar las herramientas.

Convenciones de nomenclatura de herramientas

• Nombres en snake_case que coinciden con la terminología de recursos de ZapSign (create_document, add_signer, delete_template, etc.)

• Los nombres de campos en las entradas de las herramientas conservan la ortografía de la API de ZapSign (phone_country, phone_number, auth_mode, url_pdf...) para que el cuerpo de la solicitud subyacente sea exactamente lo que la API espera.

• Los parámetros de ruta aparecen como campos de nivel superior con el mismo nombre (doc_token, signer_token, template_token).

Desarrollo

npm install
npm run typecheck
npm run build

Añade nuevos endpoints creando una definición en src/tools/<resource>.ts y volviendo a ejecutar npm run build. Cada herramienta es un wrapper ligero:

registerTool(server, client, {
  name: 'create_document',
  description: 'Create a new document from a public PDF URL.',
  inputSchema: z.object({ /* fields */ }),
  handler: async (input, { client }) => client.post('/docs/', input),
});

El helper gestiona el formato del sobre de errores y la serialización JSON para el transporte MCP.

Versionado

Este paquete sigue la API v1 de ZapSign. ZapSign versiona sus endpoints detrás de /api/v1/; si/cuando se lance v2, este servidor ganará un módulo paralelo en lugar de reemplazar v1 en su lugar.

Licencia

Propietaria (interna de MindOps). Contacta con MindOps antes de redistribuir.