@esignlaunchpad/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eSign Launchpad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# eSign Launchpad MCP Server
+
+MCP (Model Context Protocol) server that enables AI agents to interact with the eSign Launchpad e-signature platform. Create, send, and manage signing packages directly from Claude, Cursor, or any MCP-compatible AI client.
+
+## Quick Start
+
+```bash
+# Install
+npm install @esignlaunchpad/mcp-server
+
+# Run (requires API key)
+ESIGN_API_KEY=eslp_live_your_key_here npx @esignlaunchpad/mcp-server
+```
+
+## Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "esign-launchpad": {
+      "command": "npx",
+      "args": ["@esignlaunchpad/mcp-server"],
+      "env": {
+        "ESIGN_API_KEY": "eslp_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## What Can AI Agents Do?
+
+With this MCP server, AI agents can:
+
+- **Create signing packages** with documents, signers, and annotation fields
+- **Upload documents** (PDF, DOCX) via chunked upload
+- **Add signers** with authentication requirements (email, SMS, KBA, ID verification)
+- **Place signature fields** on documents with precise positioning
+- **Send packages** for signing with custom email messages
+- **Track status** of packages and individual signers
+- **Download completed documents** and certificates of completion
+- **Manage templates** for reusable signing workflows
+- **Configure webhooks** for real-time event notifications
+- **Manage signing groups** for team-based signing
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ESIGN_API_KEY` | Yes | - | Your eSign Launchpad API key (`eslp_live_...`) |
+| `ESIGN_API_URL` | No | `https://api.esignlaunchpad.com` | API base URL |
+| `ESIGN_SPEC_URL` | No | `{API_URL}/openapi/tenant-api.json` | OpenAPI spec URL |
+
+## API Key Setup
+
+1. Log in to [eSign Launchpad](https://app.esignlaunchpad.com)
+2. Go to **Settings > API**
+3. Click **Generate API Key**
+4. Select the permissions your agent needs
+5. Copy the key (shown only once)
+
+## Available Permissions
+
+API keys are scoped. Select only what your agent needs:
+
+| Scope | Operations |
+|-------|-----------|
+| `packages:read` | List, view, download packages |
+| `packages:write` | Create, send, void, archive packages |
+| `templates:read` | List and view templates |
+| `templates:write` | Create and modify templates |
+| `webhooks:manage` | Create and manage webhook subscriptions |
+| `signing-groups:read` | View signing groups |
+| `signing-groups:manage` | Create and manage signing groups |
+
+## How It Works
+
+This MCP server reads the eSign Launchpad OpenAPI specification at startup and dynamically generates MCP tools for each API endpoint. When the API is updated with new features, simply restart the server to pick up new tools automatically.
+
+No code generation needed. No manual tool definitions. The OpenAPI spec is the single source of truth.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@esignlaunchpad/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP (Model Context Protocol) server for eSign Launchpad - enables AI agents to create, send, and manage e-sign packages.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "esign-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "esign",
+    "e-signature",
+    "electronic-signature",
+    "ai-agent",
+    "claude",
+    "cursor",
+    "signing",
+    "documents",
+    "api"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "eSign Launchpad",
+    "email": "preflight@notarylaunchpad.com",
+    "url": "https://www.esignlaunchpad.com"
+  },
+  "homepage": "https://www.esignlaunchpad.com/Home/Developers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/esignlaunchpad/mcp-server"
+  },
+  "bugs": {
+    "url": "https://www.esignlaunchpad.com/Home/Support",
+    "email": "preflight@notarylaunchpad.com"
+  },
+  "funding": {
+    "type": "commercial",
+    "url": "https://www.esignlaunchpad.com/Home/Pricing"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/index.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+
+/**
+ * eSign Launchpad MCP Server
+ *
+ * Exposes the eSign Launchpad REST API as MCP tools for AI agents.
+ * Reads the OpenAPI spec at startup and dynamically generates tools
+ * for each API operation. When the API changes, restart the server
+ * to pick up new endpoints automatically.
+ *
+ * Usage:
+ *   npx @esignlaunchpad/mcp-server
+ *
+ * Environment variables:
+ *   ESIGN_API_KEY     - Your eSign Launchpad API key (eslp_live_...)
+ *   ESIGN_API_URL     - API base URL (default: https://api.esignlaunchpad.com)
+ *   ESIGN_SPEC_URL    - OpenAPI spec URL (default: {ESIGN_API_URL}/openapi/tenant-api.json)
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_KEY = process.env.ESIGN_API_KEY;
+const API_URL = (process.env.ESIGN_API_URL || "https://api.esignlaunchpad.com").replace(/\/$/, "");
+const SPEC_URL = process.env.ESIGN_SPEC_URL || `${API_URL}/openapi/tenant-api.json`;
+
+if (!API_KEY) {
+  console.error("Error: ESIGN_API_KEY environment variable is required.");
+  console.error("Generate an API key at https://app.esignlaunchpad.com/Settings/Api");
+  process.exit(1);
+}
+
+// ── Fetch and parse OpenAPI spec ──
+
+async function fetchSpec() {
+  const res = await fetch(SPEC_URL);
+  if (!res.ok) throw new Error(`Failed to fetch OpenAPI spec from ${SPEC_URL}: ${res.status}`);
+  return res.json();
+}
+
+// ── Convert OpenAPI schema to Zod schema ──
+
+function openApiSchemaToZod(schema, required = false) {
+  if (!schema) return required ? z.unknown() : z.unknown().optional();
+
+  if (schema.enum) {
+    return required ? z.enum(schema.enum) : z.enum(schema.enum).optional();
+  }
+
+  switch (schema.type) {
+    case "string":
+      return required ? z.string().describe(schema.description || "") : z.string().optional().describe(schema.description || "");
+    case "integer":
+    case "number":
+      return required ? z.number().describe(schema.description || "") : z.number().optional().describe(schema.description || "");
+    case "boolean":
+      return required ? z.boolean().describe(schema.description || "") : z.boolean().optional().describe(schema.description || "");
+    case "array":
+      const itemSchema = openApiSchemaToZod(schema.items, true);
+      return required ? z.array(itemSchema).describe(schema.description || "") : z.array(itemSchema).optional().describe(schema.description || "");
+    case "object":
+      if (schema.properties) {
+        const shape = {};
+        const reqFields = new Set(schema.required || []);
+        for (const [key, prop] of Object.entries(schema.properties)) {
+          shape[key] = openApiSchemaToZod(prop, reqFields.has(key));
+        }
+        return required ? z.object(shape).describe(schema.description || "") : z.object(shape).optional().describe(schema.description || "");
+      }
+      return required ? z.record(z.unknown()) : z.record(z.unknown()).optional();
+    default:
+      return required ? z.unknown() : z.unknown().optional();
+  }
+}
+
+// ── Resolve $ref in OpenAPI spec ──
+
+function resolveRef(spec, ref) {
+  if (!ref || !ref.startsWith("#/")) return ref;
+  const parts = ref.substring(2).split("/");
+  let current = spec;
+  for (const part of parts) {
+    current = current?.[part];
+    if (current === undefined) return null;
+  }
+  return current;
+}
+
+function resolveSchema(spec, schema) {
+  if (!schema) return null;
+  if (schema.$ref) return resolveRef(spec, schema.$ref);
+  return schema;
+}
+
+// ── Build tool name from operationId or path ──
+
+function buildToolName(method, path, operation) {
+  if (operation.operationId) {
+    // Convert PascalCase to snake_case
+    return operation.operationId
+      .replace(/([a-z])([A-Z])/g, "$1_$2")
+      .replace(/([A-Z])([A-Z][a-z])/g, "$1_$2")
+      .toLowerCase()
+      .replace(/[^a-z0-9_]/g, "_")
+      .replace(/_+/g, "_")
+      .substring(0, 64);
+  }
+  // Fallback: method + path
+  return `${method}_${path.replace(/[^a-zA-Z0-9]/g, "_").replace(/_+/g, "_")}`.toLowerCase().substring(0, 64);
+}
+
+// ── Build tool description ──
+
+function buildDescription(operation, method, path) {
+  const parts = [];
+  if (operation.summary) parts.push(operation.summary);
+  if (operation.description && operation.description !== operation.summary) {
+    parts.push(operation.description);
+  }
+  parts.push(`[${method.toUpperCase()} ${path}]`);
+  return parts.join("\n\n");
+}
+
+// ── Extract parameters and request body into a single Zod schema ──
+
+function buildInputSchema(spec, operation, pathParams) {
+  const shape = {};
+
+  // Path and query parameters
+  const allParams = [...(pathParams || []), ...(operation.parameters || [])];
+  for (const param of allParams) {
+    const resolved = param.$ref ? resolveRef(spec, param.$ref) : param;
+    if (!resolved) continue;
+    const paramSchema = resolveSchema(spec, resolved.schema) || { type: "string" };
+    shape[resolved.name] = openApiSchemaToZod(paramSchema, resolved.required);
+    if (resolved.description && shape[resolved.name]) {
+      shape[resolved.name] = shape[resolved.name].describe(resolved.description);
+    }
+  }
+
+  // Request body (JSON)
+  const body = operation.requestBody;
+  if (body) {
+    const resolved = body.$ref ? resolveRef(spec, body.$ref) : body;
+    const content = resolved?.content?.["application/json"];
+    if (content?.schema) {
+      const bodySchema = resolveSchema(spec, content.schema);
+      if (bodySchema?.properties) {
+        const reqFields = new Set(bodySchema.required || []);
+        for (const [key, prop] of Object.entries(bodySchema.properties)) {
+          const resolvedProp = resolveSchema(spec, prop) || prop;
+          shape[key] = openApiSchemaToZod(resolvedProp, reqFields.has(key));
+        }
+      } else {
+        // Opaque body — accept as JSON string
+        shape["_body"] = z.string().optional().describe("JSON request body");
+      }
+    }
+  }
+
+  return Object.keys(shape).length > 0 ? z.object(shape) : z.object({});
+}
+
+// ── Make API call ──
+
+async function callApi(method, pathTemplate, params, spec) {
+  // Substitute path parameters
+  let path = pathTemplate;
+  const queryParams = {};
+  const bodyParams = {};
+
+  // Identify which params are path, query, or body
+  const pathParamNames = new Set(
+    (pathTemplate.match(/\{([^}]+)\}/g) || []).map((m) => m.slice(1, -1))
+  );
+
+  // Collect all declared parameters
+  const operation = getOperation(spec, method, pathTemplate);
+  const declaredParams = new Set();
+  for (const p of [...(spec.paths[pathTemplate]?.parameters || []), ...(operation?.parameters || [])]) {
+    const resolved = p.$ref ? resolveRef(spec, p.$ref) : p;
+    if (resolved) declaredParams.add(resolved.name);
+  }
+
+  for (const [key, value] of Object.entries(params || {})) {
+    if (value === undefined || value === null) continue;
+    if (key === "_body") continue;
+    if (pathParamNames.has(key)) {
+      path = path.replace(`{${key}}`, encodeURIComponent(String(value)));
+    } else if (declaredParams.has(key)) {
+      // It's a declared query param
+      queryParams[key] = value;
+    } else {
+      // Everything else goes into body
+      bodyParams[key] = value;
+    }
+  }
+
+  // Build URL with query string
+  const url = new URL(`${API_URL}${path}`);
+  for (const [k, v] of Object.entries(queryParams)) {
+    url.searchParams.set(k, String(v));
+  }
+
+  // Build request
+  const fetchOptions = {
+    method: method.toUpperCase(),
+    headers: {
+      "X-API-KEY": API_KEY,
+      "Accept": "application/json",
+    },
+  };
+
+  // Add body for non-GET methods
+  const hasBody = Object.keys(bodyParams).length > 0 || params?._body;
+  if (hasBody && method !== "get") {
+    fetchOptions.headers["Content-Type"] = "application/json";
+    fetchOptions.body = params?._body || JSON.stringify(bodyParams);
+  }
+
+  const res = await fetch(url.toString(), fetchOptions);
+  const contentType = res.headers.get("content-type") || "";
+
+  if (contentType.includes("application/json")) {
+    const json = await res.json();
+    return { status: res.status, data: json };
+  } else {
+    const text = await res.text();
+    return { status: res.status, data: text.substring(0, 5000) };
+  }
+}
+
+function getOperation(spec, method, path) {
+  return spec.paths?.[path]?.[method];
+}
+
+// ── Main ──
+
+async function main() {
+  console.error(`eSign Launchpad MCP Server starting...`);
+  console.error(`API: ${API_URL}`);
+  console.error(`Spec: ${SPEC_URL}`);
+
+  const spec = await fetchSpec();
+  console.error(`Loaded OpenAPI spec: ${spec.info?.title} ${spec.info?.version}`);
+
+  const server = new McpServer({
+    name: "esign-launchpad",
+    version: "1.0.0",
+  });
+
+  // Register a tool for each API operation
+  let toolCount = 0;
+  for (const [path, pathItem] of Object.entries(spec.paths || {})) {
+    const pathParams = pathItem.parameters || [];
+
+    for (const method of ["get", "post", "put", "patch", "delete"]) {
+      const operation = pathItem[method];
+      if (!operation) continue;
+
+      // Skip operations not in the tenant-api group
+      const tags = operation.tags || [];
+
+      const toolName = buildToolName(method, path, operation);
+      const description = buildDescription(operation, method, path);
+      const inputSchema = buildInputSchema(spec, operation, pathParams);
+
+      server.tool(toolName, description, inputSchema.shape, async (params) => {
+        try {
+          const result = await callApi(method, path, params, spec);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+              },
+            ],
+          };
+        } catch (err) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({ error: err.message }, null, 2),
+              },
+            ],
+            isError: true,
+          };
+        }
+      });
+
+      toolCount++;
+    }
+  }
+
+  console.error(`Registered ${toolCount} tools from OpenAPI spec`);
+
+  // Connect via stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP server connected via stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});