phaedo-mcp 0.3.1 → 0.3.3

package/README.md

@@ -18,12 +18,15 @@ when your phone is offline, is encrypted too.
 
 ## What you need
 
-1. **The Phaedo phone app.** Your 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.
+1. **A profile**, from either:
+   - **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).
 
-Without the phone app there is no profile, and the server says so plainly rather
-than guessing. You can still try Phaedo with a made-up example profile.
+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.
 
 ## Try it with the example profile (no phone needed)
 
@@ -63,6 +66,31 @@ 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)
 
 1. **Get this folder.** On [the GitHub page](https://github.com/phaedo-labs/phaedo-mcp),
@@ -149,10 +177,14 @@ receipts-audit surfaces (the tools table above) shipped on top of these across t
   `../docs/roadmap/mcp-revocable-approval-plan.md`. Phone-gated unlock stays a
   deferred enterprise mode behind a config flag.
 
-**No conversation capture.** MCP never returns the conversation, so your
-fingerprint does not learn from MCP sessions (binding §5). (Consultation,
-escalation, and `phaedo_record_outcome` shape and record *decisions*, but none
-capture conversation text into the fingerprint.)
+**Conversation capture is opt-in.** The MCP protocol never hands a server the
+conversation, so the server itself learns nothing from your chats (binding §5).
+Consultation, escalation and `phaedo_record_outcome` record *decisions*, not
+conversation text. Capture happens only through things you turn on: the Claude
+Code hooks (`npm run setup:code-hook`; see *Capture from Claude Code / Cowork*
+below) and, on a Mac, the separately installed accessibility reader that feeds
+`capture-a11y.js`. Both read on this computer, keep only signal names and
+counts, and discard the text.
 Local **stdio** only; **standard** mode only (enhanced-privacy/Stained-Glass and
 remote HTTP/SSE are out of this cut).
 
@@ -215,9 +247,11 @@ if you prefer.)*
 
 **Phase 1a — local JSON.** With no pairing record, reads a **vault payload**
 from `PHAEDO_FINGERPRINT` (a path, or the word `sample` for the shipped
-`mcp/sample-fingerprint.json`), then `mcp/fingerprint.json`. With neither, there
-is **no profile**: every tool returns a plain-language `decryption_failed` error
-saying so. The sample is never served unless asked for by name — until 0.3.1 it
+`mcp/sample-fingerprint.json`), then `mcp/fingerprint.json`. With neither, a
+**starter profile**: the Claude Code capture state on this computer folded onto an
+empty fingerprint (id `starter-local`), served only if it learned something. With
+nothing captured, there is **no profile**: every tool returns a plain-language
+`decryption_failed` error saying so. The sample is never served unless asked for by name — until 0.3.1 it
 was the silent fallback, so a fresh `npx phaedo-mcp` injected a made-up person's
 style without saying so. The file looks like this:
 ```json

package/fingerprint-source.js

@@ -5,10 +5,12 @@
 //   Phase 1b (phone): if a pairing record is configured (PHAEDO_PAIRING or
 //     mcp/pairing.json), authorize → pull /v1/profile → unwrap the §7.2 envelope
 //     from the paired phone (phone-source.js). Spec-faithful; no plaintext at rest.
-//   Phase 1a (local): otherwise read a local vault-payload JSON. With neither, there is
-//     no profile — tools say so (NO_PROFILE_MESSAGE); the shipped sample is opt-in only.
+//   Phase 1a (local): otherwise read a local vault-payload JSON. With neither, a STARTER
+//     profile from this computer's own capture (loadStarterProfile), else no profile — tools
+//     say so (NO_PROFILE_MESSAGE). The shipped sample is opt-in only.
 
 import { readFile } from 'fs/promises';
+import { existsSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { hasPairingRecord, loadPairingRecord, loadFingerprintFromPhone, PhoneError } from './phone-source.js';
@@ -78,6 +80,7 @@ export function foldConfigHome(vd) {
 // Resolution order for the local fixture (1a):
 //   1. PHAEDO_FINGERPRINT env var (absolute or cwd-relative path, or `sample`)
 //   2. ./fingerprint.json next to the server
+//   3. a starter profile folded from this computer's capture state (see loadStarterProfile)
 //   — nothing else. There is deliberately NO silent fallback to the shipped sample.
 //
 // NO PROFILE IS AN ANSWER, NOT A DEMO. Until 2026-10-20 an unpaired install with no file fell
@@ -100,8 +103,52 @@ function resolveSourcePath(baseDir) {
 export const NO_PROFILE_MESSAGE =
   'No Phaedo profile is set up on this computer, so there is nothing to load and Phaedo has ' +
   'not changed how the assistant responds. A profile comes from the Phaedo phone app, which is ' +
-  'not open to the public yet (https://phaedo.so to hear when it is). To try Phaedo with a made-up example profile ' +
-  'instead, set PHAEDO_FINGERPRINT=sample in this server\'s settings.';
+  'not open to the public yet (https://phaedo.so to hear when it is). Without the phone, Phaedo ' +
+  'can start one from your own Claude Code sessions on this computer once its Claude Code hook ' +
+  'is installed (see the README). To try a made-up example profile instead, set ' +
+  'PHAEDO_FINGERPRINT=sample in this server\'s settings.';
+
+// 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.';
+
+// STARTER PROFILE — the phone-less path.
+//
+// Someone without the phone app has no fingerprint to pull, but if they turned on the Claude
+// Code capture hook, this computer already holds their own signal counts (capture-local.js, the
+// tier-3 owner). Folding those onto an EMPTY fingerprint gives a profile made only of what they
+// did — never the sample's invented traits, which is what this branch fell back to until 0.3.0.
+// It is thin by construction (persona_strength 0; the projection's confidence section says
+// "treat all signals as preliminary"), and that is the honest label for it.
+//
+// Served only when the fold learned something: zero signals is still "no profile". The id is a
+// constant so receipts and the agreement metric stay on one subject across loads; pairing a
+// phone later replaces it (the phone inherits the cumulative counts — capture-local.js §5).
+export const STARTER_FINGERPRINT_ID = 'starter-local';
+
+async function loadStarterProfile(now = new Date().toISOString()) {
+  if (!await isLocalCaptureOwner(false)) return null;
+  const base = { phaedo_fingerprint: { fingerprint_id: STARTER_FINGERPRINT_ID, updated_at: now, layers: {} } };
+  const vd = await foldLocalCapture(base, { now });
+  const layers = (vd && vd.phaedo_fingerprint && vd.phaedo_fingerprint.layers) || {};
+  if (!Object.values(layers).some((l) => Array.isArray(l?.signals) && l.signals.length)) return null;
+  return markStarter(foldConfigHome(normalizeIdentity(vd)));
+}
+
+/** One line for the server log describing where the profile will come from, or null when there
+ *  is nothing a person needs told. Never touches the phone: a pull at startup would put an
+ *  "authorize" card on it with nobody asking. */
+export async function profileStatusLine(baseDir) {
+  const env = process.env.PHAEDO_FINGERPRINT;
+  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 (await loadStarterProfile()) return 'no phone paired; using a starter profile built from your own sessions on this computer.';
+  return NO_PROFILE_LOG;
+}
 
 // Returns the vault payload:
 //   { phaedo_fingerprint, phaedo_behavioral_signals, phaedo_linguistic_profile,
@@ -131,6 +178,18 @@ function stamp(vd, cached) {
   return vd;
 }
 
+// A starter profile is read fresh every load (live), but it did not come from a phone —
+// `pull.js` must not say it did.
+function markStarter(vd) {
+  try {
+    Object.defineProperty(vd, SOURCE, {
+      value: { live: true, cachedAt: null, ageMs: 0, starter: true },
+      enumerable: false, configurable: true, writable: true,
+    });
+  } catch { /* frozen object — provenance is best-effort, never fatal */ }
+  return vd;
+}
+
 /** Provenance of a loaded fingerprint. Absent marker → a live read. */
 export function sourceOf(vd) {
   const s = vd && vd[SOURCE];
@@ -179,6 +238,8 @@ export async function loadFingerprint(baseDir) {
     // Only the default location may be absent quietly. A path the user NAMED that doesn't
     // read is their mistake to see, not "no profile".
     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', `Could not read the Phaedo profile at ${path} (${err?.code || err?.message || err}).`);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
-  "description": "Phaedo MCP server \u2014 inject your cognitive fingerprint into any MCP client, and consult your decision pattern at agent decision points (docs/protocol/mcp-binding.md).",
+  "description": "Lets Claude, Cursor and other MCP apps answer in your style, check with you before acting, send decisions to your phone to approve, and ask you to sign purchase approvals with Face ID. Needs the Phaedo phone app; set PHAEDO_FINGERPRINT=sample to try it.",
   "mcpName": "io.github.phaedo-labs/phaedo-mcp",
   "homepage": "https://phaedo.so",
   "repository": {
@@ -14,11 +14,20 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
+    "claude",
+    "claude-code",
+    "cursor",
     "personalization",
-    "fingerprint",
-    "consultation",
-    "agent"
+    "human-in-the-loop",
+    "approval",
+    "guardrails",
+    "agent",
+    "ai-agents",
+    "ap2",
+    "agent-payments",
+    "anamnesis"
   ],
   "bin": {
     "phaedo-mcp": "server.js"

package/pull.js

@@ -21,6 +21,13 @@ loadFingerprint(BASE_DIR)
     // profile went unnoticed while the agent answered authorization questions from it. The
     // whole point of this command is to verify the pairing works, so it has to distinguish
     // "your phone answered" from "your phone didn't, here's an old copy".
+    if (src.starter) {
+      process.stdout.write(
+        `✓ No phone paired — serving a starter profile built from your own sessions on this computer, ${layers} layer(s).\n` +
+        `  Pair the Phaedo phone app (npm run pair) to replace it with your full profile.\n`
+      );
+      process.exit(0);
+    }
     if (src.live) {
       process.stdout.write(
         `✓ Read your profile from the phone — fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s).\n`

package/server.js

@@ -16,7 +16,7 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-import { loadFingerprint, sourceOf } from './fingerprint-source.js';
+import { loadFingerprint, sourceOf, profileStatusLine } from './fingerprint-source.js';
 import { hasPairingRecord, loadPairingRecord } from './phone-source.js';
 import { depositDelegationSuggestions } from './delegation-sync.js';
 import { depositReceiptsDigest, drainAndApplyMarks } from './receipts-sync.js';
@@ -190,7 +190,18 @@ if (existsSync(ESCALATION_POLICY_PATH)) {
 // been the package's for two months. One source of truth; test-package-closure.mjs
 // asserts the two agree.
 const PKG_VERSION = JSON.parse(readFileSync(join(BASE_DIR, 'package.json'), 'utf8')).version;
-const server = new McpServer({ name: 'phaedo', version: PKG_VERSION });
+// The one place a client is told how the tools fit together. Without it an app saw eight
+// tool descriptions and nothing saying "load the profile first" or "consult before you ship" —
+// so whether Phaedo was used at all depended on the model guessing. Short on purpose: clients
+// put this in the model's context on every turn.
+const SERVER_INSTRUCTIONS = [
+  'Phaedo holds the user\'s profile: how they like answers written, and how they want decisions handled when an AI acts for them.',
+  '- At the start of a session, call phaedo_request_injection once and treat the returned projection as background on the user\'s style.',
+  '- Before a consequential action for the user (merging, deploying, publishing, sending a message, spending money, deleting, changing an account or setting), call phaedo_consult and follow its signal. If you are acting on your own and the decision should be the user\'s, use phaedo_escalate and do not proceed until it resolves.',
+  '- When the user reacts to an action you consulted on, call phaedo_record_outcome with its receipt_id: record what they chose, never what you inferred.',
+  '- If a tool says no Phaedo profile is set up, tell the user once, plainly, and carry on normally. Do not retry.',
+].join('\n');
+const server = new McpServer({ name: 'phaedo', version: PKG_VERSION }, { instructions: SERVER_INSTRUCTIONS });
 
 // ── Tool: phaedo_request_injection (binding §3.1) ─────────────────────────────
 server.registerTool(
@@ -252,8 +263,8 @@ const ACTION_BINDING_SCHEMA = z
   .optional()
   .describe(
     'Binds this consultation to the concrete call it describes. The action_descriptor is your ACCOUNT of the action; ' +
-    'this is the action. Recorded on the audit receipt so a later mismatch is provable, shown to the subject when an ' +
-    'escalation reaches their phone, and REQUIRED by any standing rule the subject marked require_binding before it ' +
+    'this is the action. Recorded on the audit receipt so a later mismatch is provable, shown to the user when an ' +
+    'escalation reaches their phone, and REQUIRED by any standing rule the user marked require_binding before it ' +
     'will auto-proceed.',
   );
 
@@ -348,7 +359,7 @@ server.registerTool(
     title: 'Check standing authorizations for an action',
     description:
       "Deterministic pre-flight: check whether one of the user's standing authorizations " +
-      '(§10.5) already decides this action — escalate, decline, or pre-approve — without running ' +
+      'already decides this action — escalate, decline, or pre-approve — without running ' +
       'the full consultation. Returns authorization_matched plus the authorized signal and the ' +
       'rule that fired. If no rule matches, fall back to phaedo_consult or your own default.',
     inputSchema: {
@@ -666,10 +677,10 @@ server.registerTool(
   {
     title: 'Ask the subject to sign a payment authorization (AP2 Intent Mandate)',
     description:
-      'Request the subject\'s cryptographic signature on an AP2 Intent Mandate built from their ' +
+      'Request the user\'s cryptographic signature on an AP2 Intent Mandate built from their ' +
       'standing authorizations — a credential a merchant or payments network can verify. Returns a ' +
       'request_id and the unsigned mandate immediately; then poll phaedo_sign_status with BOTH, and ' +
-      'DO NOT treat the mandate as authorized until it returns signed. The subject signs on their ' +
+      'DO NOT treat the mandate as authorized until it returns signed. The user signs on their ' +
       'phone (Face ID, key in the Secure Enclave); they may also decline. Use only when you need a ' +
       'verifiable payment credential — not for ordinary consultations.',
     inputSchema: {
@@ -719,7 +730,7 @@ server.registerTool(
             mandate,
             message: 'Sent to the subject to sign. Poll phaedo_sign_status with this request_id AND this ' +
                      'mandate; do not treat it as authorized until it returns signed. If it expires or the ' +
-                     'subject declines, the mandate stays an unsigned proposal.',
+                     'user declines, the mandate stays an unsigned proposal.',
           }
         : {
             request_type: 'sign_mandate', status: 'unreachable', reason: dep.reason,
@@ -745,9 +756,9 @@ server.registerTool(
     title: 'Check whether the subject has signed the mandate',
     description:
       'Poll a request from phaedo_sign_mandate. Pass the request_id AND the mandate that call returned. ' +
-      'Returns signed + the mandate carrying the verified signature once the subject signs, refused if ' +
+      'Returns signed + the mandate carrying the verified signature once the user signs, refused if ' +
       'they declined, pending while you should keep waiting, or expired once the window lapsed. A signed ' +
-      'result is verified against the subject\'s published signing key before it is returned.',
+      'result is verified against the user\'s published signing key before it is returned.',
     inputSchema: {
       request_id: z.string(),
       mandate: z.record(z.any()),
@@ -881,6 +892,12 @@ async function main() {
   await server.connect(transport);
   // stdio transport owns stdout for protocol framing — never console.log here.
   process.stderr.write('[phaedo-mcp] ready on stdio\n');
+  // Where the profile will come from, in one line, after the handshake so startup never waits
+  // on it. stderr is what Claude Desktop's MCP log shows — the one place a person debugging
+  // "why isn't Phaedo doing anything" will look. Best-effort: a failure here says nothing.
+  profileStatusLine(BASE_DIR)
+    .then((line) => { if (line) process.stderr.write(`[phaedo-mcp] ${line}\n`); })
+    .catch(() => {});
 }
 
 main().catch((err) => {

package/server.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.phaedo-labs/phaedo-mcp",
-  "description": "Carry your Phaedo cognitive fingerprint into any MCP client: inject, consult, escalate, sign.",
-  "version": "0.3.1",
+  "description": "Make AI apps answer your way, check with you before acting, and get approvals on your phone.",
+  "version": "0.3.3",
   "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.1",
+      "version": "0.3.3",
       "transport": {
         "type": "stdio"
       }