pst.md

INTERACTIVE UI: on a host that supports MCP Apps, list_appearance renders a theme picker showing every scheme's own colours, and the ids the user picks are sent back to you. Never build, write, or offer your own picker, swatch gallery, or HTML page for choosing a pst.md theme - the user already has one and a second one competes with it. Call list_appearance and wait for the choice. pst.md publishes Markdown notes under signed-in accounts. A note is addressed by its id; only its owner can update or delete it (sign-in required - see the client's login flow). Reading a public note by id needs no sign-in. Appearance - the color palette and font a note renders in - is chosen ONLY through Markdown front matter. There is no appearance argument. To theme a note, begin its content with a YAML block fenced by --- lines: --- title: Release notes palette-light: signal palette-dark: midnight font: lora --- # Body markdown starts here Recognized keys: - palette-light (alias: theme-light) - the theme used when the viewer is in light mode, e.g. "iterm-catppuccin-latte", "iterm-gruvbox-light", "plain-light". - palette-dark (alias: theme-dark) - the theme used when the viewer is in dark mode, e.g. "iterm-nord", "iterm-catppuccin-macchiato", "plain-dark". - palette (alias: theme) - shorthand for setting both of the above at once. A theme is one terminal scheme in one mode, so this makes both modes look the same. - font - a font id, e.g. "lora", "jetbrains-mono", "inter". - banner - the image rendered above the note and used as its link-preview image: an https URL the author hosts (the server never fetches it) or an uploaded note image's own /i/<id> path. Anything else is ignored and reported under appearance.unresolved. - title - the note's title. Front matter is the ONLY way to set it; there is no title argument. The front-matter block is kept in the stored markdown (so get_note returns it and it round-trips through edits) but is hidden when the note is rendered - it never shows in the body. Front matter is the single source of truth for appearance; there is no stored appearance field. A note's code fences are highlighted from the theme it pins (a terminal scheme is already a syntax palette), so there is no separate code theme to choose: the old code-theme (alias: code) key is still parsed and still round-trips, but it is ignored. Call list_appearance for valid theme and font ids: it returns a LEAN list ({id,label,mode,tags} - no colors) of the whole curated catalog (twenty families), and takes mode/tags/query/limit filters. Call get_appearance(ids) when color swatches are actually needed - unknown ids come back with near-match suggestions. The full lean catalog is also available as the cacheable resource pstmd://appearance/catalog. update_note requires expectedVersion (the version returned by create_note/get_note) to detect conflicting edits. Every tool result carries structuredContent matching the tool's declared outputSchema, and a text block mirroring it as compact JSON. Account-scoped tools called without authorization answer with a tool error carrying a WWW-Authenticate challenge in _meta - OAuth-capable clients handle it automatically. The tools cover the WHOLE service - notes (create/get/consume/update/delete), the library (list_library/save_note/unsave_note/set_note_folder), folders (list_folders/create_folder/update_folder/delete_folder), image uploads (create_image_upload - image bytes never travel through tools/call; it returns a short-lived pointer for a plain multipart POST - plus upload_image for hosts that pass host-held files by download_url, and list_images/delete_image for managing storage; an uploaded image's /i/<id> path works in markdown and as the banner), and whoami - so an MCP-only client never needs REST. The complete contract (every tool and its arguments, auth, appearance, one-time notes, and what Markdown renders - GFM, footnotes, syntax highlighting, KaTeX, Mermaid) is published as the pst-md skill (discovery index skill://index.json, guide skill://pst-md/SKILL.md), as the prompt pstmd_guide, and - for clients that cannot read MCP resources - as the credential-free get_skill tool. Read it before your first publish.