SignNow MCP Server

Instructions

Implementation Reference

• src/sn_mcp_server/tools/signnow.py:356-407 (handler)

  Main MCP tool handler for 'send_invite_from_template'. Registers the tool and handles input validation, token retrieval, order normalization, and delegates to the core _send_invite_from_template helper function.
  @mcp.tool( name="send_invite_from_template", description="Create document/group from template and send invite immediately", tags=["template", "template_group", "document", "document_group", "send_invite", "workflow"], ) async def send_invite_from_template( ctx: Context, entity_id: Annotated[str, Field(description="ID of the template or template group")], orders: Annotated[ list[InviteOrder] | str, Field( description="List of orders with recipients for the invite (can be a list or JSON string)", examples=[ [{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}], '[{"order": 1, "recipients": [{"email": "user@example.com", "role": "Signer 1", "action": "sign"}]}]', ], ), ], entity_type: Annotated[ Literal["template", "template_group"] | None, Field(description="Type of entity: 'template' or 'template_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type."), ] = None, name: Annotated[str | None, Field(description="Optional name for the new document or document group")] = None, ) -> SendInviteFromTemplateResponse: """Create document or document group from template and send invite immediately. This tool combines two operations: 1. Creates a document/group from template using create_from_template 2. Sends an invite to the created entity using send_invite Args: entity_id: ID of the template or template group orders: List of orders with recipients for the invite (can be a list or JSON string) entity_type: Type of entity: 'template' or 'template_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. name: Optional name for the new document or document group Returns: SendInviteFromTemplateResponse with created entity info and invite details """ headers = get_http_headers() token = token_provider.get_access_token(headers) if not token: raise ValueError("No access token available") # Normalize orders parameter (handle JSON string input) normalized_orders = _normalize_orders(orders, InviteOrder) # Initialize client and use the imported function from send_invite module client = SignNowAPIClient(token_provider.signnow_config) return await _send_invite_from_template(entity_id, entity_type, name, normalized_orders, token, client, ctx)
• src/sn_mcp_server/tools/send_invite.py:152-194 (helper)

  Core helper function implementing the logic: creates document/group from template using _create_from_template, sends invite using _send_invite, reports progress via MCP context, and returns combined response.
  async def _send_invite_from_template( entity_id: str, entity_type: Literal["template", "template_group"] | None, name: str | None, orders: list[InviteOrder], token: str, client: SignNowAPIClient, ctx: Context ) -> SendInviteFromTemplateResponse: """Private function to create document/group from template and send invite immediately. Args: entity_id: ID of the template or template group entity_type: Type of entity: 'template' or 'template_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. name: Optional name for the new document or document group orders: List of orders with recipients for the invite token: Access token for SignNow API client: SignNow API client instance ctx: FastMCP context for progress reporting Returns: SendInviteFromTemplateResponse with created entity info and invite details """ # Report initial progress await ctx.report_progress(progress=1, total=3) # Import and use the create from template function directly from .create_from_template import _create_from_template # Use the imported function to create from template created_entity = _create_from_template(entity_id, entity_type, name, token, client) # Report progress after template creation await ctx.report_progress(progress=2, total=3) # Then send invite invite_response = _send_invite(created_entity.entity_id, created_entity.entity_type or "document", orders, token, client) # Report final progress after invite sending await ctx.report_progress(progress=3, total=3) return SendInviteFromTemplateResponse( created_entity_id=created_entity.entity_id, created_entity_type=created_entity.entity_type, created_entity_name=created_entity.name, invite_id=invite_response.invite_id, invite_entity=invite_response.invite_entity, )
• src/sn_mcp_server/tools/models.py:223-240 (schema)

  Pydantic schema classes defining the input request (SendInviteFromTemplateRequest) and output response (SendInviteFromTemplateResponse) for the send_invite_from_template tool.
  class SendInviteFromTemplateRequest(BaseModel): """Request model for creating document/group from template and sending invite immediately.""" entity_id: str = Field(..., description="ID of the template or template group") entity_type: str | None = Field(None, description="Type of entity: 'template' or 'template_group' (optional)") name: str | None = Field(None, description="Optional name for the new document or document group") folder_id: str | None = Field(None, description="Optional ID of the folder to store the document group") orders: list[InviteOrder] = Field(default=[], description="List of orders with recipients for the invite") class SendInviteFromTemplateResponse(BaseModel): """Response model for creating document/group from template and sending invite immediately.""" created_entity_id: str = Field(..., description="ID of the created document or document group") created_entity_type: str = Field(..., description="Type of created entity: 'document' or 'document_group'") created_entity_name: str = Field(..., description="Name of the created entity") invite_id: str = Field(..., description="ID of the created invite") invite_entity: str = Field(..., description="Type of invite entity: 'document' or 'document_group'")
• src/sn_mcp_server/tools/signnow.py:52-106 (helper)

  Utility helper function to normalize the 'orders' input parameter, handling lists, JSON strings, dicts, converting to Pydantic InviteOrder models as used in the send_invite_from_template handler.
  def _normalize_orders(orders: Any, order_type: type) -> list[Any]: """Normalize orders parameter - handle both list and JSON string inputs. Args: orders: Input orders - can be a list, JSON string, dict, or None order_type: Type of order model (InviteOrder or EmbeddedInviteOrder) Returns: List of order objects (Pydantic models) """ if orders is None: return [] # If it's already a list, validate and convert items if needed if isinstance(orders, list): result = [] for item in orders: if isinstance(item, order_type): # Already a Pydantic model of the correct type result.append(item) elif isinstance(item, dict): # Convert dict to Pydantic model result.append(order_type(**item)) else: # Try to convert other types result.append(order_type(**item) if hasattr(item, "__dict__") else item) return result # If it's a string, try to parse as JSON if isinstance(orders, str): try: parsed = json.loads(orders) if isinstance(parsed, list): result = [] for item in parsed: if isinstance(item, dict): result.append(order_type(**item)) elif isinstance(item, order_type): result.append(item) else: raise ValueError(f"Invalid order item type in list: {type(item)}") return result elif isinstance(parsed, dict): # Single order object return [order_type(**parsed)] else: raise ValueError(f"Parsed JSON is neither a list nor a dict: {type(parsed)}") except (json.JSONDecodeError, TypeError, ValueError) as e: raise ValueError(f"Invalid orders format: {e}") from e # If it's a dict, wrap in list if isinstance(orders, dict): return [order_type(**orders)] raise ValueError(f"Invalid orders type: {type(orders)}")