# @mindops/zapsign-mcp

Model Context Protocol server that exposes the [ZapSign](https://docs.zapsign.com.br/) REST API as MCP tools. Plug it into any MCP-aware host (Claude Desktop, VS Code, Cursor, your own SDK app) and let an LLM drive document workflows: create documents, manage signers, fill DOCX templates, run background checks, manage webhooks.

## What's covered

Tools are grouped by ZapSign resource. The set tracks the public REST API one-to-one; each tool wraps exactly one endpoint.

- **Documents** — create from PDF URL / base64 / template, list, detail, update, delete, reorder display, place signatures, oneclick, extra docs, signer activity log
- **Signers** — add, update, detail, delete, sign in batch, refuse, refuse by user, reset auth attempts, resend notifications, verification details, signer groups
- **Templates** — create from DOCX, update form fields, list, detail, update, delete
- **Users** — create, list, delete, plan info
- **Webhooks** — create, delete (event payloads are reference docs, not API endpoints)
- **Auth (JWT)** — get token, refresh token (alternative to static API token)
- **Background checks** — create person/company check, list, detail
- **Timestamp** — apply timestamp to a signed PDF, or to an arbitrary PDF without altering signatures
- **Validation** — verify a signed PDF
- **Partner** — partner company management, payment status updates, plan-usage CSV report

## Install

After publishing to the registry:

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

### Local install (before publish)

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

### First-time publish

The package targets the **@mindops** scope on npmjs.org with `restricted` access. To publish:

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

If the @mindops org doesn't yet exist on npm, create it first at https://www.npmjs.com/org/create.

## Configure

Create a `.env` file (or set environment variables in your MCP host config):

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

Recommended: a **System User permanent token** (Configurações → API → Tokens in the ZapSign panel). User-bound tokens expire and break automation.

## Use from an MCP host

### Claude Desktop / Claude Code

Add to your MCP config (typically `~/Library/Application Support/Claude/claude_desktop_config.json`):

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

### VS Code / Cursor

Same shape — drop it into the MCP servers section of your settings.

### Locally during development

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

The server speaks stdio; connect with any MCP client to introspect tools.

## Tool naming conventions

- snake_case names matching ZapSign's resource terminology (`create_document`, `add_signer`, `delete_template`, etc.)
- Field names in tool inputs preserve ZapSign's API spelling (`phone_country`, `phone_number`, `auth_mode`, `url_pdf`...) so the underlying request body is exactly what the API expects.
- Path parameters appear as top-level fields with the same name (`doc_token`, `signer_token`, `template_token`).

## Development

```bash
npm install
npm run typecheck
npm run build
```

Add new endpoints by creating a definition in `src/tools/<resource>.ts` and re-running `npm run build`. Each tool is a thin wrapper:

```ts
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),
});
```

The helper handles error envelope formatting and JSON-stringification for the MCP transport.

## Versioning

This package tracks the ZapSign **v1** API. ZapSign versions their endpoints behind `/api/v1/`; if/when v2 ships, this server will gain a parallel module rather than replace v1 in place.

## License

Proprietary (MindOps internal). Contact MindOps before redistributing.