--- name: melfina-write-file description: "Write a file to your private file tree (overwrites existing content). Pass `content` for text; pass `content_base64` (+ optional `mime`) for binary — UTF-8 text stays a text file either way. For large binaries prefer PUT /api/files/{path}, which takes raw bytes without base64. (HTTP fallback for the `write_file` Melfina MCP tool.)" --- If the Melfina MCP server is available, use the corresponding MCP tool instead of this skill. Use this skill only as an HTTP fallback when MCP is unavailable. Do not call both MCP and HTTP for the same operation. ## When to use Write a file to your private file tree (overwrites existing content). Pass `content` for text; pass `content_base64` (+ optional `mime`) for binary — UTF-8 text stays a text file either way. For large binaries prefer PUT /api/files/{path}, which takes raw bytes without base64. Use this when your runtime cannot run the Melfina MCP server (no MCP client, or a lightweight/cloud agent) and you need the same operation over plain JSON HTTP. ## Endpoint POST https://melfina.dragonshorn.cloud/api/tools/write_file Content-Type: application/json `GET https://melfina.dragonshorn.cloud/api/tools` lists the whole tool surface with scopes. `melfina-api.json` in this package is the machine-readable manifest. ## Auth Send a Melfina key your runtime injects — credentials never live in this file: Authorization: Bearer $MELFINA_API_KEY Key forms: - `melf_…` dedicated agent key — your persona is included in the key. - `melfs_…` scoped API key — this call needs the `files:write` scope (403 without it; the `all:read` preset covers every read scope and `all:write` every scope). - `melfg_…` fleet key — also name your agent: `"name": ""` in the body, an `X-Melfina-Agent-Key: ` header, or `?agent_key=` in the query (names only). URL-only clients can pin it as the Basic username: `https://:$MELFINA_API_KEY@melfina.dragonshorn.cloud/api/tools/write_file`. ## Request The body is the tool's arguments object — the same shape MCP `tools/call` takes in `params.arguments`: ```json { "properties": { "path": { "description": "Path of the file to write, e.g. \"notes/todo.txt\".", "type": "string" }, "content": { "description": "Full text content to store (replaces existing). Required unless content_base64 is passed.", "type": "string" }, "content_base64": { "description": "Binary content, base64-encoded (replaces existing). Alternative to content for non-text files; bytes over ~1 MB belong on PUT /api/files/{path} instead.", "type": "string" }, "mime": { "description": "Declared content type for content_base64, e.g. \"image/png\". The stored mime always comes from sniffing the actual bytes.", "type": "string" }, "name": { "description": "Your agent name \u2014 your persona on this install. Required when the connection authenticates with the shared fleet key; on a dedicated key it must match that key's agent.", "type": "string" } }, "type": "object", "required": [ "path" ] } ``` ## Response `200 OK` returns `{"ok": true, "result": …, "resultType": "…"}`. `result` is this tool's text payload verbatim (`resultType` is `text`) — file contents stay a string even when they look like JSON. Multi-part results surface as `resultType: "content"` with `result.content` holding the MCP content parts. Errors return `{"ok": false, "error": "…"}` with a non-2xx status: - `401` — no key, an unknown or revoked key, a disabled agent, a fleet key with no persona, or a `name` claim that does not match the key's agent. - `403` — a scoped key (`melfs_…`) lacking the `files:write` scope. - `404` — no such tool. - `422` — invalid arguments; on schema violations `fields` names the offenders. - `429` — too many requests (the endpoint's throttle — the response is the framework's, not the `ok`/`error` envelope). - `400` — a tool-level error — the failure the MCP tool would return as `isError` (for example a not-found file or a rate limit), as the `error` string.