upsert_file
Create or update files in shared folders by automatically detecting if a file exists and performing the appropriate operation to write content.
Instructions
Create or update a file in a folder share.
Automatically detects whether the file exists:
Existing file -> updates content (PUT)
New file -> creates file and registers in folder metadata (POST)
This is the recommended way to write files to folder shares.
Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "notes/todo.md"). content: Full text content to write.
Returns: JSON with doc_id, path, length, operation ("created" or "updated").
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| share_id | Yes | ||
| file_path | Yes | ||
| content | Yes |
Implementation Reference
- relay_mcp.py:248-308 (handler)The upsert_file handler function creates or updates a file in a folder share. It first checks if the file exists by listing files, then either PUTs to update or POSTs to create a new file, returning JSON with operation status ('created' or 'updated').@mcp.tool() def upsert_file(share_id: str, file_path: str, content: str) -> str: """Create or update a file in a folder share. Automatically detects whether the file exists: - Existing file -> updates content (PUT) - New file -> creates file and registers in folder metadata (POST) This is the recommended way to write files to folder shares. Args: share_id: UUID of the folder share. file_path: File path within the folder (e.g. "notes/todo.md"). content: Full text content to write. Returns: JSON with doc_id, path, length, operation ("created" or "updated"). """ import json # Check if file exists with _get_client() as client: r = client.get( f"{_get_base_url()}/v1/documents/{share_id}/files", headers=_headers(), params={"share_id": share_id}, ) r.raise_for_status() files_data = r.json() files = files_data.get("files", {}) file_meta = files.get(file_path) existing_doc_id = None if file_meta: existing_doc_id = file_meta.get("id") or file_meta.get("doc_id") if existing_doc_id: # Update existing file with _get_client() as client: r = client.put( f"{_get_base_url()}/v1/documents/{existing_doc_id}/content", headers=_headers(), json={"share_id": share_id, "content": content, "key": "contents"}, ) r.raise_for_status() result = r.json() result["path"] = file_path result["operation"] = "updated" return json.dumps(result) else: # Create new file with _get_client() as client: r = client.post( f"{_get_base_url()}/v1/documents/{share_id}/files", headers=_headers(), json={"share_id": share_id, "path": file_path, "content": content}, ) r.raise_for_status() result = r.json() result["operation"] = "created" return json.dumps(result)
- relay_mcp.py:248-248 (registration)The @mcp.tool() decorator registers the upsert_file function as an MCP tool, making it available to clients through the FastMCP server.@mcp.tool()