SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:338-375 (handler)

  The MCP tool handler function for 'create_embedded_editor'. It handles authentication, parameter validation via type hints, and delegates to the core _create_embedded_editor helper.

      name="create_embedded_editor",
      description=(
          "Create embedded editor for editing 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_editor_from_template"
      ),
      tags=["edit", "document", "document_group", "embedded"],
  )
  def create_embedded_editor(
      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=15, le=43200, description="Optional link expiration in minutes (15-43200)")] = None,
  ) -> CreateEmbeddedEditorResponse:
      """Create embedded editor for editing 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_editor_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 editor link
          redirect_target: Optional redirect target for the editor link
          link_expiration: Optional number of minutes for the editor link to expire (15-43200)
  
      Returns:
          CreateEmbeddedEditorResponse with editor ID and entity type
      """
      token, client = _get_token_and_client(token_provider)
  
      return _create_embedded_editor(entity_id, entity_type, redirect_uri, redirect_target, link_expiration, token, client)

• src/sn_mcp_server/tools/signnow.py:338-375 (registration)

  The @mcp.tool decorator registers this function as the 'create_embedded_editor' tool on the FastMCP server instance.

      name="create_embedded_editor",
      description=(
          "Create embedded editor for editing 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_editor_from_template"
      ),
      tags=["edit", "document", "document_group", "embedded"],
  )
  def create_embedded_editor(
      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=15, le=43200, description="Optional link expiration in minutes (15-43200)")] = None,
  ) -> CreateEmbeddedEditorResponse:
      """Create embedded editor for editing 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_editor_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 editor link
          redirect_target: Optional redirect target for the editor link
          link_expiration: Optional number of minutes for the editor link to expire (15-43200)
  
      Returns:
          CreateEmbeddedEditorResponse with editor ID and entity type
      """
      token, client = _get_token_and_client(token_provider)
  
      return _create_embedded_editor(entity_id, entity_type, redirect_uri, redirect_target, link_expiration, token, client)

• src/sn_mcp_server/tools/embedded_editor.py:48-97 (helper)

  Core helper implementing the embedded editor creation logic: auto-detects entity type (document or document_group), calls specific API methods via SignNow client, and returns formatted response.

  def _create_embedded_editor(
      entity_id: str,
      entity_type: Literal["document", "document_group"] | None,
      redirect_uri: str | None,
      redirect_target: str | None,
      link_expiration: int | None,
      token: str,
      client: SignNowAPIClient,
  ) -> CreateEmbeddedEditorResponse:
      """Private function to create embedded editor for editing 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 editor link
          redirect_target: Optional redirect target for the editor link
          link_expiration: Optional number of minutes for the editor link to expire (15-43200)
          token: Access token for SignNow API
          client: SignNow API client instance
  
      Returns:
          CreateEmbeddedEditorResponse with editor 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":
          # Create document group embedded editor
          # 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_editor(client, token, entity_id, redirect_uri, redirect_target, link_expiration)
      else:
          # Create document embedded editor
          return _create_document_embedded_editor(client, token, entity_id, redirect_uri, redirect_target, link_expiration)

• src/sn_mcp_server/tools/models.py:190-195 (schema)

  Pydantic model defining the output schema for the create_embedded_editor tool response.

  class CreateEmbeddedEditorResponse(BaseModel):
      """Response model for creating embedded editor."""
  
      editor_entity: str = Field(..., description="Type of editor entity: 'document' or 'document_group'")
      editor_url: str = Field(..., description="URL for the embedded editor")