SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:297-336 (handler)

  MCP tool handler for 'create_embedded_sending': decorated function that authenticates, calls helper, returns CreateEmbeddedSendingResponse

      name="create_embedded_sending",
      description=(
          "Create embedded sending for managing, editing, or sending invites for 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_sending_from_template"
      ),
      tags=["edit", "document", "document_group", "send_invite", "embedded", "workflow"],
  )
  def create_embedded_sending(
      ctx: Context,
      entity_id: Annotated[str, Field(description="ID of the document or document group")],
      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,
      redirect_uri: Annotated[str | None, Field(description="Optional redirect URI after completion")] = None,
      redirect_target: Annotated[str | None, Field(description="Optional redirect target: 'self' (default), 'blank'")] = None,
      link_expiration: Annotated[int | None, Field(ge=14, le=45, description="Optional link expiration in days (14-45)")] = None,
      type: Annotated[Literal["manage", "edit", "send-invite"] | None, Field(description="Type of sending step: 'manage', 'edit', or 'send-invite'")] = "manage",
  ) -> CreateEmbeddedSendingResponse:
      """Create embedded sending for managing, editing, or sending invites for 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_sending_from_template
  
      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.
          redirect_uri: Optional redirect URI for the sending link
          redirect_target: Optional redirect target for the sending link
          link_expiration: Optional number of days for the sending link to expire (14-45)
          type: Specifies the sending step: 'manage' (default), 'edit', 'send-invite'
  
      Returns:
          CreateEmbeddedSendingResponse with entity type, and URL
      """
      token, client = _get_token_and_client(token_provider)
  
      return _create_embedded_sending(entity_id, entity_type, redirect_uri, redirect_target, link_expiration, type, token, client)

• src/sn_mcp_server/tools/embedded_sending.py:54-105 (helper)

  Core helper implementing the logic: auto-detects entity type (document or document_group), delegates to type-specific helpers, constructs response

  def _create_embedded_sending(
      entity_id: str,
      entity_type: Literal["document", "document_group"] | None,
      redirect_uri: str | None,
      redirect_target: str | None,
      link_expiration: int | None,
      sending_type: str | None,
      token: str,
      client: SignNowAPIClient,
  ) -> CreateEmbeddedSendingResponse:
      """Private function to create embedded sending for managing, editing, or sending invites for 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.
          redirect_uri: Optional redirect URI for the sending link
          redirect_target: Optional redirect target for the sending link
          link_expiration: Optional number of days for the sending link to expire (14-45)
          sending_type: Specifies the sending step: 'manage' (default), 'edit', 'send-invite'
          token: Access token for SignNow API
          client: SignNow API client instance
  
      Returns:
          CreateEmbeddedSendingResponse with entity type and URL
      """
      # 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":
          # Create document group embedded sending
          # 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_sending(client, token, entity_id, redirect_uri, redirect_target, link_expiration, sending_type)
      else:
          # Create document embedded sending
          return _create_document_embedded_sending(client, token, entity_id, redirect_uri, redirect_target, link_expiration, sending_type)

• src/sn_mcp_server/tools/embedded_sending.py:35-52 (helper)

  Document-specific helper calling SignNow client.create_document_embedded_sending

  def _create_document_embedded_sending(
      client: SignNowAPIClient, token: str, entity_id: str, redirect_uri: str | None, redirect_target: str | None, link_expiration: int | None, sending_type: str | None
  ) -> CreateEmbeddedSendingResponse:
      """Private function to create document embedded sending."""
      from signnow_client import CreateDocumentEmbeddedSendingRequest
  
      # Map sending type to entity type for documents BEFORE making the request
      if sending_type == "send-invite":
          mapped_type = "invite"
      else:  # manage or edit
          mapped_type = "document"
  
      request_data = CreateDocumentEmbeddedSendingRequest(redirect_uri=redirect_uri, redirect_target=redirect_target, link_expiration=link_expiration, type=mapped_type)
  
      response = client.create_document_embedded_sending(token, entity_id, request_data)
  
      return CreateEmbeddedSendingResponse(sending_entity="document", sending_url=response.data.url)

• src/sn_mcp_server/tools/embedded_sending.py:20-33 (helper)

  Document group-specific helper calling SignNow client.create_document_group_embedded_sending

  def _create_document_group_embedded_sending(
      client: SignNowAPIClient, token: str, entity_id: str, redirect_uri: str | None, redirect_target: str | None, link_expiration: int | None, sending_type: str | None
  ) -> CreateEmbeddedSendingResponse:
      """Private function to create document group embedded sending."""
      from signnow_client import (
          CreateDocumentGroupEmbeddedSendingRequest as SignNowEmbeddedSendingRequest,
      )
  
      request_data = SignNowEmbeddedSendingRequest(redirect_uri=redirect_uri, redirect_target=redirect_target, link_expiration=link_expiration, type=sending_type)
  
      response = client.create_document_group_embedded_sending(token, entity_id, request_data)
  
      return CreateEmbeddedSendingResponse(sending_entity="document_group", sending_url=response.data.url)

• src/sn_mcp_server/tools/models.py:215-220 (schema)

  Pydantic model for tool response: sending_entity and sending_url

  class CreateEmbeddedSendingResponse(BaseModel):
      """Response model for creating embedded sending."""
  
      sending_entity: str = Field(..., description="Type of sending entity: 'document', 'document_group', or 'invite'")
      sending_url: str = Field(..., description="URL for the embedded sending")