SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:376-403 (handler)

  Handler function decorated with @mcp.tool for registration of 'create_from_template'. Executes the tool by getting auth token/client and delegating to helper _create_from_template.

  @mcp.tool(
      name="create_from_template",
      description="Create a new document or document group from an existing template or template group",
      tags=["template", "template_group", "document", "document_group", "create", "workflow"],
  )
  def create_from_template(
      ctx: Context,
      entity_id: Annotated[str, Field(description="ID of the template or template group")],
      entity_type: Annotated[
          Literal["template", "template_group"] | None,
          Field(description="Type of entity: 'template' or 'template_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,
      name: Annotated[str | None, Field(description="Optional name for the new document group or document (required for template groups)")] = None,
  ) -> CreateFromTemplateResponse:
      """Create a new document or document group from an existing template or template group.
  
      Args:
          entity_id: ID of the template or template group
          entity_type: Type of entity: 'template' or 'template_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.
          name: Optional name for the new document group or document (required for template groups)
  
      Returns:
          CreateFromTemplateResponse with created entity ID, type and name
      """
      token, client = _get_token_and_client(token_provider)
  
      return _create_from_template(entity_id, entity_type, name, token, client)

• src/sn_mcp_server/tools/models.py:358-364 (schema)

  Pydantic response schema for the create_from_template tool.

  class CreateFromTemplateResponse(BaseModel):
      """Response model for creating document/group from template."""
  
      entity_id: str = Field(..., description="ID of the created document or document group")
      entity_type: str = Field(..., description="Type of created entity: 'document' or 'document_group'")
      name: str = Field(..., description="Name of the created entity")

• src/sn_mcp_server/tools/create_from_template.py:81-128 (helper)

  Main helper function implementing the core logic: determines entity type, handles name resolution, and calls specific creation functions for document or document group from template.

  def _create_from_template(entity_id: str, entity_type: Literal["template", "template_group"] | None, name: str | None, token: str, client: SignNowAPIClient) -> CreateFromTemplateResponse:
      """Private function to create a new document or document group from an existing template or template group.
  
      Args:
          entity_id: ID of the template or template group
          entity_type: Type of entity: 'template' or 'template_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.
          name: Optional name for the new document group or document (required for template groups)
          token: Access token for SignNow API
          client: SignNow API client instance
  
      Returns:
          CreateFromTemplateResponse with created entity ID, type and name
      """
  
      # Find template group if needed (for entity type detection or name extraction)
      found_template_group = None
      if not entity_type:
          found_template_group = _find_template_group(entity_id, token, client)
  
      # Determine entity type if not provided
      if not entity_type:
          if found_template_group:
              entity_type = "template_group"
          else:
              entity_type = "template"
  
      if entity_type == "template_group":
          # If name is not provided, try to get it from found_template_group
          if name is None:
              if found_template_group:
                  # Use name from found template group
                  name = found_template_group.template_group_name
              else:
                  # found_template_group was not found, get it by ID to extract name
                  found_template_group = _find_template_group(entity_id, token, client)
                  if found_template_group:
                      # Use name from found template group
                      name = found_template_group.template_group_name
                  else:
                      # Get template group by ID to extract name (more reliable method)
                      template_group_data = client.get_document_group_template(token, entity_id)
                      name = template_group_data.group_name
  
          return _create_document_group_from_template(client, token, entity_id, name)
      else:
          # Create document from template
          return _create_document_from_template(client, token, entity_id, name)

• src/sn_mcp_server/tools/create_from_template.py:15-31 (helper)

  Helper to create a single document from a template using SignNow API.

  def _create_document_from_template(client: SignNowAPIClient, token: str, entity_id: str, name: str | None) -> CreateFromTemplateResponse:
      """Private function to create document from template."""
      from signnow_client import CreateDocumentFromTemplateRequest
  
      # Prepare request data
      request_data = None
      if name:
          request_data = CreateDocumentFromTemplateRequest(document_name=name)
  
      # Create document from template
      response = client.create_document_from_template(token, entity_id, request_data)
  
      # Use provided name or fallback to response document_name or entity_id
      document_name = name or getattr(response, "document_name", None) or f"Document_{response.id[:8]}"
  
      return CreateFromTemplateResponse(entity_id=response.id, entity_type="document", name=document_name)

• src/sn_mcp_server/tools/create_from_template.py:33-58 (helper)

  Helper to create a document group from a template group using SignNow API.

  def _create_document_group_from_template(client: SignNowAPIClient, token: str, entity_id: str, name: str) -> CreateFromTemplateResponse:
      """Private function to create document group from template group."""
      from signnow_client import CreateDocumentGroupFromTemplateRequest
  
      if not name:
          raise ValueError("name is required when creating document group from template group")
  
      # Prepare request data
      request_data = CreateDocumentGroupFromTemplateRequest(group_name=name)
  
      # Create document group from template group
      response = client.create_document_group_from_template(token, entity_id, request_data)
  
      # Extract document group ID from response data
      response_data = response.data
      if isinstance(response_data, dict) and "unique_id" in response_data:
          created_id = response_data["unique_id"]
      elif isinstance(response_data, dict) and "id" in response_data:
          created_id = response_data["id"]
      elif isinstance(response_data, dict) and "group_id" in response_data:
          created_id = response_data["group_id"]
      else:
          created_id = str(response_data.get("id", response_data.get("group_id", "unknown")))
  
      return CreateFromTemplateResponse(entity_id=created_id, entity_type="document_group", name=name)