fmrl-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Too Great LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# fmrl
+
+Share anything your AI made. `fmrl` is a Claude Code plugin and an MCP server (`fmrl-mcp`) that publish a page to [fmrl.site](https://fmrl.site) and hand back a link. No account; the page lasts seven days unless someone keeps it from the page itself.
+
+## Install
+
+Claude Code:
+
+```
+/plugin marketplace add toogreatwtf/fmrl-plugin
+/plugin install fmrl@fmrl-plugin
+```
+
+Any MCP client (Claude Desktop, Cursor, Codex, Windsurf, and the rest):
+
+```json
+{ "mcpServers": { "fmrl": { "command": "npx", "args": ["-y", "fmrl-mcp"] } } }
+```
+
+No key step. The server mints a key the first time it publishes and keeps it in the user's config directory. `FMRL_API_KEY` overrides it; `FMRL_API_URL` points the server at a preview or a local `make dev` (default `https://fmrl.site`).
+
+curl, for people who want neither:
+
+```
+curl -sX POST https://fmrl.site/api/v1/keys
+curl -sX POST https://fmrl.site/api/v1/publish \
+  -H "Authorization: Bearer fmrl_…" -H "Content-Type: application/json" \
+  -d '{"format":"md","content":"# hello"}'
+```
+
+## What you get
+
+In Claude Code, `/fmrl:share` publishes what is at hand — a file you named or something the agent composed — and replies with the link, the expiry, and a manage link that removes the page.
+
+Any MCP client gets five tools:
+
+| Tool | Does |
+|---|---|
+| `fmrl_publish` | `content`, optional `format` (`html` or `md`; detected when left out), optional `title` → the page's URL, expiry and manage link |
+| `fmrl_publish_file` | `path` to a `.html`, `.htm`, `.md`, `.markdown`, `.mdx` or `.txt` file (2 MiB at most), optional `title` |
+| `fmrl_get` | an id or a viewer URL → status, format, size, expiry, whether it was kept |
+| `fmrl_delete` | an id or a viewer URL → removes a page this key published |
+| `fmrl_whoami` | the key's prefix and this month's quota |
+
+## Keys and limits
+
+The server mints a key on first use and stores it in `~/.config/fmrl/credentials.json` (`$XDG_CONFIG_HOME/fmrl/credentials.json`; `%APPDATA%\fmrl\credentials.json` on Windows), one key per API base URL, file mode 0600. `FMRL_API_KEY` overrides the file. 25 publishes a month per key, 5 keys a day per network, 2 MiB per page. Content is subject to fmrl.site's [acceptable use policy](https://fmrl.site/aup). Full API reference: [marky.md/api](https://marky.md/api).
+
+## License
+
+MIT, Too Great LLC.

package/dist/api.js

@@ -0,0 +1,91 @@
+/** ApiError is any non-2xx answer: the contract's code and message, plus resets_at on a 402 and retryAfterSeconds on a 429. A network failure (no response at all) is status 0, code "network". */
+export class ApiError extends Error {
+    status;
+    code;
+    resetsAt;
+    retryAfterSeconds;
+    constructor(status, code, message, resetsAt, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.resetsAt = resetsAt;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "ApiError";
+    }
+}
+/** FmrlApi is the thin HTTP client for /api/v1. It knows nothing about keys on disk. */
+export class FmrlApi {
+    root;
+    fetchImpl;
+    timeoutMs;
+    extraHeaders;
+    constructor(baseUrl, opts = {}) {
+        this.root = baseUrl.replace(/\/+$/, "") + "/api/v1";
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.timeoutMs = opts.timeoutMs ?? 30000;
+        this.extraHeaders = opts.headers ?? {};
+    }
+    /** viewerBase is the host pages live on: the configured base URL without /api/v1. */
+    get viewerBase() {
+        return this.root.slice(0, -"/api/v1".length);
+    }
+    mint(label) {
+        return this.call("POST", "/keys", undefined, { label });
+    }
+    publish(key, body) {
+        const payload = { content: body.content };
+        if (body.format !== undefined)
+            payload.format = body.format;
+        if (body.title !== undefined)
+            payload.title = body.title;
+        return this.call("POST", "/publish", key, payload);
+    }
+    get(key, id) {
+        return this.call("GET", `/docs/${encodeURIComponent(id)}`, key);
+    }
+    async delete(key, id) {
+        await this.call("DELETE", `/docs/${encodeURIComponent(id)}`, key);
+    }
+    me(key) {
+        return this.call("GET", "/me", key);
+    }
+    async call(method, path, key, body) {
+        const headers = { Accept: "application/json", ...this.extraHeaders };
+        if (key)
+            headers.Authorization = `Bearer ${key}`;
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let res;
+        try {
+            res = await this.fetchImpl(this.root + path, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (e) {
+            if (e instanceof Error && (e.name === "TimeoutError" || e.name === "AbortError")) {
+                throw new ApiError(0, "timeout", `No answer from ${this.root} within ${this.timeoutMs / 1000}s.`);
+            }
+            const cause = e.cause?.message ?? (e instanceof Error ? e.message : String(e));
+            throw new ApiError(0, "network", `Couldn't reach ${this.root}: ${cause}`);
+        }
+        const text = await res.text();
+        if (res.status === 204)
+            return undefined;
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (res.ok)
+            return parsed;
+        const err = parsed?.error;
+        const retryAfterHeader = res.headers.get("retry-after");
+        const retryAfterSeconds = retryAfterHeader !== null && /^\d+$/.test(retryAfterHeader) ? parseInt(retryAfterHeader, 10) : undefined;
+        throw new ApiError(res.status, err?.code ?? `http_${res.status}`, err?.message ?? `${method} ${path} answered ${res.status}.`, err?.resets_at, retryAfterSeconds);
+    }
+}

package/dist/config.js

@@ -0,0 +1,18 @@
+export const DEFAULT_BASE_URL = "https://fmrl.site";
+/** loadConfig reads FMRL_API_URL and FMRL_API_KEY; the client appends /api/v1 to baseUrl. */
+export function loadConfig(env = process.env) {
+    const rawUrl = (env.FMRL_API_URL ?? "").trim();
+    const baseUrl = (rawUrl === "" ? DEFAULT_BASE_URL : rawUrl).replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`FMRL_API_URL must be an http(s) URL, got ${JSON.stringify(rawUrl)}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`FMRL_API_URL must be an http(s) URL, got ${JSON.stringify(rawUrl)}`);
+    }
+    const rawKey = (env.FMRL_API_KEY ?? "").trim();
+    return { baseUrl, apiKey: rawKey === "" ? undefined : rawKey };
+}

package/dist/credentials.js

@@ -0,0 +1,42 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const EMPTY = { version: 1, keys: {} };
+/**
+ * credentialsPath is $XDG_CONFIG_HOME/fmrl/credentials.json (default
+ * ~/.config) on macOS and Linux, and %APPDATA%\fmrl\credentials.json on
+ * Windows. Keyed by API base URL inside, so one file serves every host.
+ */
+export function credentialsPath(env = process.env, platform = process.platform, homedir = os.homedir) {
+    if (platform === "win32") {
+        const base = (env.APPDATA ?? "").trim() || path.win32.join(homedir(), "AppData", "Roaming");
+        return path.win32.join(base, "fmrl", "credentials.json");
+    }
+    const xdg = (env.XDG_CONFIG_HOME ?? "").trim();
+    const base = xdg !== "" ? xdg : path.join(homedir(), ".config");
+    return path.join(base, "fmrl", "credentials.json");
+}
+/** readCredentials treats a missing, unreadable, or malformed file as empty. */
+export async function readCredentials(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (parsed && parsed.version === 1 && parsed.keys && typeof parsed.keys === "object") {
+            return { version: 1, keys: { ...parsed.keys } };
+        }
+        return { ...EMPTY, keys: {} };
+    }
+    catch {
+        return { ...EMPTY, keys: {} };
+    }
+}
+/** writeCredentials writes to a sibling temp file with mode 0600 and renames it into place. */
+export async function writeCredentials(file, data) {
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32")
+        await chmod(dir, 0o700);
+    const tmp = path.join(dir, `.credentials.json.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    await writeFile(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+    await rename(tmp, file);
+}

package/dist/format.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+export const ACCEPTED_EXTENSIONS = [".html", ".htm", ".md", ".markdown", ".mdx", ".txt"];
+export const MAX_BYTES = 2 * 1024 * 1024;
+export const TOO_LARGE_MESSAGE = "That's bigger than the 2 MiB limit.";
+const BY_EXTENSION = {
+    ".html": "html",
+    ".htm": "html",
+    ".md": "md",
+    ".markdown": "md",
+    ".mdx": "md",
+    ".txt": "md",
+};
+/** formatForPath maps a file's extension to the format hint, or throws naming the accepted extensions. */
+export function formatForPath(p) {
+    const base = p.split(/[\\/]/).pop() ?? "";
+    const ext = path.extname(base).toLowerCase();
+    const format = ext === "" ? undefined : BY_EXTENSION[ext];
+    if (!format) {
+        throw new Error(`fmrl_publish_file accepts ${ACCEPTED_EXTENSIONS.join(", ")} files; ${base || p} is not one. Use fmrl_publish with the content instead.`);
+    }
+    return format;
+}

package/dist/ids.js

@@ -0,0 +1,21 @@
+const ID = /^[0-9abcdefghjkmnpqrstvwxyz]{12}$/;
+/** parseDocId accepts a 12-character document id or any fmrl URL that contains one as a path segment. */
+export function parseDocId(input) {
+    const s = input.trim();
+    if (ID.test(s))
+        return s;
+    let url;
+    try {
+        url = new URL(s);
+    }
+    catch {
+        url = undefined;
+    }
+    if (url) {
+        for (const seg of url.pathname.split("/")) {
+            if (ID.test(seg))
+                return seg;
+        }
+    }
+    throw new Error(`${JSON.stringify(input)} is not a document id or a fmrl.site URL.`);
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { FmrlApi } from "./api.js";
+import { loadConfig } from "./config.js";
+import { credentialsPath } from "./credentials.js";
+import { KeyStore } from "./keys.js";
+import { createServer } from "./server.js";
+// stdout is the JSON-RPC channel; everything we say goes to stderr.
+const log = (line) => process.stderr.write(line + "\n");
+async function main() {
+    const cfg = loadConfig();
+    const api = new FmrlApi(cfg.baseUrl);
+    const keys = new KeyStore({ api, baseUrl: cfg.baseUrl, apiKeyFromEnv: cfg.apiKey, file: credentialsPath(), log });
+    const server = createServer({ api, keys });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((e) => {
+    log(`fmrl-mcp: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+});

package/dist/keys.js

@@ -0,0 +1,56 @@
+import { ApiError } from "./api.js";
+import { readCredentials, writeCredentials } from "./credentials.js";
+const LABEL = "fmrl-mcp";
+/**
+ * KeyStore resolves the key every call uses: FMRL_API_KEY when set, else the
+ * credentials file's entry for this base URL, else a freshly minted key that
+ * is saved for next time. A stored key that answers 401 (revoked, or a
+ * preview whose memory store restarted) is replaced once and the call
+ * retried; a key from the environment is never replaced.
+ */
+export class KeyStore {
+    o;
+    cached;
+    pending;
+    constructor(o) {
+        this.o = o;
+    }
+    async getKey() {
+        if (this.o.apiKeyFromEnv)
+            return this.o.apiKeyFromEnv;
+        if (this.cached)
+            return this.cached;
+        const stored = (await readCredentials(this.o.file)).keys[this.o.baseUrl];
+        if (stored?.key) {
+            this.cached = stored.key;
+            return stored.key;
+        }
+        return this.mintOnce();
+    }
+    async withKey(fn) {
+        const key = await this.getKey();
+        try {
+            return await fn(key);
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 401 && !this.o.apiKeyFromEnv) {
+                const fresh = await this.mintOnce();
+                return fn(fresh);
+            }
+            throw e;
+        }
+    }
+    /** mintOnce collapses concurrent mint calls into a single in-flight request. */
+    mintOnce() {
+        return (this.pending ??= this.mint().finally(() => { this.pending = undefined; }));
+    }
+    async mint() {
+        const minted = await this.o.api.mint(LABEL);
+        const file = await readCredentials(this.o.file);
+        file.keys[this.o.baseUrl] = { key: minted.key, prefix: minted.prefix, created_at: minted.created_at };
+        await writeCredentials(this.o.file, file);
+        this.cached = minted.key;
+        this.o.log?.(`fmrl-mcp: minted key ${minted.prefix}… for ${this.o.baseUrl}, saved to ${this.o.file}`);
+        return minted.key;
+    }
+}

package/dist/server.js

@@ -0,0 +1,159 @@
+import { open as fsOpen, stat as fsStat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ApiError } from "./api.js";
+import { MAX_BYTES, TOO_LARGE_MESSAGE, formatForPath } from "./format.js";
+import { parseDocId } from "./ids.js";
+export const SEVEN_DAYS = "This page lasts seven days unless someone keeps it on the page itself.";
+function ok(text, structured) {
+    return { content: [{ type: "text", text }], structuredContent: structured };
+}
+function fail(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function errorText(e) {
+    if (e instanceof ApiError) {
+        let msg = e.resetsAt && !e.message.includes(e.resetsAt) ? `${e.message} Resets at ${e.resetsAt}.` : e.message;
+        if (e.status === 429 && e.retryAfterSeconds) {
+            msg += e.retryAfterSeconds < 120
+                ? ` Try again in ${e.retryAfterSeconds} seconds.`
+                : ` Try again in ${Math.ceil(e.retryAfterSeconds / 60)} minutes.`;
+        }
+        return msg;
+    }
+    return e instanceof Error ? e.message : String(e);
+}
+function publishText(p) {
+    return [
+        `Published: ${p.url}`,
+        `Expires ${p.expires_at}`,
+        SEVEN_DAYS,
+        `Manage link (removes the page; give it only to someone who should be able to): ${p.manage_url}`,
+    ].join("\n");
+}
+function docText(d) {
+    const kept = d.pinned ? `kept forever${d.cid ? ` (${d.cid})` : ""}` : `expires ${d.expires_at}`;
+    return [`${d.url}: ${d.status}, ${d.format}, ${d.size} bytes, ${kept}.`, SEVEN_DAYS].join("\n");
+}
+function meText(m) {
+    const q = m.quota.publishes;
+    return [`${m.prefix}…: ${q.used} of ${q.limit} publishes used this month, resets ${q.resets_at}.`, SEVEN_DAYS].join("\n");
+}
+const publishOutput = {
+    id: z.string(), url: z.string(), raw_url: z.string(), manage_url: z.string(), expires_at: z.string(), status: z.string(),
+};
+const docOutput = {
+    id: z.string(), url: z.string(), status: z.string(), format: z.string(), size: z.number(),
+    expires_at: z.string().nullable(), pinned: z.boolean(), cid: z.string().optional(),
+};
+const meOutput = {
+    prefix: z.string(), created_at: z.string(),
+    quota: z.object({ publishes: z.object({ used: z.number(), limit: z.number(), resets_at: z.string() }) }),
+};
+/** createServer registers the five contract tools on an McpServer. deps.keys owns the key; deps.api speaks HTTP. */
+export function createServer(deps) {
+    const { api, keys } = deps;
+    const open = deps.open ?? fsOpen;
+    const stat = deps.stat ?? fsStat;
+    const server = new McpServer({ name: "fmrl", version: "0.1.0" });
+    const run = async (fn, render) => {
+        try {
+            const v = await keys.withKey(fn);
+            return ok(render(v), v);
+        }
+        catch (e) {
+            return fail(errorText(e));
+        }
+    };
+    server.registerTool("fmrl_publish", {
+        title: "Publish a page to fmrl.site",
+        description: "Publish HTML or Markdown as a page on fmrl.site and get its link. The page lasts seven days unless someone keeps it from the page itself. Only call this when the user asked to share, send, or get a link for something.",
+        inputSchema: {
+            content: z.string().min(1).describe("The HTML or Markdown to publish (2 MiB at most)."),
+            format: z.enum(["html", "md"]).optional().describe("html or md; leave out to let the server detect it."),
+            title: z.string().optional().describe("Page title; the first heading is used when left out."),
+        },
+        outputSchema: publishOutput,
+    }, async ({ content, format, title }) => run((k) => api.publish(k, { content, format, title }), publishText));
+    server.registerTool("fmrl_publish_file", {
+        title: "Publish a file to fmrl.site",
+        description: "Publish a .html, .htm, .md, .markdown, .mdx or .txt file (2 MiB at most) as a page on fmrl.site and get its link. Only call this when the user asked to share the file.",
+        inputSchema: {
+            path: z.string().min(1).describe("Absolute path to the file (a leading ~ is expanded)."),
+            title: z.string().optional().describe("Page title; the file's first heading is used when left out."),
+        },
+        outputSchema: publishOutput,
+    }, async ({ path: p, title }) => {
+        let format;
+        let content;
+        try {
+            const expanded = p === "~" || p.startsWith("~/") ? path.join(os.homedir(), p.slice(1)) : p;
+            const resolved = path.resolve(expanded);
+            format = formatForPath(resolved);
+            const info = await stat(resolved);
+            if (info.size > MAX_BYTES)
+                return fail(TOO_LARGE_MESSAGE);
+            const buf = Buffer.alloc(MAX_BYTES + 1);
+            let bytesRead;
+            const handle = await open(resolved, "r");
+            try {
+                ({ bytesRead } = await handle.read(buf, 0, MAX_BYTES + 1, 0));
+            }
+            finally {
+                await handle.close();
+            }
+            if (bytesRead > MAX_BYTES)
+                return fail(TOO_LARGE_MESSAGE);
+            try {
+                content = new TextDecoder("utf-8", { fatal: true }).decode(buf.subarray(0, bytesRead));
+            }
+            catch {
+                return fail("That file isn't UTF-8 text.");
+            }
+        }
+        catch (e) {
+            return fail(errorText(e));
+        }
+        return run((k) => api.publish(k, { content, format, title }), publishText);
+    });
+    server.registerTool("fmrl_get", {
+        title: "Describe a fmrl.site page",
+        description: "Look up a page by id or URL: status, format, size, expiry, and whether it has been kept.",
+        inputSchema: { id: z.string().min(1).describe("A document id or any fmrl.site URL for it.") },
+        outputSchema: docOutput,
+    }, async ({ id }) => {
+        let docId;
+        try {
+            docId = parseDocId(id);
+        }
+        catch (e) {
+            return fail(errorText(e));
+        }
+        return run((k) => api.get(k, docId), docText);
+    });
+    server.registerTool("fmrl_delete", {
+        title: "Remove a fmrl.site page",
+        description: "Remove a page this key published, by id or URL. The page answers 410 from then on. Only call this when the user asked to remove it.",
+        inputSchema: { id: z.string().min(1).describe("A document id or any fmrl.site URL for it.") },
+        outputSchema: { id: z.string(), url: z.string(), removed: z.boolean() },
+    }, async ({ id }) => {
+        let docId;
+        try {
+            docId = parseDocId(id);
+        }
+        catch (e) {
+            return fail(errorText(e));
+        }
+        const url = `${api.viewerBase}/${docId}`;
+        return run(async (k) => { await api.delete(k, docId); return { id: docId, url, removed: true }; }, (v) => `Removed page ${v.id}. It answers 410 from now on.\n${SEVEN_DAYS}`);
+    });
+    server.registerTool("fmrl_whoami", {
+        title: "This fmrl.site key",
+        description: "The key's prefix and how many of this month's free publishes it has used.",
+        inputSchema: {},
+        outputSchema: meOutput,
+    }, async () => run((k) => api.me(k), meText));
+    return server;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "fmrl-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for fmrl.site: publish a page from any agent and get a link.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "fmrl-mcp": "dist/index.js" },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "repository": { "type": "git", "url": "https://github.com/toogreatwtf/fmrl-plugin", "directory": "packages/mcp" },
+  "homepage": "https://fmrl.site/install",
+  "keywords": ["mcp", "fmrl", "share", "publish"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.0"
+  }
+}