SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:249-295 (handler)

  MCP tool registration and handler for 'create_embedded_invite'. Decorated with @mcp.tool, processes inputs including orders normalization, retrieves auth token and client, and calls the core helper function.

      name="create_embedded_invite",
      description=(
          "Create embedded invite for signing a document or document group. "
          "This tool is ONLY for documents and document groups. "
          "If you have template or template_group, use the alternative tool: create_embedded_invite_from_template"
      ),
      tags=["send_invite", "document", "document_group", "sign", "embedded", "workflow"],
  )
  def create_embedded_invite(
      ctx: Context,
      entity_id: Annotated[str, Field(description="ID of the document or document group")],
      orders: Annotated[
          list[EmbeddedInviteOrder] | str | None,
          Field(
              description="List of orders with recipients (can be a list or JSON string)",
              examples=[
                  [{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign", "auth_method": "none"}]}],
                  '[{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign", "auth_method": "none"}]}]',
              ],
          ),
      ] = None,
      entity_type: Annotated[
          Literal["document", "document_group"] | None,
          Field(description="Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type."),
      ] = None,
  ) -> CreateEmbeddedInviteResponse:
      """Create embedded invite for signing a document or document group.
  
      This tool is ONLY for documents and document groups.
      If you have template or template_group, use the alternative tool: create_embedded_invite_from_template
  
      Args:
          entity_id: ID of the document or document group
          orders: List of orders with recipients (can be a list or JSON string)
          entity_type: Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type.
  
      Returns:
          CreateEmbeddedInviteResponse with invite ID and entity type
      """
      token, client = _get_token_and_client(token_provider)
  
      # Normalize orders parameter (handle JSON string input)
      normalized_orders = _normalize_orders(orders, EmbeddedInviteOrder)
  
      # Initialize client and use the imported function from embedded_invite module
      return _create_embedded_invite(entity_id, entity_type, normalized_orders, token, client)

• src/sn_mcp_server/tools/models.py:165-171 (schema)

  Output schema: CreateEmbeddedInviteResponse defining the return type of the tool.

  class CreateEmbeddedInviteResponse(BaseModel):
      """Response model for creating embedded invite."""
  
      invite_id: str = Field(..., description="ID of the created embedded invite")
      invite_entity: str = Field(..., description="Type of invite entity: 'document' or 'document_group'")
      recipient_links: list[dict[str, str]] = Field(..., description="Array of objects with role and link for recipients with delivery_type='link'")

• src/sn_mcp_server/tools/models.py:150-155 (schema)

  Input schema component: EmbeddedInviteOrder used for the 'orders' parameter structure.

  class EmbeddedInviteOrder(BaseModel):
      """Order information for embedded invite."""
  
      order: int = Field(..., description="Order number for this step")
      recipients: list[EmbeddedInviteRecipient] = Field(..., description="List of recipients for this order")

• src/sn_mcp_server/tools/embedded_invite.py:134-179 (helper)

  Core helper function implementing the logic to create embedded invite: auto-detects entity type, validates orders, and routes to document or document_group specific helpers which call the SignNow client.

  def _create_embedded_invite(
      entity_id: str, entity_type: Literal["document", "document_group"] | None, orders: list[EmbeddedInviteOrder], token: str, client: SignNowAPIClient
  ) -> CreateEmbeddedInviteResponse:
      """Private function to create embedded invite for signing a document or document group.
  
      Args:
          entity_id: ID of the document or document group
          entity_type: Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type.
          orders: List of orders with recipients
          token: Access token for SignNow API
          client: SignNow API client instance
  
      Returns:
          CreateEmbeddedInviteResponse with invite ID and entity type
      """
      # Determine entity type if not provided
      document_group = None  # Store document group if found during auto-detection
  
      if not entity_type:
          # Try to determine entity type by attempting to get document group first (higher priority)
          try:
              document_group = client.get_document_group(token, entity_id)
              entity_type = "document_group"
          except Exception:
              # If document group not found, try document
              try:
                  client.get_document(token, entity_id)
                  entity_type = "document"
              except Exception:
                  raise ValueError(f"Entity with ID {entity_id} not found as either document group or document") from None
  
      # Validate orders
      if not orders:
          raise ValueError("At least one order with recipients is required")
  
      if entity_type == "document_group":
          # Create document group embedded invite
          # Get the document group if we don't have it yet
          if not document_group:
              document_group = client.get_document_group(token, entity_id)
  
          return _create_document_group_embedded_invite(client, token, entity_id, orders, document_group)
      else:
          # Create document embedded invite
          return _create_document_embedded_invite(client, token, entity_id, orders)

• src/signnow_client/client_document_groups.py:157-189 (helper)

  SignNow API client method called by helpers to create the embedded invite via HTTP POST to the SignNow API.

  def create_embedded_invite(self, token: str, document_group_id: str, request_data: CreateEmbeddedInviteRequest) -> EmbeddedInviteResponse:
      """
      Create embedded signing invite for a document group.
  
      This endpoint allows users to create an embedded signing invite for a document group.
      Once the invite is created, generate an embedded signing link using the invite ID.
  
      Args:
          token: Access token for authentication
          document_group_id: ID of the document group
          request_data: Embedded invite request data with signers and documents
  
      Returns:
          Validated EmbeddedInviteResponse model with the created invite ID
  
      Raises:
          SignNowAPIError: When current user is not the document group owner
          SignNowAPIError: When document group has no document with fields
          SignNowAPIError: When document group has active invites
          SignNowAPIError: When role doesn't exist in the document
          SignNowAPIError: When not all document roles were used
          SignNowAPIError: When document owner's email was used as signer's email
      """
  
      headers = {"Accept": "application/json", "Content-Type": "application/json", "Authorization": f"Bearer {token}"}
  
      return self._post(
          f"/v2/document-groups/{document_group_id}/embedded-invites",
          headers=headers,
          json_data=request_data.model_dump(exclude_none=True),
          validate_model=EmbeddedInviteResponse,
      )