docura-mcp 1.0.0

package/README.md

@@ -0,0 +1,170 @@
+# docura-mcp
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the Docura e-signature platform. Connect Claude Code, Cursor, or any MCP-compatible AI client to your Docura account and manage documents via natural language.
+
+No build step required — `npx` downloads and runs it automatically.
+
+## What you can do
+
+Once connected, ask your AI assistant things like:
+
+- *"List all my templates"*
+- *"Send the Master Services Agreement to alice@company.com and bob@company.com for signing"*
+- *"What's the status of submission abc123? Has everyone signed?"*
+- *"Resend the invitation to the second signer on the Smith contract"*
+- *"Void the Q3 NDA submission"*
+- *"Get the full audit trail for submission xyz"*
+- *"How do I download the signed PDF for the Johnson agreement?"*
+- *"List all our registered webhooks and test the production one"*
+
+## Prerequisites
+
+- Node.js 18+
+- A Docura API key (`sk_live_*`) — generate one at **Settings → API Keys** in the dashboard
+
+## Setup
+
+### Step 1 — Get an API key
+
+Log in to your Docura dashboard → **Settings → API Keys** → create a new key. It starts with `sk_live_`.
+
+### Step 2 — Add to Claude Code
+
+Add the server to `.claude/settings.local.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "docura": {
+      "command": "npx",
+      "args": ["-y", "docura-mcp"],
+      "env": {
+        "DOCURA_API_KEY": "sk_live_your_key_here",
+        "DOCURA_BASE_URL": "https://app.docura.com"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code. The `docura` server appears in the MCP panel.
+
+### Add to Cursor
+
+Go to **Cursor Settings → MCP** and add the same block above.
+
+### Install globally (optional — skips the npx download delay)
+
+```bash
+npm install -g docura-mcp
+```
+
+Then use `"command": "docura-mcp"` (no `args`) in your MCP config instead of the `npx` form.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DOCURA_API_KEY` | Yes | — | API key from Docura Settings → API Keys |
+| `DOCURA_BASE_URL` | No | `http://localhost:3000` | Base URL of your Docura instance |
+
+Set `DOCURA_BASE_URL` to your deployed URL (e.g. `https://app.docura.com`) for production use.
+
+## Available tools
+
+### Templates
+
+| Tool | Description |
+|------|-------------|
+| `list_templates` | List all PDF templates in your organization |
+| `get_template` | Get a template's details, fields, and signer roles |
+
+### Submissions
+
+| Tool | Description |
+|------|-------------|
+| `list_submissions` | List submissions, optionally filtered by status |
+| `get_submission` | Get status and signer progress for a submission |
+| `create_submission` | Send a template to one or more signers |
+| `void_submission` | Cancel a pending submission |
+| `resend_invitation` | Resend the signing email to a specific signer |
+
+### Audit & download
+
+| Tool | Description |
+|------|-------------|
+| `get_audit_trail` | Full cryptographic event log (timestamps, IPs, hashes) |
+| `get_download_url` | Get the URL + curl command to download a completed signed PDF |
+
+### Webhooks
+
+| Tool | Description |
+|------|-------------|
+| `list_webhooks` | List all registered webhook endpoints |
+| `test_webhook` | Send a test event to verify a webhook is reachable |
+
+## Tool reference
+
+### `create_submission`
+
+Sends a document to signers. The `signers` array must contain one entry per signer role defined in the template. Use `get_template` first to see the available role names.
+
+```json
+{
+  "templateId": "tmpl_abc123",
+  "signers": [
+    { "email": "alice@company.com", "name": "Alice", "roleName": "Client" },
+    { "email": "bob@company.com",   "name": "Bob",   "roleName": "Vendor" }
+  ],
+  "message": "Please review and sign at your earliest convenience.",
+  "expiresAt": "2025-12-31T23:59:59Z"
+}
+```
+
+### `resend_invitation`
+
+Resends the signing email to a signer who hasn't signed yet. Get the `signerId` from `get_submission`.
+
+```json
+{
+  "submissionId": "sub_xyz789",
+  "signerId": "sgn_def456"
+}
+```
+
+### `get_download_url`
+
+Returns a URL and curl command for downloading the completed signed PDF. The submission must have status `COMPLETED`.
+
+```json
+{ "submissionId": "sub_xyz789" }
+```
+
+Response:
+```json
+{
+  "downloadUrl": "https://app.docura.com/api/v1/submissions/sub_xyz789/download",
+  "instructions": "curl -H \"Authorization: Bearer $DOCURA_API_KEY\" \"...\" -o signed.pdf"
+}
+```
+
+## Development
+
+```bash
+# Clone the repo and build from source
+cd mcp-server
+npm install
+npm run build
+node dist/index.js
+
+# Run without building (uses tsx)
+npm run dev
+```
+
+To test the server manually with [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+Set `DOCURA_API_KEY` and optionally `DOCURA_BASE_URL` in your shell before running.

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+declare const BASE_URL: string;
+declare const API_KEY: string;
+export declare function apiGet(path: string): Promise<unknown>;
+export declare function apiPost(path: string, body?: unknown): Promise<unknown>;
+export declare function apiDelete(path: string): Promise<unknown>;
+export { BASE_URL, API_KEY };

package/dist/client.js

@@ -0,0 +1,35 @@
+const BASE_URL = (process.env.DOCURA_BASE_URL ?? "http://localhost:3000").replace(/\/$/, "");
+const API_KEY = process.env.DOCURA_API_KEY ?? "";
+function headers() {
+    return {
+        Authorization: `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+    };
+}
+async function checkResponse(res) {
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Docura API ${res.status}: ${body}`);
+    }
+    return res.json();
+}
+export async function apiGet(path) {
+    const res = await fetch(`${BASE_URL}/api/v1${path}`, { headers: headers() });
+    return checkResponse(res);
+}
+export async function apiPost(path, body) {
+    const res = await fetch(`${BASE_URL}/api/v1${path}`, {
+        method: "POST",
+        headers: headers(),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    return checkResponse(res);
+}
+export async function apiDelete(path) {
+    const res = await fetch(`${BASE_URL}/api/v1${path}`, {
+        method: "DELETE",
+        headers: headers(),
+    });
+    return checkResponse(res);
+}
+export { BASE_URL, API_KEY };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { templateTools, handleTemplateTools } from "./tools/templates.js";
+import { submissionTools, handleSubmissionTools } from "./tools/submissions.js";
+import { auditTools, handleAuditTools } from "./tools/audit.js";
+import { webhookTools, handleWebhookTools } from "./tools/webhooks.js";
+if (!process.env.DOCURA_API_KEY) {
+    process.stderr.write("Error: DOCURA_API_KEY environment variable is required.\n" +
+        "Get your API key from: Docura Dashboard → Settings → API Keys\n");
+    process.exit(1);
+}
+const allTools = [
+    ...templateTools,
+    ...submissionTools,
+    ...auditTools,
+    ...webhookTools,
+];
+const toolNameSet = new Set(allTools.map((t) => t.name));
+const server = new Server({ name: "docura", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    if (!toolNameSet.has(name)) {
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    try {
+        let result;
+        const a = args;
+        if (templateTools.some((t) => t.name === name)) {
+            result = await handleTemplateTools(name, a);
+        }
+        else if (submissionTools.some((t) => t.name === name)) {
+            result = await handleSubmissionTools(name, a);
+        }
+        else if (auditTools.some((t) => t.name === name)) {
+            result = await handleAuditTools(name, a);
+        }
+        else {
+            result = await handleWebhookTools(name, a);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/audit.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const auditTools: Tool[];
+export declare function handleAuditTools(name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/audit.js

@@ -0,0 +1,45 @@
+import { apiGet, BASE_URL } from "../client.js";
+export const auditTools = [
+    {
+        name: "get_audit_trail",
+        description: "Get the cryptographic audit trail for a submission — all events (invited, viewed, signed, declined, voided) with timestamps, IP addresses, and integrity metadata",
+        inputSchema: {
+            type: "object",
+            properties: {
+                submissionId: { type: "string", description: "Submission ID" },
+            },
+            required: ["submissionId"],
+        },
+    },
+    {
+        name: "get_download_url",
+        description: "Get instructions and the URL to download the completed signed PDF for a submission. The submission must have status COMPLETED.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                submissionId: {
+                    type: "string",
+                    description: "Submission ID (must be COMPLETED)",
+                },
+            },
+            required: ["submissionId"],
+        },
+    },
+];
+export async function handleAuditTools(name, args) {
+    switch (name) {
+        case "get_audit_trail": {
+            return apiGet(`/submissions/${args.submissionId}/audit`);
+        }
+        case "get_download_url": {
+            const url = `${BASE_URL}/api/v1/submissions/${args.submissionId}/download`;
+            return {
+                downloadUrl: url,
+                instructions: `Send a GET request to the URL with your API key in the Authorization header:\n` +
+                    `curl -H "Authorization: Bearer $DOCURA_API_KEY" "${url}" -o signed.pdf`,
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/tools/submissions.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const submissionTools: Tool[];
+export declare function handleSubmissionTools(name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/submissions.js

@@ -0,0 +1,124 @@
+import { apiGet, apiPost, apiDelete } from "../client.js";
+export const submissionTools = [
+    {
+        name: "list_submissions",
+        description: "List document submissions in your organization. Optionally filter by status.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                status: {
+                    type: "string",
+                    enum: ["DRAFT", "PENDING", "COMPLETED", "DECLINED", "EXPIRED", "VOIDED"],
+                    description: "Filter by submission status",
+                },
+                page: { type: "number", description: "Page number (default: 1)" },
+                limit: { type: "number", description: "Results per page, max 100 (default: 20)" },
+            },
+        },
+    },
+    {
+        name: "get_submission",
+        description: "Get the status and details of a specific submission, including each signer's progress",
+        inputSchema: {
+            type: "object",
+            properties: {
+                submissionId: { type: "string", description: "Submission ID" },
+            },
+            required: ["submissionId"],
+        },
+    },
+    {
+        name: "create_submission",
+        description: "Send a document for signing by creating a submission from a template. Returns signing URLs for each signer.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                templateId: { type: "string", description: "ID of the template to send" },
+                signers: {
+                    type: "array",
+                    description: "List of signers — one per signer role in the template",
+                    items: {
+                        type: "object",
+                        properties: {
+                            email: { type: "string", description: "Signer email address" },
+                            name: { type: "string", description: "Signer display name (optional)" },
+                            roleName: {
+                                type: "string",
+                                description: "Signer role name — must match a role defined in the template",
+                            },
+                        },
+                        required: ["email", "roleName"],
+                    },
+                },
+                message: {
+                    type: "string",
+                    description: "Optional message to include in the signing invitation email",
+                },
+                expiresAt: {
+                    type: "string",
+                    description: "Optional expiry date in ISO 8601 format (e.g. 2025-12-31T23:59:59Z)",
+                },
+            },
+            required: ["templateId", "signers"],
+        },
+    },
+    {
+        name: "void_submission",
+        description: "Cancel (void) a pending submission so signers can no longer sign it",
+        inputSchema: {
+            type: "object",
+            properties: {
+                submissionId: { type: "string", description: "Submission ID to void" },
+            },
+            required: ["submissionId"],
+        },
+    },
+    {
+        name: "resend_invitation",
+        description: "Resend the signing invitation email to a specific signer who hasn't signed yet",
+        inputSchema: {
+            type: "object",
+            properties: {
+                submissionId: { type: "string", description: "Submission ID" },
+                signerId: {
+                    type: "string",
+                    description: "Signer ID — use get_submission to find signer IDs",
+                },
+            },
+            required: ["submissionId", "signerId"],
+        },
+    },
+];
+export async function handleSubmissionTools(name, args) {
+    switch (name) {
+        case "list_submissions": {
+            const params = new URLSearchParams();
+            if (args.status)
+                params.set("status", String(args.status));
+            if (args.page)
+                params.set("page", String(args.page));
+            if (args.limit)
+                params.set("limit", String(args.limit));
+            const qs = params.toString();
+            return apiGet(`/submissions${qs ? `?${qs}` : ""}`);
+        }
+        case "get_submission": {
+            return apiGet(`/submissions/${args.submissionId}`);
+        }
+        case "create_submission": {
+            return apiPost(`/templates/${args.templateId}/submissions`, {
+                signers: args.signers,
+                ...(args.message ? { message: args.message } : {}),
+                ...(args.expiresAt ? { expiresAt: args.expiresAt } : {}),
+            });
+        }
+        case "void_submission": {
+            return apiDelete(`/submissions/${args.submissionId}`);
+        }
+        case "resend_invitation": {
+            return apiPost(`/submissions/${args.submissionId}/signers/${args.signerId}/resend`);
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/tools/templates.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const templateTools: Tool[];
+export declare function handleTemplateTools(name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/templates.js

@@ -0,0 +1,39 @@
+import { apiGet } from "../client.js";
+export const templateTools = [
+    {
+        name: "list_templates",
+        description: "List all PDF templates in your Docura organization",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page: { type: "number", description: "Page number (default: 1)" },
+                limit: { type: "number", description: "Results per page, max 100 (default: 20)" },
+            },
+        },
+    },
+    {
+        name: "get_template",
+        description: "Get details of a specific template including its fields and signer roles",
+        inputSchema: {
+            type: "object",
+            properties: {
+                templateId: { type: "string", description: "Template ID" },
+            },
+            required: ["templateId"],
+        },
+    },
+];
+export async function handleTemplateTools(name, args) {
+    switch (name) {
+        case "list_templates": {
+            const page = args.page ?? 1;
+            const limit = args.limit ?? 20;
+            return apiGet(`/templates?page=${page}&limit=${limit}`);
+        }
+        case "get_template": {
+            return apiGet(`/templates/${args.templateId}`);
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/tools/webhooks.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const webhookTools: Tool[];
+export declare function handleWebhookTools(name: string, args: Record<string, unknown>): Promise<unknown>;

package/dist/tools/webhooks.js

@@ -0,0 +1,34 @@
+import { apiGet, apiPost } from "../client.js";
+export const webhookTools = [
+    {
+        name: "list_webhooks",
+        description: "List all webhook endpoints registered in your Docura organization",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "test_webhook",
+        description: "Send a test event to a registered webhook endpoint to verify it is reachable and responding correctly",
+        inputSchema: {
+            type: "object",
+            properties: {
+                webhookId: { type: "string", description: "Webhook ID to test" },
+            },
+            required: ["webhookId"],
+        },
+    },
+];
+export async function handleWebhookTools(name, args) {
+    switch (name) {
+        case "list_webhooks": {
+            return apiGet("/webhooks");
+        }
+        case "test_webhook": {
+            return apiPost(`/webhooks/${args.webhookId}/test`);
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "docura-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the Docura e-signature platform — manage documents from Claude Code, Cursor, or any MCP-compatible AI client",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "docura-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "docura",
+    "e-signature",
+    "esign",
+    "ai",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.22.4",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}