SignNow MCP Server

Instructions

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)