list_document_groups
Retrieve document groups with basic information for organizing and managing e-signature documents using pagination controls.
Instructions
Get simplified list of document groups with basic information
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of document groups to return (default: 50, max: 50) | |
| offset | No | Number of document groups to skip for pagination (default: 0) |
Implementation Reference
- MCP tool handler: decorated function that validates input parameters (limit, offset), retrieves authentication token, and delegates to internal helper for execution.@mcp.tool(name="list_document_groups", description="Get simplified list of document groups with basic information", tags=["document_group", "list"]) def list_document_groups( ctx: Context, limit: Annotated[int, Field(ge=1, le=50, description="Maximum number of document groups to return (default: 50, max: 50)")] = 50, offset: Annotated[int, Field(ge=0, description="Number of document groups to skip for pagination (default: 0)")] = 0, ) -> SimplifiedDocumentGroupsResponse: """Provide simplified list of document groups with basic fields. Args: limit: Maximum number of document groups to return (default: 50, max: 50) offset: Number of document groups to skip for pagination (default: 0) """ headers = get_http_headers() token = token_provider.get_access_token(headers) if not token: raise ValueError("No access token available") # Use the imported function from list_documents module return _list_document_groups(token, token_provider.signnow_config, limit, offset)
- Core helper function: calls SignNow API client.get_document_groups(), processes and simplifies the response data into Pydantic models for the tool output.def _list_document_groups(token: str, signnow_config: SignNowConfig, limit: int = 50, offset: int = 0) -> SimplifiedDocumentGroupsResponse: """Provide simplified list of document groups with basic fields. Args: token: Access token for SignNow API signnow_config: SignNow configuration object limit: Maximum number of document groups to return (default: 50, max: 50) offset: Number of document groups to skip for pagination (default: 0) Returns: SimplifiedDocumentGroupsResponse with document groups """ # Use the client to get document groups - API already applies limit and offset client = SignNowAPIClient(signnow_config) full_response = client.get_document_groups(token, limit=limit, offset=offset) # Convert to simplified models for MCP tools simplified_groups = [] for group in full_response.document_groups: simplified_docs = [] for doc in group.documents: # Use document_name if available, otherwise fallback to document ID document_name = doc.document_name if doc.document_name is not None else doc.id simplified_doc = SimplifiedDocumentGroupDocument(id=doc.id, name=document_name, roles=doc.roles) simplified_docs.append(simplified_doc) simplified_group = SimplifiedDocumentGroup( last_updated=group.last_updated, group_id=group.group_id, group_name=group.group_name, invite_id=group.invite_id, invite_status=group.invite_status, documents=simplified_docs, ) simplified_groups.append(simplified_group) # Use the total count from API response, not the length of current page return SimplifiedDocumentGroupsResponse(document_groups=simplified_groups, document_group_total_count=full_response.document_group_total_count)
- Pydantic model defining the output schema of the list_document_groups tool response, including list of simplified document groups and total count.class SimplifiedDocumentGroupsResponse(BaseModel): """Simplified response for MCP tools with document groups""" document_groups: list[SimplifiedDocumentGroup] document_group_total_count: int = Field(..., description="Total number of document groups")
- Pydantic model for individual simplified document group, used in the tool response.class SimplifiedDocumentGroup(BaseModel): """Simplified document group for MCP tools.""" last_updated: int = Field(..., description="Unix timestamp of the last update") group_id: str = Field(..., description="Document group ID") group_name: str = Field(..., description="Name of the 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[SimplifiedDocumentGroupDocument] = Field(..., description="List of documents in this group")
- Pydantic model for simplified document within a group, used in the tool response.class SimplifiedDocumentGroupDocument(BaseModel): """Simplified document information for MCP tools.""" id: str = Field(..., description="Document ID") name: str = Field(..., description="Document name") roles: list[str] = Field(..., description="Roles defined for this document")