phaedo-mcp 0.1.0

package/install.mjs

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+// `phaedo-mcp` one-click installer — wires the Phaedo MCP server into the MCP
+// clients you already have (Claude Desktop, Cursor, Claude Code), so injection
+// "just works" without hand-editing JSON.
+//
+// What it does:
+//   1. Find each MCP client's config file for this OS.
+//   2. Merge a `phaedo` server entry into its `mcpServers` map (never clobbering
+//      your other servers or settings — the file is backed up first).
+//   3. Point that entry at THIS checkout's server.js, run by THIS node binary
+//      (absolute path — a GUI-launched client often has no `node` on PATH).
+//   4. Optionally run the one-time pairing (`--pair`) and print next steps.
+//
+// Pure Node builtins — runs before `npm install`. (Pairing/serving need the deps;
+// the platform launchers in installers/ run `npm install` first.)
+//
+// Usage:
+//   node install.mjs                 configure every detected client
+//   node install.mjs --pair          configure, then run the pairing flow
+//   node install.mjs --uninstall     remove the phaedo entry from every client
+//   node install.mjs --dry-run       show what would change, write nothing
+//   node install.mjs --only cursor   restrict to one client id
+//   node install.mjs --help
+
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+
+const BASE_DIR = dirname(fileURLToPath(import.meta.url));
+const SERVER_PATH = join(BASE_DIR, 'server.js');
+const HOOK_PATH = join(BASE_DIR, 'hooks', 'session-start.mjs');
+const ENTRY_KEY = 'phaedo';
+const HOOK_MARKER = 'hooks/session-start.mjs'; // identifies our SessionStart entry
+
+// ── Client registry ──────────────────────────────────────────────────────────
+// Every supported client stores MCP servers as a top-level `mcpServers` object,
+// so one merge shape covers them all. `configPath` is resolved per-OS from an
+// injectable env (so tests can drive every platform without touching real files).
+export function detectClients({ platform = process.platform, home = homedir(), env = process.env } = {}) {
+  const appData = env.APPDATA || join(home, 'AppData', 'Roaming');
+  const macSupport = join(home, 'Library', 'Application Support');
+  const xdgConfig = env.XDG_CONFIG_HOME || join(home, '.config');
+
+  const claudeDesktop = {
+    win32: join(appData, 'Claude', 'claude_desktop_config.json'),
+    darwin: join(macSupport, 'Claude', 'claude_desktop_config.json'),
+    linux: join(xdgConfig, 'Claude', 'claude_desktop_config.json'),
+  }[platform];
+
+  const clients = [
+    { id: 'claude-desktop', name: 'Claude Desktop', configPath: claudeDesktop, createIfMissing: true,
+      restartHint: 'Quit and reopen Claude Desktop.' },
+    // Cursor: global MCP config in ~/.cursor/mcp.json.
+    { id: 'cursor', name: 'Cursor', configPath: join(home, '.cursor', 'mcp.json'), createIfMissing: true,
+      restartHint: 'Restart Cursor (or toggle the MCP server in Settings → MCP).' },
+    // Claude Code: the CLI manages ~/.claude.json. We only merge into it when it
+    // already exists — never hand-create that large, CLI-owned file.
+    { id: 'claude-code', name: 'Claude Code', configPath: join(home, '.claude.json'), createIfMissing: false,
+      restartHint: 'Start a new Claude Code session (or run `/mcp` to confirm).' },
+  ];
+  return clients.filter((c) => Boolean(c.configPath));
+}
+
+// The server entry written into a client's mcpServers map. Uses the absolute
+// node binary (process.execPath) because GUI-launched clients often lack a PATH
+// that resolves bare `node`. `nodePath`/`serverPath`/`env` injectable for tests.
+export function serverEntry({ nodePath = process.execPath, serverPath = SERVER_PATH, env } = {}) {
+  const entry = { command: nodePath, args: [serverPath] };
+  if (env && Object.keys(env).length) entry.env = env;
+  return entry;
+}
+
+// ── Consult model judge config (on by default) ────────────────────────────────
+// The MCP server runs the consult model judge when PHAEDO_CONSULT_MODEL is set;
+// it falls back to the local rule engine if the model/Ollama isn't there, so
+// defaulting it ON is safe. We write a LOCAL endpoint only (privacy-clean); a
+// frontier (off-device) judge is intentionally not wired here.
+const DEFAULT_CONSULT_MODEL = 'llama3.1:8b';
+const DEFAULT_CONSULT_URL = 'http://localhost:11434';
+
+export function buildConsultEnv({ model = DEFAULT_CONSULT_MODEL, url = DEFAULT_CONSULT_URL, disabled = false } = {}) {
+  if (disabled) return {};
+  return { PHAEDO_CONSULT_MODEL: model, PHAEDO_CONSULT_MODEL_URL: url };
+}
+
+// Probe local Ollama so "on by default" works with whatever model the user has.
+// Picks the first installed general-purpose model (skips the phaedo extraction
+// fine-tune). Falls back to the default string + reachable:false on any failure.
+export async function detectConsultModel({ url = DEFAULT_CONSULT_URL, fallback = DEFAULT_CONSULT_MODEL, fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const res = await fetchImpl(`${url.replace(/\/$/, '')}/api/tags`, { signal: AbortSignal.timeout(1500) });
+    if (!res.ok) return { model: fallback, reachable: false, hadModels: false };
+    const data = await res.json();
+    const names = (data.models || []).map((m) => m.name || m.model).filter(Boolean);
+    const general = names.find((n) => !/phaedo|extract/i.test(n));
+    return { model: general || fallback, reachable: true, hadModels: names.length > 0, picked: !!general };
+  } catch {
+    return { model: fallback, reachable: false, hadModels: false };
+  }
+}
+
+export function readConfig(path) {
+  // Returns { config, existed }. Throws on malformed JSON so the caller can
+  // refuse to overwrite a file it can't safely parse (never destroy hand-edits).
+  if (!existsSync(path)) return { config: {}, existed: false };
+  const raw = readFileSync(path, 'utf8');
+  if (raw.trim() === '') return { config: {}, existed: true };
+  try {
+    const config = JSON.parse(raw);
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+      throw new Error('top-level value is not a JSON object');
+    }
+    return { config, existed: true };
+  } catch (err) {
+    throw new Error(`malformed JSON (${err.message})`);
+  }
+}
+
+// Merge our entry under mcpServers.phaedo, preserving every other server and
+// every other top-level key. Returns { config, changed }.
+export function mergeServerEntry(config, entry, key = ENTRY_KEY) {
+  const next = { ...config, mcpServers: { ...(config.mcpServers || {}) } };
+  const before = JSON.stringify(next.mcpServers[key] || null);
+  next.mcpServers[key] = entry;
+  return { config: next, changed: JSON.stringify(entry) !== before };
+}
+
+// Remove our entry. Returns { config, changed }.
+export function removeServerEntry(config, key = ENTRY_KEY) {
+  if (!config.mcpServers || !(key in config.mcpServers)) return { config, changed: false };
+  const servers = { ...config.mcpServers };
+  delete servers[key];
+  return { config: { ...config, mcpServers: servers }, changed: true };
+}
+
+// ── Claude Code SessionStart hook (--code-hook) ───────────────────────────────
+// True auto-injection for Claude Code: ~/.claude/settings.json runs our hook
+// script at every session start. Merged non-destructively into settings.hooks.
+export function claudeSettingsPath({ home = homedir() } = {}) {
+  return join(home, '.claude', 'settings.json');
+}
+
+export function hookCommand({ nodePath = process.execPath, hookPath = HOOK_PATH } = {}) {
+  // Quote both — node path / checkout path may contain spaces; the hook runs in a shell.
+  return `"${nodePath}" "${hookPath}"`;
+}
+
+const isPhaedoHookEntry = (e) =>
+  e && Array.isArray(e.hooks) &&
+  e.hooks.some((h) => typeof h.command === 'string' && h.command.includes(HOOK_MARKER));
+
+export function mergeSessionStartHook(settings, command) {
+  const next = { ...settings, hooks: { ...(settings.hooks || {}) } };
+  const prior = Array.isArray(next.hooks.SessionStart) ? next.hooks.SessionStart : [];
+  const others = prior.filter((e) => !isPhaedoHookEntry(e)); // drop a stale phaedo entry (path refresh)
+  const existing = prior.find(isPhaedoHookEntry);
+  const already = !!existing && existing.hooks.some((h) => h.command === command);
+  next.hooks.SessionStart = [...others, { hooks: [{ type: 'command', command }] }];
+  return { settings: next, changed: !already };
+}
+
+export function removeSessionStartHook(settings) {
+  if (!settings.hooks || !Array.isArray(settings.hooks.SessionStart)) return { settings, changed: false };
+  const prior = settings.hooks.SessionStart;
+  const others = prior.filter((e) => !isPhaedoHookEntry(e));
+  if (others.length === prior.length) return { settings, changed: false };
+  const hooks = { ...settings.hooks };
+  if (others.length) hooks.SessionStart = others; else delete hooks.SessionStart;
+  const next = { ...settings, hooks };
+  if (Object.keys(next.hooks).length === 0) delete next.hooks;
+  return { settings: next, changed: true };
+}
+
+// action: 'install' | 'uninstall'. Returns a result record. settings.json is a
+// small, safe-to-create file (unlike the CLI-owned ~/.claude.json).
+export function applyCodeHook({ action, dryRun = false, home = homedir() } = {}) {
+  const path = claudeSettingsPath({ home });
+  const name = 'Claude Code hook';
+  let read;
+  try {
+    read = readConfig(path);
+  } catch (err) {
+    return { name, status: 'error', detail: `skipped — ${err.message}; not touched` };
+  }
+  if (action === 'uninstall') {
+    if (!read.existed) return { name, status: 'absent', detail: 'no settings.json' };
+    const { settings, changed } = removeSessionStartHook(read.config);
+    if (!changed) return { name, status: 'absent', detail: 'no phaedo hook to remove' };
+    if (!dryRun) { backup(path); writeConfig(path, settings); }
+    return { name, status: dryRun ? 'would-remove' : 'removed', detail: path };
+  }
+  const { settings, changed } = mergeSessionStartHook(read.config, hookCommand());
+  if (!changed) return { name, status: 'unchanged', detail: 'already configured' };
+  if (!dryRun) { if (read.existed) backup(path); writeConfig(path, settings); }
+  return { name, status: dryRun ? 'would-write' : 'configured', detail: path };
+}
+
+function backup(path) {
+  const bak = `${path}.phaedo.bak`;
+  copyFileSync(path, bak);
+  return bak;
+}
+
+function writeConfig(path, config) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+// ── Per-client apply ───────────────────────────────────────────────────────-
+// action: 'install' | 'uninstall'. Returns a result record for reporting.
+export function applyToClient(client, { action, entry, dryRun = false } = {}) {
+  const { configPath } = client;
+  let read;
+  try {
+    read = readConfig(configPath);
+  } catch (err) {
+    return { ...client, status: 'error', detail: `skipped — ${err.message}; not touched` };
+  }
+
+  if (action === 'uninstall') {
+    if (!read.existed) return { ...client, status: 'absent', detail: 'no config file' };
+    const { config, changed } = removeServerEntry(read.config);
+    if (!changed) return { ...client, status: 'absent', detail: 'no phaedo entry to remove' };
+    if (!dryRun) { backup(configPath); writeConfig(configPath, config); }
+    return { ...client, status: dryRun ? 'would-remove' : 'removed', detail: configPath };
+  }
+
+  // install
+  if (!read.existed && !client.createIfMissing) {
+    return { ...client, status: 'absent', detail: 'not installed (config file not found)' };
+  }
+  const { config, changed } = mergeServerEntry(read.config, entry);
+  if (!changed) return { ...client, status: 'unchanged', detail: 'already configured' };
+  if (!dryRun) {
+    if (read.existed) backup(configPath);
+    writeConfig(configPath, config);
+  }
+  return { ...client, status: dryRun ? 'would-write' : 'configured', detail: configPath };
+}
+
+function parseArgs(argv) {
+  const opts = { pair: false, uninstall: false, dryRun: false, only: null, codeHook: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--pair') opts.pair = true;
+    else if (a === '--uninstall') opts.uninstall = true;
+    else if (a === '--dry-run') opts.dryRun = true;
+    else if (a === '--only') opts.only = argv[++i];
+    else if (a === '--code-hook') opts.codeHook = true;
+    else if (a === '--consult-model') opts.consultModel = argv[++i];
+    else if (a === '--consult-url') opts.consultUrl = argv[++i];
+    else if (a === '--no-model-judge') opts.noModelJudge = true;
+    else if (a === '--help' || a === '-h') opts.help = true;
+    else throw new Error(`unknown option: ${a}`);
+  }
+  return opts;
+}
+
+const HELP = `Phaedo MCP installer
+
+  node install.mjs                 configure every detected MCP client
+  node install.mjs --pair          configure, then run the one-time pairing
+  node install.mjs --code-hook     also add the Claude Code SessionStart hook
+                                   (true auto-injection; ~/.claude/settings.json)
+  node install.mjs --uninstall     remove the phaedo entry (and hook) everywhere
+  node install.mjs --dry-run       preview changes, write nothing
+  node install.mjs --only <id>     one client only: claude-desktop | cursor | claude-code
+
+  Consult model judge (ON by default, local Ollama, falls back to the rule engine):
+  node install.mjs --consult-model <id>   pin the model (e.g. llama3.1:8b)
+  node install.mjs --consult-url <url>    endpoint (default http://localhost:11434)
+  node install.mjs --no-model-judge       rule engine only (no model env)
+`;
+
+function runPairing() {
+  if (!existsSync(join(BASE_DIR, 'node_modules'))) {
+    console.log('\n⚠  Dependencies not installed — run `npm install` in this folder first,');
+    console.log('   then `npm run pair`. (The platform launcher does this for you.)');
+    return 1;
+  }
+  console.log('\n— Pairing with your phone (one time) —\n');
+  const r = spawnSync(process.execPath, [join(BASE_DIR, 'pair.js')], { stdio: 'inherit' });
+  return r.status ?? 1;
+}
+
+async function main(argv) {
+  let opts;
+  try { opts = parseArgs(argv); }
+  catch (err) { console.error(err.message + '\n\n' + HELP); return 2; }
+  if (opts.help) { console.log(HELP); return 0; }
+
+  let clients = detectClients();
+  if (opts.only) {
+    clients = clients.filter((c) => c.id === opts.only);
+    if (!clients.length) { console.error(`No such client id: ${opts.only}`); return 2; }
+  }
+
+  const action = opts.uninstall ? 'uninstall' : 'install';
+
+  // Consult model judge: ON by default. Pin it if --consult-model is given,
+  // otherwise probe local Ollama and pick an installed general model. Off with
+  // --no-model-judge. Always falls back to the rule engine at runtime, so a
+  // missing model never breaks consultation.
+  let env = {}, consultNote = '';
+  if (action === 'install' && !opts.noModelJudge) {
+    const url = opts.consultUrl || DEFAULT_CONSULT_URL;
+    if (opts.consultModel) {
+      env = buildConsultEnv({ model: opts.consultModel, url });
+      consultNote = `model judge ON → ${opts.consultModel} @ ${url} (pinned)`;
+    } else {
+      const d = await detectConsultModel({ url });
+      env = buildConsultEnv({ model: d.model, url });
+      consultNote = d.reachable
+        ? `model judge ON → ${d.model} @ ${url} (${d.picked ? 'detected in Ollama' : 'default; `ollama pull ' + d.model + '`'})`
+        : `model judge ON → ${d.model} @ ${url} (Ollama not detected — falls back to the rule engine until it's running)`;
+    }
+  } else if (action === 'install') {
+    consultNote = 'model judge OFF (rule engine only)';
+  }
+  const entry = serverEntry({ env });
+  console.log(`Phaedo MCP — ${action}${opts.dryRun ? ' (dry run)' : ''}`);
+  console.log(`Server: ${SERVER_PATH}`);
+  console.log(`Node:   ${process.execPath}`);
+  if (consultNote) console.log(`Consult: ${consultNote}`);
+  console.log('');
+
+  const results = clients.map((c) => applyToClient(c, { action, entry, dryRun: opts.dryRun }));
+  // The Claude Code SessionStart hook: opt-in on install (--code-hook), always
+  // cleaned up on uninstall.
+  if (opts.codeHook || action === 'uninstall') {
+    results.push(applyCodeHook({ action, dryRun: opts.dryRun }));
+  }
+  const touched = [];
+  for (const r of results) {
+    const mark = { configured: '✓', removed: '✓', 'would-write': '·', 'would-remove': '·',
+      unchanged: '=', absent: '–', error: '✗' }[r.status] || '?';
+    console.log(`  ${mark} ${r.name.padEnd(16)} ${r.detail}`);
+    if (r.status === 'configured' || r.status === 'would-write') touched.push(r);
+  }
+
+  if (action === 'install') {
+    if (!touched.length) {
+      console.log('\nNo clients were updated. Are Claude Desktop / Cursor / Claude Code installed?');
+    } else if (!opts.dryRun) {
+      console.log('\nNext:');
+      console.log('  1. Pair with your phone:  npm run pair   (or re-run with --pair)');
+      console.log('  2. Restart any client that was already open:');
+      for (const r of touched) console.log(`       • ${r.name}: ${r.restartHint}`);
+      console.log('  3. Inject your fingerprint at session start:');
+      console.log('       • any client: run the `/phaedo` prompt (one click), or call');
+      console.log('         the `phaedo_request_injection` tool.');
+      if (opts.codeHook) {
+        console.log('       • Claude Code: AUTOMATIC — the SessionStart hook injects it for you.');
+      } else {
+        console.log('       • Claude Code: `--code-hook` makes it automatic at every session start.');
+      }
+    }
+    if (opts.pair && !opts.dryRun && touched.length) return runPairing();
+  }
+  return 0;
+}
+
+// Only run when invoked directly (so test-install.mjs can import the helpers).
+if (resolve(process.argv[1] || '') === resolve(fileURLToPath(import.meta.url))) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/installers/linux/install-phaedo-mcp.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Run this to install Phaedo into your AI apps (Claude Desktop, Cursor, Claude
+# Code) and pair with your phone:  bash install-phaedo-mcp.sh
+# Safe to run again any time — it updates, never clobbers.
+set -e
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MCP_DIR="$(cd "$HERE/../.." && pwd)"
+cd "$MCP_DIR"
+
+echo "Phaedo MCP installer"
+echo "Folder: $MCP_DIR"
+echo
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "✗ Node.js isn't installed. Install it from https://nodejs.org or your package"
+  echo "  manager (e.g. 'sudo apt install nodejs npm'), then run this again."
+  exit 1
+fi
+echo "Using node: $(node --version) at $(command -v node)"
+echo
+
+if [ ! -d node_modules ]; then
+  echo "Installing dependencies (one time)…"
+  npm install --omit=dev
+  echo
+fi
+
+node install.mjs --pair
+
+echo
+echo "Done. If a client was already open, restart it so it picks up Phaedo."

package/installers/macos/Install Phaedo MCP.command

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Double-click this file to install Phaedo into your AI apps (Claude Desktop,
+# Cursor, Claude Code) and pair with your phone. It opens in Terminal and runs
+# the installer for you. Safe to run again any time — it updates, never clobbers.
+set -e
+
+# Resolve the mcp/ folder relative to this script (installers/macos/ -> mcp/).
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MCP_DIR="$(cd "$HERE/../.." && pwd)"
+cd "$MCP_DIR"
+
+echo "Phaedo MCP installer"
+echo "Folder: $MCP_DIR"
+echo
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "✗ Node.js isn't installed."
+  echo "  Install it from https://nodejs.org (the LTS button), then double-click this again."
+  echo
+  read -n 1 -s -r -p "Press any key to close."
+  exit 1
+fi
+echo "Using node: $(node --version) at $(command -v node)"
+echo
+
+if [ ! -d node_modules ]; then
+  echo "Installing dependencies (one time)…"
+  npm install --omit=dev
+  echo
+fi
+
+# Configure every detected client, then run the one-time phone pairing.
+node install.mjs --pair
+
+echo
+echo "Done. If a client was already open, restart it so it picks up Phaedo."
+read -n 1 -s -r -p "Press any key to close."

package/installers/windows/Install Phaedo MCP.bat

@@ -0,0 +1,39 @@
+@echo off
+REM Double-click to install Phaedo into your AI apps (Claude Desktop, Cursor,
+REM Claude Code) and pair with your phone. Safe to run again any time.
+setlocal
+
+REM Resolve the mcp\ folder relative to this script (installers\windows\ -> mcp\).
+set "HERE=%~dp0"
+pushd "%HERE%..\.." || (echo Could not find the mcp folder & pause & exit /b 1)
+
+echo Phaedo MCP installer
+echo Folder: %CD%
+echo.
+
+where node >nul 2>nul
+if errorlevel 1 (
+  echo Node.js isn't installed.
+  echo Install it from https://nodejs.org ^(the LTS button^), then double-click this again.
+  echo.
+  pause
+  popd
+  exit /b 1
+)
+for /f "delims=" %%v in ('node --version') do echo Using node %%v
+echo.
+
+if not exist node_modules (
+  echo Installing dependencies ^(one time^)...
+  call npm install --omit=dev
+  echo.
+)
+
+REM Configure every detected client, then run the one-time phone pairing.
+node install.mjs --pair
+
+echo.
+echo Done. If a client was already open, restart it so it picks up Phaedo.
+pause
+popd
+endlocal

package/lib/node-vault.js

@@ -0,0 +1,34 @@
+// Minimal `globalThis.phaedoVault` shim for Node, so the repo-root identity.js
+// (which reads/writes globalThis.phaedoVault) can persist the MCP server's
+// long-term X25519 identity outside a browser.
+//
+// D2 (signed off 2026-06-05): a restricted-perms (0600) JSON file. The
+// `privateKeyJwk` it holds is a long-term secret — same class as `pair_key` in
+// pairing.json. OS keychain is the documented upgrade path.
+//
+// identity.js treats a falsy read() as "vault locked" and throws; this shim
+// always returns a truthy object (empty {} when the file doesn't exist yet), so
+// getOrCreate() generates a fresh identity and update()s it on first use.
+
+import { readFileSync, writeFileSync, existsSync, chmodSync } from 'fs';
+import { resolve } from 'path';
+
+export function installNodeVault(filePath) {
+  const path = resolve(filePath);
+
+  const read = () => {
+    if (!existsSync(path)) return {};
+    try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; }
+  };
+
+  globalThis.phaedoVault = {
+    async read() { return read(); },
+    async update(patch) {
+      const next = { ...read(), ...patch };
+      writeFileSync(path, JSON.stringify(next, null, 2), { mode: 0o600 });
+      try { chmodSync(path, 0o600); } catch {}   // enforce perms if the file pre-existed
+    },
+  };
+
+  return path;
+}

package/lib/phaedo-crypto.js

@@ -0,0 +1,36 @@
+// Loads the repo-root Phaedo crypto modules into Node and exposes them.
+//
+// They're classic scripts that set globalThis.Phaedo.* and (verified) load in
+// Node with zero shims — Node has global crypto.subtle / TextEncoder / btoa.
+// Load order matters: protocol → envelope → kdf → identity (envelope.js and
+// kdf.js read Phaedo.Protocol at load).
+//
+// Option B (1b-i) uses only the STATELESS path: Kdf.* + Identity.generateEphemeral
+// / deriveEphemeralShared + Envelope.unwrap. The vault-backed Identity functions
+// (getOrCreate/getPublicKey) are NOT called here, so no phaedoVault shim is needed.
+
+import { createRequire } from 'module';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const require = createRequire(import.meta.url);
+const HERE = dirname(fileURLToPath(import.meta.url)); // mcp/lib
+const VENDOR = resolve(HERE, '..', 'vendor');         // mcp/vendor — bundled (npm package)
+const ROOT = resolve(HERE, '..', '..');               // repo root — dev
+
+// Prefer the bundled copies (self-contained package) over the repo root (dev).
+// Load order matters: protocol → envelope → kdf → identity.
+for (const f of ['protocol.js', 'envelope.js', 'kdf.js', 'identity.js']) {
+  const vf = resolve(VENDOR, f);
+  require(existsSync(vf) ? vf : resolve(ROOT, f));
+}
+
+export const Phaedo = globalThis.Phaedo;
+if (!Phaedo?.Envelope || !Phaedo?.Kdf || !Phaedo?.Identity || !Phaedo?.Protocol) {
+  throw new Error('Phaedo crypto modules did not load (Protocol/Envelope/Kdf/Identity).');
+}
+
+// base64url <-> Uint8Array (Node-native), matching the extension's wire encoding.
+export const b64uEnc = (u8) => Buffer.from(u8).toString('base64url');
+export const b64uDec = (s) => new Uint8Array(Buffer.from(s, 'base64url'));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "phaedo-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "Phaedo MCP server — inject your cognitive fingerprint into any MCP client, and consult your decision pattern at agent decision points (docs/protocol/mcp-binding.md).",
+  "mcpName": "io.github.galavoxx/phaedo",
+  "homepage": "https://getphaedo.com",
+  "repository": { "type": "git", "url": "https://github.com/galavoxx/phaedo", "directory": "mcp" },
+  "keywords": ["mcp", "model-context-protocol", "personalization", "fingerprint", "consultation", "agent"],
+  "bin": { "phaedo-mcp": "server.js" },
+  "files": [
+    "server.js", "server.json", "fingerprint-source.js", "projection.js", "errors.js",
+    "consult.js", "consult-core.js", "consult-policy.js", "receipts.js", "agreement.js", "phone-source.js",
+    "cache.js", "pairing.js", "pair.js", "pull.js",
+    "install.mjs", "build-package.mjs", "vendor/", "lib/", "hooks/", "installers/",
+    "policy-editor.html", "sample-fingerprint.json", "pairing.sample.json",
+    "consult-policies.sample.json", "README.md"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "build": "node build-package.mjs",
+    "prepack": "node build-package.mjs",
+    "setup": "node install.mjs",
+    "setup:pair": "node install.mjs --pair",
+    "setup:code-hook": "node install.mjs --code-hook",
+    "unsetup": "node install.mjs --uninstall",
+    "pair": "node pair.js",
+    "pull": "node pull.js",
+    "test": "node test-smoke.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-receipts.mjs && node test-agreement.mjs",
+    "receipts": "node receipts.js list",
+    "agreement": "node agreement.js",
+    "smoke": "node test-smoke.mjs",
+    "smoke:phone": "node test-phone-boundary.mjs",
+    "smoke:cache": "node test-cache.mjs",
+    "smoke:pair": "node test-pairing.mjs",
+    "smoke:revoke": "node test-revoke.mjs",
+    "smoke:install": "node test-install.mjs",
+    "smoke:consult": "node test-consult.mjs",
+    "smoke:policy": "node test-consult-policy.mjs",
+    "smoke:receipts": "node test-receipts.mjs",
+    "smoke:agreement": "node test-agreement.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  }
+}

package/pair.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// `phaedo-mcp pair` — pair this MCP server with the phone vault as its own
+// SAS-approved, revocable client (plan: mcp-revocable-approval-plan.md, P3).
+//
+// Writes the server's long-term identity to identity.json (0600) and the
+// resulting pairing record to pairing.json (0600) — the file phone-source.js
+// reads. Run once; the server then authorizes autonomously.
+//
+//   node pair.js
+//   PHAEDO_IDENTITY=/secure/id.json PHAEDO_PAIRING=/secure/pairing.json node pair.js
+
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { pair } from './pairing.js';
+
+const BASE_DIR = dirname(fileURLToPath(import.meta.url));
+const identityPath = process.env.PHAEDO_IDENTITY
+  ? resolve(process.cwd(), process.env.PHAEDO_IDENTITY)
+  : resolve(BASE_DIR, 'identity.json');
+const pairingPath = process.env.PHAEDO_PAIRING
+  ? resolve(process.cwd(), process.env.PHAEDO_PAIRING)
+  : resolve(BASE_DIR, 'pairing.json');
+
+pair({ identityPath, pairingPath, log: (m) => process.stdout.write(m + '\n') })
+  .then(() => process.exit(0))
+  .catch((err) => {
+    process.stderr.write(`\n✗ Pairing failed: ${err.message}\n`);
+    process.exit(1);
+  });