phaedo-mcp 0.3.4 → 0.3.5

package/README.md

@@ -22,12 +22,46 @@ when your phone is offline, is encrypted too.
    - **the Phaedo phone app** — your full profile lives there. The app isn't open
      to the public yet; [phaedo.so](https://phaedo.so) has a link to hear when it is.
    - **your own Claude Code sessions** — no phone needed. Phaedo builds a starter
-     profile on this computer from how you work in Claude Code (see below).
-2. **Node.js**, free from [nodejs.org](https://nodejs.org) (the LTS button).
+     profile on this computer from how you work in Claude Code (see *Install*).
+2. **Node.js**, free from [nodejs.org](https://nodejs.org) (the LTS button), for
+   Claude Code and other apps. Claude Desktop brings its own.
 
 With neither, there is no profile, and the server says so plainly rather than
 guessing. You can still try Phaedo with a made-up example profile.
 
+## Install
+
+**Claude Code** (and Cowork) — run these two commands in Terminal:
+
+```bash
+claude plugin marketplace add phaedo-labs/phaedo-mcp
+```
+
+```bash
+claude plugin install phaedo@phaedo
+```
+
+Then start a new Claude Code session. That's all: Phaedo loads your profile at the
+start of each session, checks with you before Claude merges, deploys or publishes,
+and learns from how you work. Without the phone app, it builds a starter profile from
+your own sessions (for example, that you want short answers without headers). It
+starts thin and grows as you work. In Claude Code, type `/phaedo:status` to see how
+far along it is, and `/phaedo:pair` to pair the phone app.
+
+**Claude Desktop** — download
+[phaedo.mcpb](https://github.com/phaedo-labs/phaedo-mcp/raw/main/desktop/phaedo.mcpb)
+and double-click it. Claude Desktop shows what it installs and asks you to confirm.
+Node.js comes with Claude Desktop, so nothing else is needed. Desktop uses the same
+profile and pairing as the Claude Code plugin on this computer.
+
+**Other apps** (Cursor and others) — see *Use your own profile in other apps* below,
+or the manual setup under *Reference*.
+
+What Phaedo reads stays on this computer: each Claude Code session is reduced to
+counts (like "asked for a shorter answer, 4 times"), and the text itself is
+discarded. If you pair the phone app later, your full profile replaces the starter
+one and keeps what it learned.
+
 ## Try it with the example profile (no phone needed)
 
 This loads a made-up person's profile, so you can see what Phaedo adds before you
@@ -66,32 +100,7 @@ example, delete the `env` line in Claude Desktop, or in Claude Code run
 `claude mcp remove -s user phaedo` and add it again without `-e …`. The server
 will then tell you there's no profile until you pair your phone.
 
-## Start a profile from your Claude Code sessions (no phone needed)
-
-If you use Claude Code, Phaedo can learn from how you work there and build a
-starter profile on this computer — for example, that you want short answers
-without headers. It starts thin and grows as you work.
-
-1. **Get this folder** as in step 1 below (Code → Download ZIP, unzip, open the
-   `mcp` folder).
-2. **Install the Claude Code hook.** In Terminal, from the `mcp` folder:
-   ```bash
-   npm install
-   ```
-   ```bash
-   npm run setup:code-hook
-   ```
-   This adds Phaedo to your AI apps and turns on three things in Claude Code:
-   loading your profile when a session starts, checking with you before it merges
-   or publishes, and learning from your sessions.
-3. **Quit and reopen Claude Code**, then keep working. The first sessions build the
-   profile, and each later session picks up what's been learned.
-
-What it reads stays on this computer: each session is reduced to counts (like "asked
-for a shorter answer, 4 times"), and the text itself is discarded. If you pair the
-phone app later, your full profile replaces the starter one and keeps what it learned.
-
-## Use your own profile (with the phone app)
+## Use your own profile in other apps (with the phone app)
 
 1. **Get this folder.** On [the GitHub page](https://github.com/phaedo-labs/phaedo-mcp),
    click **Code → Download ZIP**, unzip it, and open the `mcp` folder inside.
@@ -102,7 +111,9 @@ phone app later, your full profile replaces the starter one and keeps what it le
    - Linux: run `bash installers/linux/install-phaedo-mcp.sh`.
 
    It adds Phaedo to Claude Desktop, Cursor and Claude Code — keeping your other
-   settings, and backing each file up first — then starts pairing.
+   settings, and backing each file up first — then starts pairing. (In Claude Code
+   and Claude Desktop, the plugin and the `.mcpb` above are simpler; use one route
+   per app, not both.)
 3. **Pair with your phone.** Open Phaedo on your phone. On the same Wi-Fi, approve
    **"Phaedo MCP Server"** and check that the code matches the one in Terminal.
    On a different network, tap **Pair with code** and type the code Terminal shows.

package/consult-runtime.js

@@ -7,6 +7,7 @@
 // policies or delegation signals its own way would be the third time.
 
 import { join } from 'path';
+import { configDir } from './lib/config-dir.js';
 import { readFileSync, existsSync } from 'fs';
 import { loadFingerprint, loadFingerprintPreferCache } from './fingerprint-source.js';
 import { readServingClientId } from './phone-source.js';
@@ -24,7 +25,7 @@ export function buildConsultOpts(baseDir, env = process.env, { warn = (m) => pro
   // the server (mcp/consult-policies.json — what policy-editor.html produces). Zero
   // config: drop the file in and restart the client. (Portable vault policies in
   // phaedo_consult_policies always apply too, regardless of this file.)
-  const policiesPath = env.PHAEDO_CONSULT_POLICIES || join(baseDir, 'consult-policies.json');
+  const policiesPath = env.PHAEDO_CONSULT_POLICIES || join(configDir(baseDir, env), 'consult-policies.json');
   if (existsSync(policiesPath)) {
     try { opts.policies = JSON.parse(readFileSync(policiesPath, 'utf8')); }
     catch (e) { warn(`[phaedo-mcp] ignoring malformed consult policies (${policiesPath}): ${e.message}\n`); }

package/fingerprint-source.js

@@ -18,6 +18,7 @@ import { defaultStateDir, writeCache, readCache, clearCache } from './cache.js';
 import { foldLocalCapture, isLocalCaptureOwner, localCaptureSessionCount } from './capture-local.js';
 import { Capabilities, AuthoredSource } from './lib/phaedo-crypto.js';
 import { PhaedoError } from './errors.js';
+import { configDir } from './lib/config-dir.js';
 
 // §4.1 protocol-identity normalization (consumer defense-in-depth, 2026-06-16).
 // A stored fingerprint from a producer that predates identity stamping (or whose
@@ -95,7 +96,7 @@ function resolveSourcePath(baseDir) {
   const env = process.env.PHAEDO_FINGERPRINT;
   if (env === SAMPLE_KEYWORD) return SAMPLE_PATH;
   if (env) return resolve(process.cwd(), env);
-  return resolve(baseDir, 'fingerprint.json');
+  return resolve(configDir(baseDir), 'fingerprint.json');
 }
 
 // Read by the assistant (a tool error) and, through it, by the person — so plain words, and
@@ -108,11 +109,26 @@ export const NO_PROFILE_MESSAGE =
   'is installed (see the README). To try a made-up example profile instead, set ' +
   'PHAEDO_FINGERPRINT=sample in this server\'s settings.';
 
+// Inside the Claude plugin the Claude Code hook is already installed — the plugin is the hook —
+// so telling the person to install it would send them looking for a step that doesn't exist.
+// Claude Code exports CLAUDE_PLUGIN_ROOT to a plugin's MCP server and hooks, and to nothing else.
+export const PLUGIN_NO_PROFILE_MESSAGE =
+  'No Phaedo profile is set up yet, so Phaedo has not changed how the assistant responds. It ' +
+  'starts one from your own Claude Code sessions on this computer: after a session or two, it ' +
+  'loads at the start of the next one. For your full profile, pair the Phaedo phone app with ' +
+  '/phaedo:pair (the app is not open to the public yet; https://phaedo.so to hear when it is).';
+
+export function noProfileMessage(env = process.env) {
+  return env.CLAUDE_PLUGIN_ROOT ? PLUGIN_NO_PROFILE_MESSAGE : NO_PROFILE_MESSAGE;
+}
+
 // The same news for the server's log (Claude Desktop's MCP log shows stderr), one line.
 const NO_PROFILE_LOG =
   'no profile is set up on this computer, so Phaedo will not change how the assistant responds. ' +
   'Pair the Phaedo phone app, install the Claude Code hook to start one from your own sessions, ' +
   'or set PHAEDO_FINGERPRINT=sample to try the example.';
+const PLUGIN_NO_PROFILE_LOG =
+  'no profile yet; one starts from your Claude Code sessions on this computer, or pair the phone app with /phaedo:pair.';
 
 // STARTER PROFILE — the phone-less path.
 //
@@ -172,7 +188,7 @@ export async function profileStatusLine(baseDir) {
   if (env === SAMPLE_KEYWORD) return 'using the made-up example profile (PHAEDO_FINGERPRINT=sample).';
   if (env) return null;
   if (hasPairingRecord(baseDir)) return null;
-  if (existsSync(resolve(baseDir, 'fingerprint.json'))) return null;
+  if (existsSync(resolve(configDir(baseDir), 'fingerprint.json'))) return null;
   const starter = await loadStarterProfile();
   if (starter) {
     const { learned, areas, sessions, stage } = await summarizeStarter(starter);
@@ -180,7 +196,7 @@ export async function profileStatusLine(baseDir) {
       `${learned} thing${learned === 1 ? '' : 's'} learned across ${areas} area${areas === 1 ? '' : 's'}` +
       `${sessions ? ` from ${sessions} session${sessions === 1 ? '' : 's'}` : ''} — ${stage}`;
   }
-  return NO_PROFILE_LOG;
+  return process.env.CLAUDE_PLUGIN_ROOT ? PLUGIN_NO_PROFILE_LOG : NO_PROFILE_LOG;
 }
 
 // Returns the vault payload:
@@ -273,7 +289,7 @@ export async function loadFingerprint(baseDir) {
     if (!process.env.PHAEDO_FINGERPRINT && err?.code === 'ENOENT') {
       const starter = await loadStarterProfile();
       if (starter) return starter;
-      throw new PhaedoError('decryption_failed', NO_PROFILE_MESSAGE);
+      throw new PhaedoError('decryption_failed', noProfileMessage());
     }
     throw new PhaedoError('decryption_failed', `Could not read the Phaedo profile at ${path} (${err?.code || err?.message || err}).`);
   }

package/lib/config-dir.js

@@ -0,0 +1,43 @@
+// Where this install keeps the subject's own config files: pairing.json, identity.json,
+// consult-policies.json, escalation-policy.json and fingerprint.json.
+//
+// A clone or the npm package keeps them beside server.js, as it always has. A packaged install
+// can't: a Claude Code plugin's folder is replaced on every update (`${CLAUDE_PLUGIN_ROOT}` is a
+// per-version cache directory), and a Claude Desktop bundle's folder belongs to Claude Desktop.
+// A pairing written there is lost on the next update. So both packages ship an
+// `install-layout.json` marker beside server.js, and keep these files in the state dir
+// (~/.phaedo-mcp, or PHAEDO_MCP_STATE_DIR) instead — the same folder for both, so pairing once
+// from either covers the other.
+//
+// A file marker rather than an environment variable, because the plugin's hooks and its
+// `pair.js` / `pull.js` run in processes that don't all get the plugin's environment (commands
+// Claude runs through its Bash tool see no CLAUDE_PLUGIN_ROOT). The marker travels with the
+// files. PHAEDO_CONFIG_DIR still overrides both.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const LAYOUT_MARKER = 'install-layout.json';
+
+const cache = new Map();
+
+/** True when the package at `baseDir` is a packaged install (plugin or Desktop bundle). */
+export function isPackagedInstall(baseDir) {
+  const key = resolve(baseDir);
+  if (!cache.has(key)) {
+    let packaged = false;
+    try {
+      const marker = join(key, LAYOUT_MARKER);
+      packaged = existsSync(marker) && JSON.parse(readFileSync(marker, 'utf8'))?.config === 'state-dir';
+    } catch { packaged = false; }   // an unreadable marker → the old, beside-the-server layout
+    cache.set(key, packaged);
+  }
+  return cache.get(key);
+}
+
+export function configDir(baseDir, env = process.env) {
+  if (env.PHAEDO_CONFIG_DIR) return resolve(env.PHAEDO_CONFIG_DIR);
+  if (isPackagedInstall(baseDir)) return env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+  return baseDir;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
@@ -92,7 +92,7 @@
     "unsetup": "node install.mjs --uninstall",
     "pair": "node pair.js",
     "pull": "node pull.js",
-    "test": "node test-smoke.mjs && node test-no-profile.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-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs",
+    "test": "node test-smoke.mjs && node test-no-profile.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-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs && node test-plugin.mjs",
     "receipts": "node receipts.js list",
     "agreement": "node agreement.js",
     "ship-readout": "node ship-readout.js",

package/pair.js

@@ -12,14 +12,15 @@
 import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 import { pair } from './pairing.js';
+import { configDir } from './lib/config-dir.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');
+  : resolve(configDir(BASE_DIR), 'identity.json');
 const pairingPath = process.env.PHAEDO_PAIRING
   ? resolve(process.cwd(), process.env.PHAEDO_PAIRING)
-  : resolve(BASE_DIR, 'pairing.json');
+  : resolve(configDir(BASE_DIR), 'pairing.json');
 
 pair({ identityPath, pairingPath, log: (m) => process.stdout.write(m + '\n') })
   .then(() => process.exit(0))

package/phone-source.js

@@ -23,6 +23,7 @@
 // after the one-time pairing.
 
 import { readFile } from 'fs/promises';
+import { configDir } from './lib/config-dir.js';
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
 import { Phaedo, b64uEnc, b64uDec, Capabilities } from './lib/phaedo-crypto.js';
@@ -55,7 +56,7 @@ const APPROVE_TIMEOUT_MS = 120000;   // human-in-the-loop: /v1/authorize
 export async function loadPairingRecord(baseDir) {
   const path = process.env.PHAEDO_PAIRING
     ? resolve(process.cwd(), process.env.PHAEDO_PAIRING)
-    : resolve(baseDir, 'pairing.json');
+    : resolve(configDir(baseDir), 'pairing.json');
   let raw;
   try {
     raw = await readFile(path, 'utf8');
@@ -78,7 +79,7 @@ export async function loadPairingRecord(baseDir) {
 // True iff a pairing record is configured (→ use the phone source over local JSON).
 export function hasPairingRecord(baseDir) {
   if (process.env.PHAEDO_PAIRING) return true;
-  return existsSync(resolve(baseDir, 'pairing.json'));
+  return existsSync(resolve(configDir(baseDir), 'pairing.json'));
 }
 
 // This server's OWN paired-client identifier — the identity §10.5 `agents` scoping
@@ -96,7 +97,7 @@ export function hasPairingRecord(baseDir) {
 export function readServingClientId(baseDir) {
   const path = process.env.PHAEDO_PAIRING
     ? resolve(process.cwd(), process.env.PHAEDO_PAIRING)
-    : resolve(baseDir, 'pairing.json');
+    : resolve(configDir(baseDir), 'pairing.json');
   try {
     const id = JSON.parse(readFileSync(path, 'utf8'))?.client_id;
     return typeof id === 'string' && id.trim() ? id.trim() : null;

package/server.js

@@ -17,6 +17,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
 import { loadFingerprint, sourceOf, profileStatusLine } from './fingerprint-source.js';
+import { configDir } from './lib/config-dir.js';
 import { hasPairingRecord, loadPairingRecord } from './phone-source.js';
 import { depositDelegationSuggestions } from './delegation-sync.js';
 import { depositReceiptsDigest, drainAndApplyMarks } from './receipts-sync.js';
@@ -178,7 +179,7 @@ const ESCALATION_WINDOW_MS = (() => {
 // over the stakes-gated default. Local file (PHAEDO_ESCALATION_POLICY, else
 // mcp/escalation-policy.json beside the server) overrides; the portable vault policy
 // (phaedo_fingerprint.escalation_policy) is merged in per-call (loadEscalationPolicy).
-const ESCALATION_POLICY_PATH = process.env.PHAEDO_ESCALATION_POLICY || join(BASE_DIR, 'escalation-policy.json');
+const ESCALATION_POLICY_PATH = process.env.PHAEDO_ESCALATION_POLICY || join(configDir(BASE_DIR), 'escalation-policy.json');
 let ESCALATION_POLICY_FILE = null;
 if (existsSync(ESCALATION_POLICY_PATH)) {
   try { ESCALATION_POLICY_FILE = JSON.parse(readFileSync(ESCALATION_POLICY_PATH, 'utf8')); }

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.phaedo-labs/phaedo-mcp",
   "description": "Make AI apps answer your way, check with you before acting, and get approvals on your phone.",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "repository": {
     "url": "https://github.com/phaedo-labs/phaedo-mcp",
     "source": "github",
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "phaedo-mcp",
-      "version": "0.3.4",
+      "version": "0.3.5",
       "transport": {
         "type": "stdio"
       }