get_document
Retrieve complete document or document group information including field values from SignNow e-signature platform using document ID.
Instructions
Get full document or document group information with field values
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ID of the document or document group to retrieve | |
| entity_type | No | Type of entity: 'document' or 'document_group' (optional). If not provided, will be determined automatically |
Input Schema (JSON Schema)
{
"properties": {
"entity_id": {
"description": "ID of the document or document group to retrieve",
"title": "Entity Id",
"type": "string"
},
"entity_type": {
"anyOf": [
{
"enum": [
"document",
"document_group"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Type of entity: 'document' or 'document_group' (optional). If not provided, will be determined automatically",
"title": "Entity Type"
}
},
"required": [
"entity_id"
],
"type": "object"
}
Implementation Reference
- src/sn_mcp_server/tools/signnow.py:609-651 (registration)Registration of the 'get_document' MCP tool with @mcp.tool decorator, including input schema via Annotated Fields and thin handler that obtains auth token and calls core _get_document helper.@mcp.tool( name="get_document", description="Get full document, template, template group or document group information with field values", tags=["document", "document_group", "template", "template_group", "get", "fields"], ) def get_document( 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 """ headers = get_http_headers() token = token_provider.get_access_token(headers) if not token: raise ValueError("No access token available") # Initialize client and use the imported function from document module client = SignNowAPIClient(token_provider.signnow_config) return _get_document(client, token, entity_id, entity_type)
- Core handler logic for the get_document tool: auto-detects or uses provided entity_type to fetch appropriate data via SignNow client APIs (get_document, get_document_group_v2, get_document_group_template), constructs and returns unified DocumentGroup response.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)
- Primary output schema (Pydantic model) for get_document tool: DocumentGroup defining unified structure for single/group documents/templates with fields, roles, metadata.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")
- Helper function to extract and construct DocumentGroupDocument from raw SignNow document response, including parsing text fields with values.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)
- Helper to fetch and aggregate full details for all documents in a document_group, calling get_document and _get_full_document for each.def _get_full_document_group(client: SignNowAPIClient, token: str, group_data: GetDocumentGroupV2Response) -> DocumentGroup: """ Get full document group information including all documents with their field values. This function retrieves a document group using v2 API and for each document in the group, gets the complete document information including field values. Args: client: SignNow API client instance token: Access token for authentication document_group_id: ID of the document group to retrieve group_data: Pre-fetched group data to avoid duplicate API calls Returns: DocumentGroup with complete information including all documents with field values """ # Use provided group data group_data = group_data.data # Get full document information for each document in the group full_documents = [] for doc in group_data.documents: # Get document data first document_data = client.get_document(token, doc.id) full_doc = _get_full_document(client=client, token=token, document_id=doc.id, document_data=document_data) full_documents.append(full_doc) # Create DocumentGroup with full document information return DocumentGroup( last_updated=group_data.created, # Use created timestamp as last_updated entity_id=group_data.id, group_name=group_data.name, entity_type="document_group", invite_id=group_data.invite_id, invite_status=group_data.state, # Use state as invite_status documents=full_documents, )