signbee-mcp

Instructions

Implementation Reference

• src/index.ts:55-140 (handler)

  Handler function for send_document tool - makes POST request to SignBee API, handles responses for both verified and unverified senders, and returns formatted success/error messages

  async (params) => {
    try {
      const body: Record<string, unknown> = {
        markdown: params.markdown,
        sender_name: params.sender_name,
        sender_email: params.sender_email,
        recipient_name: params.recipient_name,
        recipient_email: params.recipient_email,
      };
  
      if (params.title) body.title = params.title;
      if (params.expires_in_days) body.expires_in_days = params.expires_in_days;
  
      const headers: Record<string, string> = {
        "Content-Type": "application/json",
      };
  
      if (SIGNBEE_API_KEY) {
        headers["Authorization"] = `Bearer ${SIGNBEE_API_KEY}`;
      }
  
      const response = await fetch(`${SIGNBEE_API_URL}/api/v1/send`, {
        method: "POST",
        headers,
        body: JSON.stringify(body),
      });
  
      const data = await response.json();
  
      if (!response.ok) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error (${response.status}): ${JSON.stringify(data)}`,
            },
          ],
          isError: true,
        };
      }
  
      const status = data.status;
      let summary: string;
  
      if (status === "pending_recipient") {
        summary = [
          `✅ Document sent successfully!`,
          ``,
          `📄 Document ID: ${data.document_id}`,
          `👤 Sender: ${data.sender} (pre-verified via API key)`,
          `📩 Recipient: ${data.recipient}`,
          `⏰ Expires: ${data.expires_at}`,
          ``,
          `The recipient has been emailed a signing link.`,
        ].join("\n");
      } else if (status === "pending_sender") {
        summary = [
          `📧 Verification required`,
          ``,
          `📄 Document ID: ${data.document_id}`,
          `📩 ${data.message}`,
          ``,
          `The sender must verify their email before the document is sent to the recipient.`,
          ``,
          `💡 Tip: Set the SIGNBEE_API_KEY environment variable to skip sender verification.`,
          `   Get your API key at: https://signb.ee/dashboard`,
        ].join("\n");
      } else {
        summary = JSON.stringify(data, null, 2);
      }
  
      return {
        content: [{ type: "text" as const, text: summary }],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Failed to send document: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:20-54 (schema)

  Zod schema defining input validation for send_document tool: markdown content, title (optional), sender/recipient details, and expiration days (optional)

  {
    markdown: z
      .string()
      .min(10)
      .describe(
        "Document content in markdown format. This will be converted to a professional PDF."
      ),
    title: z
      .string()
      .optional()
      .describe(
        "Document title. If omitted, extracted from the first markdown heading."
      ),
    sender_name: z.string().describe("Full name of the document sender"),
    sender_email: z
      .string()
      .email()
      .describe("Email address of the sender"),
    recipient_name: z
      .string()
      .describe("Full name of the document recipient"),
    recipient_email: z
      .string()
      .email()
      .describe("Email address of the recipient"),
    expires_in_days: z
      .number()
      .int()
      .min(1)
      .max(30)
      .optional()
      .describe(
        "Days until the signing link expires. Default: 7"
      ),
  },

• src/index.ts:16-18 (registration)

  Tool registration with server.tool() - registers 'send_document' tool name and description for sending documents for e-signing

  // --- Tool: send_document ---
  server.tool(
    "send_document",