SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:201-247 (handler)

  The primary handler function for the 'send_invite' MCP tool. It handles input normalization, retrieves authentication token and client, and delegates to the _send_invite helper function to execute the core logic.

      name="send_invite",
      description=(
          "Send invite to sign 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: send_invite_from_template"
      ),
      tags=["send_invite", "document", "document_group", "sign", "workflow"],
  )
  def send_invite(
      ctx: Context,
      entity_id: Annotated[str, Field(description="ID of the document or document group")],
      orders: Annotated[
          list[InviteOrder] | 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"}]}],
                  '[{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}]',
              ],
          ),
      ] = 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,
  ) -> SendInviteResponse:
      """Send invite to sign 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: send_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:
          SendInviteResponse 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, InviteOrder)
  
      # Initialize client and use the imported function from send_invite module
      return _send_invite(entity_id, entity_type, normalized_orders, token, client)

• src/sn_mcp_server/tools/signnow.py:201-247 (registration)

  The @mcp.tool decorator that registers the 'send_invite' tool with FastMCP, including name, description, tags, and input parameters.

      name="send_invite",
      description=(
          "Send invite to sign 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: send_invite_from_template"
      ),
      tags=["send_invite", "document", "document_group", "sign", "workflow"],
  )
  def send_invite(
      ctx: Context,
      entity_id: Annotated[str, Field(description="ID of the document or document group")],
      orders: Annotated[
          list[InviteOrder] | 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"}]}],
                  '[{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}]',
              ],
          ),
      ] = 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,
  ) -> SendInviteResponse:
      """Send invite to sign 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: send_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:
          SendInviteResponse 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, InviteOrder)
  
      # Initialize client and use the imported function from send_invite module
      return _send_invite(entity_id, entity_type, normalized_orders, token, client)

• src/sn_mcp_server/tools/models.py:117-122 (schema)

  Pydantic model for the response of the send_invite tool.

  class SendInviteResponse(BaseModel):
      """Response model for sending invite."""
  
      invite_id: str = Field(..., description="ID of the created invite")
      invite_entity: str = Field(..., description="Type of invite entity: 'document' or 'document_group'")

• src/sn_mcp_server/tools/models.py:110-116 (schema)

  Pydantic model for invite orders used as input to send_invite.

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

• src/sn_mcp_server/tools/send_invite.py:110-150 (helper)

  Core helper function implementing the send invite logic, including entity type detection, and delegating to document-specific or document group-specific invite functions.

  def _send_invite(entity_id: str, entity_type: Literal["document", "document_group"] | None, orders: list[InviteOrder], token: str, client: SignNowAPIClient) -> SendInviteResponse:
      """Private function to send invite to sign 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:
          SendInviteResponse 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
  
      if entity_type == "document_group":
          # Send document group field 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 _send_document_group_field_invite(client, token, entity_id, orders, document_group)
      else:
          # Send document field invite
          return _send_document_field_invite(client, token, entity_id, orders)