@pastepile/mcp 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# @pastepile/mcp
+
+The **persistent memory layer for AI coding assistants.** A
+[Model Context Protocol](https://modelcontextprotocol.io) server that lets
+Claude, Cursor, Windsurf, and any MCP client save knowledge to
+[Pastepile](https://pastepile.com) and retrieve it later by a stable URL.
+
+Give your assistant durable, URL-addressable storage: when it produces a design
+doc, a working snippet, a log, or a decision record, it saves it here and
+remembers the slug. Next session, it loads it straight back. Zero dependencies,
+so it adds no supply-chain surface of its own.
+
+## Tools
+
+| Tool               | What it does                                                        |
+| ------------------ | ------------------------------------------------------------------- |
+| `pastepile_save`   | Save text/code and get back a stable `url`, `slug`, and `edit_key`. |
+| `pastepile_get`    | Retrieve a paste by slug or full Pastepile URL.                     |
+| `pastepile_search` | Search the public paste corpus by keyword.                          |
+| `pastepile_list`   | List the most recent public pastes.                                 |
+
+Saved pastes default to **unlisted** (retrievable by URL, never shown in public
+listings or search) and **never expire**, so stored knowledge persists. Both are
+adjustable per call. End-to-end encrypted, password-protected, and
+burn-after-read pastes cannot be read back through the API and are out of scope
+for `pastepile_get`.
+
+## Requirements
+
+Node.js 18 or newer (the server uses the built-in global `fetch`). No install
+step, no build.
+
+## Configuration
+
+The server is configured entirely by environment variables:
+
+| Variable            | Default                 | Purpose                                                                                |
+| ------------------- | ----------------------- | -------------------------------------------------------------------------------------- |
+| `PASTEPILE_API`     | `https://pastepile.com` | Base URL. Point at a self-hosted or staging deploy.                                    |
+| `PASTEPILE_API_KEY` | (none)                  | Optional Pastepile API key, sent as `X-API-Key` for a higher rate limit. Never logged. |
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add pastepile -- npx -y @pastepile/mcp
+```
+
+Or add it to `.mcp.json` in your project (shared with your team):
+
+```json
+{
+  "mcpServers": {
+    "pastepile": {
+      "command": "npx",
+      "args": ["-y", "@pastepile/mcp"],
+      "env": { "PASTEPILE_API_KEY": "your-key-optional" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "pastepile": {
+      "command": "npx",
+      "args": ["-y", "@pastepile/mcp"],
+      "env": { "PASTEPILE_API_KEY": "your-key-optional" }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pastepile": {
+      "command": "npx",
+      "args": ["-y", "@pastepile/mcp"],
+      "env": { "PASTEPILE_API_KEY": "your-key-optional" }
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+The server speaks JSON-RPC 2.0 over stdio. Run it with:
+
+```bash
+npx -y @pastepile/mcp
+```
+
+Point your client at that command. The `env` block is optional; without it the
+server talks to `https://pastepile.com` anonymously.
+
+## Example
+
+Once configured, ask your assistant to use it in plain language:
+
+> "Save this migration plan to Pastepile so we can pick it up tomorrow."
+
+> "Pull up the paste at pastepile.com/p/abc123 and continue where we left off."
+
+The assistant calls `pastepile_save` / `pastepile_get` for you and keeps the
+returned slug in context.
+
+## How it works
+
+This server is a thin wrapper over the public Pastepile REST API
+(`/api/public/pastes`). It holds no state of its own: every tool call is one
+HTTPS request, tagged with a `pastepile-mcp/<version>` User-Agent. Your content
+goes straight to Pastepile under the same privacy model as the web app and CLI.
+For end-to-end encryption, create the paste in the web app or CLI (the
+encryption key never leaves the client) and share the resulting link.
+
+## License
+
+MIT. Part of the [Pastepile](https://pastepile.com) project.

package/bin/pastepile-mcp.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Pastepile MCP server: stdio transport.
+//
+// Reads newline-delimited JSON-RPC messages from stdin, hands each to the pure
+// dispatcher in ../src/server.mjs, and writes responses (one JSON object per
+// line) to stdout. Nothing but protocol messages is ever written to stdout;
+// diagnostics go to stderr so they cannot corrupt the JSON-RPC stream.
+//
+// Configuration is by environment:
+//   PASTEPILE_API      base URL         (default https://pastepile.com)
+//   PASTEPILE_API_KEY  optional API key (sent as X-API-Key for higher limits)
+import { createInterface } from "node:readline";
+import { dispatch, VERSION, DEFAULT_BASE } from "../src/server.mjs";
+
+const deps = {
+  fetch: globalThis.fetch,
+  baseUrl: (process.env.PASTEPILE_API || DEFAULT_BASE).replace(/\/+$/, ""),
+  apiKey: process.env.PASTEPILE_API_KEY || null,
+  version: VERSION,
+};
+
+if (typeof deps.fetch !== "function") {
+  process.stderr.write(
+    "pastepile-mcp: global fetch is unavailable. Node 18 or newer is required.\n",
+  );
+  process.exit(1);
+}
+
+function write(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n");
+}
+
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+rl.on("line", async (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  let message;
+  try {
+    message = JSON.parse(trimmed);
+  } catch {
+    write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+    return;
+  }
+
+  try {
+    const response = await dispatch(message, deps);
+    if (response) write(response);
+  } catch (err) {
+    const id = message && message.id != null ? message.id : null;
+    write({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32603, message: err && err.message ? err.message : "Internal error" },
+    });
+  }
+});
+
+// Exit cleanly when the host closes the pipe.
+rl.on("close", () => process.exit(0));

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pastepile/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Pastepile - durable, URL-addressable memory for AI coding assistants. Save and retrieve knowledge from Claude, Cursor, Windsurf, and any MCP client.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "pastepile-mcp": "bin/pastepile-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pastepile",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "memory",
+    "claude",
+    "cursor",
+    "windsurf",
+    "pastebin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/asterismos-v1/pastepile.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://pastepile.com"
+}

package/src/server.mjs

@@ -0,0 +1,376 @@
+// Pastepile MCP server: the persistent memory layer for AI coding assistants.
+//
+// Implements the Model Context Protocol (JSON-RPC 2.0 over stdio) as a thin,
+// hardened wrapper over the Pastepile public REST API. Zero dependencies,
+// exactly like the CLI, so it adds no supply-chain surface. Node 18+ (global
+// fetch).
+//
+// The transport (bin/pastepile-mcp.mjs) reads newline-delimited JSON from
+// stdin and writes responses to stdout. Everything protocol-related lives here
+// and is pure and testable: `dispatch(message, deps)` takes a parsed JSON-RPC
+// message plus injectable dependencies (fetch, base URL, api key, version) and
+// returns the response object, or null for a notification that must not be
+// answered.
+
+export const VERSION = "0.1.0";
+export const PROTOCOL_VERSION = "2025-06-18";
+export const SERVER_NAME = "pastepile";
+export const DEFAULT_BASE = "https://pastepile.com";
+
+// One line the host shows the model so it treats Pastepile as durable memory.
+export const INSTRUCTIONS =
+  "Pastepile is durable, URL-addressable storage for AI assistants. When you " +
+  "produce something worth keeping across sessions (a design, a snippet, a " +
+  "log, a decision record), call pastepile_save and remember the returned " +
+  "slug or URL. Reload it later with pastepile_get. Search the public corpus " +
+  "with pastepile_search. Saved pastes default to unlisted (retrievable by " +
+  "URL, not shown in public listings or search).";
+
+const EXPIRY_VALUES = ["10m", "1h", "1d", "1w", "1mo", "never", "burn"];
+const VISIBILITY_VALUES = ["public", "unlisted"];
+
+export const TOOLS = [
+  {
+    name: "pastepile_save",
+    description:
+      "Save text, code, notes, or any knowledge to Pastepile and get back a " +
+      "stable, shareable URL you can retrieve later. Use this as durable " +
+      "memory: whenever you produce output worth keeping across sessions, " +
+      "save it and remember the returned slug or URL. Returns url, slug, " +
+      "raw_url, and edit_key. The edit_key is shown only once and is required " +
+      "to later update or delete the paste, so retain it if you may change it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: {
+          type: "string",
+          description: "The text or code to store. Required.",
+        },
+        title: {
+          type: "string",
+          description: "Optional short title for the paste.",
+        },
+        language: {
+          type: "string",
+          description:
+            'Optional syntax-highlighting language, e.g. "typescript", ' +
+            '"python", "markdown". Defaults to "plaintext".',
+        },
+        expiry: {
+          type: "string",
+          enum: EXPIRY_VALUES,
+          description:
+            'When the paste expires. Defaults to "never" so stored knowledge ' +
+            'persists. "burn" destroys it after the first read.',
+        },
+        visibility: {
+          type: "string",
+          enum: VISIBILITY_VALUES,
+          description:
+            '"unlisted" (default) keeps the paste out of public listings and ' +
+            'search but retrievable by URL. "public" also lists it and makes ' +
+            "it findable via pastepile_search.",
+        },
+      },
+      required: ["content"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "pastepile_get",
+    description:
+      "Retrieve a previously saved paste by its slug or full Pastepile URL. " +
+      "Returns the title, language, and file contents. Use this to reload " +
+      "knowledge you or a teammate saved earlier. End-to-end encrypted, " +
+      "password-protected, and burn-after-read pastes are not retrievable " +
+      "through this tool.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: {
+          type: "string",
+          description:
+            'The paste slug (e.g. "abc123") or a full share URL (e.g. ' +
+            '"https://pastepile.com/p/abc123"). Required.',
+        },
+      },
+      required: ["slug"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "pastepile_search",
+    description:
+      "Search public Pastepile pastes by keyword and get back matching " +
+      "titles, previews, and URLs. This searches the global public corpus of " +
+      "listed pastes, not a private per-user store. Use it to find existing " +
+      "public snippets or reference material before writing from scratch.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Keywords to match against public paste titles and content. Required.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description: "Maximum results to return (1-100, default 20).",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "pastepile_list",
+    description:
+      "List the most recent public Pastepile pastes. Returns slugs, titles, " +
+      "and URLs. Use this to browse what has been shared publicly; for " +
+      "targeted lookups use pastepile_search instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description: "Maximum results to return (1-100, default 20).",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+// A tool-level failure the model should see (returned as an isError result,
+// not a JSON-RPC protocol error).
+export class ToolError extends Error {}
+
+function normalizeBase(base) {
+  return String(base || DEFAULT_BASE).replace(/\/+$/, "");
+}
+
+// Accept a bare slug or a full share/raw URL, exactly like the CLI's `get`.
+// Returns null for a URL we could not extract a slug from.
+export function slugFromInput(input) {
+  const s = String(input == null ? "" : input).trim();
+  if (!s) return null;
+  const hashIdx = s.indexOf("#");
+  const raw = hashIdx >= 0 ? s.slice(0, hashIdx) : s;
+  const m = /\/(?:p|raw)\/([^/?#]+)/.exec(raw);
+  if (m) return decodeURIComponent(m[1]);
+  if (/^https?:\/\//.test(raw)) return null;
+  return raw;
+}
+
+function clampLimit(value, fallback = 20) {
+  const n = Number.parseInt(value, 10);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(n, 1), 100);
+}
+
+async function readJson(res) {
+  const txt = await res.text();
+  if (!txt) return null;
+  try {
+    return JSON.parse(txt);
+  } catch {
+    return { raw: txt };
+  }
+}
+
+function apiError(res, data) {
+  const message =
+    data && data.error && typeof data.error.message === "string"
+      ? data.error.message
+      : data && typeof data.raw === "string"
+        ? data.raw.slice(0, 300)
+        : `${res.status} ${res.statusText}`;
+  return new ToolError(`Pastepile API error (HTTP ${res.status}): ${message}`);
+}
+
+async function apiFetch(deps, method, path, body) {
+  const url = `${normalizeBase(deps.baseUrl)}${path}`;
+  const headers = {
+    // Analytics attribution: every request from this server is tagged so
+    // MCP-driven traffic can be measured distinctly from the web app and CLI.
+    "User-Agent": `pastepile-mcp/${deps.version || VERSION}`,
+    Accept: "application/json",
+  };
+  if (deps.apiKey) headers["X-API-Key"] = deps.apiKey;
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+  return deps.fetch(url, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+}
+
+async function toolSave(deps, args) {
+  if (typeof args.content !== "string" || args.content.length === 0) {
+    throw new ToolError("`content` is required and must be a non-empty string.");
+  }
+  const expiry = args.expiry === undefined ? "never" : args.expiry;
+  if (!EXPIRY_VALUES.includes(expiry)) {
+    throw new ToolError(`Invalid expiry "${expiry}". Use one of: ${EXPIRY_VALUES.join(", ")}.`);
+  }
+  const visibility = args.visibility === undefined ? "unlisted" : args.visibility;
+  if (!VISIBILITY_VALUES.includes(visibility)) {
+    throw new ToolError(`Invalid visibility "${visibility}". Use "public" or "unlisted".`);
+  }
+
+  const body = { content: args.content, expiry, visibility };
+  if (typeof args.title === "string" && args.title.length > 0) body.title = args.title;
+  if (typeof args.language === "string" && args.language.length > 0) body.language = args.language;
+
+  const res = await apiFetch(deps, "POST", "/api/public/pastes", body);
+  const data = await readJson(res);
+  if (!res.ok || !data) throw apiError(res, data);
+  return {
+    saved: true,
+    url: data.url,
+    slug: data.slug,
+    raw_url: data.raw_url,
+    edit_key: data.edit_key,
+    visibility,
+    expiry,
+    note: "Retain edit_key to update or delete this paste later; it is shown only once.",
+  };
+}
+
+async function toolGet(deps, args) {
+  const slug = slugFromInput(args.slug);
+  if (!slug) throw new ToolError("Provide a valid paste slug or Pastepile URL.");
+  const res = await apiFetch(deps, "GET", `/api/public/pastes/${encodeURIComponent(slug)}`);
+  const data = await readJson(res);
+  if (!res.ok || !data) throw apiError(res, data);
+  return {
+    slug: data.slug,
+    title: data.title,
+    language: data.language,
+    files: data.files,
+    created_at: data.created_at,
+    expires_at: data.expires_at,
+    url: `${normalizeBase(deps.baseUrl)}/p/${data.slug}`,
+  };
+}
+
+function pickListItem(item) {
+  return {
+    slug: item.slug,
+    title: item.title,
+    language: item.language,
+    preview: item.preview,
+    file_count: item.file_count,
+    created_at: item.created_at,
+    url: item.url,
+    raw_url: item.raw_url,
+  };
+}
+
+async function toolSearch(deps, args) {
+  if (typeof args.query !== "string" || args.query.trim().length === 0) {
+    throw new ToolError("`query` is required and must be a non-empty string.");
+  }
+  const limit = clampLimit(args.limit);
+  const qs = new URLSearchParams({ search: args.query.slice(0, 80), limit: String(limit) });
+  const res = await apiFetch(deps, "GET", `/api/public/pastes?${qs.toString()}`);
+  const data = await readJson(res);
+  if (!res.ok || !data) throw apiError(res, data);
+  const items = Array.isArray(data.items) ? data.items : [];
+  return {
+    query: args.query,
+    total: typeof data.total === "number" ? data.total : items.length,
+    results: items.map(pickListItem),
+  };
+}
+
+async function toolList(deps, args) {
+  const limit = clampLimit(args.limit);
+  const qs = new URLSearchParams({ limit: String(limit) });
+  const res = await apiFetch(deps, "GET", `/api/public/pastes?${qs.toString()}`);
+  const data = await readJson(res);
+  if (!res.ok || !data) throw apiError(res, data);
+  const items = Array.isArray(data.items) ? data.items : [];
+  return {
+    total: typeof data.total === "number" ? data.total : items.length,
+    results: items.map(pickListItem),
+  };
+}
+
+const TOOL_HANDLERS = {
+  pastepile_save: toolSave,
+  pastepile_get: toolGet,
+  pastepile_search: toolSearch,
+  pastepile_list: toolList,
+};
+
+/**
+ * Handle one parsed JSON-RPC message. Returns a response object to write back,
+ * or null when the message is a notification (no `id`) that must not be
+ * answered. `deps` is { fetch, baseUrl, apiKey, version }.
+ */
+export async function dispatch(message, deps) {
+  const isNotification = message == null || message.id === undefined || message.id === null;
+  const respond = (result) => (isNotification ? null : { jsonrpc: "2.0", id: message.id, result });
+  const fail = (code, msg) =>
+    isNotification ? null : { jsonrpc: "2.0", id: message.id, error: { code, message: msg } };
+
+  if (!message || message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    return fail(-32600, "Invalid Request");
+  }
+
+  switch (message.method) {
+    case "initialize":
+      return respond({
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: SERVER_NAME, version: deps.version || VERSION },
+        instructions: INSTRUCTIONS,
+      });
+
+    // Client -> server notifications: acknowledged by silence.
+    case "notifications/initialized":
+    case "initialized":
+    case "notifications/cancelled":
+      return null;
+
+    case "ping":
+      return respond({});
+
+    case "tools/list":
+      return respond({ tools: TOOLS });
+
+    case "tools/call": {
+      const params = message.params || {};
+      const name = params.name;
+      const args = params.arguments || {};
+      const handler = TOOL_HANDLERS[name];
+      if (!handler) {
+        return respond({
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        });
+      }
+      try {
+        const result = await handler(deps, args);
+        return respond({
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        });
+      } catch (err) {
+        // Tool failures are reported as isError results (model-visible), not as
+        // JSON-RPC protocol errors, so the assistant can read and react.
+        const text =
+          err instanceof ToolError
+            ? err.message
+            : `Unexpected error: ${err && err.message ? err.message : String(err)}`;
+        return respond({ content: [{ type: "text", text }], isError: true });
+      }
+    }
+
+    default:
+      return fail(-32601, `Method not found: ${message.method}`);
+  }
+}