whamlink-mcp 0.1.1 → 0.1.3

package/README.md

@@ -25,13 +25,14 @@ Running from source instead of npm: `"command": "node", "args": ["/path/to/whaml
 
 ### Environment
 
-- `WHAMLINK_API_KEY` (required) — your whamlink API key.
+- `WHAMLINK_API_KEY` (optional) — your whamlink API key. If unset, the server still starts; the agent can `register` to create an account in-session (save the returned key here to persist).
 - `WHAMLINK_BASE_URL` (optional) — defaults to `https://whamlink.com`.
 
 ## Tools
 
 | Tool | What it does |
 |------|--------------|
+| `register` | Create an account on the user's behalf (consent + real email). Lets a new user go zero-to-published without setting a key first. |
 | `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. |

package/dist/client.d.ts

@@ -26,6 +26,10 @@ export interface AccessArgs {
     allowNetwork?: boolean;
     title?: string;
 }
+export declare function registerAccount(cfg: WhamlinkConfig, args: {
+    email: string;
+    name: string;
+}): Promise<any>;
 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>;

package/dist/client.js

@@ -26,6 +26,18 @@ async function call(cfg, method, path, body) {
     }
     return json;
 }
+// Register a new account. No auth (there's no key yet) — returns { user, apiKey, _setup }.
+export async function registerAccount(cfg, args) {
+    const f = cfg.fetchImpl ?? fetch;
+    const res = await f(`${cfg.baseUrl}/v1/auth/register`, {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(args),
+    });
+    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 ?? `Register 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)}`);

package/dist/index.js

@@ -2,28 +2,34 @@
 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 };
+import { WhamlinkError, registerAccount, publishLink, listLinks, deleteLink, setLinkAccess, replaceLinkContent, } from "./client.js";
+// The key is mutable: it can come from the env, or be set in-session by the `register` tool, so a
+// brand-new user can go from zero to published in one conversation. cfg.apiKey is read at call time.
+const cfg = { baseUrl: process.env.WHAMLINK_BASE_URL ?? "https://whamlink.com", apiKey: process.env.WHAMLINK_API_KEY ?? "" };
 const ok = (text) => ({ content: [{ type: "text", text }] });
+const errText = (text) => ({ content: [{ type: "text", text }], isError: true });
 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 };
+        return errText(msg);
     }
 }
+// Tools that act on an account need a key. Fail with a clear instruction rather than a raw 401.
+const needKey = () => cfg.apiKey ? null : errText("No whamlink API key. Ask the user for consent and their real email, call `register` to create an account (or have them set WHAMLINK_API_KEY in the MCP config), then retry.");
 const visibility = z.enum(["public", "private", "password", "email"]);
 // Text-based modes only: MCP tool args are JSON, which can't carry binary. PDF/image files must
 // go through the dashboard or the multipart API, so they're intentionally not offered here.
 const mode = z.enum(["sandboxed_html", "sanitized_html", "markdown", "text"]);
-const server = new McpServer({ name: "whamlink", version: "0.1.0" });
+const server = new McpServer({ name: "whamlink", version: "0.1.2" });
+server.tool("register", "Create a whamlink account on the USER'S behalf. Only call this with the user's explicit consent and their REAL email — a verification link is sent there. Returns an API key used for the rest of this session; tell the user to set it as WHAMLINK_API_KEY in their MCP config to keep it across restarts.", { email: z.string().email().describe("the user's real email"), name: z.string() }, (a) => guard(async () => {
+    const r = await registerAccount(cfg, a);
+    if (r?.apiKey)
+        cfg.apiKey = r.apiKey; // use it for the rest of this session
+    return r;
+}, (r) => `Account created for ${r.user?.email ?? "the user"} — you can publish now.\nAPI key (save as WHAMLINK_API_KEY to persist): ${r.apiKey}\nA verification link was emailed; clicking it unlocks full quota (3 links allowed before verifying).`));
 server.tool("publish_link", "Publish text-based content (HTML, Markdown, or plain text) to a permanent whamlink URL. Links are public (unlisted) by default; set visibility to private/password/email to gate them. (PDF/image files aren't supported over MCP — use the whamlink dashboard or multipart API for those.) Never publish secrets or private data.", {
     mode: mode.describe("sandboxed_html (runs JS, isolated origin), sanitized_html (scripts stripped), markdown, or text"),
     content: z.string().describe("The text content to publish (UTF-8)."),
@@ -32,10 +38,10 @@ server.tool("publish_link", "Publish text-based content (HTML, Markdown, or plai
     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." :
+}, (a) => needKey() ?? 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).", {}, () => needKey() ?? 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("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) => needKey() ?? 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(),
@@ -43,7 +49,7 @@ server.tool("set_link_access", "Change a link's access: visibility (public/priva
     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}).`));
+}, ({ id, ...rest }) => needKey() ?? 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 }) => needKey() ?? 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

@@ -1,6 +1,6 @@
 {
   "name": "whamlink-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for whamlink \u2014 publish a single file to a permanent, shareable link from any MCP client.",
   "type": "module",
   "bin": {
@@ -19,10 +19,13 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
+    "ai-agents",
+    "claude",
     "mcp",
-    "whamlink",
+    "mcp-server",
+    "model-context-protocol",
     "publish",
-    "model-context-protocol"
+    "whamlink"
   ],
   "license": "MIT",
   "dependencies": {
@@ -33,5 +36,14 @@
     "@types/node": "^26.0.1",
     "typescript": "^5.5.0",
     "vitest": "^2.1.0"
-  }
+  },
+  "homepage": "https://whamlink.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/billkinddev/whamlink-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/billkinddev/whamlink-mcp/issues"
+  },
+  "author": "whamlink"
 }