relic-mcp 0.1.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "relic-mcp",
+  "version": "0.1.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",
+  "main": "dist/relic-mcp.js",
+  "bin": {
+    "relic-mcp": "dist/relic-mcp.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "encryption",
+    "zero-knowledge",
+    "file-sharing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheBushidoCollective/artifacts.git",
+    "directory": "packages/relic-mcp"
+  },
+  "homepage": "https://github.com/TheBushidoCollective/artifacts#readme",
+  "bugs": {
+    "url": "https://github.com/TheBushidoCollective/artifacts/issues"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "bun run build.ts"
+  },
+  "devDependencies": {
+    "@relic/format": "workspace:*",
+    "@relic/server": "workspace:*"
+  }
+}

package/src/files.ts

@@ -0,0 +1,30 @@
+/** Filesystem access through Node, kept behind the FileReader interface. */
+
+import { lstat, readFile } from 'node:fs/promises';
+import { basename as pathBasename, resolve as pathResolve } from 'node:path';
+import type { FileReader } from './publish.ts';
+
+export const nodeFiles: FileReader = {
+  resolve(path) {
+    // A relative path resolves against the server process's working
+    // directory, and the result is echoed so a publish that picked up the
+    // wrong file is diagnosable from the result rather than a support thread.
+    return pathResolve(process.cwd(), path);
+  },
+
+  basename(path) {
+    return pathBasename(path);
+  },
+
+  async stat(path) {
+    const info = await lstat(path).catch(() => undefined);
+    if (info === undefined) return { kind: 'other' };
+    if (info.isDirectory()) return { kind: 'directory' };
+    if (!info.isFile()) return { kind: 'other' };
+    return { kind: 'file', size: info.size };
+  },
+
+  async read(path) {
+    return new Uint8Array(await readFile(path));
+  },
+};

package/src/http.ts

@@ -0,0 +1,192 @@
+/**
+ * Streamable HTTP transport, revision `2026-07-28`.
+ *
+ * Stateless by construction: a single POST endpoint, one HTTP request per
+ * JSON-RPC message, no session, and no `Mcp-Session-Id`. Nothing is retained
+ * between calls, so a load balancer can round-robin across processes with no
+ * sticky routing and no shared session store.
+ *
+ * **This does not make Relic hostable.** The transport says how bytes reach
+ * the server, not where the server runs. The publishing client must sit next
+ * to the plaintext, because encrypting it anywhere else is the thing the
+ * product exists to avoid. HTTP is here so one server can be shared between
+ * local agents, run under a supervisor, or be probed by tooling that speaks
+ * only HTTP. The default bind is loopback, and that is deliberate.
+ */
+
+import {
+  decodeHeaderValue,
+  ERROR_CODES,
+  errorResponse,
+  expectedMcpName,
+  isSupportedVersion,
+  type JsonRpcRequest,
+  requestedProtocolVersion,
+  unsupportedVersionError,
+} from './protocol.ts';
+import type { PublishDeps } from './publish.ts';
+import { handleMessage } from './server.ts';
+
+export interface HttpOptions {
+  /**
+   * Origins allowed to call the endpoint.
+   *
+   * The transport requires `Origin` validation to defeat DNS rebinding: a page
+   * on any website can otherwise reach a server bound to loopback. An empty
+   * list refuses every request that carries an `Origin` at all, which is the
+   * right default for a local server driven by a non-browser client.
+   */
+  readonly allowedOrigins?: readonly string[];
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/**
+ * Build the fetch handler for the MCP endpoint.
+ *
+ * Every check below is a MUST in the transport spec, and each is a place a
+ * lenient implementation becomes a security problem rather than a
+ * compatibility one.
+ */
+export function createHttpHandler(
+  deps: PublishDeps,
+  options: HttpOptions = {}
+): (request: Request) => Promise<Response> {
+  const allowed = new Set(options.allowedOrigins ?? []);
+
+  return async (request: Request): Promise<Response> => {
+    // DNS rebinding defence. A browser page cannot suppress `Origin`, so a
+    // present-and-unlisted origin is refused outright.
+    const origin = request.headers.get('origin');
+    if (origin !== null && !allowed.has(origin)) {
+      return jsonResponse(
+        errorResponse(null, ERROR_CODES.headerMismatch, 'origin not allowed'),
+        403
+      );
+    }
+
+    // Sessions and standalone SSE streams are gone in this revision. An older
+    // client gets a clear refusal rather than a confusing 404.
+    if (request.method !== 'POST') {
+      return new Response('Method not allowed', {
+        status: 405,
+        headers: { allow: 'POST' },
+      });
+    }
+
+    let message: JsonRpcRequest;
+    try {
+      message = (await request.json()) as JsonRpcRequest;
+    } catch {
+      return jsonResponse(
+        errorResponse(null, ERROR_CODES.parseError, 'parse error'),
+        400
+      );
+    }
+
+    const id = message.id ?? null;
+
+    // The version header and the `_meta` field must agree. They exist so an
+    // intermediary can route without parsing the body, and a mismatch is
+    // exactly the split-brain where a gateway and a server act on different
+    // values.
+    const headerVersion = request.headers.get('mcp-protocol-version');
+    const bodyVersion = requestedProtocolVersion(message);
+
+    if (headerVersion === null) {
+      return jsonResponse(
+        errorResponse(
+          id,
+          ERROR_CODES.headerMismatch,
+          'MCP-Protocol-Version header is required'
+        ),
+        400
+      );
+    }
+    if (bodyVersion !== undefined && headerVersion !== bodyVersion) {
+      return jsonResponse(
+        errorResponse(
+          id,
+          ERROR_CODES.headerMismatch,
+          `Header mismatch: MCP-Protocol-Version header value ` +
+            `'${headerVersion}' does not match body value '${bodyVersion}'`
+        ),
+        400
+      );
+    }
+    if (!isSupportedVersion(headerVersion)) {
+      return jsonResponse(unsupportedVersionError(id, headerVersion), 400);
+    }
+
+    // `Mcp-Method` mirrors `method`, and `Mcp-Name` mirrors `params.name` or
+    // `params.uri`, so gateways can route and meter on headers alone.
+    const headerMethod = request.headers.get('mcp-method');
+    if (headerMethod === null) {
+      return jsonResponse(
+        errorResponse(
+          id,
+          ERROR_CODES.headerMismatch,
+          'Mcp-Method header is required'
+        ),
+        400
+      );
+    }
+    if (headerMethod !== message.method) {
+      return jsonResponse(
+        errorResponse(
+          id,
+          ERROR_CODES.headerMismatch,
+          `Header mismatch: Mcp-Method header value '${headerMethod}' does ` +
+            `not match body value '${message.method}'`
+        ),
+        400
+      );
+    }
+
+    const wantsName = expectedMcpName(message);
+    if (wantsName !== undefined) {
+      const rawName = request.headers.get('mcp-name');
+      if (rawName === null) {
+        return jsonResponse(
+          errorResponse(
+            id,
+            ERROR_CODES.headerMismatch,
+            'Mcp-Name header is required for this method'
+          ),
+          400
+        );
+      }
+      // Decoded before comparison, or a non-ASCII name fails against its own
+      // request body.
+      if (decodeHeaderValue(rawName) !== wantsName) {
+        return jsonResponse(
+          errorResponse(
+            id,
+            ERROR_CODES.headerMismatch,
+            'Header mismatch: Mcp-Name header value does not match body value'
+          ),
+          400
+        );
+      }
+    }
+
+    const response = await handleMessage(message, deps);
+
+    // A notification is accepted with no body.
+    if (response === undefined) return new Response(null, { status: 202 });
+
+    // An unknown method is a 404 carrying a JSON-RPC error, which is what
+    // distinguishes a modern server from a legacy one that simply does not
+    // host this path.
+    if (response.error?.code === ERROR_CODES.methodNotFound) {
+      return jsonResponse(response, 404);
+    }
+
+    return jsonResponse(response);
+  };
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Entry point for the local MCP server.
+ *
+ * Plain Node, no Bun APIs, because this ships to npm and runs under whatever
+ * runtime `npx` happens to have. Everything it needs (`fetch`, `crypto.subtle`,
+ * `TextEncoder`, web streams) is standard from Node 18 on.
+ *
+ * stdio by default, which is what every agent runner expects. Set
+ * `RELIC_MCP_HTTP=1` to serve the Streamable HTTP transport instead.
+ *
+ * Nothing is written to stdout except JSON-RPC. Diagnostics go to stderr,
+ * because a stray stdout write corrupts the protocol stream.
+ */
+
+import { createServer } from 'node:http';
+import { Readable } from 'node:stream';
+import { nodeFiles } from './files.ts';
+import { createHttpHandler } from './http.ts';
+import type { PublishDeps } from './publish.ts';
+import { serveStdio } from './server.ts';
+
+const deps: PublishDeps = {
+  serviceOrigin: process.env['RELIC_SERVICE_ORIGIN'] ?? 'https://relic.example',
+  relicOrigin:
+    process.env['RELIC_ORIGIN'] ??
+    process.env['RELIC_SERVICE_ORIGIN'] ??
+    'https://relic.example',
+  files: nodeFiles,
+  fetch: globalThis.fetch,
+  clientName: process.env['RELIC_CLIENT_NAME'] ?? 'relic-mcp/0.1.0',
+};
+
+if (process.env['RELIC_MCP_HTTP'] === '1') {
+  const port = Number(process.env['RELIC_MCP_PORT'] ?? 7333);
+  // Loopback, not 0.0.0.0. This process can read any file its user can, so
+  // binding it to a network interface hands that reach to the network.
+  const hostname = process.env['RELIC_MCP_HOST'] ?? '127.0.0.1';
+
+  const allowedOrigins = (process.env['RELIC_MCP_ALLOWED_ORIGINS'] ?? '')
+    .split(',')
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+
+  const handler = createHttpHandler(deps, { allowedOrigins });
+
+  createServer((incoming, outgoing) => {
+    const chunks: Buffer[] = [];
+    incoming.on('data', (chunk: Buffer) => chunks.push(chunk));
+    incoming.on('end', () => {
+      void (async () => {
+        const url = new URL(
+          incoming.url ?? '/',
+          `http://${incoming.headers.host ?? `${hostname}:${port}`}`
+        );
+
+        if (url.pathname !== '/mcp') {
+          outgoing.writeHead(404).end('Not found');
+          return;
+        }
+
+        const method = incoming.method ?? 'GET';
+        const request = new Request(url, {
+          method,
+          headers: incoming.headers as Record<string, string>,
+          ...(method === 'GET' || method === 'HEAD'
+            ? {}
+            : { body: Buffer.concat(chunks) }),
+        });
+
+        const response = await handler(request);
+        outgoing.writeHead(
+          response.status,
+          Object.fromEntries(response.headers.entries())
+        );
+        const body = await response.arrayBuffer();
+        outgoing.end(Buffer.from(body));
+      })();
+    });
+  }).listen(port, hostname, () => {
+    console.error(`relic-mcp listening on http://${hostname}:${port}/mcp`);
+  });
+} else {
+  // Node's stdin is a classic Readable; the transport reads a web stream.
+  await serveStdio(
+    deps,
+    Readable.toWeb(process.stdin) as unknown as ReadableStream<Uint8Array>,
+    (line) => {
+      process.stdout.write(`${line}\n`);
+    }
+  );
+}

package/src/protocol.ts

@@ -0,0 +1,148 @@
+/**
+ * MCP protocol plumbing, shared by both transports.
+ *
+ * Revision `2026-07-28` is the pin, and it is the revision that made the
+ * protocol core stateless: there is no `initialize` handshake, no session, and
+ * no `Mcp-Session-Id`. Every request declares its own version in `_meta` and
+ * the server accepts or rejects each one independently.
+ *
+ * That suits Relic exactly. The server holds nothing between calls, so it can
+ * be restarted, load-balanced, or run one-shot without a client noticing.
+ *
+ * The legacy `initialize` handshake is still answered, which the spec calls a
+ * dual-era server. A publishing client that only speaks the newest revision is
+ * unusable in most of the agents this product exists to serve.
+ */
+
+/** The revision this server prefers. */
+export const PROTOCOL_VERSION = '2026-07-28';
+
+/**
+ * Handshake-based revisions this server still answers.
+ *
+ * Legacy clients have no fall-forward mechanism, so dropping these would make
+ * Relic unreachable from them with no diagnostic they could act on.
+ */
+export const LEGACY_PROTOCOL_VERSIONS = [
+  '2025-11-25',
+  '2025-06-18',
+  '2025-03-26',
+] as const;
+
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+  PROTOCOL_VERSION,
+  ...LEGACY_PROTOCOL_VERSIONS,
+] as const;
+
+/** The `_meta` key carrying the per-request protocol version. */
+export const PROTOCOL_VERSION_META_KEY =
+  'io.modelcontextprotocol/protocolVersion';
+
+/** Protocol-defined error codes used here. */
+export const ERROR_CODES = {
+  /** Headers disagree with the body, or a required header is missing. */
+  headerMismatch: -32020,
+  /** The requested revision is one this server does not implement. */
+  unsupportedProtocolVersion: -32022,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  parseError: -32700,
+} as const;
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export function errorResponse(
+  id: string | number | null,
+  code: number,
+  message: string,
+  data?: unknown
+): JsonRpcResponse {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: data === undefined ? { code, message } : { code, message, data },
+  };
+}
+
+/**
+ * The version a request declares, or undefined when it declares none.
+ *
+ * A missing version is not an error here: a legacy client sending
+ * `initialize` has no `_meta` to put one in, and that request is answered
+ * under legacy semantics.
+ */
+export function requestedProtocolVersion(
+  message: JsonRpcRequest
+): string | undefined {
+  const meta = message.params?.['_meta'];
+  if (typeof meta !== 'object' || meta === null) return undefined;
+  const version = (meta as Record<string, unknown>)[PROTOCOL_VERSION_META_KEY];
+  return typeof version === 'string' ? version : undefined;
+}
+
+export function isSupportedVersion(version: string): boolean {
+  return (SUPPORTED_PROTOCOL_VERSIONS as readonly string[]).includes(version);
+}
+
+/**
+ * `UnsupportedProtocolVersionError`, carrying what the server does support so
+ * the client can retry rather than guess.
+ */
+export function unsupportedVersionError(
+  id: string | number | null,
+  requested: string
+): JsonRpcResponse {
+  return errorResponse(
+    id,
+    ERROR_CODES.unsupportedProtocolVersion,
+    'Unsupported protocol version',
+    { supported: [...SUPPORTED_PROTOCOL_VERSIONS], requested }
+  );
+}
+
+/**
+ * Decode the Base64 sentinel form the transport uses for header values that
+ * cannot be represented as plain ASCII.
+ *
+ * `=?base64?{value}?=`, markers lowercase and case-sensitive. Servers MUST
+ * decode before comparing a header to the body, or a tool with a non-ASCII
+ * name would fail validation against its own request.
+ */
+export function decodeHeaderValue(raw: string): string {
+  if (!raw.startsWith('=?base64?') || !raw.endsWith('?=')) return raw;
+  const encoded = raw.slice('=?base64?'.length, -'?='.length);
+  try {
+    return new TextDecoder().decode(
+      Uint8Array.from(atob(encoded), (ch) => ch.charCodeAt(0))
+    );
+  } catch {
+    // An undecodable sentinel is returned as-is so the comparison fails and
+    // the request is rejected, rather than throwing here.
+    return raw;
+  }
+}
+
+/** The value `Mcp-Name` must carry for a given message, if any. */
+export function expectedMcpName(message: JsonRpcRequest): string | undefined {
+  if (message.method === 'tools/call' || message.method === 'prompts/get') {
+    const name = message.params?.['name'];
+    return typeof name === 'string' ? name : undefined;
+  }
+  if (message.method === 'resources/read') {
+    const uri = message.params?.['uri'];
+    return typeof uri === 'string' ? uri : undefined;
+  }
+  return undefined;
+}