@mindstone-engineering/mcp-server-pandadoc 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PandaDoc authentication module.
+ *
+ * Manages the API key lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+/**
+ * Returns the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Returns true if an API key is configured.
+ */
+export declare function isConfigured(): boolean;
+/**
+ * Update the API key at runtime (e.g. after configure_pandadoc_api_key).
+ */
+export declare function setApiKey(key: string): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,26 @@
+/**
+ * PandaDoc authentication module.
+ *
+ * Manages the API key lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+let apiKey = process.env.PANDADOC_API_KEY || '';
+/**
+ * Returns the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Returns true if an API key is configured.
+ */
+export function isConfigured() {
+    return apiKey.length > 0;
+}
+/**
+ * Update the API key at runtime (e.g. after configure_pandadoc_api_key).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * PandaDoc API HTTP client.
+ *
+ * Centralises API-Key header injection, error handling, and rate-limit
+ * messaging for all PandaDoc API calls.
+ *
+ * IMPORTANT: PandaDoc uses `Authorization: API-Key {key}` — not Bearer.
+ */
+/**
+ * Make an authenticated request to the PandaDoc API.
+ *
+ * @param path  API path relative to base, e.g. `/documents`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export declare function pandadocFetch<T>(path: string, options?: RequestInit): Promise<T>;
+/**
+ * Make an authenticated raw request (for binary downloads).
+ *
+ * @param path  API path relative to base
+ * @param options  Additional fetch options
+ * @returns Raw Response object
+ */
+export declare function pandadocFetchRaw(path: string, options?: RequestInit): Promise<Response>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,113 @@
+/**
+ * PandaDoc API HTTP client.
+ *
+ * Centralises API-Key header injection, error handling, and rate-limit
+ * messaging for all PandaDoc API calls.
+ *
+ * IMPORTANT: PandaDoc uses `Authorization: API-Key {key}` — not Bearer.
+ */
+import { getApiKey } from './auth.js';
+import { PandaDocError, PANDADOC_API_BASE, REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Make an authenticated request to the PandaDoc API.
+ *
+ * @param path  API path relative to base, e.g. `/documents`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export async function pandadocFetch(path, options = {}) {
+    const key = getApiKey();
+    if (!key) {
+        throw new PandaDocError('PandaDoc API key not configured', 'AUTH_REQUIRED', 'Use configure_pandadoc_api_key to set your API key first.');
+    }
+    const url = `${PANDADOC_API_BASE}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                Authorization: `API-Key ${key}`,
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new PandaDocError('Request to PandaDoc API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the PandaDoc API is available.');
+        }
+        throw error;
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new PandaDocError('Authentication failed', 'AUTH_FAILED', 'Your PandaDoc API key is invalid or revoked. Use configure_pandadoc_api_key to set a new key.');
+    }
+    if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        const parsed = retryAfter ? parseInt(retryAfter, 10) : NaN;
+        const waitSeconds = Number.isFinite(parsed) ? parsed : 60;
+        throw new PandaDocError(`Rate limited by PandaDoc API. Please wait ${waitSeconds} seconds before retrying.`, 'RATE_LIMITED', `Wait ${waitSeconds} seconds and try again. PandaDoc has per-minute rate limits.`);
+    }
+    if (response.status === 404) {
+        throw new PandaDocError('Resource not found', 'NOT_FOUND', 'The requested document or template does not exist. Verify the ID using list_documents or list_templates.');
+    }
+    if (response.status === 409) {
+        const errorBody = await response.text().catch(() => '');
+        throw new PandaDocError(`Conflict (409): ${errorBody || 'Document is not ready for this operation.'}`, 'CONFLICT', 'Check the document status with get_document_status. The document may not be in the required state.');
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'Unknown error');
+        throw new PandaDocError(`PandaDoc API error (${response.status}): ${errorText}`, 'API_ERROR', 'Check the request parameters and try again.');
+    }
+    // Some endpoints may return empty body
+    const text = await response.text();
+    if (!text)
+        return {};
+    return JSON.parse(text);
+}
+/**
+ * Make an authenticated raw request (for binary downloads).
+ *
+ * @param path  API path relative to base
+ * @param options  Additional fetch options
+ * @returns Raw Response object
+ */
+export async function pandadocFetchRaw(path, options = {}) {
+    const key = getApiKey();
+    if (!key) {
+        throw new PandaDocError('PandaDoc API key not configured', 'AUTH_REQUIRED', 'Use configure_pandadoc_api_key to set your API key first.');
+    }
+    const url = `${PANDADOC_API_BASE}${path}`;
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                Authorization: `API-Key ${key}`,
+                Accept: 'application/pdf',
+                ...options.headers,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new PandaDocError('Request to PandaDoc API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the PandaDoc API is available.');
+        }
+        throw error;
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new PandaDocError('Authentication failed', 'AUTH_FAILED', 'Your PandaDoc API key is invalid or revoked. Use configure_pandadoc_api_key to set a new key.');
+    }
+    if (response.status === 409) {
+        throw new PandaDocError('Document is not ready for download. It may still be processing or in draft status.', 'CONFLICT', 'Check the document status with get_document_status. Documents must be sent or completed to download.');
+    }
+    if (response.status === 404) {
+        throw new PandaDocError('Document not found.', 'NOT_FOUND', 'Verify the document ID is correct using list_documents.');
+    }
+    if (!response.ok) {
+        throw new PandaDocError(`Download failed (${response.status}): ${response.statusText}`, 'DOWNLOAD_ERROR', 'Check the document status and try again.');
+    }
+    return response;
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * PandaDoc MCP Server
+ *
+ * Provides PandaDoc document automation via Model Context Protocol.
+ * Upload documents, create from templates, send for e-signature,
+ * track status, download.
+ *
+ * Environment variables:
+ * - PANDADOC_API_KEY: User's PandaDoc API key — required for all operations
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * PandaDoc MCP Server
+ *
+ * Provides PandaDoc document automation via Model Context Protocol.
+ * Upload documents, create from templates, send for e-signature,
+ * track status, download.
+ *
+ * Environment variables:
+ * - PANDADOC_API_KEY: User's PandaDoc API key — required for all operations
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('PandaDoc MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerDocumentTools, registerTemplateTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'pandadoc-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerDocumentTools(server);
+    registerTemplateTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { setApiKey } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { PandaDocError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_pandadoc_api_key', {
+        description: 'Configure the PandaDoc API key. Call this tool when the user provides their PandaDoc API key. ' +
+            'Get an API key from the PandaDoc Developer Dashboard: ' +
+            'Settings → API → Developer Dashboard → Generate a Sandbox key (for testing) or Production key (for live use). ' +
+            'Note: API access requires a PandaDoc Business or Enterprise plan.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('The PandaDoc API key from Settings > API > Developer Dashboard'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const trimmedKey = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/pandadoc/configure', { apiKey: trimmedKey });
+                if (result.success) {
+                    setApiKey(trimmedKey);
+                    const message = result.warning
+                        ? `PandaDoc API key configured successfully. Note: ${result.warning}`
+                        : 'PandaDoc API key configured successfully! You can now use list_documents, upload_document, and other PandaDoc tools.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new PandaDocError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof PandaDocError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new PandaDocError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge configured — configure in-memory only
+        setApiKey(trimmedKey);
+        return JSON.stringify({
+            ok: true,
+            message: 'PandaDoc API key configured successfully! You can now use list_documents, upload_document, and other PandaDoc tools.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/documents.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDocumentTools(server: McpServer): void;
+//# sourceMappingURL=documents.d.ts.map

package/dist/tools/documents.js

@@ -0,0 +1,444 @@
+import { z } from 'zod';
+import * as fs from 'fs';
+import * as path from 'path';
+import { pandadocFetch, pandadocFetchRaw } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+import { MAX_FILE_SIZE } from '../types.js';
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'PandaDoc API key not configured',
+        resolution: 'To use PandaDoc, you need to configure an API key first.',
+        next_step: {
+            action: 'Ask the user for their PandaDoc API key, then call configure_pandadoc_api_key',
+            tool_to_call: 'configure_pandadoc_api_key',
+            tool_parameters: { api_key: '<user_provided_key>' },
+            get_key_from: 'PandaDoc Settings → API → Developer Dashboard. Requires Business or Enterprise plan.',
+        },
+    });
+}
+function formatDocumentCompact(doc) {
+    return {
+        id: doc.id,
+        name: doc.name,
+        status: doc.status,
+        date_created: doc.date_created,
+        date_modified: doc.date_modified,
+        expiration_date: doc.expiration_date,
+        version: doc.version,
+    };
+}
+function formatDocumentDetails(doc) {
+    return {
+        id: doc.id,
+        name: doc.name,
+        status: doc.status,
+        date_created: doc.date_created,
+        date_modified: doc.date_modified,
+        date_completed: doc.date_completed,
+        date_sent: doc.date_sent,
+        expiration_date: doc.expiration_date,
+        version: doc.version,
+        created_by: doc.created_by,
+        template: doc.template,
+        recipients: doc.recipients,
+        fields: doc.fields,
+        tokens: doc.tokens,
+        metadata: doc.metadata,
+        tags: doc.tags,
+        grand_total: doc.grand_total,
+        linked_objects: doc.linked_objects,
+    };
+}
+function paginationHint(count, page, pageSize) {
+    if (count < pageSize)
+        return `Showing all ${count} results.`;
+    return `Showing ${count} results (page ${page}). Use page=${page + 1} to see more.`;
+}
+export function registerDocumentTools(server) {
+    // ── list_documents ──────────────────────────────────────────────────
+    server.registerTool('list_documents', {
+        description: `List and search PandaDoc documents with filtering.
+
+Supports filtering by status, template, name/reference, tags, metadata, date ranges, and more.
+Returns compact summaries: id, name, status, dates.
+
+Status codes: 0=draft, 1=sent, 2=completed, 3=uploaded, 4=error, 5=viewed,
+6=waiting_approval, 7=approved, 8=rejected, 9=waiting_pay, 10=paid, 11=voided, 12=declined
+
+RELATED TOOLS:
+- get_document_details: Get full details for a specific document
+- get_document_status: Quick status check by document ID`,
+        inputSchema: z.object({
+            q: z.string().optional().describe('Search by document name or reference number'),
+            status: z.number().optional().describe('Filter by status code (0=draft, 1=sent, 2=completed, etc.)'),
+            template_id: z.string().optional().describe('Filter by parent template ID'),
+            folder_uuid: z.string().optional().describe('Filter by folder ID'),
+            tag: z.string().optional().describe('Filter by tag'),
+            created_from: z.string().optional().describe('Documents created on or after this date (ISO 8601)'),
+            created_to: z.string().optional().describe('Documents created before this date (ISO 8601)'),
+            order_by: z.string().optional().describe('Sort field. Prefix with - for DESC (e.g., "-date_created"). Default: date_status_changed'),
+            count: z.number().min(1).max(100).default(50).describe('Results per page (default 50, max 100)'),
+            page: z.number().min(1).default(1).describe('Page number (starts at 1)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const params = new URLSearchParams();
+        params.set('count', String(args.count));
+        params.set('page', String(args.page));
+        if (args.q)
+            params.set('q', args.q);
+        if (args.status !== undefined)
+            params.set('status', String(args.status));
+        if (args.template_id)
+            params.set('template_id', args.template_id);
+        if (args.folder_uuid)
+            params.set('folder_uuid', args.folder_uuid);
+        if (args.tag)
+            params.set('tag', args.tag);
+        if (args.created_from)
+            params.set('created_from', args.created_from);
+        if (args.created_to)
+            params.set('created_to', args.created_to);
+        if (args.order_by)
+            params.set('order_by', args.order_by);
+        const result = await pandadocFetch(`/documents?${params.toString()}`);
+        const documents = (result.results || []).map(formatDocumentCompact);
+        const hint = paginationHint(documents.length, args.page, args.count);
+        return JSON.stringify({ ok: true, documents, count: documents.length, pagination: hint });
+    }));
+    // ── get_document_status ─────────────────────────────────────────────
+    server.registerTool('get_document_status', {
+        description: `Check the current status of a PandaDoc document.
+
+Returns: id, name, status, dates. Lightweight alternative to get_document_details.
+Use this to poll after upload/creation until status changes to 'document.draft'.
+
+Status values: document.uploaded, document.draft, document.sent, document.completed,
+document.viewed, document.waiting_approval, document.approved, document.rejected,
+document.waiting_pay, document.paid, document.voided, document.declined, document.error
+
+WORKFLOW — After upload:
+1. Upload returns status 'document.uploaded'
+2. Poll this tool every 2-3 seconds
+3. When status is 'document.draft', the document is ready to send`,
+        inputSchema: z.object({
+            document_id: z.string().min(1).describe('The document ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const result = await pandadocFetch(`/documents/${encodeURIComponent(args.document_id)}`);
+        return JSON.stringify({ ok: true, document: formatDocumentCompact(result) });
+    }));
+    // ── get_document_details ────────────────────────────────────────────
+    server.registerTool('get_document_details', {
+        description: `Get full details for a PandaDoc document.
+
+Returns comprehensive data: recipients, fields, tokens, pricing, metadata, tags, linked objects, and more.
+Use this to inspect a document's content and state before sending or after completion.
+
+RELATED TOOLS:
+- list_documents: Find document IDs
+- get_document_status: Quick status check (lighter weight than full details)
+- send_document: Send the document for signing`,
+        inputSchema: z.object({
+            document_id: z.string().min(1).describe('The document ID'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const result = await pandadocFetch(`/documents/${encodeURIComponent(args.document_id)}/details`);
+        return JSON.stringify({ ok: true, document: formatDocumentDetails(result) });
+    }));
+    // ── create_document_from_template ───────────────────────────────────
+    server.registerTool('create_document_from_template', {
+        description: `Create a new PandaDoc document from an existing template.
+
+Templates can contain fields, tokens (variables), pricing tables, images, and content placeholders.
+Pre-fill field values, set recipients, and customize content when creating.
+
+WORKFLOW:
+1. Call list_templates to find the template ID
+2. Create the document with this tool (pre-fill fields/tokens as needed)
+3. Poll get_document_status until status is 'document.draft'
+4. Use send_document to send for signing
+
+RELATED TOOLS:
+- list_templates: Find available templates and their IDs
+- get_document_details: See all fields/tokens after creation
+- send_document: Send the created document`,
+        inputSchema: z.object({
+            template_uuid: z.string().min(1).describe('Template ID (from list_templates or PandaDoc app URL)'),
+            name: z.string().optional().describe('Document name'),
+            recipients: z.array(z.object({
+                email: z.string().describe('Recipient email'),
+                first_name: z.string().optional().describe('Recipient first name'),
+                last_name: z.string().optional().describe('Recipient last name'),
+                role: z.string().optional().describe('Must match a role in the template'),
+                signing_order: z.number().optional().describe('Order in signing sequence'),
+            })).min(1).describe('Document recipients (at least one required)'),
+            tokens: z.array(z.object({
+                name: z.string().describe('Token/variable name from template'),
+                value: z.string().describe('Value to fill in'),
+            })).optional().describe('Template variables to pre-fill'),
+            fields: z.record(z.unknown()).optional().describe('Map of field names to values: { "FieldName": { "value": "text" } }'),
+            metadata: z.record(z.unknown()).optional().describe('Custom key-value metadata to associate with the document'),
+            tags: z.array(z.string()).optional().describe('Tags to apply'),
+            folder_uuid: z.string().optional().describe('Folder ID to store the document in'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const body = {
+            template_uuid: args.template_uuid,
+            recipients: args.recipients,
+        };
+        if (args.name)
+            body.name = args.name;
+        if (args.tokens)
+            body.tokens = args.tokens;
+        if (args.fields)
+            body.fields = args.fields;
+        if (args.metadata)
+            body.metadata = args.metadata;
+        if (args.tags)
+            body.tags = args.tags;
+        if (args.folder_uuid)
+            body.folder_uuid = args.folder_uuid;
+        const result = await pandadocFetch('/documents', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return JSON.stringify({
+            ok: true,
+            document: formatDocumentCompact(result),
+            info: result.info_message || 'Document created. Poll get_document_status until status is "document.draft" before sending.',
+        });
+    }));
+    // ── upload_document ─────────────────────────────────────────────────
+    server.registerTool('upload_document', {
+        description: `Upload a PDF, DOCX, or RTF file to PandaDoc to create a new document.
+
+The file is uploaded and converted into an interactive PandaDoc document.
+After upload, the document status is 'document.uploaded' and transitions to 'document.draft' after processing (typically 1-5 seconds).
+
+WORKFLOW:
+1. Upload the file with this tool
+2. Poll get_document_status until status is 'document.draft'
+3. Then use send_document to send it for signing
+
+COMMON MISTAKES:
+- Don't try to send a document while it's still in 'document.uploaded' status — wait for 'document.draft'
+- File must be under 50 MB
+- Encrypted PDFs are not supported
+
+RELATED TOOLS:
+- get_document_status: Check when document is ready (status = 'document.draft')
+- send_document: Send the processed document for e-signature`,
+        inputSchema: z.object({
+            file_path: z.string().min(1).describe('Absolute path to the PDF, DOCX, or RTF file to upload'),
+            name: z.string().optional().describe('Document name in PandaDoc (defaults to filename)'),
+            recipients: z.array(z.object({
+                email: z.string().describe('Recipient email address'),
+                first_name: z.string().optional().describe('Recipient first name'),
+                last_name: z.string().optional().describe('Recipient last name'),
+                role: z.string().optional().describe('Recipient role (e.g., "Client", "Signer")'),
+            })).optional().describe('List of document recipients (at least one required for sending)'),
+            parse_form_fields: z.boolean().optional().describe('If true, recognizes PDF form fields as PandaDoc fields. Default: false'),
+            tags: z.array(z.string()).optional().describe('Tags to apply to the document'),
+            folder_uuid: z.string().optional().describe('ID of the PandaDoc folder to store the document in'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const resolvedPath = path.resolve(args.file_path);
+        // Validate file exists and check size
+        let fileInfo;
+        try {
+            fileInfo = fs.statSync(resolvedPath);
+        }
+        catch {
+            return JSON.stringify({
+                ok: false,
+                error: `File not found: ${resolvedPath}`,
+                resolution: 'Check the file path exists and is accessible.',
+            });
+        }
+        if (fileInfo.size > MAX_FILE_SIZE) {
+            return JSON.stringify({
+                ok: false,
+                error: `File too large (${(fileInfo.size / 1024 / 1024).toFixed(1)}MB). Maximum is 50MB.`,
+                resolution: 'Use a smaller file or compress it before uploading.',
+            });
+        }
+        // Validate file extension
+        const ext = path.extname(resolvedPath).toLowerCase();
+        if (!['.pdf', '.docx', '.rtf'].includes(ext)) {
+            return JSON.stringify({
+                ok: false,
+                error: `Unsupported file type: ${ext}. PandaDoc accepts PDF, DOCX, and RTF files.`,
+                resolution: 'Convert the file to PDF, DOCX, or RTF before uploading.',
+            });
+        }
+        const fileBuffer = fs.readFileSync(resolvedPath);
+        const fileName = args.name || path.basename(resolvedPath);
+        // Build metadata JSON for the 'data' field
+        const data = { name: fileName };
+        if (args.recipients)
+            data.recipients = args.recipients;
+        if (args.tags)
+            data.tags = args.tags;
+        if (args.folder_uuid)
+            data.folder_uuid = args.folder_uuid;
+        if (args.parse_form_fields)
+            data.parse_form_fields = true;
+        const mimeTypes = {
+            '.pdf': 'application/pdf',
+            '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            '.rtf': 'application/rtf',
+        };
+        const formData = new FormData();
+        formData.append('file', new Blob([fileBuffer], { type: mimeTypes[ext] || 'application/octet-stream' }), path.basename(resolvedPath));
+        formData.append('data', JSON.stringify(data));
+        // Upload — use pandadocFetch but with FormData body and no Content-Type (let browser set multipart boundary)
+        const key = (await import('../auth.js')).getApiKey();
+        const { PANDADOC_API_BASE, REQUEST_TIMEOUT_MS } = await import('../types.js');
+        const { PandaDocError } = await import('../types.js');
+        const useFormFields = args.parse_form_fields ? '&use_form_field_properties=true' : '';
+        const url = `${PANDADOC_API_BASE}/documents?upload${useFormFields}`;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                headers: {
+                    Authorization: `API-Key ${key}`,
+                },
+                body: formData,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                throw new PandaDocError('Upload to PandaDoc API timed out', 'TIMEOUT', 'The upload took too long. Try again or use a smaller file.');
+            }
+            throw error;
+        }
+        if (!response.ok) {
+            if (response.status === 429) {
+                throw new PandaDocError('Rate limited by PandaDoc API.', 'RATE_LIMITED', 'Wait a moment and try again.');
+            }
+            const errorText = await response.text().catch(() => 'Unknown error');
+            throw new PandaDocError(`PandaDoc upload error (${response.status}): ${errorText}`, 'UPLOAD_ERROR', 'Check the file and try again.');
+        }
+        const result = await response.json();
+        return JSON.stringify({
+            ok: true,
+            document: formatDocumentCompact(result),
+            info: result.info_message || 'Document uploaded. Poll get_document_status until status is "document.draft" before sending.',
+        });
+    }));
+    // ── send_document ───────────────────────────────────────────────────
+    server.registerTool('send_document', {
+        description: `Send a PandaDoc document to recipients for viewing/signing.
+
+The document must be in 'document.draft' status before sending.
+Optionally include a custom email message and subject line.
+
+COMMON MISTAKES:
+- Cannot send a document in 'document.uploaded' status — wait for 'document.draft'
+- Cannot re-send a document that is already 'document.completed' or 'document.voided'
+
+RELATED TOOLS:
+- get_document_status: Verify document is in 'document.draft' before sending
+- get_document_details: Review document content before sending`,
+        inputSchema: z.object({
+            document_id: z.string().min(1).describe('The document ID'),
+            message: z.string().optional().describe('Email body message sent to recipients with the document link'),
+            subject: z.string().optional().describe('Email subject line'),
+            silent: z.boolean().optional().describe('If true, suppresses email notifications to recipients. Default: false'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const body = {};
+        if (args.message)
+            body.message = args.message;
+        if (args.subject)
+            body.subject = args.subject;
+        if (args.silent !== undefined)
+            body.silent = args.silent;
+        const result = await pandadocFetch(`/documents/${encodeURIComponent(args.document_id)}/send`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return JSON.stringify({
+            ok: true,
+            document: {
+                id: result.id,
+                name: result.name,
+                status: result.status,
+                recipients: result.recipients,
+            },
+            message: 'Document sent successfully.',
+        });
+    }));
+    // ── download_document ───────────────────────────────────────────────
+    server.registerTool('download_document', {
+        description: `Download a PandaDoc document as a PDF file.
+
+Returns the file path where the PDF has been saved. The document must be in a
+completed or sent status to download.
+
+RELATED TOOLS:
+- get_document_status: Check document status before downloading
+- list_documents: Find document IDs`,
+        inputSchema: z.object({
+            document_id: z.string().min(1).describe('The document ID'),
+            watermark_text: z.string().optional().describe('Optional watermark text to overlay on the PDF'),
+            watermark_color: z.string().optional().describe('Watermark color as HEX code (e.g., "#FF5733")'),
+            watermark_font_size: z.number().optional().describe('Watermark font size'),
+            watermark_opacity: z.number().optional().describe('Watermark opacity (0.0 to 1.0)'),
+            separate_files: z.boolean().optional().describe('If true, downloads as a zip archive with separate PDFs per section'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const params = new URLSearchParams();
+        if (args.watermark_text)
+            params.set('watermark_text', args.watermark_text);
+        if (args.watermark_color)
+            params.set('watermark_color', args.watermark_color);
+        if (args.watermark_font_size)
+            params.set('watermark_font_size', String(args.watermark_font_size));
+        if (args.watermark_opacity)
+            params.set('watermark_opacity', String(args.watermark_opacity));
+        if (args.separate_files)
+            params.set('separate_files', 'true');
+        const queryStr = params.toString();
+        const downloadPath = `/documents/${encodeURIComponent(args.document_id)}/download${queryStr ? `?${queryStr}` : ''}`;
+        const response = await pandadocFetchRaw(downloadPath);
+        // Save the PDF to a temp file
+        const pdfBuffer = Buffer.from(await response.arrayBuffer());
+        const tmpDir = process.env.TMPDIR || process.env.TEMP || '/tmp';
+        const safeName = `pandadoc_${args.document_id.replace(/[^a-zA-Z0-9_-]/g, '_')}.pdf`;
+        const outputPath = path.join(tmpDir, safeName);
+        fs.writeFileSync(outputPath, pdfBuffer);
+        return JSON.stringify({
+            ok: true,
+            file_path: outputPath,
+            file_size: `${(pdfBuffer.length / 1024).toFixed(1)}KB`,
+            message: `Document downloaded to ${outputPath}`,
+        });
+    }));
+}
+//# sourceMappingURL=documents.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerDocumentTools } from './documents.js';
+export { registerTemplateTools } from './templates.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerDocumentTools } from './documents.js';
+export { registerTemplateTools } from './templates.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/templates.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTemplateTools(server: McpServer): void;
+//# sourceMappingURL=templates.d.ts.map

package/dist/tools/templates.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { pandadocFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'PandaDoc API key not configured',
+        resolution: 'To use PandaDoc, you need to configure an API key first.',
+        next_step: {
+            action: 'Ask the user for their PandaDoc API key, then call configure_pandadoc_api_key',
+            tool_to_call: 'configure_pandadoc_api_key',
+            tool_parameters: { api_key: '<user_provided_key>' },
+            get_key_from: 'PandaDoc Settings → API → Developer Dashboard. Requires Business or Enterprise plan.',
+        },
+    });
+}
+function paginationHint(count, page, pageSize) {
+    if (count < pageSize)
+        return `Showing all ${count} results.`;
+    return `Showing ${count} results (page ${page}). Use page=${page + 1} to see more.`;
+}
+export function registerTemplateTools(server) {
+    server.registerTool('list_templates', {
+        description: `List available PandaDoc templates.
+
+Returns template IDs, names, and dates. Use template IDs with create_document_from_template.
+
+RELATED TOOLS:
+- create_document_from_template: Use a template ID to create a new document`,
+        inputSchema: z.object({
+            q: z.string().optional().describe('Search by template name'),
+            folder_uuid: z.string().optional().describe('Filter by folder ID'),
+            tag: z.array(z.string()).optional().describe('Filter by tags'),
+            count: z.number().min(1).max(100).default(50).describe('Results per page (default 50, max 100)'),
+            page: z.number().min(1).default(1).describe('Page number (starts at 1)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const params = new URLSearchParams();
+        params.set('count', String(args.count));
+        params.set('page', String(args.page));
+        if (args.q)
+            params.set('q', args.q);
+        if (args.folder_uuid)
+            params.set('folder_uuid', args.folder_uuid);
+        if (args.tag && Array.isArray(args.tag)) {
+            for (const t of args.tag) {
+                params.append('tag', t);
+            }
+        }
+        const result = await pandadocFetch(`/templates?${params.toString()}`);
+        const templates = (result.results || []).map((t) => ({
+            id: t.id,
+            name: t.name,
+            date_created: t.date_created,
+            date_modified: t.date_modified,
+            version: t.version,
+        }));
+        const hint = paginationHint(templates.length, args.page, args.count);
+        return JSON.stringify({ ok: true, templates, count: templates.length, pagination: hint });
+    }));
+}
+//# sourceMappingURL=templates.js.map

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const PANDADOC_API_BASE = "https://api.pandadoc.com/public/v1";
+export declare const MAX_FILE_SIZE: number;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class PandaDocError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export interface DocumentCompact {
+    id: string;
+    name: string;
+    status: string;
+    date_created: string;
+    date_modified: string;
+    expiration_date: string | null;
+    version: string | null;
+}
+export interface DocumentDetails extends DocumentCompact {
+    date_completed: string | null;
+    date_sent: string | null;
+    created_by: Record<string, unknown>;
+    template: Record<string, unknown> | null;
+    recipients: Record<string, unknown>[];
+    fields: Record<string, unknown>[];
+    tokens: Record<string, unknown>[];
+    metadata: Record<string, unknown>;
+    tags: string[];
+    grand_total: Record<string, unknown> | null;
+    linked_objects: Record<string, unknown>[];
+}
+export interface DocumentListResponse {
+    results: Record<string, unknown>[];
+}
+export interface TemplateListResponse {
+    results: Record<string, unknown>[];
+}
+export interface DocumentCreateResponse {
+    id: string;
+    name: string;
+    status: string;
+    date_created: string;
+    date_modified: string;
+    expiration_date: string | null;
+    version: string | null;
+    uuid: string;
+    links: Array<{
+        rel: string;
+        href: string;
+        type: string;
+    }>;
+    info_message: string;
+}
+export interface DocumentSendResponse {
+    id: string;
+    name: string;
+    status: string;
+    date_created: string;
+    date_modified: string;
+    recipients: Array<Record<string, unknown>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,14 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const PANDADOC_API_BASE = 'https://api.pandadoc.com/public/v1';
+export const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB
+export class PandaDocError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'PandaDocError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On PandaDocError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { PandaDocError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On PandaDocError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof PandaDocError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-pandadoc",
+  "version": "0.1.0",
+  "description": "PandaDoc document automation MCP server for Model Context Protocol hosts",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-pandadoc": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/pandadoc"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/pandadoc",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}