@reidar80/webshelf-mcp 0.1.0

package/README.md

@@ -0,0 +1,93 @@
+# @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.
+
+## Install
+
+The package runs as a one-off via `npx`, so most users don't install it
+globally:
+
+```bash
+npx -y @reidar80/webshelf-mcp
+```
+
+Or pin a version in your MCP client config (preferred for stability).
+
+## Configure your MCP client
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and
+add:
+
+```json
+{
+  "mcpServers": {
+    "webshelf": {
+      "command": "npx",
+      "args": ["-y", "@reidar80/webshelf-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude. The first time the server starts, it prints a URL to
+stderr — open it, sign in to Webshelf, and approve the connection.
+
+### Other clients
+
+Anything that runs MCP servers over stdio works the same way. Point it
+at `npx -y @reidar80/webshelf-mcp`.
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `WEBSHELF_BASE_URL` | `https://webshelf.app` | Override for staging / self-hosted instances. |
+| `WEBSHELF_CLIENT_NAME` | `MCP (<hostname>)` | Label that shows up on your "API sessions" page. |
+| `WEBSHELF_CREDENTIALS_FILE` | `~/.webshelf/credentials.json` | Where the OAuth tokens are cached. |
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `webshelf_whoami` | Identity sanity check. |
+| `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_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):
+
+1. It calls `POST /api/oauth/device` to get a one-time `user_code`.
+2. It prints the verification URL + code to stderr.
+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).
+
+The access token has a 1-hour TTL and refreshes automatically. To
+revoke a session, visit **Settings → API sessions** on webshelf.app and
+hit "Revoke" on the matching row.
+
+## Permissions
+
+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.
+
+## 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).

package/dist/api.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Thin typed client around Webshelf's `/api/v1/*` surface.
+ *
+ * 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.
+ */
+export interface ApiFile {
+    id: string;
+    name: string;
+    description: string | null;
+    collectionId: string | null;
+    ownerId: string;
+    protection: "public" | "authenticated" | "inherit" | "individual";
+    sizeBytes: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+export interface ApiCollection {
+    id: string;
+    name: string;
+    ownerId: string;
+    companyId: string | null;
+    company: {
+        id: string;
+        name: string;
+        slug: string;
+    } | null;
+    protection: "private" | "public";
+    createdAt: string;
+}
+export interface ApiClient {
+    me(): Promise<{
+        user: {
+            id: string;
+            email: string;
+            displayName: string | null;
+        };
+    }>;
+    listFiles(params?: {
+        collectionId?: string;
+        personal?: boolean;
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        files: ApiFile[];
+        nextCursor: string | null;
+    }>;
+    getFile(id: string): Promise<{
+        file: ApiFile;
+    }>;
+    getFileContent(id: string): Promise<{
+        name: string;
+        html: string;
+    }>;
+    createFile(input: {
+        name: string;
+        description?: string | null;
+        collectionId: string | null;
+        protection?: ApiFile["protection"];
+        html: string;
+    }): Promise<{
+        file: ApiFile;
+    }>;
+    updateFile(id: string, input: {
+        name?: string;
+        description?: string | null;
+        collectionId?: string | null;
+    }): Promise<{
+        file: ApiFile;
+    }>;
+    deleteFile(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    listCollections(): Promise<{
+        collections: ApiCollection[];
+    }>;
+}
+export declare function createApiClient(options: {
+    baseUrl: string;
+    clientName: string;
+}): ApiClient;

package/dist/api.js

@@ -0,0 +1,72 @@
+/**
+ * Thin typed client around Webshelf's `/api/v1/*` surface.
+ *
+ * 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.
+ */
+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;
+        let res = await fetch(`${creds.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${creds.accessToken}`,
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                ...headers,
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        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: {
+                    authorization: `Bearer ${creds.accessToken}`,
+                    ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                    ...headers,
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`HTTP ${res.status} ${method} ${path}: ${text}`);
+        }
+        const contentType = res.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            return (await res.json());
+        }
+        return (await res.text());
+    }
+    return {
+        me: () => request("GET", "/api/v1/me"),
+        listFiles: (params = {}) => {
+            const search = new URLSearchParams();
+            if (params.collectionId)
+                search.set("collectionId", params.collectionId);
+            if (params.personal)
+                search.set("personal", "true");
+            if (params.limit)
+                search.set("limit", String(params.limit));
+            if (params.cursor)
+                search.set("cursor", params.cursor);
+            const qs = search.toString();
+            return request("GET", `/api/v1/files${qs ? `?${qs}` : ""}`);
+        },
+        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 };
+        },
+        createFile: (input) => request("POST", "/api/v1/files", input),
+        updateFile: (id, input) => request("PATCH", `/api/v1/files/${id}`, input),
+        deleteFile: (id) => request("DELETE", `/api/v1/files/${id}`),
+        listCollections: () => request("GET", "/api/v1/collections"),
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OAuth 2.0 device-authorization flow for @reidar80/webshelf-mcp.
+ *
+ * Reads/writes a credentials JSON file at:
+ *   $WEBSHELF_CREDENTIALS_FILE  (when set)
+ *   ~/.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).
+ *
+ * Bare tokens never leave this file — they're returned only to the
+ * fetch wrapper in `api.ts`.
+ */
+interface Credentials {
+    accessToken: string;
+    refreshToken: string;
+    /** epoch ms when `accessToken` expires. */
+    accessExpiresAtMs: number;
+    /** epoch ms when `refreshToken` expires. */
+    refreshExpiresAtMs: number;
+    /** Base URL of the Webshelf instance these tokens belong to. */
+    baseUrl: string;
+}
+export interface DeviceFlowOptions {
+    baseUrl: string;
+    clientName: string;
+    /** Print the user instructions / poll progress. Defaults to stderr. */
+    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.
+ */
+export declare function runDeviceFlow(options: DeviceFlowOptions): Promise<Credentials>;
+/**
+ * Return a live credentials object, refreshing if needed. Initiates the
+ * device flow when no credentials are present on disk yet.
+ */
+export declare function ensureCredentials(baseUrl: string, clientName: string): Promise<Credentials>;
+/** Force a refresh, used by the API client on 401. */
+export declare function forceRefresh(creds: Credentials): Promise<Credentials>;
+export {};

package/dist/auth.js

@@ -0,0 +1,170 @@
+/**
+ * OAuth 2.0 device-authorization flow for @reidar80/webshelf-mcp.
+ *
+ * Reads/writes a credentials JSON file at:
+ *   $WEBSHELF_CREDENTIALS_FILE  (when set)
+ *   ~/.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).
+ *
+ * Bare tokens never leave this file — they're returned only to the
+ * fetch wrapper in `api.ts`.
+ */
+import { mkdir, readFile, writeFile, chmod } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+const REFRESH_LEAD_TIME_MS = 60 * 1000;
+function credentialsPath() {
+    const explicit = process.env.WEBSHELF_CREDENTIALS_FILE;
+    if (explicit)
+        return explicit;
+    return join(homedir(), ".webshelf", "credentials.json");
+}
+async function readCredentials() {
+    try {
+        const buf = await readFile(credentialsPath(), "utf8");
+        const parsed = JSON.parse(buf);
+        if (typeof parsed?.accessToken === "string" &&
+            typeof parsed?.refreshToken === "string" &&
+            typeof parsed?.accessExpiresAtMs === "number" &&
+            typeof parsed?.refreshExpiresAtMs === "number" &&
+            typeof parsed?.baseUrl === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+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 {
+        // ignore
+    }
+}
+/**
+ * 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.
+ */
+export async function runDeviceFlow(options) {
+    const log = options.log ?? ((line) => process.stderr.write(`${line}\n`));
+    const start = await fetch(`${options.baseUrl}/api/oauth/device`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ client_name: options.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})` : ""}`);
+    }
+    throw new Error("device code expired before user approval");
+}
+/**
+ * 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.
+ */
+async function refreshAccessToken(creds) {
+    const res = await fetch(`${creds.baseUrl}/api/oauth/token`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            grant_type: "refresh_token",
+            refresh_token: creds.refreshToken,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`refresh failed: HTTP ${res.status} ${await res.text()}; re-run device flow`);
+    }
+    const tokens = (await res.json());
+    const next = {
+        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: creds.baseUrl,
+    };
+    await writeCredentials(next);
+    return next;
+}
+/**
+ * Return a live credentials object, refreshing if needed. Initiates the
+ * device flow when no credentials are present on disk yet.
+ */
+export async function ensureCredentials(baseUrl, clientName) {
+    let creds = await readCredentials();
+    if (!creds || creds.baseUrl !== baseUrl) {
+        creds = await runDeviceFlow({ baseUrl, clientName });
+    }
+    if (creds.accessExpiresAtMs - Date.now() < REFRESH_LEAD_TIME_MS) {
+        creds = await refreshAccessToken(creds);
+    }
+    return creds;
+}
+/** 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

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * @reidar80/webshelf-mcp — Model Context Protocol server for Webshelf.
+ *
+ * Speaks MCP over stdio. The first run launches the OAuth 2.0 device
+ * flow against `WEBSHELF_BASE_URL` (default https://webshelf.app), prints
+ * a one-time URL the user opens in their browser, then waits for the
+ * polling exchange to succeed before serving any tool calls.
+ *
+ * Environment variables:
+ *   WEBSHELF_BASE_URL          — defaults to https://webshelf.app
+ *   WEBSHELF_CLIENT_NAME       — defaults to "MCP (<hostname>)"
+ *   WEBSHELF_CREDENTIALS_FILE  — override credentials cache location
+ *
+ * Tools exposed to the MCP client:
+ *   webshelf_whoami         — verify the session and surface identity
+ *   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_update_file    — rename / move / re-describe
+ *   webshelf_delete_file    — soft-delete a file (recycle bin)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * @reidar80/webshelf-mcp — Model Context Protocol server for Webshelf.
+ *
+ * Speaks MCP over stdio. The first run launches the OAuth 2.0 device
+ * flow against `WEBSHELF_BASE_URL` (default https://webshelf.app), prints
+ * a one-time URL the user opens in their browser, then waits for the
+ * polling exchange to succeed before serving any tool calls.
+ *
+ * Environment variables:
+ *   WEBSHELF_BASE_URL          — defaults to https://webshelf.app
+ *   WEBSHELF_CLIENT_NAME       — defaults to "MCP (<hostname>)"
+ *   WEBSHELF_CREDENTIALS_FILE  — override credentials cache location
+ *
+ * Tools exposed to the MCP client:
+ *   webshelf_whoami         — verify the session and surface identity
+ *   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_update_file    — rename / move / re-describe
+ *   webshelf_delete_file    — soft-delete a file (recycle bin)
+ */
+import { hostname } from "node:os";
+import { z } from "zod";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createApiClient } from "./api.js";
+const BASE_URL = process.env.WEBSHELF_BASE_URL?.replace(/\/$/, "") ?? "https://webshelf.app";
+const CLIENT_NAME = process.env.WEBSHELF_CLIENT_NAME ?? `MCP (${hostname()})`;
+const client = createApiClient({ baseUrl: BASE_URL, clientName: CLIENT_NAME });
+const tools = [
+    {
+        name: "webshelf_whoami",
+        description: "Return the email and id of the Webshelf user the MCP server is acting on behalf of. Use as a connectivity sanity check.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {},
+        },
+        handler: async () => {
+            const { user } = await client.me();
+            return text(`Signed in as ${user.email} (${user.displayName ?? "no display name"})`);
+        },
+    },
+    {
+        name: "webshelf_list_collections",
+        description: "List collections the authenticated user can see, including which workspace they belong to. Returns id, name, workspace, and protection.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {},
+        },
+        handler: async () => {
+            const { collections } = await client.listCollections();
+            return text(collections
+                .map((c) => `${c.id}  ${JSON.stringify(c.name)}  workspace=${c.company?.slug ?? "(personal)"}  protection=${c.protection}`)
+                .join("\n") || "(no collections visible)");
+        },
+    },
+    {
+        name: "webshelf_list_files",
+        description: "List files. By default returns the caller's own files across all collections. Pass collectionId to list files inside a specific collection (caller must be a member). Pass personal=true to limit to standalone personal files.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                collectionId: { type: "string", format: "uuid" },
+                personal: { type: "boolean" },
+                limit: { type: "integer", minimum: 1, maximum: 100 },
+                cursor: { type: "string", format: "date-time" },
+            },
+        },
+        handler: async (input) => {
+            const parsed = z
+                .object({
+                collectionId: z.string().uuid().optional(),
+                personal: z.boolean().optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+                cursor: z.string().datetime().optional(),
+            })
+                .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}`)
+                .join("\n") || "(no files match)";
+            return text(nextCursor ? `${body}\n\nnextCursor=${nextCursor}` : body);
+        },
+    },
+    {
+        name: "webshelf_get_file",
+        description: "Get metadata for a single file by id (no body). Use webshelf_read_file to retrieve the HTML payload.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["id"],
+            properties: {
+                id: { type: "string", format: "uuid" },
+            },
+        },
+        handler: async (input) => {
+            const { id } = z.object({ id: z.string().uuid() }).parse(input);
+            const { file } = await client.getFile(id);
+            return text(JSON.stringify(file, null, 2));
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["id"],
+            properties: {
+                id: { type: "string", format: "uuid" },
+            },
+        },
+        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}`);
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name", "html"],
+            properties: {
+                name: { type: "string", minLength: 1, maxLength: 200 },
+                description: { type: "string", maxLength: 2000 },
+                collectionId: { type: ["string", "null"], format: "uuid" },
+                protection: {
+                    type: "string",
+                    enum: ["public", "authenticated", "inherit", "individual"],
+                },
+                html: { type: "string" },
+            },
+        },
+        handler: async (input) => {
+            const parsed = z
+                .object({
+                name: z.string().min(1).max(200),
+                description: z.string().max(2000).optional(),
+                collectionId: z.string().uuid().nullable().default(null),
+                protection: z
+                    .enum(["public", "authenticated", "inherit", "individual"])
+                    .optional(),
+                html: 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}`);
+        },
+    },
+    {
+        name: "webshelf_update_file",
+        description: "Rename, re-describe, or move a file. Pass only the fields you want to change.",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["id"],
+            properties: {
+                id: { type: "string", format: "uuid" },
+                name: { type: "string", minLength: 1, maxLength: 200 },
+                description: { type: ["string", "null"], maxLength: 2000 },
+                collectionId: { type: ["string", "null"], format: "uuid" },
+            },
+        },
+        handler: async (input) => {
+            const parsed = z
+                .object({
+                id: z.string().uuid(),
+                name: z.string().min(1).max(200).optional(),
+                description: z.string().max(2000).nullable().optional(),
+                collectionId: z.string().uuid().nullable().optional(),
+            })
+                .parse(input);
+            const { id, ...rest } = parsed;
+            const { file } = await client.updateFile(id, rest);
+            return text(`Updated file ${file.id}: ${JSON.stringify(file, null, 2)}`);
+        },
+    },
+    {
+        name: "webshelf_delete_file",
+        description: "Soft-delete a file (moves it to the recycle bin; restorable from the web UI for 30 days).",
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["id"],
+            properties: { id: { type: "string", format: "uuid" } },
+        },
+        handler: async (input) => {
+            const { id } = z.object({ id: z.string().uuid() }).parse(input);
+            await client.deleteFile(id);
+            return text(`Moved ${id} to recycle bin.`);
+        },
+    },
+];
+const server = new Server({
+    name: "@reidar80/webshelf-mcp",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.find((t) => t.name === request.params.name);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [
+                { type: "text", text: `Unknown tool: ${request.params.name}` },
+            ],
+        };
+    }
+    try {
+        const result = await tool.handler(request.params.arguments ?? {});
+        return { content: [result] };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: err instanceof Error ? err.message : String(err),
+                },
+            ],
+        };
+    }
+});
+function text(body) {
+    return { type: "text", text: body };
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`webshelf-mcp failed to start: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "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.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "webshelf",
+    "claude",
+    "ai"
+  ],
+  "homepage": "https://webshelf.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reidar80/webshelf.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/reidar80/webshelf/issues"
+  },
+  "license": "MIT",
+  "author": "Webshelf",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "webshelf-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}