# docuseal-mcp-server

MCP server for DocuSeal (self-hosted or cloud) using stdio transport.

Package name: `@caffeinebounce/docuseal-mcp-server`

## Features

Implements these MCP tools:

### Templates
- `list_templates` — list templates (paginated)
- `get_template` — get template by ID
- `create_template_from_pdf` — upload PDF from file path or base64

### Submissions
- `create_submission` — create signature request from template
- `list_submissions` — list submissions (paginated + status filter)
- `get_submission` — get submission details
- `get_submission_documents` — get documents for a submission (optional local download)

### Submitters
- `list_submitters` — list submitters (optionally by submission)
- `get_submitter` — get submitter details
- `update_submitter` — update submitter fields (including reminder-style flags like `send_email`)

## Requirements

- Node.js 18+
- A DocuSeal instance with API enabled
- API key with required permissions

## Environment Variables

- `DOCUSEAL_URL` — base URL for DocuSeal (default: `http://localhost:3030`)
- `DOCUSEAL_API_KEY` — API key for `X-Auth-Token` header (**required**)

Example:

```bash
export DOCUSEAL_URL="http://localhost:3030"
export DOCUSEAL_API_KEY="<your-api-key>"
```

## Install and Build

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

## Run

```bash
npm start
```

Or in development:

```bash
npm run dev
```

## MCP Client Configuration (example)

```json
{
  "mcpServers": {
    "docuseal": {
      "command": "node",
      "args": ["/absolute/path/to/docuseal-mcp-server/dist/index.js"],
      "env": {
        "DOCUSEAL_URL": "http://localhost:3030",
        "DOCUSEAL_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

## Notes

- API calls use `fetch` and include `X-Auth-Token`.
- API errors include HTTP status + response body in tool output for debugging.
- `get_submission_documents` can optionally download returned document URLs to disk using:
  - `download: true`
  - optional `output_dir` (default: `./downloads/submission_<id>`)