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

src/sn_mcp_server/tools/signnow.py:172-184 (handler)

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)

src/sn_mcp_server/tools/list_documents.py:17-53 (helper)

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)

src/sn_mcp_server/tools/models.py:81-86 (schema)

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")

src/sn_mcp_server/tools/models.py:70-79 (schema)

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")

src/sn_mcp_server/tools/signnow.py:168-171 (helper)

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)

SignNow MCP Server