@reidar80/webshelf-mcp 0.1.0 → 0.2.2

package/README.md

@@ -1,8 +1,18 @@
 # @reidar80/webshelf-mcp
 
 Model Context Protocol server for [Webshelf](https://webshelf.app). Lets
-any MCP-aware client (Claude Desktop, Cursor, Continue, etc.) list, read,
-upload and manage HTML files on your Webshelf account.
+any MCP-aware client (Claude Desktop, Claude Code, Cursor, Continue, etc.)
+list, read, upload and manage HTML and markdown files on your Webshelf
+account.
+
+## Associated repository
+
+The Webshelf web app — the host this MCP server talks to — lives in
+[`reidar80/webshelf`](https://github.com/reidar80/webshelf). That repo
+owns the database schema, the Next.js app, and the `/api/v1/*` HTTP
+surface this client wraps. The authoritative API contract is published
+there as [`openapi/webshelf.yaml`](https://github.com/reidar80/webshelf/blob/main/openapi/webshelf.yaml);
+keep `src/api.ts` and `src/index.ts` here in sync with it.
 
 ## Install
 
@@ -15,7 +25,7 @@ npx -y @reidar80/webshelf-mcp
 
 Or pin a version in your MCP client config (preferred for stability).
 
-## Configure your MCP client
+## Use Webshelf from Claude
 
 ### Claude Desktop
 
@@ -34,8 +44,20 @@ add:
 }
 ```
 
-Restart Claude. The first time the server starts, it prints a URL to
-stderr — open it, sign in to Webshelf, and approve the connection.
+Restart Claude. The first launch prints a one-time
+`https://webshelf.app/app/device` URL + `user_code` to stderr — open it
+in your browser, sign in to Webshelf, and approve the connection.
+Credentials persist in `~/.webshelf/credentials.json` (mode 0600);
+access tokens refresh automatically.
+
+### Claude Code
+
+```bash
+claude mcp add webshelf -- npx -y @reidar80/webshelf-mcp
+```
+
+Then run `claude` as usual — the same device-flow approval happens on
+the first MCP call.
 
 ### Other clients
 
@@ -58,23 +80,48 @@ at `npx -y @reidar80/webshelf-mcp`.
 | `webshelf_list_collections` | List collections you can upload into. |
 | `webshelf_list_files` | List your files (or files in a collection). |
 | `webshelf_get_file` | Metadata for a single file. |
-| `webshelf_read_file` | Fetch the HTML body of a file. |
-| `webshelf_create_file` | Upload a new HTML file. |
+| `webshelf_read_file` | Fetch the body of a file (HTML or markdown). |
+| `webshelf_create_file` | Upload a new HTML or markdown file. |
 | `webshelf_update_file` | Rename, re-describe, or move a file. |
 | `webshelf_delete_file` | Move a file to the recycle bin. |
 
 ## How auth works
 
-On first launch the server runs the OAuth 2.0 device-authorization
-grant (RFC 8628):
+On the first tool call without saved credentials the server runs the
+OAuth 2.0 device-authorization grant (RFC 8628):
 
-1. It calls `POST /api/oauth/device` to get a one-time `user_code`.
-2. It prints the verification URL + code to stderr.
+1. It calls `POST /api/oauth/device` to get a one-time `user_code` and
+   writes the pending state to `~/.webshelf/credentials.pending.json`.
+2. The first tool call returns an error message containing the
+   verification URL + code — your MCP client (Claude Desktop, Claude
+   Code, etc.) shows it to you verbatim. The same prompt is mirrored
+   to stderr for log-tailing setups.
 3. You open the URL in your browser, sign in to Webshelf, and approve
    the connection.
-4. The server polls `POST /api/oauth/token` until the approval comes
-   through, then caches the resulting `access_token` + `refresh_token`
-   in `~/.webshelf/credentials.json` (mode 0600).
+4. Retry any tool call. The server exchanges the pending device_code
+   for tokens in one shot and caches `access_token` + `refresh_token`
+   in `~/.webshelf/credentials.json` (mode 0600). The pending file is
+   removed.
+
+### Authorize from the command line
+
+If you'd rather authorize before configuring your MCP client, run
+
+```
+npx -y @reidar80/webshelf-mcp auth
+```
+
+(or just `npx -y @reidar80/webshelf-mcp` from an interactive terminal —
+the binary detects a TTY and falls through to the same flow). It will
+print the verification URL, sit and poll, and exit with "Authorization
+complete. Token stored." once you approve. The credentials it writes
+are what your MCP client picks up automatically on next launch.
+
+This fast-fail design — surface the URL to the user instead of polling
+for the device-code TTL — avoids the four-minute timeouts MCP hosts
+enforce when a server doesn't respond to a tool call. If approval
+takes a while, every subsequent tool call before approval gets the
+same "still pending" error with the URL.
 
 The access token has a 1-hour TTL and refreshes automatically. To
 revoke a session, visit **Settings → API sessions** on webshelf.app and
@@ -86,8 +133,24 @@ The MCP server inherits the signed-in user's permissions exactly — it
 cannot read or write any file the user couldn't read or write from the
 browser. There's no separate API-level role.
 
+## Development
+
+```bash
+npm install
+npm run typecheck    # tsc --noEmit
+npm run build        # tsc → dist/
+npm start            # node dist/index.js (runs the device flow)
+```
+
+The HTTP surface this client wraps is documented in
+[`openapi/webshelf.yaml`](https://github.com/reidar80/webshelf/blob/main/openapi/webshelf.yaml)
+in the Webshelf web-app repo. Any change to a request/response shape
+there needs a matching update in `src/api.ts` and `src/index.ts` here,
+followed by a `version` bump in `package.json` so the next push to
+`main` publishes a new npm release.
+
 ## Reporting issues
 
-Open an issue at https://github.com/reidar80/webshelf/issues. Include
-the MCP client name + version, the tool you were calling, and the full
-error message (with any token values redacted).
+Open an issue at https://github.com/reidar80/webshelf-mcp/issues.
+Include the MCP client name + version, the tool you were calling, and
+the full error message (with any token values redacted).

package/dist/api.d.ts

@@ -4,6 +4,12 @@
  * Owns the auth lifecycle: pulls credentials from auth.ts, attaches the
  * Bearer header, refreshes on 401, retries once. Beyond that, the wire
  * format matches the OpenAPI spec exactly — no client-side renaming.
+ *
+ * Credentials are resolved lazily — on the first request, not at module
+ * load — so that a missing or pending device flow surfaces as a tool
+ * error (DeviceFlowPendingError carries the URL the user must visit),
+ * never as a four-minute hang while the MCP host waits for the stdio
+ * server to respond.
  */
 export interface ApiFile {
     id: string;
@@ -12,6 +18,7 @@ export interface ApiFile {
     collectionId: string | null;
     ownerId: string;
     protection: "public" | "authenticated" | "inherit" | "individual";
+    format: "html" | "markdown";
     sizeBytes: number;
     createdAt: string;
     updatedAt: string;
@@ -52,14 +59,16 @@ export interface ApiClient {
     }>;
     getFileContent(id: string): Promise<{
         name: string;
-        html: string;
+        content: string;
+        format: ApiFile["format"];
     }>;
     createFile(input: {
         name: string;
         description?: string | null;
         collectionId: string | null;
         protection?: ApiFile["protection"];
-        html: string;
+        format?: ApiFile["format"];
+        content: string;
     }): Promise<{
         file: ApiFile;
     }>;

package/dist/api.js

@@ -4,12 +4,20 @@
  * Owns the auth lifecycle: pulls credentials from auth.ts, attaches the
  * Bearer header, refreshes on 401, retries once. Beyond that, the wire
  * format matches the OpenAPI spec exactly — no client-side renaming.
+ *
+ * Credentials are resolved lazily — on the first request, not at module
+ * load — so that a missing or pending device flow surfaces as a tool
+ * error (DeviceFlowPendingError carries the URL the user must visit),
+ * never as a four-minute hang while the MCP host waits for the stdio
+ * server to respond.
  */
 import { ensureCredentials, forceRefresh } from "./auth.js";
 export function createApiClient(options) {
-    let credsPromise = ensureCredentials(options.baseUrl, options.clientName);
     async function request(method, path, body, headers = {}) {
-        let creds = await credsPromise;
+        // Lazy — only kicks the device flow when a tool actually needs the
+        // API. Missing/pending credentials surface as DeviceFlowPendingError
+        // (handled by the MCP server wrapper), not a hung Promise.
+        let creds = await ensureCredentials(options.baseUrl, options.clientName);
         let res = await fetch(`${creds.baseUrl}${path}`, {
             method,
             headers: {
@@ -22,7 +30,6 @@ export function createApiClient(options) {
         if (res.status === 401) {
             // Stale access token; refresh and retry once.
             creds = await forceRefresh(creds);
-            credsPromise = Promise.resolve(creds);
             res = await fetch(`${creds.baseUrl}${path}`, {
                 method,
                 headers: {
@@ -61,8 +68,8 @@ export function createApiClient(options) {
         getFile: (id) => request("GET", `/api/v1/files/${id}`),
         getFileContent: async (id) => {
             const json = await request("GET", `/api/v1/files/${id}/content?as=base64`);
-            const html = Buffer.from(json.contentBase64, "base64").toString("utf8");
-            return { name: json.name, html };
+            const content = Buffer.from(json.contentBase64, "base64").toString("utf8");
+            return { name: json.name, content, format: json.format };
         },
         createFile: (input) => request("POST", "/api/v1/files", input),
         updateFile: (id, input) => request("PATCH", `/api/v1/files/${id}`, input),

package/dist/auth.d.ts

@@ -1,17 +1,27 @@
 /**
  * OAuth 2.0 device-authorization flow for @reidar80/webshelf-mcp.
  *
- * Reads/writes a credentials JSON file at:
- *   $WEBSHELF_CREDENTIALS_FILE  (when set)
+ * Reads/writes credentials JSON files at:
+ *   $WEBSHELF_CREDENTIALS_FILE  (when set, base path)
  *   ~/.webshelf/credentials.json (otherwise)
  *
- * The credentials file contains the refresh + access tokens issued at
- * the end of the device flow. The MCP server consults it on every API
- * call and silently refreshes the access token when it's within 60s of
- * expiry (or when the server returns 401).
+ * Two files are involved:
+ *   • credentials.json — the live access + refresh tokens.
+ *   • credentials.pending.json — an in-progress device flow (device_code +
+ *     verification URL) waiting for the human to approve in their browser.
  *
- * Bare tokens never leave this file — they're returned only to the
- * fetch wrapper in `api.ts`.
+ * Why a pending file: when the MCP server runs under a host like Claude
+ * Desktop, stderr is captured to a log file the user never opens. If we
+ * blocked the first tool call on a 10-minute polling loop (RFC 8628's
+ * device-code TTL), the MCP client times out after a few minutes with a
+ * "server unresponsive" error — and the user never sees the verification
+ * URL printed to stderr. Instead, we fast-fail the first tool call with
+ * the URL in the error message (which the MCP client surfaces verbatim
+ * to the user). The user approves in their browser, retries any tool,
+ * and the retry exchanges the device_code for tokens in one shot.
+ *
+ * Bare tokens never leave this module — they're returned only via the
+ * `Credentials` object to the fetch wrapper in `api.ts`.
  */
 interface Credentials {
     accessToken: string;
@@ -23,6 +33,18 @@ interface Credentials {
     /** Base URL of the Webshelf instance these tokens belong to. */
     baseUrl: string;
 }
+interface PendingDeviceFlow {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string;
+    /** epoch ms when the device_code stops being redeemable. */
+    expiresAtMs: number;
+    /** Base URL the device flow was started against. */
+    baseUrl: string;
+    /** Label the user picked when launching the flow. */
+    clientName: string;
+}
 export interface DeviceFlowOptions {
     baseUrl: string;
     clientName: string;
@@ -30,14 +52,23 @@ export interface DeviceFlowOptions {
     log?: (line: string) => void;
 }
 /**
- * Run the OAuth device flow and persist the resulting tokens. Resolves
- * with the live credentials. Rejects if the user denies, the device
- * code expires, or the network breaks.
+ * Thrown when the caller has no credentials and must approve the device
+ * flow in their browser. Carries the verification URL so the MCP client
+ * can show it to the user verbatim. After approval, retrying any tool
+ * resumes the flow via {@link tryCompletePending}.
  */
-export declare function runDeviceFlow(options: DeviceFlowOptions): Promise<Credentials>;
+export declare class DeviceFlowPendingError extends Error {
+    readonly verificationUri: string;
+    readonly verificationUriComplete: string;
+    readonly userCode: string;
+    readonly expiresAtMs: number;
+    constructor(pending: PendingDeviceFlow);
+}
 /**
- * Return a live credentials object, refreshing if needed. Initiates the
- * device flow when no credentials are present on disk yet.
+ * Return live credentials or throw {@link DeviceFlowPendingError} when
+ * the user needs to approve the flow first. Never blocks for more than a
+ * single HTTP round trip — the long poll that would happen in a vanilla
+ * device flow is replaced by "throw → user approves → retry → redeem".
  */
 export declare function ensureCredentials(baseUrl: string, clientName: string): Promise<Credentials>;
 /** Force a refresh, used by the API client on 401. */

package/dist/auth.js

@@ -1,19 +1,29 @@
 /**
  * OAuth 2.0 device-authorization flow for @reidar80/webshelf-mcp.
  *
- * Reads/writes a credentials JSON file at:
- *   $WEBSHELF_CREDENTIALS_FILE  (when set)
+ * Reads/writes credentials JSON files at:
+ *   $WEBSHELF_CREDENTIALS_FILE  (when set, base path)
  *   ~/.webshelf/credentials.json (otherwise)
  *
- * The credentials file contains the refresh + access tokens issued at
- * the end of the device flow. The MCP server consults it on every API
- * call and silently refreshes the access token when it's within 60s of
- * expiry (or when the server returns 401).
+ * Two files are involved:
+ *   • credentials.json — the live access + refresh tokens.
+ *   • credentials.pending.json — an in-progress device flow (device_code +
+ *     verification URL) waiting for the human to approve in their browser.
  *
- * Bare tokens never leave this file — they're returned only to the
- * fetch wrapper in `api.ts`.
+ * Why a pending file: when the MCP server runs under a host like Claude
+ * Desktop, stderr is captured to a log file the user never opens. If we
+ * blocked the first tool call on a 10-minute polling loop (RFC 8628's
+ * device-code TTL), the MCP client times out after a few minutes with a
+ * "server unresponsive" error — and the user never sees the verification
+ * URL printed to stderr. Instead, we fast-fail the first tool call with
+ * the URL in the error message (which the MCP client surfaces verbatim
+ * to the user). The user approves in their browser, retries any tool,
+ * and the retry exchanges the device_code for tokens in one shot.
+ *
+ * Bare tokens never leave this module — they're returned only via the
+ * `Credentials` object to the fetch wrapper in `api.ts`.
  */
-import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { mkdir, readFile, unlink, writeFile, chmod } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 const REFRESH_LEAD_TIME_MS = 60 * 1000;
@@ -23,6 +33,9 @@ function credentialsPath() {
         return explicit;
     return join(homedir(), ".webshelf", "credentials.json");
 }
+function pendingPath() {
+    return credentialsPath().replace(/\.json$/, ".pending.json");
+}
 async function readCredentials() {
     try {
         const buf = await readFile(credentialsPath(), "utf8");
@@ -44,8 +57,36 @@ async function writeCredentials(creds) {
     const path = credentialsPath();
     await mkdir(dirname(path), { recursive: true });
     await writeFile(path, JSON.stringify(creds, null, 2), "utf8");
-    // Try to lock down permissions to the current user. chmod is a no-op
-    // on Windows but harmless.
+    try {
+        await chmod(path, 0o600);
+    }
+    catch {
+        // chmod is a no-op on Windows but harmless.
+    }
+}
+async function readPending() {
+    try {
+        const buf = await readFile(pendingPath(), "utf8");
+        const parsed = JSON.parse(buf);
+        if (typeof parsed?.deviceCode === "string" &&
+            typeof parsed?.userCode === "string" &&
+            typeof parsed?.verificationUri === "string" &&
+            typeof parsed?.verificationUriComplete === "string" &&
+            typeof parsed?.expiresAtMs === "number" &&
+            typeof parsed?.baseUrl === "string" &&
+            typeof parsed?.clientName === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+async function writePending(pending) {
+    const path = pendingPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(pending, null, 2), "utf8");
     try {
         await chmod(path, 0o600);
     }
@@ -53,76 +94,109 @@ async function writeCredentials(creds) {
         // ignore
     }
 }
+async function clearPending() {
+    try {
+        await unlink(pendingPath());
+    }
+    catch {
+        // already gone
+    }
+}
 /**
- * Run the OAuth device flow and persist the resulting tokens. Resolves
- * with the live credentials. Rejects if the user denies, the device
- * code expires, or the network breaks.
+ * Thrown when the caller has no credentials and must approve the device
+ * flow in their browser. Carries the verification URL so the MCP client
+ * can show it to the user verbatim. After approval, retrying any tool
+ * resumes the flow via {@link tryCompletePending}.
  */
-export async function runDeviceFlow(options) {
-    const log = options.log ?? ((line) => process.stderr.write(`${line}\n`));
-    const start = await fetch(`${options.baseUrl}/api/oauth/device`, {
+export class DeviceFlowPendingError extends Error {
+    verificationUri;
+    verificationUriComplete;
+    userCode;
+    expiresAtMs;
+    constructor(pending) {
+        super([
+            "Webshelf needs you to authorize this MCP server before it can act on your behalf.",
+            "",
+            `  1. Open: ${pending.verificationUriComplete}`,
+            `     (or visit ${pending.verificationUri} and enter code ${pending.userCode})`,
+            "  2. Approve in your browser.",
+            "  3. Retry the tool call — it will complete automatically.",
+        ].join("\n"));
+        this.name = "DeviceFlowPendingError";
+        this.verificationUri = pending.verificationUri;
+        this.verificationUriComplete = pending.verificationUriComplete;
+        this.userCode = pending.userCode;
+        this.expiresAtMs = pending.expiresAtMs;
+    }
+}
+/**
+ * Start a device flow and write the pending state. Returns the pending
+ * record so the caller can decide whether to throw it as a user-visible
+ * error or wait on it. Does NOT poll.
+ */
+async function startDeviceFlow(baseUrl, clientName) {
+    const start = await fetch(`${baseUrl}/api/oauth/device`, {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ client_name: options.clientName }),
+        body: JSON.stringify({ client_name: clientName }),
     });
     if (!start.ok) {
         throw new Error(`device authorization failed: HTTP ${start.status} ${await start.text()}`);
     }
     const auth = (await start.json());
-    log("");
-    log("┌─ Webshelf authorization ──────────────────────────────");
-    log(`│ Open this URL in your browser:`);
-    log(`│   ${auth.verification_uri_complete}`);
-    log(`│`);
-    log(`│ Or visit ${auth.verification_uri} and enter the code:`);
-    log(`│   ${auth.user_code}`);
-    log("└────────────────────────────────────────────────────────");
-    log("");
-    const deadline = Date.now() + auth.expires_in * 1000;
-    let interval = auth.interval;
-    while (Date.now() < deadline) {
-        await sleep(interval * 1000);
-        const res = await fetch(`${options.baseUrl}/api/oauth/token`, {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({
-                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
-                device_code: auth.device_code,
-            }),
-        });
-        if (res.ok) {
-            const tokens = (await res.json());
-            const creds = {
-                accessToken: tokens.access_token,
-                refreshToken: tokens.refresh_token,
-                accessExpiresAtMs: Date.now() + tokens.expires_in * 1000,
-                refreshExpiresAtMs: Date.now() + (tokens.refresh_expires_in ?? 30 * 24 * 60 * 60) * 1000,
-                baseUrl: options.baseUrl,
-            };
-            await writeCredentials(creds);
-            log("Authorization complete. Token stored.");
-            return creds;
-        }
-        const body = (await res
-            .json()
-            .catch(() => ({ error: "unknown" })));
-        if (body.error === "authorization_pending") {
-            // keep polling
-            continue;
-        }
-        if (body.error === "slow_down") {
-            // RFC 8628 §3.5: bump the interval by 5s and keep polling.
-            interval += 5;
-            continue;
-        }
-        throw new Error(`device authorization rejected: ${body.error}${body.error_description ? ` (${body.error_description})` : ""}`);
+    const pending = {
+        deviceCode: auth.device_code,
+        userCode: auth.user_code,
+        verificationUri: auth.verification_uri,
+        verificationUriComplete: auth.verification_uri_complete,
+        expiresAtMs: Date.now() + auth.expires_in * 1000,
+        baseUrl,
+        clientName,
+    };
+    await writePending(pending);
+    // Best-effort stderr breadcrumb so headless runs (CLI tail -f) and host
+    // log files contain the URL even when no tool has been called yet.
+    process.stderr.write(`\nWebshelf authorization required.\n  Visit: ${pending.verificationUriComplete}\n  Code:  ${pending.userCode}\n\n`);
+    return pending;
+}
+/**
+ * Attempt to redeem a pending device_code exactly once. Returns the new
+ * credentials on success, null when the user hasn't approved yet, and
+ * throws when the device code expired or the flow was rejected (in
+ * which case the caller should restart).
+ */
+async function tryRedeemDeviceCode(pending) {
+    const res = await fetch(`${pending.baseUrl}/api/oauth/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+            device_code: pending.deviceCode,
+        }),
+    });
+    if (res.ok) {
+        const tokens = (await res.json());
+        const creds = {
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            accessExpiresAtMs: Date.now() + tokens.expires_in * 1000,
+            refreshExpiresAtMs: Date.now() + (tokens.refresh_expires_in ?? 30 * 24 * 60 * 60) * 1000,
+            baseUrl: pending.baseUrl,
+        };
+        return creds;
+    }
+    const body = (await res.json().catch(() => ({ error: "unknown" })));
+    if (body.error === "authorization_pending" || body.error === "slow_down") {
+        return null;
     }
-    throw new Error("device code expired before user approval");
+    // expired_token / access_denied / unknown — caller should drop pending
+    // state and restart from scratch.
+    throw new Error(`device authorization rejected: ${body.error ?? "unknown"}${body.error_description ? ` (${body.error_description})` : ""}`);
 }
 /**
  * Refresh an expired or near-expired access token. Returns the updated
  * credentials. Throws if the refresh token itself has expired or been
- * revoked — caller should re-run the device flow in that case.
+ * revoked — caller should clear credentials and re-run the device flow.
  */
 async function refreshAccessToken(creds) {
     const res = await fetch(`${creds.baseUrl}/api/oauth/token`, {
@@ -148,23 +222,54 @@ async function refreshAccessToken(creds) {
     return next;
 }
 /**
- * Return a live credentials object, refreshing if needed. Initiates the
- * device flow when no credentials are present on disk yet.
+ * Return live credentials or throw {@link DeviceFlowPendingError} when
+ * the user needs to approve the flow first. Never blocks for more than a
+ * single HTTP round trip — the long poll that would happen in a vanilla
+ * device flow is replaced by "throw → user approves → retry → redeem".
  */
 export async function ensureCredentials(baseUrl, clientName) {
-    let creds = await readCredentials();
-    if (!creds || creds.baseUrl !== baseUrl) {
-        creds = await runDeviceFlow({ baseUrl, clientName });
+    // 1. Live credentials? Refresh if they're stale and return.
+    const existing = await readCredentials();
+    if (existing && existing.baseUrl === baseUrl) {
+        if (existing.accessExpiresAtMs - Date.now() < REFRESH_LEAD_TIME_MS) {
+            const refreshed = await refreshAccessToken(existing);
+            await writeCredentials(refreshed);
+            return refreshed;
+        }
+        return existing;
     }
-    if (creds.accessExpiresAtMs - Date.now() < REFRESH_LEAD_TIME_MS) {
-        creds = await refreshAccessToken(creds);
+    // 2. Pending flow? Try to complete it — but bounce out fast if not
+    //    ready. The user might still be in the browser; better to surface
+    //    the URL than to hold the MCP transport hostage.
+    let pending = await readPending();
+    if (pending && pending.baseUrl === baseUrl && pending.expiresAtMs > Date.now()) {
+        try {
+            const redeemed = await tryRedeemDeviceCode(pending);
+            if (redeemed) {
+                await writeCredentials(redeemed);
+                await clearPending();
+                return redeemed;
+            }
+        }
+        catch (err) {
+            // Device code expired or was denied — fall through to start a new one.
+            await clearPending();
+            pending = null;
+            // Stick the failure on stderr so logs explain why we restarted.
+            process.stderr.write(`[webshelf-mcp] pending device flow rejected (${err instanceof Error ? err.message : String(err)}); restarting.\n`);
+        }
+        if (pending)
+            throw new DeviceFlowPendingError(pending);
     }
-    return creds;
+    // 3. Nothing live or pending — kick off a new flow and bail out so the
+    //    user can approve. Their next tool call lands in branch (2).
+    if (pending && pending.expiresAtMs <= Date.now()) {
+        await clearPending();
+    }
+    const fresh = await startDeviceFlow(baseUrl, clientName);
+    throw new DeviceFlowPendingError(fresh);
 }
 /** Force a refresh, used by the API client on 401. */
 export async function forceRefresh(creds) {
     return refreshAccessToken(creds);
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/dist/index.d.ts

@@ -17,8 +17,8 @@
  *   webshelf_list_collections — list collections the caller can write to
  *   webshelf_list_files     — list files (own / by collection)
  *   webshelf_get_file       — metadata for a single file
- *   webshelf_read_file      — fetch HTML contents
- *   webshelf_create_file    — upload a new HTML file
+ *   webshelf_read_file      — fetch file contents (HTML or markdown)
+ *   webshelf_create_file    — upload a new HTML or markdown file
  *   webshelf_update_file    — rename / move / re-describe
  *   webshelf_delete_file    — soft-delete a file (recycle bin)
  */

package/dist/index.js

@@ -17,8 +17,8 @@
  *   webshelf_list_collections — list collections the caller can write to
  *   webshelf_list_files     — list files (own / by collection)
  *   webshelf_get_file       — metadata for a single file
- *   webshelf_read_file      — fetch HTML contents
- *   webshelf_create_file    — upload a new HTML file
+ *   webshelf_read_file      — fetch file contents (HTML or markdown)
+ *   webshelf_create_file    — upload a new HTML or markdown file
  *   webshelf_update_file    — rename / move / re-describe
  *   webshelf_delete_file    — soft-delete a file (recycle bin)
  */
@@ -84,7 +84,7 @@ const tools = [
                 .parse(input ?? {});
             const { files, nextCursor } = await client.listFiles(parsed);
             const body = files
-                .map((f) => `${f.id}  ${JSON.stringify(f.name)}  collection=${f.collectionId ?? "(personal)"}  ${formatBytes(f.sizeBytes)}  ${f.protection}  updated=${f.updatedAt}`)
+                .map((f) => `${f.id}  ${JSON.stringify(f.name)}  format=${f.format}  collection=${f.collectionId ?? "(personal)"}  ${formatBytes(f.sizeBytes)}  ${f.protection}  updated=${f.updatedAt}`)
                 .join("\n") || "(no files match)";
             return text(nextCursor ? `${body}\n\nnextCursor=${nextCursor}` : body);
         },
@@ -108,7 +108,7 @@ const tools = [
     },
     {
         name: "webshelf_read_file",
-        description: "Return the HTML body of a file by id. The response is returned as a text block; the MCP client can save it, render it, or feed it back into a tool call.",
+        description: "Return the contents of a file by id. Returns the raw source — HTML for `format=html` files, markdown for `format=markdown` files. The response is a text block; the MCP client can save it, render it, or feed it back into a tool call.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
@@ -119,17 +119,18 @@ const tools = [
         },
         handler: async (input) => {
             const { id } = z.object({ id: z.string().uuid() }).parse(input);
-            const { html, name } = await client.getFileContent(id);
-            return text(`Filename: ${name}.html\n\n${html}`);
+            const { content, name, format } = await client.getFileContent(id);
+            const ext = format === "markdown" ? "md" : "html";
+            return text(`Filename: ${name}.${ext}\nFormat: ${format}\n\n${content}`);
         },
     },
     {
         name: "webshelf_create_file",
-        description: "Upload a new HTML file. Set collectionId to a uuid to place inside a collection (caller must be owner/manager), or null for a standalone personal file. Returns the created file's metadata.",
+        description: "Upload a new file. `format` may be \"html\" (default) or \"markdown\"; pass the bytes in `content`. Set collectionId to a uuid to place inside a collection (caller must be owner/manager), or null for a standalone personal file. Returns the created file's metadata.",
         inputSchema: {
             type: "object",
             additionalProperties: false,
-            required: ["name", "html"],
+            required: ["name", "content"],
             properties: {
                 name: { type: "string", minLength: 1, maxLength: 200 },
                 description: { type: "string", maxLength: 2000 },
@@ -138,7 +139,8 @@ const tools = [
                     type: "string",
                     enum: ["public", "authenticated", "inherit", "individual"],
                 },
-                html: { type: "string" },
+                format: { type: "string", enum: ["html", "markdown"] },
+                content: { type: "string" },
             },
         },
         handler: async (input) => {
@@ -150,11 +152,12 @@ const tools = [
                 protection: z
                     .enum(["public", "authenticated", "inherit", "individual"])
                     .optional(),
-                html: z.string().min(1),
+                format: z.enum(["html", "markdown"]).optional(),
+                content: z.string().min(1),
             })
                 .parse(input);
             const { file } = await client.createFile(parsed);
-            return text(`Created file ${file.id} (${file.name}) — ${formatBytes(file.sizeBytes)}\n${BASE_URL}/app/files/${file.id}`);
+            return text(`Created ${file.format} file ${file.id} (${file.name}) — ${formatBytes(file.sizeBytes)}\n${BASE_URL}/app/files/${file.id}`);
         },
     },
     {
@@ -203,7 +206,7 @@ const tools = [
 ];
 const server = new Server({
     name: "@reidar80/webshelf-mcp",
-    version: "0.1.0",
+    version: "0.2.2",
 }, {
     capabilities: {
         tools: {},
@@ -252,7 +255,57 @@ function formatBytes(n) {
         return `${(n / 1024).toFixed(1)} KB`;
     return `${(n / (1024 * 1024)).toFixed(2)} MB`;
 }
+async function runCliAuthFlow() {
+    // Manual / interactive authorization: kick off a device flow, print
+    // the verification URL to stdout, and poll until the user approves
+    // (or the device_code expires). Reuses the same `ensureCredentials`
+    // surface as the stdio handlers, but in a loop so the CLI can sit
+    // and wait — the 4-minute MCP-host timeout doesn't apply here.
+    const { ensureCredentials, DeviceFlowPendingError } = await import("./auth.js");
+    process.stdout.write("\n┌─ Webshelf authorization ──────────────────\n");
+    // Each iteration: ensureCredentials either returns creds (done) or
+    // throws DeviceFlowPendingError (still waiting). We poll every 3s.
+    const pollIntervalMs = 3000;
+    // RFC 8628 device-code TTL ceiling; we'll give up earlier if the
+    // server signals expiry via ensureCredentials throwing a non-pending
+    // error and re-starting the flow.
+    const deadline = Date.now() + 11 * 60 * 1000;
+    let lastPrinted = null;
+    while (Date.now() < deadline) {
+        try {
+            await ensureCredentials(BASE_URL, CLIENT_NAME);
+            process.stdout.write("│ Authorization complete. Token stored.\n└────────────────────────────────────────\n");
+            return;
+        }
+        catch (err) {
+            if (err instanceof DeviceFlowPendingError) {
+                if (lastPrinted !== err.verificationUriComplete) {
+                    process.stdout.write(`│ Open this URL in your browser:\n`);
+                    process.stdout.write(`│   ${err.verificationUriComplete}\n`);
+                    process.stdout.write(`│ Or visit ${err.verificationUri}\n`);
+                    process.stdout.write(`│ and enter code ${err.userCode}\n│\n`);
+                    process.stdout.write(`│ Waiting for approval…\n`);
+                    lastPrinted = err.verificationUriComplete;
+                }
+                await new Promise((r) => setTimeout(r, pollIntervalMs));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw new Error("device code expired before user approval");
+}
 async function main() {
+    // If a human is at the terminal (no MCP host piping stdio) and the
+    // first positional arg is `auth`, or stdin is a TTY without args at
+    // all, run the device flow eagerly so they can authorize from the
+    // command line. Otherwise speak stdio MCP as normal.
+    const arg = process.argv[2];
+    const interactive = arg === "auth" || (!arg && process.stdin.isTTY === true);
+    if (interactive) {
+        await runCliAuthFlow();
+        return;
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reidar80/webshelf-mcp",
-  "version": "0.1.0",
-  "description": "Model Context Protocol server for Webshelf — list, read, upload and manage HTML files hosted on webshelf.app from any MCP-aware client.",
+  "version": "0.2.2",
+  "description": "Model Context Protocol server for Webshelf — list, read, upload and manage HTML and markdown files hosted on webshelf.app from any MCP-aware client.",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -12,11 +12,10 @@
   "homepage": "https://webshelf.app",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/reidar80/webshelf.git",
-    "directory": "mcp"
+    "url": "git+https://github.com/reidar80/webshelf-mcp.git"
   },
   "bugs": {
-    "url": "https://github.com/reidar80/webshelf/issues"
+    "url": "https://github.com/reidar80/webshelf-mcp/issues"
   },
   "license": "MIT",
   "author": "Webshelf",