relic-mcp 0.1.1 → 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "relic",
+  "description": "Relic: zero-knowledge publishing for agent output. Turns a local file into a shareable link without handing the file to anybody.",
+  "owner": {
+    "name": "The Bushido Collective",
+    "url": "https://thebushido.co"
+  },
+  "plugins": [
+    {
+      "name": "relic",
+      "description": "Publish a file from your machine as an encrypted, shareable link. The agent encrypts locally, uploads only ciphertext, and hands back a URL whose fragment holds the key, so the service stores something it cannot read.",
+      "version": "0.2.0",
+      "source": "./",
+      "author": {
+        "name": "The Bushido Collective",
+        "url": "https://thebushido.co"
+      },
+      "homepage": "https://github.com/TheBushidoCollective/relic",
+      "category": "productivity"
+    }
+  ],
+  "metadata": {
+    "version": "0.2.0"
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "relic",
+  "version": "0.2.0",
+  "description": "Publish a file from your machine as an encrypted, shareable link. The agent encrypts locally, uploads only ciphertext, and hands back a URL whose fragment holds the key, so the service stores something it cannot read.",
+  "mcpServers": "./mcp-servers.json",
+  "author": {
+    "name": "The Bushido Collective",
+    "url": "https://thebushido.co"
+  },
+  "homepage": "https://github.com/TheBushidoCollective/relic",
+  "repository": "https://github.com/TheBushidoCollective/relic",
+  "license": "UNLICENSED",
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "sharing",
+    "encryption",
+    "zero-knowledge",
+    "publishing"
+  ]
+}

package/README.md

@@ -87,4 +87,4 @@ revisions (`2025-11-25` and earlier) are still answered.
 
 Requires Node 18 or newer.
 
-MIT licensed. Source: https://github.com/TheBushidoCollective/artifacts
+MIT licensed. Source: https://github.com/TheBushidoCollective/relic

package/dist/relic-mcp.js

@@ -1042,13 +1042,387 @@ function createHttpHandler(deps, options = {}) {
   };
 }
 
+// src/installer.ts
+import { spawnSync } from "node:child_process";
+import { copyFile, mkdir, readFile as readFile2, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/install.ts
+var HARNESSES = [
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    format: "plugin",
+    configPath: ""
+  },
+  {
+    id: "claude-desktop",
+    label: "Claude Desktop",
+    format: "json-mcp-servers",
+    configPath: "Library/Application Support/Claude/claude_desktop_config.json"
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    format: "json-mcp-servers",
+    configPath: ".cursor/mcp.json"
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    format: "json-mcp-servers",
+    configPath: ".codeium/windsurf/mcp_config.json"
+  },
+  {
+    id: "gemini",
+    label: "Gemini CLI",
+    format: "json-mcp-servers",
+    configPath: ".gemini/settings.json"
+  },
+  {
+    id: "vscode",
+    label: "VS Code",
+    format: "json-servers",
+    configPath: "Library/Application Support/Code/User/mcp.json"
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    format: "toml",
+    configPath: ".codex/config.toml"
+  }
+];
+
+class UnknownHarnessError extends Error {
+}
+
+class ExistingEntryError extends Error {
+}
+function planFor(harnessId, spec, existing, options = {}) {
+  const harness = HARNESSES.find((h) => h.id === harnessId);
+  if (harness === undefined) {
+    throw new UnknownHarnessError(`Unknown harness ${harnessId}. Known: ${HARNESSES.map((h) => h.id).join(", ")}`);
+  }
+  if (harness.format === "toml") {
+    return tomlPlan(harness, spec, existing, options);
+  }
+  return jsonPlan(harness, spec, existing, options);
+}
+function jsonPlan(harness, spec, existing, options) {
+  const key = harness.format === "json-servers" ? "servers" : "mcpServers";
+  let root = {};
+  if (existing !== undefined && existing.trim().length > 0) {
+    try {
+      root = JSON.parse(existing);
+    } catch (error) {
+      throw new ExistingEntryError(`${harness.configPath} is not valid JSON, so merging would destroy it: ` + `${error.message}`);
+    }
+  }
+  const servers = root[key] ?? {};
+  const replaced = Object.hasOwn(servers, spec.name);
+  if (replaced && options.force !== true) {
+    throw new ExistingEntryError(`${harness.label} already has a server named "${spec.name}". ` + "Pass --force to replace it.");
+  }
+  const entry = harness.format === "json-servers" ? { type: "stdio", command: spec.command, args: spec.args, env: spec.env } : { command: spec.command, args: spec.args, env: spec.env };
+  const merged = { ...root, [key]: { ...servers, [spec.name]: entry } };
+  return {
+    harness,
+    path: harness.configPath,
+    contents: `${JSON.stringify(merged, null, 2)}
+`,
+    replaced
+  };
+}
+function tomlPlan(harness, spec, existing, options) {
+  const body = existing ?? "";
+  const header = `[mcp_servers.${spec.name}]`;
+  const replaced = body.includes(header);
+  if (replaced && options.force !== true) {
+    throw new ExistingEntryError(`${harness.label} already has [mcp_servers.${spec.name}]. ` + "Pass --force to replace it.");
+  }
+  const table = [
+    header,
+    `command = ${tomlString(spec.command)}`,
+    `args = [${spec.args.map(tomlString).join(", ")}]`,
+    ...Object.keys(spec.env).length > 0 ? [
+      `[mcp_servers.${spec.name}.env]`,
+      ...Object.entries(spec.env).map(([k, v]) => `${k} = ${tomlString(v)}`)
+    ] : []
+  ].join(`
+`);
+  const withoutOld = replaced ? dropTomlTable(body, spec.name) : body;
+  const separator = withoutOld.length === 0 || withoutOld.endsWith(`
+
+`) ? "" : withoutOld.endsWith(`
+`) ? `
+` : `
+
+`;
+  return {
+    harness,
+    path: harness.configPath,
+    contents: `${withoutOld}${separator}${table}
+`,
+    replaced
+  };
+}
+function dropTomlTable(body, name) {
+  const lines = body.split(`
+`);
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    const isHeader = /^\s*\[/.test(line);
+    if (isHeader) {
+      skipping = line.trim() === `[mcp_servers.${name}]` || line.trim().startsWith(`[mcp_servers.${name}.`);
+    }
+    if (!skipping)
+      kept.push(line);
+  }
+  return `${kept.join(`
+`).replace(/\n{3,}$/, `
+
+`).trimEnd()}
+`;
+}
+function tomlString(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+function snippetFor(spec) {
+  return `${JSON.stringify({
+    mcpServers: {
+      [spec.name]: { command: spec.command, args: spec.args, env: spec.env }
+    }
+  }, null, 2)}
+`;
+}
+
+// src/origin.ts
+function requiredOrigin(name, raw) {
+  if (raw === undefined || raw.trim().length === 0) {
+    throw new Error(`${name} is not set. It is the Relic service this client publishes to, ` + "for example https://relic.example.com. Installing the Relic plugin " + "sets it for you; set it yourself when running this server directly.");
+  }
+  let parsed;
+  try {
+    parsed = new URL(raw.trim());
+  } catch {
+    throw new Error(`${name} is not a URL: ${raw}`);
+  }
+  const loopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+  if (parsed.protocol !== "https:" && !loopback) {
+    throw new Error(`${name} must be https, or a loopback host for development. Got ${raw}. ` + "Plaintext never leaves this machine, but the grant that authorizes " + "an upload does, and over http anyone on the path can take it.");
+  }
+  return parsed.origin;
+}
+
+// src/installer.ts
+var USAGE = `relic-mcp - publish a file as an encrypted, shareable link
+
+  relic-mcp                      run the MCP server on stdio
+  relic-mcp install [options]    add this server to an agent harness
+  relic-mcp --help               this
+
+Install options:
+  --client <id>     ${HARNESSES.map((h) => h.id).join(", ")}
+                    Omit to see which of these are installed here.
+  --origin <url>    The Relic service to publish to. Falls back to
+                    RELIC_SERVICE_ORIGIN.
+  --name <name>     Server name in the config. Default: relic.
+  --print           Write nothing; print the config to paste.
+  --force           Replace an existing entry of the same name.
+  --dry-run         Show the file and what would change, without writing.
+`;
+function parseArgs(argv) {
+  const options = {
+    client: undefined,
+    origin: undefined,
+    name: "relic",
+    print: false,
+    force: false,
+    dryRun: false
+  };
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => {
+      const value = argv[++i];
+      if (value === undefined)
+        throw new Error(`${arg} needs a value`);
+      return value;
+    };
+    if (arg === "--client")
+      options.client = next();
+    else if (arg === "--origin")
+      options.origin = next();
+    else if (arg === "--name")
+      options.name = next();
+    else if (arg === "--print")
+      options.print = true;
+    else if (arg === "--force")
+      options.force = true;
+    else if (arg === "--dry-run")
+      options.dryRun = true;
+    else
+      throw new Error(`Unknown option ${arg}`);
+  }
+  return options;
+}
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+async function exists(path) {
+  return readFile2(path).then(() => true).catch(() => false);
+}
+async function runInstall(argv) {
+  let options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+
+${USAGE}`);
+    process.exit(2);
+  }
+  const spec = {
+    name: options.name,
+    command: "npx",
+    args: ["-y", "relic-mcp"],
+    env: {}
+  };
+  if (options.print && options.client === undefined) {
+    process.stdout.write(snippetFor(withOrigin(spec, options)));
+    return;
+  }
+  if (options.client === undefined) {
+    await reportDetected();
+    return;
+  }
+  const resolved = withOrigin(spec, options);
+  if (options.client === "claude-code") {
+    await installClaudeCode(options);
+    return;
+  }
+  const home = homedir();
+  const harness = HARNESSES.find((h) => h.id === options.client);
+  if (harness === undefined) {
+    process.stderr.write(`Unknown client ${options.client}. Known: ` + `${HARNESSES.map((h) => h.id).join(", ")}
+`);
+    process.exit(2);
+  }
+  const path = join(home, harness.configPath);
+  const existing = await readFile2(path, "utf8").catch(() => {
+    return;
+  });
+  let plan;
+  try {
+    plan = planFor(options.client, resolved, existing, {
+      force: options.force
+    });
+  } catch (error) {
+    if (error instanceof ExistingEntryError || error instanceof UnknownHarnessError) {
+      process.stderr.write(`${error.message}
+`);
+      process.exit(1);
+    }
+    throw error;
+  }
+  if (options.print) {
+    process.stdout.write(plan.contents);
+    return;
+  }
+  if (options.dryRun) {
+    process.stdout.write(`Would ${plan.replaced ? "replace" : "add"} "${resolved.name}" in ${path}
+`);
+    return;
+  }
+  if (existing !== undefined) {
+    await copyFile(path, `${path}.relic-backup`);
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, plan.contents);
+  process.stdout.write(`${plan.replaced ? "Replaced" : "Added"} "${resolved.name}" in ${path}
+` + (existing === undefined ? "" : `Previous config saved to ${path}.relic-backup
+`) + `Restart ${harness.label} to pick it up.
+`);
+}
+async function installClaudeCode(options) {
+  const root = packageRoot();
+  if (!await exists(join(root, ".claude-plugin", "marketplace.json"))) {
+    process.stderr.write("This copy of relic-mcp does not carry the plugin manifests, so it " + "cannot be installed as a Claude Code plugin. Use --print and add " + `the server manually, or install a newer version.
+`);
+    process.exit(1);
+  }
+  if (options.dryRun) {
+    process.stdout.write(`Would add marketplace ${root} and install relic@relic
+`);
+    return;
+  }
+  for (const args of [
+    ["plugin", "marketplace", "add", root],
+    ["plugin", "install", "relic@relic"]
+  ]) {
+    const result = spawnSync("claude", args, { stdio: "inherit" });
+    if (result.error !== undefined || result.status !== 0) {
+      process.stderr.write(`
+claude ${args.join(" ")} failed. Is the Claude Code CLI on PATH?
+`);
+      process.exit(1);
+    }
+  }
+  process.stdout.write(`
+Restart Claude Code to pick it up.
+`);
+}
+function withOrigin(spec, options) {
+  const raw = options.origin ?? process.env["RELIC_SERVICE_ORIGIN"];
+  let origin;
+  try {
+    origin = requiredOrigin("--origin", raw);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+
+Pass --origin https://your-relic-service
+`);
+    process.exit(2);
+  }
+  return { ...spec, env: { RELIC_SERVICE_ORIGIN: origin } };
+}
+async function reportDetected() {
+  const home = homedir();
+  const lines = ["Harnesses detected here:", ""];
+  for (const harness of HARNESSES) {
+    if (harness.format === "plugin") {
+      const found2 = spawnSync("claude", ["--version"], { stdio: "ignore" });
+      lines.push(`  ${found2.status === 0 ? "*" : " "} ${harness.id.padEnd(15)}${harness.label}`);
+      continue;
+    }
+    const dir = dirname(join(home, harness.configPath));
+    const found = await stat(dir).then((info) => info.isDirectory()).catch(() => false);
+    lines.push(`  ${found ? "*" : " "} ${harness.id.padEnd(15)}${harness.label}`);
+  }
+  lines.push("", "Install with:", "  relic-mcp install --client <id>", "");
+  process.stdout.write(lines.join(`
+`));
+}
+
 // src/index.ts
+var argv = process.argv.slice(2);
+if (argv[0] === "install") {
+  await runInstall(argv.slice(1));
+  process.exit(0);
+}
+if (argv[0] === "--help" || argv[0] === "-h" || argv[0] === "help") {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+var serviceOrigin = requiredOrigin("RELIC_SERVICE_ORIGIN", process.env["RELIC_SERVICE_ORIGIN"]);
 var deps = {
-  serviceOrigin: process.env["RELIC_SERVICE_ORIGIN"] ?? "https://relic.example",
-  relicOrigin: process.env["RELIC_ORIGIN"] ?? process.env["RELIC_SERVICE_ORIGIN"] ?? "https://relic.example",
+  serviceOrigin,
+  relicOrigin: process.env["RELIC_ORIGIN"] === undefined ? serviceOrigin : requiredOrigin("RELIC_ORIGIN", process.env["RELIC_ORIGIN"]),
   files: nodeFiles,
   fetch: globalThis.fetch,
-  clientName: process.env["RELIC_CLIENT_NAME"] ?? "relic-mcp/0.1.0"
+  clientName: process.env["RELIC_CLIENT_NAME"] ?? "relic-mcp"
 };
 if (process.env["RELIC_MCP_HTTP"] === "1") {
   const port = Number(process.env["RELIC_MCP_PORT"] ?? 7333);

package/mcp-servers.json

@@ -0,0 +1,11 @@
+{
+  "relic": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "relic-mcp@0.1.1"],
+    "env": {
+      "RELIC_SERVICE_ORIGIN": "https://relic-wh2jw5fg2q-uc.a.run.app",
+      "RELIC_CLIENT_NAME": "relic-plugin/0.1.0"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relic-mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Publish a file as an encrypted relic. The key is generated on your machine and never sent to the service.",
   "license": "MIT",
   "type": "module",
@@ -20,17 +20,20 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/TheBushidoCollective/artifacts.git",
+    "url": "git+https://github.com/TheBushidoCollective/relic.git",
     "directory": "packages/relic-mcp"
   },
-  "homepage": "https://github.com/TheBushidoCollective/artifacts#readme",
+  "homepage": "https://github.com/TheBushidoCollective/relic#readme",
   "bugs": {
-    "url": "https://github.com/TheBushidoCollective/artifacts/issues"
+    "url": "https://github.com/TheBushidoCollective/relic/issues"
   },
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    ".claude-plugin",
+    "skills",
+    "mcp-servers.json"
   ],
   "publishConfig": {
     "access": "public",

package/skills/relic/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: relic
+description: Publish a local file as an encrypted, shareable link when someone outside this session needs to see it. Use when the user says "share this", "send this to X", "publish this", "give me a link for this", "make this shareable", or has just been handed a generated report, HTML page, deck, image, or export and needs it somewhere a person can open. Also covers what the recipient sees, how long a link lives, and what the service can and cannot read.
+---
+
+# Relic
+
+Turn a file on this machine into a URL you can hand to a person.
+
+The file is encrypted here, before anything is uploaded. Only ciphertext
+reaches the service. The key lives in the URL fragment, which browsers never
+send to a server, so the operator holds bytes they cannot open.
+
+## Publishing
+
+Call `relic_publish` with a filesystem path:
+
+```
+relic_publish(path: "/Users/me/Downloads/report.html")
+```
+
+It takes a **path, not content**. That is deliberate: the plaintext never
+enters the conversation, so it is never in the transcript, never in a model
+context window, and never in whatever stores those. Do not read a file into
+context and pass its text; pass where it lives.
+
+Optional arguments worth knowing:
+
+- `filename` overrides the display name shown to the recipient.
+- `ttl_days` shortens the life of the link. Shorter is better for anything
+  sensitive; the default is the service maximum.
+
+## Say this when you hand over the link
+
+**The key is in the URL, and the URL is now in the transcript.** Anyone with
+this conversation can open the file. That is structural, not a bug being fixed
+later: returning a usable link is the product, and a usable link contains the
+key.
+
+So the honest framing for the user is: zero-knowledge holds against whoever
+runs Relic. It does not hold against their model provider, or anyone who can
+read their session history. If the content should not be in a transcript at
+all, it should not go through an agent.
+
+Also worth one line, unprompted, the first time in a session:
+
+- links expire (the tool returns the exact date)
+- opens are capped, and the tool's mint response reports how many remain
+- anyone with the link can read it; there are no per-recipient permissions
+
+## What the recipient gets
+
+A page that fetches the ciphertext, decrypts it in their browser, and renders
+by type. Markdown, code, images, and plain text render inline. HTML renders in
+a sandboxed frame on a separate origin, so a published page cannot reach the
+key or the service. Anything else offers a download.
+
+They need the whole URL including the `#...` part. A link truncated at the `#`
+is a page that cannot decrypt anything, and that is the most common way sharing
+fails: chat clients and ticket systems sometimes cut fragments.
+
+## When not to use it
+
+- **Something that belongs in the repo.** Commit it. A relic expires; a commit
+  does not.
+- **A client deliverable.** Those have a durable home, and a link that dies in
+  a week is not it. Publish a relic in addition if someone needs to look at it
+  now, never instead.
+- **Credentials, keys, or tokens.** Encrypted in transit and at rest still ends
+  with a secret sitting in a URL in a transcript.
+
+## Checking what the client does
+
+`relic_describe_client` returns the client's own account of what it uploads and
+what it withholds, plus the service it is pointed at. Use it when the user asks
+what is actually being sent, rather than paraphrasing this file. The published
+source is one file and is deliberately unminified, so "read it yourself" is a
+real answer.

package/src/index.ts

@@ -17,18 +17,48 @@ import { createServer } from 'node:http';
 import { Readable } from 'node:stream';
 import { nodeFiles } from './files.ts';
 import { createHttpHandler } from './http.ts';
+import { runInstall, USAGE } from './installer.ts';
+import { requiredOrigin } from './origin.ts';
 import type { PublishDeps } from './publish.ts';
 import { serveStdio } from './server.ts';
 
+// Subcommands are handled before anything that needs configuration, so
+// `--help` works on a machine that has never set an origin.
+const argv = process.argv.slice(2);
+
+if (argv[0] === 'install') {
+  await runInstall(argv.slice(1));
+  process.exit(0);
+}
+
+if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+// The value travels with whatever installs this: the plugin sets it, and one
+// plugin version bump moves every install. See origin.ts for why there is no
+// default.
+const serviceOrigin = requiredOrigin(
+  'RELIC_SERVICE_ORIGIN',
+  process.env['RELIC_SERVICE_ORIGIN']
+);
+
 const deps: PublishDeps = {
-  serviceOrigin: process.env['RELIC_SERVICE_ORIGIN'] ?? 'https://relic.example',
+  serviceOrigin,
+  // Where the shareable link points, when a reverse proxy or custom domain
+  // fronts the API. Defaults to the API's own origin, which is the common case.
   relicOrigin:
-    process.env['RELIC_ORIGIN'] ??
-    process.env['RELIC_SERVICE_ORIGIN'] ??
-    'https://relic.example',
+    process.env['RELIC_ORIGIN'] === undefined
+      ? serviceOrigin
+      : requiredOrigin('RELIC_ORIGIN', process.env['RELIC_ORIGIN']),
   files: nodeFiles,
   fetch: globalThis.fetch,
-  clientName: process.env['RELIC_CLIENT_NAME'] ?? 'relic-mcp/0.1.0',
+  // Recorded against the grant, so the service can tell what published. No
+  // version baked in: a literal here goes stale the first release nobody
+  // remembers to edit, and a wrong version in a log is worse than none.
+  // Whatever installs this can set the variable to something more specific.
+  clientName: process.env['RELIC_CLIENT_NAME'] ?? 'relic-mcp',
 };
 
 if (process.env['RELIC_MCP_HTTP'] === '1') {

package/src/install.ts

@@ -0,0 +1,260 @@
+/**
+ * Installing this server into whichever agent harness somebody actually uses.
+ *
+ * The server itself needs nothing per harness. MCP over stdio is already the
+ * portable layer, and every target below launches the same command with the
+ * same environment. What differs is only where the config lives and what the
+ * wrapper key is called, which is a packaging problem wearing an integration
+ * problem's clothes.
+ *
+ * So this file holds no protocol code. It computes an edit and hands it back.
+ * The pure `planFor` is what the tests exercise; touching the filesystem is a
+ * separate, small step, because a bug here corrupts somebody's editor config
+ * rather than failing a request.
+ */
+
+export type Format = 'json-mcp-servers' | 'json-servers' | 'toml' | 'plugin';
+
+export interface Harness {
+  readonly id: string;
+  readonly label: string;
+  readonly format: Format;
+  /** Relative to the user's home directory. */
+  readonly configPath: string;
+}
+
+/**
+ * The targets, with the config location each one actually reads.
+ *
+ * Deliberately a short list of things that were checked rather than a long
+ * list of things that sound right. A wrong path here does not error: it
+ * writes a file nobody reads, and the user concludes the tool is broken.
+ */
+export const HARNESSES: readonly Harness[] = [
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    format: 'plugin',
+    configPath: '',
+  },
+  {
+    id: 'claude-desktop',
+    label: 'Claude Desktop',
+    format: 'json-mcp-servers',
+    configPath: 'Library/Application Support/Claude/claude_desktop_config.json',
+  },
+  {
+    id: 'cursor',
+    label: 'Cursor',
+    format: 'json-mcp-servers',
+    configPath: '.cursor/mcp.json',
+  },
+  {
+    id: 'windsurf',
+    label: 'Windsurf',
+    format: 'json-mcp-servers',
+    configPath: '.codeium/windsurf/mcp_config.json',
+  },
+  {
+    id: 'gemini',
+    label: 'Gemini CLI',
+    format: 'json-mcp-servers',
+    configPath: '.gemini/settings.json',
+  },
+  {
+    id: 'vscode',
+    label: 'VS Code',
+    format: 'json-servers',
+    configPath: 'Library/Application Support/Code/User/mcp.json',
+  },
+  {
+    id: 'codex',
+    label: 'Codex',
+    format: 'toml',
+    configPath: '.codex/config.toml',
+  },
+];
+
+export interface ServerSpec {
+  readonly name: string;
+  readonly command: string;
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string>>;
+}
+
+export interface Plan {
+  readonly harness: Harness;
+  /** The file to write, absent for harnesses driven by their own CLI. */
+  readonly path: string | undefined;
+  readonly contents: string;
+  /** True when an entry of this name was already there and got replaced. */
+  readonly replaced: boolean;
+}
+
+export class UnknownHarnessError extends Error {}
+export class ExistingEntryError extends Error {}
+
+/**
+ * Merge the server into whatever the harness already has.
+ *
+ * Merging rather than writing, always. These files hold every other server the
+ * user has configured, and clobbering them to add one entry would be a far
+ * worse bug than failing to install.
+ */
+export function planFor(
+  harnessId: string,
+  spec: ServerSpec,
+  existing: string | undefined,
+  options: { readonly force?: boolean } = {}
+): Plan {
+  const harness = HARNESSES.find((h) => h.id === harnessId);
+  if (harness === undefined) {
+    throw new UnknownHarnessError(
+      `Unknown harness ${harnessId}. Known: ${HARNESSES.map((h) => h.id).join(', ')}`
+    );
+  }
+
+  if (harness.format === 'toml') {
+    return tomlPlan(harness, spec, existing, options);
+  }
+  return jsonPlan(harness, spec, existing, options);
+}
+
+function jsonPlan(
+  harness: Harness,
+  spec: ServerSpec,
+  existing: string | undefined,
+  options: { readonly force?: boolean }
+): Plan {
+  const key = harness.format === 'json-servers' ? 'servers' : 'mcpServers';
+
+  let root: Record<string, unknown> = {};
+  if (existing !== undefined && existing.trim().length > 0) {
+    try {
+      root = JSON.parse(existing) as Record<string, unknown>;
+    } catch (error) {
+      // Refuse rather than replace. An unparseable config is somebody's
+      // settings with a typo in it, not an empty slot.
+      throw new ExistingEntryError(
+        `${harness.configPath} is not valid JSON, so merging would destroy it: ` +
+          `${(error as Error).message}`
+      );
+    }
+  }
+
+  const servers = (root[key] ?? {}) as Record<string, unknown>;
+  const replaced = Object.hasOwn(servers, spec.name);
+  if (replaced && options.force !== true) {
+    throw new ExistingEntryError(
+      `${harness.label} already has a server named "${spec.name}". ` +
+        'Pass --force to replace it.'
+    );
+  }
+
+  // VS Code names the launch mode explicitly; the others infer stdio.
+  const entry =
+    harness.format === 'json-servers'
+      ? { type: 'stdio', command: spec.command, args: spec.args, env: spec.env }
+      : { command: spec.command, args: spec.args, env: spec.env };
+
+  const merged = { ...root, [key]: { ...servers, [spec.name]: entry } };
+  return {
+    harness,
+    path: harness.configPath,
+    contents: `${JSON.stringify(merged, null, 2)}\n`,
+    replaced,
+  };
+}
+
+/**
+ * Codex keeps servers in TOML.
+ *
+ * Appending a table rather than reformatting the file, because a real config
+ * carries comments and ordering that a parse-and-reserialize round trip would
+ * quietly throw away. The only edit made is adding or replacing one table.
+ */
+function tomlPlan(
+  harness: Harness,
+  spec: ServerSpec,
+  existing: string | undefined,
+  options: { readonly force?: boolean }
+): Plan {
+  const body = existing ?? '';
+  const header = `[mcp_servers.${spec.name}]`;
+  const replaced = body.includes(header);
+
+  if (replaced && options.force !== true) {
+    throw new ExistingEntryError(
+      `${harness.label} already has [mcp_servers.${spec.name}]. ` +
+        'Pass --force to replace it.'
+    );
+  }
+
+  const table = [
+    header,
+    `command = ${tomlString(spec.command)}`,
+    `args = [${spec.args.map(tomlString).join(', ')}]`,
+    ...(Object.keys(spec.env).length > 0
+      ? [
+          `[mcp_servers.${spec.name}.env]`,
+          ...Object.entries(spec.env).map(
+            ([k, v]) => `${k} = ${tomlString(v)}`
+          ),
+        ]
+      : []),
+  ].join('\n');
+
+  const withoutOld = replaced ? dropTomlTable(body, spec.name) : body;
+  const separator =
+    withoutOld.length === 0 || withoutOld.endsWith('\n\n')
+      ? ''
+      : withoutOld.endsWith('\n')
+        ? '\n'
+        : '\n\n';
+
+  return {
+    harness,
+    path: harness.configPath,
+    contents: `${withoutOld}${separator}${table}\n`,
+    replaced,
+  };
+}
+
+/** Remove `[mcp_servers.<name>]` and its sub-tables, leaving the rest intact. */
+function dropTomlTable(body: string, name: string): string {
+  const lines = body.split('\n');
+  const kept: string[] = [];
+  let skipping = false;
+
+  for (const line of lines) {
+    const isHeader = /^\s*\[/.test(line);
+    if (isHeader) {
+      skipping =
+        line.trim() === `[mcp_servers.${name}]` ||
+        line.trim().startsWith(`[mcp_servers.${name}.`);
+    }
+    if (!skipping) kept.push(line);
+  }
+
+  return `${kept
+    .join('\n')
+    .replace(/\n{3,}$/, '\n\n')
+    .trimEnd()}\n`;
+}
+
+function tomlString(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/** The snippet to paste, for any harness not listed above. */
+export function snippetFor(spec: ServerSpec): string {
+  return `${JSON.stringify(
+    {
+      mcpServers: {
+        [spec.name]: { command: spec.command, args: spec.args, env: spec.env },
+      },
+    },
+    null,
+    2
+  )}\n`;
+}

package/src/installer.ts

@@ -0,0 +1,266 @@
+/**
+ * The `relic-mcp install` command.
+ *
+ * Everything that decides *what* to write lives in `install.ts` and is pure.
+ * This file is the part that touches the disk and talks to the user, kept thin
+ * on purpose: it is the half that can damage somebody's editor configuration,
+ * and the less logic it holds the less there is to get wrong.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  ExistingEntryError,
+  HARNESSES,
+  planFor,
+  type ServerSpec,
+  snippetFor,
+  UnknownHarnessError,
+} from './install.ts';
+import { requiredOrigin } from './origin.ts';
+
+export const USAGE = `relic-mcp - publish a file as an encrypted, shareable link
+
+  relic-mcp                      run the MCP server on stdio
+  relic-mcp install [options]    add this server to an agent harness
+  relic-mcp --help               this
+
+Install options:
+  --client <id>     ${HARNESSES.map((h) => h.id).join(', ')}
+                    Omit to see which of these are installed here.
+  --origin <url>    The Relic service to publish to. Falls back to
+                    RELIC_SERVICE_ORIGIN.
+  --name <name>     Server name in the config. Default: relic.
+  --print           Write nothing; print the config to paste.
+  --force           Replace an existing entry of the same name.
+  --dry-run         Show the file and what would change, without writing.
+`;
+
+interface Options {
+  client: string | undefined;
+  origin: string | undefined;
+  name: string;
+  print: boolean;
+  force: boolean;
+  dryRun: boolean;
+}
+
+function parseArgs(argv: readonly string[]): Options {
+  const options: Options = {
+    client: undefined,
+    origin: undefined,
+    name: 'relic',
+    print: false,
+    force: false,
+    dryRun: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = (): string => {
+      const value = argv[++i];
+      if (value === undefined) throw new Error(`${arg} needs a value`);
+      return value;
+    };
+
+    if (arg === '--client') options.client = next();
+    else if (arg === '--origin') options.origin = next();
+    else if (arg === '--name') options.name = next();
+    else if (arg === '--print') options.print = true;
+    else if (arg === '--force') options.force = true;
+    else if (arg === '--dry-run') options.dryRun = true;
+    else throw new Error(`Unknown option ${arg}`);
+  }
+
+  return options;
+}
+
+/** The directory of the installed package, which is also the plugin root. */
+function packageRoot(): string {
+  // dist/relic-mcp.js -> the package directory.
+  return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+async function exists(path: string): Promise<boolean> {
+  return readFile(path)
+    .then(() => true)
+    .catch(() => false);
+}
+
+export async function runInstall(argv: readonly string[]): Promise<void> {
+  let options: Options;
+  try {
+    options = parseArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${(error as Error).message}\n\n${USAGE}`);
+    process.exit(2);
+  }
+
+  const spec: ServerSpec = {
+    name: options.name,
+    command: 'npx',
+    args: ['-y', 'relic-mcp'],
+    env: {},
+  };
+
+  if (options.print && options.client === undefined) {
+    process.stdout.write(snippetFor(withOrigin(spec, options)));
+    return;
+  }
+
+  if (options.client === undefined) {
+    await reportDetected();
+    return;
+  }
+
+  const resolved = withOrigin(spec, options);
+
+  if (options.client === 'claude-code') {
+    await installClaudeCode(options);
+    return;
+  }
+
+  const home = homedir();
+  const harness = HARNESSES.find((h) => h.id === options.client);
+  if (harness === undefined) {
+    process.stderr.write(
+      `Unknown client ${options.client}. Known: ` +
+        `${HARNESSES.map((h) => h.id).join(', ')}\n`
+    );
+    process.exit(2);
+  }
+
+  const path = join(home, harness.configPath);
+  const existing = await readFile(path, 'utf8').catch(() => undefined);
+
+  let plan: ReturnType<typeof planFor>;
+  try {
+    plan = planFor(options.client, resolved, existing, {
+      force: options.force,
+    });
+  } catch (error) {
+    if (
+      error instanceof ExistingEntryError ||
+      error instanceof UnknownHarnessError
+    ) {
+      process.stderr.write(`${error.message}\n`);
+      process.exit(1);
+    }
+    throw error;
+  }
+
+  if (options.print) {
+    process.stdout.write(plan.contents);
+    return;
+  }
+
+  if (options.dryRun) {
+    process.stdout.write(
+      `Would ${plan.replaced ? 'replace' : 'add'} "${resolved.name}" in ${path}\n`
+    );
+    return;
+  }
+
+  // Back up before touching a file this tool did not create. Cheap, and the
+  // difference between an annoying mistake and a lost configuration.
+  if (existing !== undefined) {
+    await copyFile(path, `${path}.relic-backup`);
+  }
+
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, plan.contents);
+
+  process.stdout.write(
+    `${plan.replaced ? 'Replaced' : 'Added'} "${resolved.name}" in ${path}\n` +
+      (existing === undefined
+        ? ''
+        : `Previous config saved to ${path}.relic-backup\n`) +
+      `Restart ${harness.label} to pick it up.\n`
+  );
+}
+
+/**
+ * Claude Code installs as a plugin rather than a bare server, because the
+ * plugin also carries the skill that tells the agent when publishing is the
+ * right move. The package ships the manifests, so the marketplace source is
+ * this directory on disk and no clone is involved.
+ */
+async function installClaudeCode(options: Options): Promise<void> {
+  const root = packageRoot();
+
+  if (!(await exists(join(root, '.claude-plugin', 'marketplace.json')))) {
+    process.stderr.write(
+      'This copy of relic-mcp does not carry the plugin manifests, so it ' +
+        'cannot be installed as a Claude Code plugin. Use --print and add ' +
+        'the server manually, or install a newer version.\n'
+    );
+    process.exit(1);
+  }
+
+  if (options.dryRun) {
+    process.stdout.write(
+      `Would add marketplace ${root} and install relic@relic\n`
+    );
+    return;
+  }
+
+  for (const args of [
+    ['plugin', 'marketplace', 'add', root],
+    ['plugin', 'install', 'relic@relic'],
+  ]) {
+    const result = spawnSync('claude', args, { stdio: 'inherit' });
+    if (result.error !== undefined || result.status !== 0) {
+      process.stderr.write(
+        `\nclaude ${args.join(' ')} failed. Is the Claude Code CLI on PATH?\n`
+      );
+      process.exit(1);
+    }
+  }
+
+  process.stdout.write('\nRestart Claude Code to pick it up.\n');
+}
+
+function withOrigin(spec: ServerSpec, options: Options): ServerSpec {
+  const raw = options.origin ?? process.env['RELIC_SERVICE_ORIGIN'];
+  let origin: string;
+  try {
+    origin = requiredOrigin('--origin', raw);
+  } catch (error) {
+    process.stderr.write(
+      `${(error as Error).message}\n\nPass --origin https://your-relic-service\n`
+    );
+    process.exit(2);
+  }
+  return { ...spec, env: { RELIC_SERVICE_ORIGIN: origin } };
+}
+
+/** What is actually on this machine, so the next command is obvious. */
+async function reportDetected(): Promise<void> {
+  const home = homedir();
+  const lines: string[] = ['Harnesses detected here:', ''];
+
+  for (const harness of HARNESSES) {
+    if (harness.format === 'plugin') {
+      const found = spawnSync('claude', ['--version'], { stdio: 'ignore' });
+      lines.push(
+        `  ${found.status === 0 ? '*' : ' '} ${harness.id.padEnd(15)}${harness.label}`
+      );
+      continue;
+    }
+    // The directory rather than the file: a harness that has never had an MCP
+    // server configured has no config file yet, and is still installed.
+    const dir = dirname(join(home, harness.configPath));
+    const found = await stat(dir)
+      .then((info) => info.isDirectory())
+      .catch(() => false);
+    lines.push(
+      `  ${found ? '*' : ' '} ${harness.id.padEnd(15)}${harness.label}`
+    );
+  }
+
+  lines.push('', 'Install with:', '  relic-mcp install --client <id>', '');
+  process.stdout.write(lines.join('\n'));
+}

package/src/origin.ts

@@ -0,0 +1,54 @@
+/**
+ * Reading the service origin out of the environment.
+ *
+ * Its own module because the entry point runs a server as a side effect of
+ * being imported, and a rule this easy to get wrong deserves tests that do not
+ * have to start one.
+ */
+
+/**
+ * Require an origin, or explain what is missing.
+ *
+ * There is deliberately no default. A placeholder would turn "you did not
+ * configure me" into a DNS failure on the first publish, which is a worse
+ * message arriving later, and a real origin baked into a published tarball
+ * would outlive whatever address the service actually has.
+ *
+ * Returns the origin only. A path, query, or fragment in the variable is
+ * dropped rather than quietly concatenated into every request URL.
+ */
+export function requiredOrigin(name: string, raw: string | undefined): string {
+  if (raw === undefined || raw.trim().length === 0) {
+    throw new Error(
+      `${name} is not set. It is the Relic service this client publishes to, ` +
+        'for example https://relic.example.com. Installing the Relic plugin ' +
+        'sets it for you; set it yourself when running this server directly.'
+    );
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(raw.trim());
+  } catch {
+    throw new Error(`${name} is not a URL: ${raw}`);
+  }
+
+  // http is allowed only against a loopback host, where there is no network
+  // path to sit on. Plaintext never leaves this machine either way, but the
+  // grant authorizing an upload does, and over http anyone between here and
+  // the service can take it and spend it.
+  const loopback =
+    parsed.hostname === 'localhost' ||
+    parsed.hostname === '127.0.0.1' ||
+    parsed.hostname === '[::1]';
+
+  if (parsed.protocol !== 'https:' && !loopback) {
+    throw new Error(
+      `${name} must be https, or a loopback host for development. Got ${raw}. ` +
+        'Plaintext never leaves this machine, but the grant that authorizes ' +
+        'an upload does, and over http anyone on the path can take it.'
+    );
+  }
+
+  return parsed.origin;
+}