whamlink-mcp 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# whamlink-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [whamlink](https://whamlink.com) — let any MCP client (Claude Desktop, IDEs, agents) publish a single file to a permanent, shareable link.
+
+## Setup
+
+1. Get an API key: register at <https://whamlink.com/app>, then create a key under **Keys**.
+2. Add the server to your MCP client config, passing the key via `WHAMLINK_API_KEY`.
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "whamlink": {
+      "command": "npx",
+      "args": ["-y", "whamlink-mcp"],
+      "env": { "WHAMLINK_API_KEY": "wl_your_key_here" }
+    }
+  }
+}
+```
+
+Running from source instead of npm: `"command": "node", "args": ["/path/to/whamlink/mcp/dist/index.js"]` (after `npm install && npm run build` in `mcp/`).
+
+### Environment
+
+- `WHAMLINK_API_KEY` (required) — your whamlink API key.
+- `WHAMLINK_BASE_URL` (optional) — defaults to `https://whamlink.com`.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `publish_link` | Publish HTML / Markdown / PDF / image / text → a permanent URL. Public by default; set `visibility` to `private` / `password` / `email` to gate it. |
+| `list_links` | List your published links (id, slug, mode, visibility, URL). |
+| `set_link_access` | Change a link's visibility, password, shared-email list, `allowNetwork`, or title. |
+| `replace_link_content` | Replace a link's content in place — the URL stays the same. |
+| `delete_link` | Permanently delete a link. |
+
+**Never publish secrets, API keys, or private data.** Public links are unlisted but anyone with the URL can view them; use `private`/`password`/`email` visibility for anything sensitive.
+
+## Develop
+
+```bash
+npm install
+npm run build
+npm test
+```

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+export interface WhamlinkConfig {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class WhamlinkError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status: number);
+}
+export type Visibility = "public" | "private" | "password" | "email";
+export type Mode = "sandboxed_html" | "sanitized_html" | "markdown" | "pdf" | "image" | "text";
+export interface PublishArgs {
+    mode: Mode;
+    content: string;
+    title?: string;
+    allowNetwork?: boolean;
+    visibility?: Visibility;
+    password?: string;
+    shareEmails?: string[];
+}
+export interface AccessArgs {
+    visibility?: Visibility;
+    password?: string;
+    shareEmails?: string[];
+    allowNetwork?: boolean;
+    title?: string;
+}
+export declare const publishLink: (cfg: WhamlinkConfig, args: PublishArgs) => Promise<any>;
+export declare const listLinks: (cfg: WhamlinkConfig) => Promise<any>;
+export declare const deleteLink: (cfg: WhamlinkConfig, id: string) => Promise<any>;
+export declare const setLinkAccess: (cfg: WhamlinkConfig, id: string, args: AccessArgs) => Promise<any>;
+export declare const replaceLinkContent: (cfg: WhamlinkConfig, id: string, args: {
+    mode: Mode;
+    content: string;
+}) => Promise<any>;

package/dist/client.js

@@ -0,0 +1,33 @@
+// Thin, testable wrapper over the whamlink HTTP API. API-key auth — no CSRF header needed
+// (the app only requires x-whamlink-app on cookie-authenticated requests).
+export class WhamlinkError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "WhamlinkError";
+    }
+}
+async function call(cfg, method, path, body) {
+    const f = cfg.fetchImpl ?? fetch;
+    const res = await f(`${cfg.baseUrl}${path}`, {
+        method,
+        headers: { "x-api-key": cfg.apiKey, ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (res.status === 204)
+        return undefined;
+    const text = await res.text();
+    const json = text ? JSON.parse(text) : undefined;
+    if (!res.ok) {
+        throw new WhamlinkError(json?.error?.code ?? "error", json?.error?.message ?? `Request failed (${res.status})`, res.status);
+    }
+    return json;
+}
+export const publishLink = (cfg, args) => call(cfg, "POST", "/v1/publish", args);
+export const listLinks = (cfg) => call(cfg, "GET", "/v1/docs");
+export const deleteLink = (cfg, id) => call(cfg, "DELETE", `/v1/docs/${encodeURIComponent(id)}`);
+export const setLinkAccess = (cfg, id, args) => call(cfg, "PATCH", `/v1/docs/${encodeURIComponent(id)}`, args);
+export const replaceLinkContent = (cfg, id, args) => call(cfg, "PUT", `/v1/docs/${encodeURIComponent(id)}/content`, args);

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { WhamlinkError, publishLink, listLinks, deleteLink, setLinkAccess, replaceLinkContent, } from "./client.js";
+const apiKey = process.env.WHAMLINK_API_KEY;
+if (!apiKey) {
+    process.stderr.write("whamlink-mcp: WHAMLINK_API_KEY is required. Get a key by registering at https://whamlink.com/app and pasting it into your MCP client config.\n");
+    process.exit(1);
+}
+const cfg = { baseUrl: process.env.WHAMLINK_BASE_URL ?? "https://whamlink.com", apiKey };
+const ok = (text) => ({ content: [{ type: "text", text }] });
+async function guard(fn, render) {
+    try {
+        return ok(render(await fn()));
+    }
+    catch (e) {
+        const msg = e instanceof WhamlinkError ? `whamlink error (${e.status} ${e.code}): ${e.message}` : `whamlink request failed: ${e.message}`;
+        return { content: [{ type: "text", text: msg }], isError: true };
+    }
+}
+const visibility = z.enum(["public", "private", "password", "email"]);
+const mode = z.enum(["sandboxed_html", "sanitized_html", "markdown", "pdf", "image", "text"]);
+const server = new McpServer({ name: "whamlink", version: "0.1.0" });
+server.tool("publish_link", "Publish one file (HTML, Markdown, PDF as base64, image as base64, or text) to a permanent whamlink URL. Links are public (unlisted) by default; set visibility to private/password/email to gate them. Never publish secrets or private data.", {
+    mode: mode.describe("sandboxed_html (runs JS, isolated), sanitized_html (scripts stripped), markdown, pdf, image, or text"),
+    content: z.string().describe("The file content. For pdf/image, base64 is accepted via the API's text path only for small files; prefer text/markdown/html here."),
+    title: z.string().optional(),
+    allowNetwork: z.boolean().optional().describe("Let sandboxed/sanitized HTML load https CDN scripts/styles"),
+    visibility: visibility.optional().describe("Default public. private = owner only; password = also pass `password`; email = also pass `shareEmails`"),
+    password: z.string().min(6).optional(),
+    shareEmails: z.array(z.string().email()).optional(),
+}, (a) => guard(() => publishLink(cfg, a), (r) => `Published: ${r.url}\n(id: ${r.id}, slug: ${r.slug})`));
+server.tool("list_links", "List the links you've published (id, slug, title, mode, visibility, size, URL).", {}, () => guard(() => listLinks(cfg), (r) => !r.docs?.length ? "No links yet." :
+    r.docs.map((d) => `• ${d.title || d.slug} — ${cfg.baseUrl}/${d.slug} [${d.mode}, ${d.visibility ?? "public"}] (id: ${d.id})`).join("\n")));
+server.tool("delete_link", "Permanently delete a published link by its id.", { id: z.string().describe("The doc id, e.g. doc_xxx (from list_links or publish_link)") }, (a) => guard(() => deleteLink(cfg, a.id), () => `Deleted ${a.id}.`));
+server.tool("set_link_access", "Change a link's access: visibility (public/private/password/email), password, shared email list, allowNetwork, or title.", {
+    id: z.string(),
+    visibility: visibility.optional(),
+    password: z.string().min(6).optional(),
+    shareEmails: z.array(z.string().email()).optional(),
+    allowNetwork: z.boolean().optional(),
+    title: z.string().optional(),
+}, ({ id, ...rest }) => guard(() => setLinkAccess(cfg, id, rest), () => `Updated access for ${id}.`));
+server.tool("replace_link_content", "Replace a link's content in place — the URL stays the same.", { id: z.string(), mode, content: z.string() }, ({ id, mode, content }) => guard(() => replaceLinkContent(cfg, id, { mode, content }), (r) => `Replaced content for ${id} (${r.url}).`));
+await server.connect(new StdioServerTransport());
+process.stderr.write(`whamlink-mcp connected (base: ${cfg.baseUrl})\n`);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "whamlink-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for whamlink — publish a single file to a permanent, shareable link from any MCP client.",
+  "type": "module",
+  "bin": {
+    "whamlink-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "whamlink",
+    "publish",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  }
+}