{ "$schema": "https://webmcp.org/schemas/model-context-v1.json", "name": "FlatWrite Render — Docs", "version": "1.0.0", "surfaceMode": "doc", "status": "ready", "handlers": [ { "url": "https://mcp.flatwrite.md/mcp", "transport": "streamable-http", "method": "POST", "headers": { "Content-Type": "application/json", "Accept": "application/json, text/event-stream" }, "authNote": "MCP Streamable HTTP transport. Server-to-server callers (no Origin header) can use X-Api-Key. Browser callers MUST mint a short-lived X-Mcp-Token from https://render.flatwrite.md/mcp-token first." }, { "url": "https://render.flatwrite.md/render", "transport": "http", "method": "POST", "headers": { "Content-Type": "application/json", "X-Api-Key": "" }, "authNote": "Browser clients mint a short-lived X-Mcp-Token from https://render.flatwrite.md/mcp-token first. Server-to-server clients may use X-Api-Key directly." } ], "tools": [ { "name": "render_markdown", "description": "Render markdown into FlatWrite-styled HTML and fragments, with optional typography and page-layout controls. Provide either the raw markdown inline (`markdown`) or an allowlisted URL (`markdownUrl`) pointing to raw markdown content. Use this when you need the rendered HTML artifacts.", "category": "render", "inputSchema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Raw markdown content to render." }, "markdownUrl": { "type": "string", "description": "URL pointing to raw markdown content. Must be on an allowlisted host (raw.githubusercontent.com, raw.gitlab.com, bitbucket.org), http(s) only, and <=1 MB. Host validation is enforced server-side." }, "font": { "type": "string", "description": "Font family — must be a bundled family.", "enum": [ "Inter", "JetBrains Mono", "Lato", "Lora", "Merriweather", "Playfair Display", "Comfortaa", "Unbounded" ] }, "appFramework": { "type": "string", "description": "UI framework applied when surfaceMode=\"app\".", "enum": [ "spectre", "poshui", "pico", "milligram", "chota" ] }, "size": { "oneOf": [ { "type": "string", "description": "Scale token (e.g. \"-1\", \"0\", \"1\")" }, { "type": "number", "description": "Absolute pixel value (8..72)" } ], "description": "Font size as a scale token (e.g. \"-1\", \"0\", \"1\").", "minimum": 8, "maximum": 72 }, "weight": { "oneOf": [ { "type": "string", "description": "Scale token (e.g. \"-1\", \"0\")" }, { "type": "number", "description": "Absolute weight (100..900, multiples of 100)" } ], "description": "Font weight as a scale token (e.g. \"-1\", \"0\").", "minimum": 100, "maximum": 900 }, "line": { "oneOf": [ { "type": "string", "description": "Scale token (e.g. \"-1\", \"0\", \"1\")" }, { "type": "number", "description": "Absolute multiplier (0.8..4.0)" } ], "description": "Line height as a scale token (e.g. \"-1\", \"0\", \"1\").", "minimum": 0.8, "maximum": 4 }, "uiZoom": { "type": "number", "description": "UI zoom level (1.0 = default; >1 zooms in, <1 zooms out).", "minimum": 0.25, "maximum": 4 }, "pageSize": { "type": "string", "description": "Page size for paged output. Only effective when docEngine is pagedjs or vivliostyle.", "enum": [ "A0", "A1", "A2", "A3", "A4", "A5", "Letter", "Legal" ] }, "orientation": { "type": "string", "description": "Page orientation.", "enum": [ "portrait", "landscape" ] }, "marginsLR": { "type": "string", "description": "Left/right page margin preset. Only effective when docEngine is pagedjs or vivliostyle.", "enum": [ "narrow", "normal", "wide" ] }, "marginsTB": { "type": "string", "description": "Top/bottom page margin preset. Only effective when docEngine is pagedjs or vivliostyle.", "enum": [ "narrow", "normal", "wide" ] }, "footer": { "type": "boolean", "description": "Include a page-number footer in paged output." }, "width": { "type": "number", "description": "Content width in pixels (400..1400). Only effective when docEngine=\"none\".", "minimum": 400, "maximum": 1400 }, "docEngine": { "type": "string", "description": "Document engine — \"none\" emits plain CSS; \"pagedjs\"/\"vivliostyle\" wrap the output in @page rules.", "enum": [ "none", "pagedjs", "vivliostyle" ] }, "surfaceMode": { "type": "string", "description": "Surface mode hint. \"app\" unlocks the appFramework picker; otherwise this is metadata only.", "enum": [ "doc", "app" ] }, "theme": { "type": "string", "description": "Theme identifier rendered as body[data-theme=\"...\"] so consumer CSS can theme via attribute selectors. Free-form (alphanumeric, dash, underscore) — common values are \"light\" and \"dark\"." } }, "required": [], "oneOf": [ { "required": [ "markdown" ] }, { "required": [ "markdownUrl" ] } ] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "description": "True on successful render." }, "kind": { "type": "string", "enum": [ "html" ], "description": "Output format — always \"html\" for render tools." }, "document": { "type": "object", "properties": { "title": { "description": "Best-effort title extracted from the first H1 heading.", "type": "string" }, "wordCount": { "description": "Approximate word count of source markdown.", "type": "number" }, "charCount": { "description": "Character count of source markdown.", "type": "number" } }, "additionalProperties": false }, "artifacts": { "type": "object", "properties": { "head": { "type": "string", "description": "Self-contained fragment." }, "body": { "type": "string", "description": "Self-contained fragment." } }, "required": [ "head", "body" ], "additionalProperties": false }, "warnings": { "description": "Non-fatal warnings.", "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "kind", "artifacts" ], "additionalProperties": false, "description": "Rendered markdown as self-contained HTML fragments with document metadata." }, "annotations": { "readOnlyHint": true }, "displayHints": { "inputFieldAliases": { "font": "fontFamily", "appFramework": "framework", "size": "fontSize", "weight": "fontWeight", "line": "lineHeight" } } }, { "name": "list_render_options", "description": "Return the supported fonts, UI frameworks, document engines, page sizes, orientations, margins, and surface modes for the render_markdown tool. Call this before rendering if you need to know which enum values are valid; call render_markdown when you have the options and are ready to render.", "category": "discovery", "inputSchema": { "type": "object", "properties": {}, "required": [] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true for successful options listing." }, "options": { "type": "object", "properties": { "fonts": { "type": "array", "items": { "type": "string" }, "description": "Bundled font families that can be passed as fontFamily." }, "frameworks": { "type": "array", "items": { "type": "string" }, "description": "UI frameworks that can be passed as framework when surfaceMode is \"app\"." }, "docEngines": { "type": "array", "items": { "type": "string" }, "description": "Document engines that can be passed as docEngine." }, "pageSizes": { "type": "array", "items": { "type": "string" }, "description": "Page size presets that can be passed as pageSize." }, "orientations": { "type": "array", "items": { "type": "string" }, "description": "Page orientations that can be passed as orientation." }, "margins": { "type": "array", "items": { "type": "string" }, "description": "Page margin presets that can be passed as marginsLR or marginsTB." }, "surfaceModes": { "type": "array", "items": { "type": "string" }, "description": "Surface mode hints that can be passed as surfaceMode." } }, "required": [ "fonts", "frameworks", "docEngines", "pageSizes", "orientations", "margins", "surfaceModes" ], "additionalProperties": false, "description": "Supported enum values for each render option category." }, "defaults": { "description": "Default values used when an option is omitted.", "type": "object", "properties": { "font": { "description": "Default font family.", "type": "string" }, "docEngine": { "description": "Default document engine.", "type": "string" }, "surfaceMode": { "description": "Default surface mode.", "type": "string" }, "pageSize": { "description": "Default page size.", "type": "string" }, "orientation": { "description": "Default orientation.", "type": "string" } }, "additionalProperties": false } }, "required": [ "ok", "options" ], "additionalProperties": false, "description": "Supported values for the render_markdown tool, wrapped in a typed envelope." }, "annotations": { "readOnlyHint": true }, "displayHints": { "inputFieldAliases": {} } }, { "name": "get_document_state", "description": "Return the current state of the active document in the FlatWrite editor: title, word count, render mode, unsaved changes flag, and available export formats. Use this before export or share tools to check readiness; use update_document_content to change the content.", "category": "lifecycle", "inputSchema": { "type": "object", "properties": {}, "required": [] }, "outputSchema": { "type": "object", "title": "DocumentStateOutput", "description": "Current state of the active document in the FlatWrite editor.", "required": [ "ok", "documentId", "title", "wordCount", "unsavedChanges", "url" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documentId": { "type": "string", "description": "Stable identifier for the active document." }, "title": { "type": "string", "description": "Best-effort title from the first H1 or document URL." }, "wordCount": { "type": "number", "description": "Approximate word count of the current markdown." }, "charCount": { "type": "number", "description": "Character count of the current markdown." }, "unsavedChanges": { "type": "boolean", "description": "Whether the editor content differs from the last loaded/saved state." }, "renderMode": { "type": "string", "enum": [ "edit", "preview", "read" ], "description": "Current editor mode." }, "docEngine": { "type": "string", "enum": [ "none", "pagedjs", "vivliostyle" ], "description": "Active document engine." }, "surfaceMode": { "type": "string", "enum": [ "doc", "app" ], "description": "Active surface mode." }, "url": { "type": "string", "description": "Canonical URL of the current document (share URL or source URL, empty if new)." }, "availableExports": { "type": "array", "items": { "type": "string", "enum": [ "html", "pdf", "markdown" ] }, "description": "Export formats available for the current document." }, "canShare": { "type": "boolean", "description": "Whether the document is small enough to share via URL." } } }, "annotations": { "readOnlyHint": true }, "displayHints": { "inputFieldAliases": {} } }, { "name": "create_document", "description": "Create a new blank document in the FlatWrite editor, optionally with initial markdown content. Use this to start a new document; use open_document to load an existing one from a URL or share link.", "category": "lifecycle", "inputSchema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Optional initial markdown content for the new document." }, "title": { "type": "string", "description": "Optional title for the new document." } }, "required": [] }, "outputSchema": { "type": "object", "title": "CreateDocumentOutput", "description": "Result of creating a new document.", "required": [ "ok", "documentId", "title", "url" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documentId": { "type": "string", "description": "Stable identifier for the new document." }, "title": { "type": "string", "description": "Title of the new document." }, "url": { "type": "string", "description": "URL of the new document (empty for a blank document)." }, "nextSuggestedTool": { "type": "string", "description": "Suggested next tool to call (e.g. update_document_content)." } } }, "annotations": { "readOnlyHint": false }, "displayHints": { "inputFieldAliases": {} } }, { "name": "open_document", "description": "Open an existing document from a URL or share link in the FlatWrite editor. Use this to load a remote markdown file or a previously shared document; use create_document to start blank.", "category": "lifecycle", "inputSchema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the markdown file or FlatWrite share link to open." } }, "required": [ "url" ] }, "outputSchema": { "type": "object", "title": "OpenDocumentOutput", "description": "Result of opening an existing document.", "required": [ "ok", "documentId", "title", "url", "active" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documentId": { "type": "string", "description": "Stable identifier for the opened document." }, "title": { "type": "string", "description": "Title of the opened document." }, "url": { "type": "string", "description": "URL of the opened document." }, "active": { "type": "boolean", "description": "Whether the document is now the active document in the editor." }, "nextSuggestedTool": { "type": "string", "description": "Suggested next tool to call (e.g. get_document_state)." } } }, "annotations": { "readOnlyHint": false }, "displayHints": { "inputFieldAliases": {} } }, { "name": "update_document_content", "description": "Update the markdown content of the active document in the FlatWrite editor. Use this to edit the document programmatically; use get_document_state to inspect the result.", "category": "lifecycle", "inputSchema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "New markdown content for the document." } }, "required": [ "markdown" ] }, "outputSchema": { "type": "object", "title": "UpdateDocumentOutput", "description": "Result of updating document content.", "required": [ "ok", "documentId", "updatedAt", "stateVersion" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documentId": { "type": "string", "description": "Stable identifier for the updated document." }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp of the update." }, "stateVersion": { "type": "number", "description": "Monotonic revision number for optimistic concurrency." }, "nextSuggestedTool": { "type": "string", "description": "Suggested next tool to call (e.g. render_markdown_preview)." } } }, "annotations": { "readOnlyHint": false }, "displayHints": { "inputFieldAliases": {} } }, { "name": "list_recent_documents", "description": "Return a list of recently opened documents from the editor session. Use this to discover what the user has been working on; use open_document to load one.", "category": "lifecycle", "inputSchema": { "type": "object", "properties": {}, "required": [] }, "outputSchema": { "type": "object", "title": "ListRecentDocumentsOutput", "description": "List of recently opened documents.", "required": [ "ok", "documents" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "documentId": { "type": "string", "description": "Stable identifier for the document." }, "title": { "type": "string", "description": "Best-effort title." }, "url": { "type": "string", "description": "Source URL or share URL." }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp of last modification." } } }, "description": "Recent documents, most recent first." } } }, "annotations": { "readOnlyHint": true }, "displayHints": { "inputFieldAliases": {} } }, { "name": "render_markdown_preview", "description": "Triggers the editor's built-in preview pane. No HTML is returned — this tool produces a visual side-effect only. Agents that need HTML output must use render_markdown instead.", "category": "render", "inputSchema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Optional markdown to preview. If omitted, previews the current editor content." } }, "required": [] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "kind": { "type": "string", "enum": [ "preview" ], "description": "Result modality — always \"preview\"." }, "documentId": { "description": "Stable identifier for the previewed document.", "type": "string" }, "warnings": { "description": "Non-fatal warnings.", "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "kind" ], "additionalProperties": false, "description": "Result of rendering markdown into the editor preview pane." }, "annotations": { "readOnlyHint": false }, "displayHints": { "inputFieldAliases": {} } }, { "name": "export_document_html", "description": "Export the active document as a self-contained HTML file. The export opens in a new browser tab for human users. Completes synchronously. Use export_document_pdf for print-ready output.", "category": "export", "inputSchema": { "type": "object", "properties": {}, "required": [] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documentId": { "type": "string", "description": "Stable identifier for the exported document." }, "format": { "type": "string", "enum": [ "html" ], "description": "Export format — always \"html\"." }, "downloadUrl": { "description": "Blob URL of the exported HTML (temporary, valid for the session).", "type": "string" }, "warnings": { "description": "Non-fatal warnings.", "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "documentId", "format" ], "additionalProperties": false, "description": "Result of exporting the document as HTML." }, "annotations": { "readOnlyHint": false }, "displayHints": { "inputFieldAliases": {} } }, { "name": "export_document_pdf", "description": "Export the active document as a PDF by triggering the browser print dialog with the rendered preview. Completes synchronously. The print dialog opens for human users. Use export_document_html for a downloadable HTML file.", "category": "export", "inputSchema": { "type": "object", "properties": {}, "required": [] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documentId": { "type": "string", "description": "Stable identifier for the exported document." }, "format": { "type": "string", "enum": [ "pdf" ], "description": "Export format — always \"pdf\"." }, "pageCount": { "description": "Number of pages in the rendered output, if known.", "type": "number" }, "warnings": { "description": "Non-fatal warnings.", "type": "array", "items": { "type": "string" } } }, "required": [ "ok", "documentId", "format" ], "additionalProperties": false, "description": "Result of exporting the document as PDF (via browser print dialog)." }, "annotations": { "readOnlyHint": false }, "displayHints": { "inputFieldAliases": {} } }, { "name": "create_share_link", "description": "Create a shareable URL for the active document and copy it to the clipboard. Use this to share the document; the link expires after 30 days. Use get_document_state to check canShare before calling.", "category": "share", "inputSchema": { "type": "object", "properties": {}, "required": [] }, "outputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "documentId": { "type": "string", "description": "Stable identifier for the shared document." }, "shareUrl": { "type": "string", "description": "Shareable URL that loads the document in the FlatWrite editor." }, "expiresAt": { "description": "ISO 8601 timestamp when the share link expires.", "type": "string" } }, "required": [ "ok", "documentId", "shareUrl" ], "additionalProperties": false, "description": "Result of creating a shareable URL for the document." }, "annotations": { "readOnlyHint": false }, "displayHints": { "inputFieldAliases": {} } }, { "name": "assist_document", "description": "Rewrite, shorten, fix grammar, or apply a custom instruction to markdown via FlatWrite Assist (Morph: Reflex + Router + Compact + Fast Models). Returns full markdown plus the edited piece. Does not modify the editor — apply with update_document_content if desired. When selectionStart and selectionEnd are provided, only that span is rewritten.", "category": "assist", "inputSchema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "Full markdown document. Optional in the browser WebMCP path (defaults to the active editor). Required for server MCP." }, "mode": { "type": "string", "description": "Assist mode.", "enum": [ "custom", "rewrite", "shorten", "fix_grammar" ] }, "instruction": { "type": "string", "description": "Freeform instruction. Required when mode is \"custom\"." }, "selectionStart": { "type": "number", "description": "Optional selection start index (inclusive) within markdown.", "minimum": 0 }, "selectionEnd": { "type": "number", "description": "Optional selection end index (exclusive) within markdown.", "minimum": 0 }, "selectionText": { "type": "string", "description": "Optional selection text (defaults to markdown.slice(start, end))." } }, "required": ["markdown"] }, "outputSchema": { "type": "object", "title": "AssistDocumentOutput", "description": "Result of Morph-powered document assist. Returns full markdown with the edit applied, plus the edited piece for selection-scoped edits. Does not modify the editor automatically.", "required": [ "ok", "markdown", "piece", "scope" ], "additionalProperties": false, "properties": { "ok": { "type": "boolean", "description": "Always true on success." }, "markdown": { "type": "string", "description": "Full document markdown after applying the edit (selection spliced or whole-doc replace)." }, "piece": { "type": "string", "description": "Edited content for the target scope only (selection text or full document)." }, "scope": { "type": "string", "enum": [ "selection", "document" ], "description": "Whether the edit targeted a selection or the whole document." }, "explanation": { "type": "string", "description": "Short human-readable summary of what changed." }, "model": { "type": "string", "description": "Morph Fast Model id that produced the edit." }, "routing": { "type": "object", "description": "Model Router outcome.", "additionalProperties": false, "properties": { "tier": { "type": "string", "description": "easy | medium | hard" }, "difficulty": { "type": "string" }, "confidence": { "type": [ "number", "null" ] }, "domain": { "type": [ "string", "null" ] } } }, "compacted": { "type": "boolean", "description": "Whether Compact ran on the input before generation." }, "usage": { "type": [ "object", "null" ], "description": "Token usage from the model call, when available.", "additionalProperties": true }, "reflex": { "type": "object", "description": "Reflex classifier labels for user and assistant turns.", "additionalProperties": true }, "selection": { "type": [ "object", "null" ], "description": "Selection range used, if any.", "additionalProperties": false, "properties": { "start": { "type": "number" }, "end": { "type": "number" } } }, "nextSuggestedTool": { "type": "string", "description": "Suggested next tool (e.g. update_document_content to apply)." } } }, "annotations": { "readOnlyHint": true }, "displayHints": { "inputFieldAliases": {} } } ] }