list_document_groups
Retrieve a paginated list of document groups with basic details from SignNow for e-signature workflows.
Instructions
Get simplified list of document groups with basic information.
Note: If your client supports MCP Resources, prefer the resource version of this endpoint; this tool exists as a compatibility fallback for tool-only clients.
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
- Primary MCP tool handler for 'list_document_groups'. Includes @mcp.tool registration decorator, input parameter schemas with validation, and delegation to implementation.@mcp.tool(name="list_document_groups", description="Get simplified list of document groups with basic information." + TOOL_FALLBACK_SUFFIX, 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) """ return _list_document_groups_impl(ctx, limit, offset)
- Core helper function implementing the logic to fetch document groups via SignNow API client and simplify the response into MCP-compatible models.def _list_document_groups(token: str, client: SignNowAPIClient, 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 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 for the list_document_groups tool.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 simplified document group structure 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")
- Intermediate helper that obtains auth token/client and calls the core list_documents helper.def _list_document_groups_impl(ctx: Context, limit: int = 50, offset: int = 0) -> SimplifiedDocumentGroupsResponse: token, client = _get_token_and_client(token_provider) return _list_document_groups(token, client, limit, offset)