create_embedded_editor
Generate an embedded editor to modify documents or document groups directly within your application for electronic signature workflows.
Instructions
Create embedded editor for editing a document or document group
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ID of the document or document group | |
| entity_type | No | Type of entity: 'document' or 'document_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. | |
| link_expiration | No | Optional link expiration in minutes (15-43200) | |
| redirect_target | No | Optional redirect target: 'self' (default), 'blank' | |
| redirect_uri | No | Optional redirect URI after completion |
Input Schema (JSON Schema)
{
"properties": {
"entity_id": {
"description": "ID of the document or document group",
"title": "Entity Id",
"type": "string"
},
"entity_type": {
"anyOf": [
{
"enum": [
"document",
"document_group"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Type of entity: 'document' or 'document_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.",
"title": "Entity Type"
},
"link_expiration": {
"anyOf": [
{
"maximum": 43200,
"minimum": 15,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional link expiration in minutes (15-43200)",
"title": "Link Expiration"
},
"redirect_target": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional redirect target: 'self' (default), 'blank'",
"title": "Redirect Target"
},
"redirect_uri": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional redirect URI after completion",
"title": "Redirect Uri"
}
},
"required": [
"entity_id"
],
"type": "object"
}
Implementation Reference
- Primary MCP tool handler function for 'create_embedded_editor'. Decorated with @mcp.tool(), handles HTTP headers, token retrieval, client initialization, parameter passing, and calls the core helper _create_embedded_editor.@mcp.tool(name="create_embedded_editor", description="Create embedded editor for editing a document or document group", tags=["edit", "document", "document_group", "embedded"]) def create_embedded_editor( ctx: Context, entity_id: Annotated[str, Field(description="ID of the document or document group")], entity_type: Annotated[ Literal["document", "document_group"] | None, Field(description="Type of entity: 'document' or 'document_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, redirect_uri: Annotated[str | None, Field(description="Optional redirect URI after completion")] = None, redirect_target: Annotated[str | None, Field(description="Optional redirect target: 'self' (default), 'blank'")] = None, link_expiration: Annotated[int | None, Field(ge=15, le=43200, description="Optional link expiration in minutes (15-43200)")] = None, ) -> CreateEmbeddedEditorResponse: """Create embedded editor for editing a document or document group. This tool is ONLY for documents and document groups. If you have template or template group, you have to convert it to document or document group first, using create_from_template tool Args: entity_id: ID of the document or document group entity_type: Type of entity: 'document' or 'document_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. redirect_uri: Optional redirect URI for the editor link redirect_target: Optional redirect target for the editor link link_expiration: Optional number of minutes for the editor link to expire (15-43200) Returns: CreateEmbeddedEditorResponse with editor ID and entity type """ headers = get_http_headers() token = token_provider.get_access_token(headers) if not token: raise ValueError("No access token available") # Initialize client and use the imported function from embedded_editor module client = SignNowAPIClient(token_provider.signnow_config) return _create_embedded_editor(entity_id, entity_type, redirect_uri, redirect_target, link_expiration, token, client)
- Core helper function implementing the embedded editor creation logic. Auto-detects entity type if not provided by querying the API, then delegates to specific document or document_group helpers, constructs and returns CreateEmbeddedEditorResponse.def _create_embedded_editor( entity_id: str, entity_type: Literal["document", "document_group"] | None, redirect_uri: str | None, redirect_target: str | None, link_expiration: int | None, token: str, client: SignNowAPIClient, ) -> CreateEmbeddedEditorResponse: """Private function to create embedded editor for editing a document or document group. Args: entity_id: ID of the document or document group entity_type: Type of entity: 'document' or 'document_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. redirect_uri: Optional redirect URI for the editor link redirect_target: Optional redirect target for the editor link link_expiration: Optional number of minutes for the editor link to expire (15-43200) token: Access token for SignNow API client: SignNow API client instance Returns: CreateEmbeddedEditorResponse with editor ID and entity type """ # Determine entity type if not provided document_group = None # Store document group if found during auto-detection if not entity_type: # Try to determine entity type by attempting to get document group first (higher priority) try: document_group = client.get_document_group(token, entity_id) entity_type = "document_group" except Exception: # If document group not found, try document try: client.get_document(token, entity_id) entity_type = "document" except Exception: raise ValueError(f"Entity with ID {entity_id} not found as either document group or document") from None if entity_type == "document_group": # Create document group embedded editor # Get the document group if we don't have it yet if not document_group: document_group = client.get_document_group(token, entity_id) return _create_document_group_embedded_editor(client, token, entity_id, redirect_uri, redirect_target, link_expiration) else: # Create document embedded editor return _create_document_embedded_editor(client, token, entity_id, redirect_uri, redirect_target, link_expiration)
- Pydantic BaseModel defining the output response schema CreateEmbeddedEditorResponse with editor_entity and editor_url fields.class CreateEmbeddedEditorResponse(BaseModel): """Response model for creating embedded editor.""" editor_entity: str = Field(..., description="Type of editor entity: 'document' or 'document_group'") editor_url: str = Field(..., description="URL for the embedded editor")
- Supporting helper for creating embedded editor specifically for document groups, wrapping the SignNow client call.def _create_document_group_embedded_editor( client: SignNowAPIClient, token: str, entity_id: str, redirect_uri: str | None, redirect_target: str | None, link_expiration: int | None ) -> CreateEmbeddedEditorResponse: """Private function to create document group embedded editor.""" from signnow_client import ( CreateDocumentGroupEmbeddedEditorRequest as SignNowEmbeddedEditorRequest, ) request_data = SignNowEmbeddedEditorRequest(redirect_uri=redirect_uri, redirect_target=redirect_target, link_expiration=link_expiration) response = client.create_document_group_embedded_editor(token, entity_id, request_data) return CreateEmbeddedEditorResponse(editor_entity="document_group", editor_url=response.data.url)
- Supporting helper for creating embedded editor specifically for single documents, wrapping the SignNow client call.def _create_document_embedded_editor( client: SignNowAPIClient, token: str, entity_id: str, redirect_uri: str | None, redirect_target: str | None, link_expiration: int | None ) -> CreateEmbeddedEditorResponse: """Private function to create document embedded editor.""" from signnow_client import CreateDocumentEmbeddedEditorRequest request_data = CreateDocumentEmbeddedEditorRequest(redirect_uri=redirect_uri, redirect_target=redirect_target, link_expiration=link_expiration) response = client.create_document_embedded_editor(token, entity_id, request_data) return CreateEmbeddedEditorResponse(editor_entity="document", editor_url=response.data.url)