SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:693-721 (handler)

  MCP tool handler for 'get_document'. Defines input schema via Annotated fields and calls internal _get_document_impl. This is the primary execution point registered via @mcp.tool decorator.

      ctx: Context,
      entity_id: Annotated[str, Field(description="ID of the document, template, template group or document group to retrieve")],
      entity_type: Annotated[
          Literal["document", "document_group", "template", "template_group"] | None,
          Field(description="Type of entity: 'document', 'template', 'template_group' or 'document_group' (optional). If not provided, will be determined automatically"),
      ] = None,
  ) -> DocumentGroup:
      """Get full document, template, template group or document group information with field values.
  
      Always returns a unified DocumentGroup wrapper even for a single document.
  
      This tool retrieves complete information about a document, template, template group or document group,
      including all field values, roles, and metadata. If entity_type is not provided,
      the tool will automatically determine whether the entity is a document, template, template group or document group.
  
      For documents, returns a DocumentGroup with a single document.
      For templates, returns a DocumentGroup with a single template.
      For template groups, returns a DocumentGroup with all templates in the group.
      For document groups, returns a DocumentGroup with all documents in the group.
  
      Args:
          entity_id: ID of the document, template, template group or document group to retrieve
          entity_type: Type of entity: 'document', 'template', 'template_group' or 'document_group' (optional)
  
      Returns:
          DocumentGroup with complete information including field values for all documents
      """
      return _get_document_impl(ctx, entity_id, entity_type)

• src/sn_mcp_server/tools/document.py:165-227 (helper)

  Core helper implementing the logic to retrieve and unify document/template/group data into DocumentGroup format, auto-detecting entity type and populating fields by calling sub-helpers.

  def _get_document(client: SignNowAPIClient, token: str, entity_id: str, entity_type: Literal["document", "document_group", "template", "template_group"] | None = None) -> DocumentGroup:
      """
      Get document or document group information with full field values.
  
      This function determines the entity type if not provided and returns
      a DocumentGroup with complete information including field values.
  
      Args:
          client: SignNow API client instance
          token: Access token for authentication
          entity_id: ID of the document or document group
          entity_type: Type of entity: 'document', 'template', 'template_group' or 'document_group' (optional)
  
      Returns:
          DocumentGroup with complete information including field values
  
      Raises:
          ValueError: If entity not found as either document or document group
      """
  
      # Determine entity type if not provided and get entity data
      document_data = None
      template_group_data = None
      group_data = None
  
      if not entity_type:
          # Try to determine entity type by attempting to get document first
          try:
              # Try to get document - if successful, it's a document
              document_data = client.get_document(token, entity_id)
              entity_type = "document"
          except:
              # If document not found, try document group
              try:
                  # Try to get document group - if successful, it's a document group
                  group_data = client.get_document_group_v2(token, entity_id)
                  entity_type = "document_group"
              except:
                  # If document group not found, try template group
                  try:
                      # Try to get template group - if successful, it's a template group
                      template_group_data = client.get_document_group_template(token, entity_id)
                      entity_type = "template_group"
                  except:
                      raise ValueError(f"Entity with ID {entity_id} not found as either document, template, template group or document group")
      else:
          # Entity type is provided, get the entity data
          if entity_type == "document_group":
              group_data = client.get_document_group_v2(token, entity_id)
          if entity_type == "template":
              document_data = client.get_document(token, entity_id)
          if entity_type == "template_group":
              template_group_data = client.get_document_group_template(token, entity_id)
          else:  # entity_type == "document"
              document_data = client.get_document(token, entity_id)
  
      # Get the appropriate data based on determined or provided entity type
      if entity_type == "document_group":
          return _get_full_document_group(client, token, group_data)
      if entity_type == "template_group":
          return _get_full_template_group(client, token, template_group_data)
      else:  # entity_type == "document"
          return _get_single_document_as_group(client, token, entity_id, document_data)

• src/sn_mcp_server/tools/models.py:50-60 (schema)

  Pydantic model defining the output schema DocumentGroup, used as return type. Includes nested DocumentGroupDocument and DocumentField models (lines 31-48, 41-48).

  class DocumentGroup(BaseModel):
      """Document group model with all fields."""
  
      last_updated: int = Field(..., description="Unix timestamp of the last update")
      entity_id: str = Field(..., description="Document group ID")
      group_name: str = Field(..., description="Name of the document group")
      entity_type: str = Field(..., description="Type of entity: 'document' or 'document_group'")
      invite_id: str | None = Field(None, description="Invite ID for this group")
      invite_status: str | None = Field(None, description="Status of the invite (e.g., 'pending')")
      documents: list[DocumentGroupDocument] = Field(..., description="List of documents in this group")

• src/sn_mcp_server/tools/__init__.py:6-8 (registration)

  Tool registration entry point. Calls signnow.bind() which registers all tools including 'get_document' via decorators in signnow.py.

  def register_tools(mcp: Any, cfg: Any) -> None:
      signnow.bind(mcp, cfg)

• src/sn_mcp_server/tools/document.py:50-87 (helper)

  Supporting helper to extract and populate field values from SignNow DocumentResponse into MCP DocumentGroupDocument format.

  def _get_full_document(client: SignNowAPIClient, token: str, document_id: str, document_data: DocumentResponse) -> DocumentGroupDocument:
      """
      Get full document information including field values.
  
      This function retrieves a document with all its metadata and field values.
      The basic information (id, name, roles) comes from the document endpoint,
      while field values are retrieved separately using get_document_fields.
  
      Args:
          client: SignNow API client instance
          token: Access token for authentication
          document_id: ID of the document to retrieve
          document_data: Pre-fetched document data to avoid duplicate API calls
  
      Returns:
          DocumentGroupDocument with complete document information including field values
      """
  
      # Use provided document data
      document_response = document_data
  
      # Create DocumentField objects with values
      document_fields = []
  
      for field in document_response.fields:
          if field.type == "text":
              document_fields.append(
                  DocumentField(
                      id=field.id,
                      type=field.type,
                      role_id=field.role,  # Using role name as role_id for consistency
                      value=field.json_attributes.prefilled_text or "",
                      name=field.json_attributes.name,
                  )
              )
  
      return DocumentGroupDocument(id=document_response.id, name=document_response.document_name, roles=[role.name for role in document_response.roles], fields=document_fields)