mcpengine/servers/pandadoc/README.md

# PandaDoc MCP Server

MCP server for PandaDoc document automation - documents, templates, contacts, fields, content library, webhooks, workspaces.

## Features

- 📄 **Document Management** - Create, send, track documents with e-signatures
- 📋 **Templates** - Build reusable document templates
- 👥 **Contact Management** - Organize recipients and contacts
- 📝 **Field Management** - Pre-fill and manage document fields
- 📚 **Content Library** - Reusable blocks, pricing tables, media
- 🔔 **Webhooks** - Real-time event notifications
- 🏢 **Workspace Management** - Multi-workspace support

## Installation

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

## Configuration

Set your PandaDoc API key:

```bash
export PANDADOC_API_KEY='your_api_key_here'
```

## Usage

Run the server:

```bash
npm start
# or
pandadoc-mcp-server
```

Add to Claude Desktop config:

```json
{
  "mcpServers": {
    "pandadoc": {
      "command": "node",
      "args": ["/path/to/pandadoc/dist/index.js"],
      "env": {
        "PANDADOC_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools

### Document Tools (7)
- `list_documents` - List documents with status/folder filtering, pagination
- `get_document` - Get document details with recipients, fields, pricing
- `create_document` - Create document from template or scratch
- `update_document` - Update draft document name, recipients, fields
- `send_document` - Send document to recipients via email
- `delete_document` - Permanently delete document
- `download_document` - Get PDF download URL for completed docs

### Template Tools (5)
- `list_templates` - List templates with folder filtering
- `get_template` - Get template details, fields, roles
- `create_template` - Create reusable document template
- `update_template` - Update template name, description, tags
- `delete_template` - Delete template (doesn't affect existing docs)

### Contact Tools (5)
- `list_contacts` - List contacts with email filtering
- `get_contact` - Get contact details and address
- `create_contact` - Create new contact
- `update_contact` - Update contact information
- `delete_contact` - Delete contact

### Field Tools (2)
- `get_document_fields` - Get all document fields with types/values
- `update_document_fields` - Pre-fill document field values

### Content Library Tools (4)
- `list_content_library` - List reusable content items by type
- `get_content_library_item` - Get content item details
- `create_content_library_item` - Create reusable content block
- `delete_content_library_item` - Delete content item

### Webhook Tools (4)
- `list_webhooks` - List all configured webhooks
- `create_webhook` - Create webhook for document events
- `update_webhook` - Update webhook URL, events, status
- `delete_webhook` - Delete webhook

### Workspace Tools (2)
- `list_workspaces` - List accessible workspaces
- `get_workspace` - Get workspace details and settings

**Total: 29 tools**

## API Coverage

### Core Entities
- ✅ Documents (list, get, create, update, send, delete, download)
- ✅ Templates (list, get, create, update, delete)
- ✅ Contacts (list, get, create, update, delete)
- ✅ Document Fields (get, update)
- ✅ Content Library (list, get, create, delete)
- ✅ Webhooks (list, create, update, delete)
- ✅ Workspaces (list, get)

### Features
- ✅ Pagination on all list operations
- ✅ Document lifecycle (draft → sent → completed)
- ✅ Template-based document creation
- ✅ Field pre-filling and validation
- ✅ Multi-recipient workflows
- ✅ Real-time webhook events
- ✅ Content reusability
- ✅ Rate limiting (300 req/min)
- ✅ Error handling

### Document Events (Webhooks)
- ✅ document_created
- ✅ document_sent
- ✅ document_viewed
- ✅ document_completed
- ✅ document_declined
- ✅ recipient_completed

## Rate Limits

- Standard: 300 requests/minute
- Automatic rate limit handling with backoff
- Rate limit headers tracked and respected

## Tool Naming Conventions

- `list_*` - Paginated collections (documents, templates, contacts, content_library, webhooks, workspaces)
- `get_*` - Single resource retrieval (document, template, contact, content_library_item, workspace, document_fields)
- `create_*` - Resource creation (document, template, contact, content_library_item, webhook)
- `update_*` - Resource modification (document, template, contact, document_fields, webhook)
- `delete_*` - Resource deletion (document, template, contact, content_library_item, webhook)
- `send_*` - Action operations (send_document)
- `download_*` - Download operations (download_document)

## Architecture

```
src/
├── index.ts                    # MCP server entry point
├── client/
│   └── pandadoc-client.ts     # API client with auth & rate limiting
├── tools/
│   ├── document-tools.ts       # Document operations (7 tools)
│   ├── template-tools.ts       # Template management (5 tools)
│   ├── contact-tools.ts        # Contact management (5 tools)
│   ├── field-tools.ts          # Field operations (2 tools)
│   ├── content-library-tools.ts # Content library (4 tools)
│   ├── webhook-tools.ts        # Webhook management (4 tools)
│   └── workspace-tools.ts      # Workspace operations (2 tools)
└── types/
    └── index.ts                # TypeScript interfaces
```

## License

MIT