protocontent 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# protocontent
+
+A co-located **stdio MCP server** that lets a coding agent publish local files to
+[protocontent](https://protocontent.com) and get back a tappable, live-updating URL.
+
+Because no MCP primitive lets a remote server read the client's disk (and Claude
+Code doesn't echo the HTTP `Mcp-Session-Id`), protocontent runs as a tiny bridge
+*next to the agent* — on your laptop or on a cloud agent VM. It reads the files you
+want to publish from the local filesystem and uploads them to the protocontent HTTP
+API, while holding a stable per-thread "space" id in memory.
+
+Zero-config: on first run it mints an anonymous project token and caches it to
+`~/.protocontent/config.json`.
+
+## Install / add to your agent
+
+It runs straight from npx — no global install needed.
+
+### Claude Code
+
+```bash
+claude mcp add protocontent -- npx -y protocontent
+```
+
+To pass through a token or a custom API base:
+
+```bash
+claude mcp add protocontent \
+  --env PROTOCONTENT_TOKEN=pc_live_xxx \
+  --env PROTOCONTENT_API=https://api.protocontent.com \
+  -- npx -y protocontent
+```
+
+### Raw MCP server JSON config
+
+For any client that takes an MCP server config block (Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "protocontent": {
+      "command": "npx",
+      "args": ["-y", "protocontent"],
+      "env": {
+        "PROTOCONTENT_TOKEN": "pc_live_xxx",
+        "PROTOCONTENT_API": "https://api.protocontent.com"
+      }
+    }
+  }
+}
+```
+
+Both `env` entries are optional. Omit `PROTOCONTENT_TOKEN` to use a cached or
+freshly-minted anonymous token; omit `PROTOCONTENT_API` to use the default
+(`https://api.protocontent.com`).
+
+This works exactly the same on a **cloud agent VM** — the bridge just needs to run in
+the same place the files live, with network access to the protocontent API.
+
+## Configuration
+
+| Env var               | Default                          | Purpose                                                        |
+| --------------------- | -------------------------------- | -------------------------------------------------------------- |
+| `PROTOCONTENT_API`    | `https://api.protocontent.com`   | Base URL of the protocontent HTTP API.                         |
+| `PROTOCONTENT_TOKEN`  | _(cached / minted)_              | Bearer token. Falls back to `~/.protocontent/config.json`, then to a freshly-minted anonymous project token. |
+| `CLAUDE_SESSION_ID`   | _(unset → random)_               | When set, deterministically seeds this process's space id so it lines up with the agent thread. |
+
+### Spaces
+
+Each running bridge process owns one **space** — a DNS-safe id like
+`amber-canyon-7f3` — generated once at startup and held in memory for the process
+lifetime. When `CLAUDE_SESSION_ID` is present the id is derived deterministically
+from it; otherwise it's random. A `spaceLabel` is derived from the current working
+directory's basename. Everything you publish in a session lands in the same space,
+served at `https://<spaceId>.protocontent.com`, which updates live.
+
+## Tools
+
+| Tool             | Arguments                                  | What it does                                                                 |
+| ---------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
+| `publish_html`   | `{ path?, content?, name?, ttl? }`         | Publish a single file (`path`) or inline `content` — exactly one of them.    |
+| `publish_folder` | `{ dir, entry?, name?, ttl? }`             | Recursively publish a directory (skips `node_modules`, `.git`, dotfiles).    |
+| `list`           | `{}`                                        | List artifacts in this space with URLs and versions.                        |
+| `history`        | `{ name }`                                  | Show an artifact's version history.                                         |
+| `unpublish`      | `{ name }`                                  | Stop an artifact's URL from serving content.                               |
+| `keep`           | `{ name }`                                  | Remove the expiry so an artifact is kept permanently.                       |
+
+Every publish returns a tappable markdown link, the live space URL, and the direct
+artifact URL.
+
+## Develop
+
+```bash
+npm install
+npm run build      # tsc -> dist/
+node dist/index.js # run the stdio server directly (it talks MCP over stdio)
+```
+
+Requires Node 18+ (uses the built-in global `fetch`).
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,73 @@
+// --- low-level request helper -----------------------------------------------
+class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+async function request(config, method, pathName, body) {
+    const url = `${config.apiBase}${pathName}`;
+    const headers = {
+        authorization: `Bearer ${config.token}`,
+        accept: "application/json",
+    };
+    if (body !== undefined) {
+        headers["content-type"] = "application/json";
+    }
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (err) {
+        throw new ApiError(`Network error calling ${method} ${pathName}: ${err.message}`);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        let detail = text;
+        try {
+            const parsed = JSON.parse(text);
+            detail = parsed.error ?? parsed.message ?? text;
+        }
+        catch {
+            // keep raw text
+        }
+        throw new ApiError(`${method} ${pathName} failed (${res.status} ${res.statusText})` +
+            (detail ? `: ${detail}` : ""), res.status, text);
+    }
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ApiError(`${method} ${pathName} returned non-JSON response: ${text.slice(0, 200)}`);
+    }
+}
+function enc(segment) {
+    return encodeURIComponent(segment);
+}
+// --- typed endpoint wrappers -------------------------------------------------
+export async function publish(config, req) {
+    return request(config, "POST", "/v1/publish", req);
+}
+export async function listSpace(config) {
+    return request(config, "GET", `/v1/spaces/${enc(config.spaceId)}/list`);
+}
+export async function artifactHistory(config, name) {
+    return request(config, "GET", `/v1/spaces/${enc(config.spaceId)}/artifacts/${enc(name)}/history`);
+}
+export async function unpublishArtifact(config, name) {
+    return request(config, "POST", `/v1/spaces/${enc(config.spaceId)}/artifacts/${enc(name)}/unpublish`);
+}
+export async function keepArtifact(config, name) {
+    return request(config, "POST", `/v1/spaces/${enc(config.spaceId)}/artifacts/${enc(name)}/keep`);
+}
+export { ApiError };

package/dist/config.js

@@ -0,0 +1,112 @@
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { generateSpaceId, slugify } from "./util.js";
+export const DEFAULT_API_BASE = "https://api.protocontent.com";
+/** Resolve the configured API base, trimming any trailing slash. */
+export function getApiBase() {
+    const raw = process.env.PROTOCONTENT_API?.trim();
+    const base = raw && raw.length > 0 ? raw : DEFAULT_API_BASE;
+    return base.replace(/\/+$/, "");
+}
+function configDir() {
+    return path.join(os.homedir(), ".protocontent");
+}
+function configPath() {
+    return path.join(configDir(), "config.json");
+}
+async function readConfigFile() {
+    try {
+        const raw = await fs.readFile(configPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeConfigFile(cfg) {
+    const dir = configDir();
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    const data = JSON.stringify(cfg, null, 2) + "\n";
+    // Write then chmod to guarantee 0600 even if umask interfered.
+    await fs.writeFile(configPath(), data, { mode: 0o600 });
+    try {
+        await fs.chmod(configPath(), 0o600);
+    }
+    catch {
+        // best effort — not all filesystems support chmod
+    }
+}
+/**
+ * Mint an anonymous project token via the public (no-auth) endpoint and
+ * cache it to ~/.protocontent/config.json.
+ */
+async function mintAnonymousToken(apiBase) {
+    let res;
+    try {
+        res = await fetch(`${apiBase}/v1/projects`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: "{}",
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not reach protocontent API at ${apiBase} to create an anonymous project: ` +
+            `${err.message}`);
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Failed to mint anonymous project token (${res.status} ${res.statusText})` +
+            (body ? `: ${body}` : ""));
+    }
+    const json = (await res.json());
+    if (!json.token) {
+        throw new Error("Project endpoint did not return a token.");
+    }
+    const cfg = { token: json.token, projectId: json.projectId };
+    await writeConfigFile(cfg);
+    return { token: json.token, projectId: json.projectId };
+}
+/**
+ * Resolve the auth token, in priority order:
+ *   1. env PROTOCONTENT_TOKEN
+ *   2. ~/.protocontent/config.json
+ *   3. mint a new anonymous token (and cache it)
+ */
+export async function resolveToken(apiBase) {
+    const envToken = process.env.PROTOCONTENT_TOKEN?.trim();
+    if (envToken)
+        return envToken;
+    const cfg = await readConfigFile();
+    if (cfg?.token)
+        return cfg.token;
+    const minted = await mintAnonymousToken(apiBase);
+    return minted.token;
+}
+/**
+ * Compute the per-process space id and label.
+ * Seeded deterministically from CLAUDE_SESSION_ID when present so the
+ * space lines up with the agent's thread; otherwise random.
+ */
+export function computeSpace() {
+    const seed = process.env.CLAUDE_SESSION_ID?.trim();
+    const spaceId = generateSpaceId(seed && seed.length > 0 ? seed : undefined);
+    let spaceLabel;
+    try {
+        const base = path.basename(process.cwd());
+        const label = slugify(base, "");
+        spaceLabel = label.length > 0 ? label : undefined;
+    }
+    catch {
+        spaceLabel = undefined;
+    }
+    return { spaceId, spaceLabel };
+}
+/** Build the full bridge config once at startup. */
+export async function loadConfig() {
+    const apiBase = getApiBase();
+    const token = await resolveToken(apiBase);
+    const { spaceId, spaceLabel } = computeSpace();
+    return { apiBase, token, spaceId, spaceLabel };
+}

package/dist/index.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { artifactHistory, keepArtifact, listSpace, publish, unpublishArtifact, } from "./api.js";
+import { loadConfig } from "./config.js";
+import { contentTypeFromName, formatBytes, slugify, slugifyBasename, walkDir, } from "./util.js";
+// Safety rails for a single publish_folder call (not the abuse-limits feature).
+const MAX_FILES_PER_CALL = 500;
+const MAX_TOTAL_BYTES = 50 * 1024 * 1024; // 50 MB
+const MAX_SINGLE_FILE_BYTES = 25 * 1024 * 1024; // 25 MB
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+function errorResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/** Format an epoch-ms timestamp (or null) as a short human-readable UTC string. */
+function fmtTime(ms) {
+    if (ms == null)
+        return "";
+    return new Date(ms).toISOString().slice(0, 16).replace("T", " ") + " UTC";
+}
+/** Format an epoch-ms expiry as an absolute time plus a relative hint. */
+function fmtExpiry(ms) {
+    if (ms == null)
+        return "";
+    const days = Math.round((ms - Date.now()) / 86400000);
+    const rel = days <= 0 ? "soon" : days === 1 ? "in ~1 day" : `in ~${days} days`;
+    return `${fmtTime(ms)} (${rel})`;
+}
+/** Compose the standard human-readable success message every tool returns. */
+function publishMessage(what, res) {
+    const lines = [];
+    lines.push(`Published ${what} (v${res.version}).`);
+    // Always surface a tappable markdown link.
+    lines.push("");
+    lines.push(res.markdown);
+    lines.push("");
+    lines.push(`Live space (updates in real time): ${res.spaceUrl}`);
+    lines.push(`Direct URL: ${res.url}`);
+    if (res.expiresAt) {
+        lines.push(`Expires ${fmtExpiry(res.expiresAt)} — use \`keep\` to make it permanent.`);
+    }
+    else {
+        lines.push("This artifact has no expiry.");
+    }
+    return lines.join("\n");
+}
+async function main() {
+    let config;
+    try {
+        config = await loadConfig();
+    }
+    catch (err) {
+        // Fatal: we cannot operate without a token. Surface clearly on stderr.
+        process.stderr.write(`[protocontent] startup failed: ${err.message}\n`);
+        process.exit(1);
+        return;
+    }
+    process.stderr.write(`[protocontent] space ${config.spaceId}` +
+        (config.spaceLabel ? ` (${config.spaceLabel})` : "") +
+        ` -> ${config.apiBase}\n`);
+    const server = new McpServer({ name: "protocontent", version: "0.1.0" }, {
+        instructions: "Publish local files/folders to protocontent and get a shareable, live-updating URL. " +
+            "Each agent thread maps to one persistent 'space'. Use publish_html for a single file " +
+            "or inline content, publish_folder for a directory (e.g. a built site), and list/history/" +
+            "unpublish/keep to manage artifacts. Always show the returned markdown link to the user.",
+    });
+    // --- publish_html ----------------------------------------------------------
+    server.registerTool("publish_html", {
+        title: "Publish a single file",
+        description: "Publish a single HTML (or other) file or inline content to this space and get a " +
+            "tappable, live URL. Provide exactly one of `path` (a file on disk) or `content` " +
+            "(inline text). The space page updates live as you republish.",
+        inputSchema: {
+            path: z
+                .string()
+                .optional()
+                .describe("Absolute or relative path to a local file to publish."),
+            content: z
+                .string()
+                .optional()
+                .describe("Inline file content to publish (alternative to `path`)."),
+            name: z
+                .string()
+                .optional()
+                .describe("Artifact name (slug). Defaults to the slugified file basename, or 'page'."),
+            ttl: z
+                .string()
+                .optional()
+                .describe("Optional time-to-live, e.g. '7d', '24h'. Omit for the default."),
+        },
+    }, async (args) => {
+        const { path: filePath, content, name, ttl } = args;
+        if ((filePath && content) || (!filePath && content === undefined)) {
+            return errorResult("Provide exactly one of `path` or `content`.");
+        }
+        let bytes;
+        let sourceName;
+        if (filePath) {
+            const abs = path.resolve(filePath);
+            try {
+                const stat = await fs.stat(abs);
+                if (!stat.isFile()) {
+                    return errorResult(`Not a file: ${abs}`);
+                }
+                if (stat.size > MAX_SINGLE_FILE_BYTES) {
+                    return errorResult(`File is ${formatBytes(stat.size)}, exceeding the ${formatBytes(MAX_SINGLE_FILE_BYTES)} single-file limit.`);
+                }
+                bytes = await fs.readFile(abs);
+            }
+            catch (err) {
+                return errorResult(`Could not read file ${abs}: ${err.message}`);
+            }
+            sourceName = path.basename(abs);
+        }
+        else {
+            bytes = Buffer.from(content, "utf8");
+            sourceName = "index.html";
+        }
+        const artifactName = name
+            ? slugify(name)
+            : filePath
+                ? slugifyBasename(sourceName)
+                : "page";
+        // relPath: a sensible filename. Use the source basename, or default to
+        // index.html for inline content.
+        const relPath = filePath ? sourceName : "index.html";
+        const file = {
+            relPath,
+            contentBase64: bytes.toString("base64"),
+            contentType: contentTypeFromName(relPath),
+        };
+        try {
+            const res = await publish(config, {
+                spaceId: config.spaceId,
+                spaceLabel: config.spaceLabel,
+                name: artifactName,
+                ttl,
+                files: [file],
+            });
+            return textResult(publishMessage(`'${artifactName}'`, res));
+        }
+        catch (err) {
+            return errorResult(`Publish failed: ${err.message}`);
+        }
+    });
+    // --- publish_folder --------------------------------------------------------
+    server.registerTool("publish_folder", {
+        title: "Publish a folder",
+        description: "Recursively publish a local directory (e.g. a built static site) to this space and " +
+            "get a tappable, live URL. Skips node_modules, .git, and dotfiles. The space page " +
+            "updates live as you republish.",
+        inputSchema: {
+            dir: z.string().describe("Path to the directory to publish."),
+            entry: z
+                .string()
+                .optional()
+                .describe("Entry file served at the root. Defaults to 'index.html'."),
+            name: z
+                .string()
+                .optional()
+                .describe("Artifact name (slug). Defaults to the slugified directory basename."),
+            ttl: z
+                .string()
+                .optional()
+                .describe("Optional time-to-live, e.g. '7d', '24h'. Omit for the default."),
+        },
+    }, async (args) => {
+        const { dir, entry, name, ttl } = args;
+        const absDir = path.resolve(dir);
+        try {
+            const stat = await fs.stat(absDir);
+            if (!stat.isDirectory()) {
+                return errorResult(`Not a directory: ${absDir}`);
+            }
+        }
+        catch (err) {
+            return errorResult(`Could not access directory ${absDir}: ${err.message}`);
+        }
+        let walked;
+        try {
+            walked = await walkDir(absDir, {
+                maxFiles: MAX_FILES_PER_CALL,
+                maxTotalBytes: MAX_TOTAL_BYTES,
+            });
+        }
+        catch (err) {
+            return errorResult(err.message);
+        }
+        if (walked.length === 0) {
+            return errorResult(`No publishable files found in ${absDir}.`);
+        }
+        const files = [];
+        for (const f of walked) {
+            if (f.size > MAX_SINGLE_FILE_BYTES) {
+                return errorResult(`File ${f.relPath} is ${formatBytes(f.size)}, exceeding the ` +
+                    `${formatBytes(MAX_SINGLE_FILE_BYTES)} single-file limit.`);
+            }
+            const buf = await fs.readFile(f.absPath);
+            files.push({
+                relPath: f.relPath,
+                contentBase64: buf.toString("base64"),
+                contentType: contentTypeFromName(f.relPath),
+            });
+        }
+        const entryFile = entry ?? "index.html";
+        const hasEntry = files.some((f) => f.relPath === entryFile);
+        const artifactName = name ? slugify(name) : slugify(path.basename(absDir));
+        try {
+            const res = await publish(config, {
+                spaceId: config.spaceId,
+                spaceLabel: config.spaceLabel,
+                name: artifactName,
+                entry: entryFile,
+                ttl,
+                files,
+            });
+            let msg = publishMessage(`'${artifactName}' (${files.length} files)`, res);
+            if (!hasEntry) {
+                msg +=
+                    `\n\nNote: entry file '${entryFile}' was not found in the folder; ` +
+                        `the root URL may 404 until you add one or pass a different \`entry\`.`;
+            }
+            return textResult(msg);
+        }
+        catch (err) {
+            return errorResult(`Publish failed: ${err.message}`);
+        }
+    });
+    // --- list ------------------------------------------------------------------
+    server.registerTool("list", {
+        title: "List artifacts in this space",
+        description: "List all artifacts published in this space, with their live URLs and versions.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const res = await listSpace(config);
+            const spaceUrl = `https://${config.spaceId}.protocontent.com`;
+            if (!res.artifacts || res.artifacts.length === 0) {
+                return textResult(`No artifacts published yet in space ${config.spaceId}.\n` +
+                    `Space: ${spaceUrl}`);
+            }
+            const lines = res.artifacts.map((a) => {
+                const exp = a.expiresAt ? ` — expires ${fmtExpiry(a.expiresAt)}` : " — no expiry";
+                return `- [${a.name} ↗](${a.url}) (v${a.version})${exp}`;
+            });
+            return textResult(`Artifacts in space ${config.spaceId}:\n` +
+                lines.join("\n") +
+                `\n\nLive space (updates in real time): ${spaceUrl}`);
+        }
+        catch (err) {
+            return errorResult(`List failed: ${err.message}`);
+        }
+    });
+    // --- history ---------------------------------------------------------------
+    server.registerTool("history", {
+        title: "Show an artifact's version history",
+        description: "Show the published version history of a named artifact in this space.",
+        inputSchema: {
+            name: z.string().describe("Artifact name (slug) to show history for."),
+        },
+    }, async (args) => {
+        const name = slugify(args.name);
+        try {
+            const res = await artifactHistory(config, name);
+            if (!res.versions || res.versions.length === 0) {
+                return textResult(`No version history for '${name}'.`);
+            }
+            const lines = res.versions
+                .slice()
+                .sort((a, b) => b.version - a.version)
+                .map((v) => `- v${v.version} — ${fmtTime(v.at)} — [open ↗](${v.url})`);
+            return textResult(`History for '${name}':\n` + lines.join("\n"));
+        }
+        catch (err) {
+            return errorResult(`History failed: ${err.message}`);
+        }
+    });
+    // --- unpublish -------------------------------------------------------------
+    server.registerTool("unpublish", {
+        title: "Unpublish an artifact",
+        description: "Remove a named artifact from this space so its URL stops serving content.",
+        inputSchema: {
+            name: z.string().describe("Artifact name (slug) to unpublish."),
+        },
+    }, async (args) => {
+        const name = slugify(args.name);
+        try {
+            const res = await unpublishArtifact(config, name);
+            if (res.ok) {
+                return textResult(`Unpublished '${name}'. Its URL no longer serves content.`);
+            }
+            return errorResult(`Unpublish of '${name}' did not succeed.`);
+        }
+        catch (err) {
+            return errorResult(`Unpublish failed: ${err.message}`);
+        }
+    });
+    // --- keep ------------------------------------------------------------------
+    server.registerTool("keep", {
+        title: "Keep an artifact permanently",
+        description: "Remove the expiry from a named artifact so it is kept permanently.",
+        inputSchema: {
+            name: z.string().describe("Artifact name (slug) to keep permanently."),
+        },
+    }, async (args) => {
+        const name = slugify(args.name);
+        try {
+            await keepArtifact(config, name);
+            return textResult(`'${name}' will now be kept permanently (expiry removed).`);
+        }
+        catch (err) {
+            return errorResult(`Keep failed: ${err.message}`);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("[protocontent] stdio MCP server ready.\n");
+}
+main().catch((err) => {
+    process.stderr.write(`[protocontent] fatal: ${err.stack ?? err}\n`);
+    process.exit(1);
+});

package/dist/util.js

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+/**
+ * Map of file extensions (without leading dot) to MIME content types.
+ * Small, hand-picked list covering the common cases an agent publishes.
+ */
+const CONTENT_TYPE_BY_EXT = {
+    html: "text/html; charset=utf-8",
+    htm: "text/html; charset=utf-8",
+    css: "text/css; charset=utf-8",
+    js: "text/javascript; charset=utf-8",
+    mjs: "text/javascript; charset=utf-8",
+    cjs: "text/javascript; charset=utf-8",
+    json: "application/json; charset=utf-8",
+    map: "application/json; charset=utf-8",
+    xml: "application/xml; charset=utf-8",
+    txt: "text/plain; charset=utf-8",
+    md: "text/markdown; charset=utf-8",
+    csv: "text/csv; charset=utf-8",
+    wasm: "application/wasm",
+    pdf: "application/pdf",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    webp: "image/webp",
+    ico: "image/x-icon",
+    avif: "image/avif",
+    bmp: "image/bmp",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    eot: "application/vnd.ms-fontobject",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+};
+const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/** Detect a content type from a file name / path using its extension. */
+export function contentTypeFromName(name) {
+    const ext = path.extname(name).slice(1).toLowerCase();
+    if (!ext)
+        return DEFAULT_CONTENT_TYPE;
+    return CONTENT_TYPE_BY_EXT[ext] ?? DEFAULT_CONTENT_TYPE;
+}
+/**
+ * Turn an arbitrary string into a DNS/URL-safe slug.
+ * Lowercases, replaces runs of non-alphanumerics with single hyphens,
+ * trims leading/trailing hyphens. Falls back to "page" when empty.
+ */
+export function slugify(input, fallback = "page") {
+    const slug = input
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "") // strip accents
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+    return slug || fallback;
+}
+/**
+ * Slugify a file basename, dropping its extension first so that
+ * "My Plan.html" -> "my-plan".
+ */
+export function slugifyBasename(fileName, fallback = "page") {
+    const base = path.basename(fileName, path.extname(fileName));
+    return slugify(base || fileName, fallback);
+}
+// --- space-id generation ----------------------------------------------------
+const ADJECTIVES = [
+    "amber", "azure", "brave", "calm", "clever", "coral", "crimson", "dawn",
+    "eager", "ember", "fancy", "fleet", "gentle", "golden", "happy", "hazel",
+    "indigo", "ivory", "jade", "jolly", "keen", "lively", "lunar", "maple",
+    "mellow", "mint", "misty", "noble", "ocean", "olive", "opal", "pearl",
+    "plum", "proud", "quiet", "rapid", "royal", "ruby", "sage", "scarlet",
+    "shy", "silent", "silver", "solar", "spry", "starry", "sunny", "swift",
+    "teal", "tidal", "topaz", "vivid", "warm", "wild", "wise", "zesty",
+];
+const NOUNS = [
+    "canyon", "harbor", "meadow", "summit", "river", "forest", "valley", "ridge",
+    "glade", "haven", "isle", "lagoon", "marsh", "oasis", "prairie", "reef",
+    "tundra", "delta", "dune", "fjord", "geyser", "grove", "knoll", "mesa",
+    "cove", "bay", "creek", "falls", "glen", "moor", "peak", "shore",
+    "spring", "thicket", "vista", "wharf", "willow", "cedar", "birch", "aspen",
+    "comet", "ember", "falcon", "heron", "lynx", "otter", "raven", "sparrow",
+    "beacon", "compass", "lantern", "anchor", "pebble", "ripple", "breeze", "echo",
+];
+function pick(arr, index) {
+    return arr[index % arr.length];
+}
+/**
+ * Generate a DNS-safe space id of the form `word-word-xxx`
+ * (e.g. `amber-canyon-7f3`). When `seed` is provided the result is
+ * deterministic (so it lines up with an agent thread/session id);
+ * otherwise it is random.
+ */
+export function generateSpaceId(seed) {
+    if (seed && seed.length > 0) {
+        const hash = createHash("sha256").update(seed).digest();
+        const adjIndex = hash.readUInt16BE(0);
+        const nounIndex = hash.readUInt16BE(2);
+        // 3-char base36 suffix derived from the next bytes.
+        const suffixNum = hash.readUInt32BE(4) % (36 * 36 * 36);
+        const suffix = suffixNum.toString(36).padStart(3, "0").slice(-3);
+        return `${pick(ADJECTIVES, adjIndex)}-${pick(NOUNS, nounIndex)}-${suffix}`;
+    }
+    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+    const suffix = Math.floor(Math.random() * (36 * 36 * 36))
+        .toString(36)
+        .padStart(3, "0")
+        .slice(-3);
+    return `${adj}-${noun}-${suffix}`;
+}
+const DEFAULT_SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".hg",
+    ".svn",
+    ".cache",
+    "dist",
+    ".next",
+    ".turbo",
+]);
+/**
+ * Recursively walk `root`, returning files with POSIX-relative paths.
+ * Enforces file-count and total-byte ceilings, throwing a clear error
+ * if either is exceeded (a safety rail against absurd uploads).
+ */
+export async function walkDir(root, options) {
+    const skipDotfiles = options.skipDotfiles ?? true;
+    const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+    const out = [];
+    let totalBytes = 0;
+    async function recurse(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const name = entry.name;
+            if (skipDotfiles && name.startsWith("."))
+                continue;
+            const abs = path.join(dir, name);
+            if (entry.isDirectory()) {
+                if (skipDirs.has(name))
+                    continue;
+                await recurse(abs);
+            }
+            else if (entry.isFile()) {
+                const stat = await fs.stat(abs);
+                out.push({
+                    absPath: abs,
+                    relPath: path.relative(root, abs).split(path.sep).join("/"),
+                    size: stat.size,
+                });
+                totalBytes += stat.size;
+                if (out.length > options.maxFiles) {
+                    throw new Error(`Folder has more than ${options.maxFiles} files — too large to publish in one call. ` +
+                        `Publish a smaller subfolder or split it up.`);
+                }
+                if (totalBytes > options.maxTotalBytes) {
+                    throw new Error(`Folder exceeds the ${formatBytes(options.maxTotalBytes)} upload ceiling. ` +
+                        `Publish a smaller subfolder or split it up.`);
+                }
+            }
+            // symlinks and other special entries are ignored
+        }
+    }
+    await recurse(root);
+    return out;
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(0)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "protocontent",
+  "version": "0.1.0",
+  "description": "Co-located stdio MCP bridge for protocontent — read local files and publish them to the protocontent HTTP API.",
+  "type": "module",
+  "bin": {
+    "protocontent": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "protocontent",
+    "publishing",
+    "stdio"
+  ],
+  "author": "Jaron Heard",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}