auramaxx 0.0.1

package/server/mcp/server.ts

@@ -0,0 +1,1589 @@
+#!/usr/bin/env node
+/**
+ * AuraMaxx MCP Server
+ * =====================
+ * Standalone MCP stdio server that gives any AI agent access to the wallet API.
+ *
+ * Auth bootstrap (in order):
+ *   1. Unix socket auto-approve (ephemeral RSA keypair, encrypted token, zero config)
+ *   2. AURA_TOKEN env var (CI/CD fallback)
+ *
+ * Usage:
+ *   npx tsx server/mcp/server.ts
+ *   AURA_TOKEN=<token> npx tsx server/mcp/server.ts
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import * as net from 'net';
+import { spawn } from 'child_process';
+import {
+  constants,
+  createDecipheriv,
+  generateKeyPairSync,
+  privateDecrypt,
+} from 'crypto';
+import { TOOLS, executeTool, jsonSchemaToZod } from './tools.js';
+import {
+  evaluateProjectScopeAccess,
+  emitProjectScopeEvent,
+  type ProjectScopeMode,
+} from '../lib/project-scope';
+import { resolveAuraSocketCandidates } from '../lib/socket-path';
+import {
+  appendDiaryEntry,
+  countDiaryEntries,
+  formatDiaryEntry,
+  getDiaryCredentialName,
+  getLegacyDiaryCredentialName,
+  resolveDiaryDate,
+} from '../lib/diary';
+import {
+  getCredentialFieldValue,
+  NOTE_CONTENT_KEY,
+} from '../../shared/credential-field-schema';
+
+let token: string | undefined = process.env.AURA_TOKEN;
+
+/** Tracks the most recent auth request so get_token can report status. */
+let pendingAuth: {
+  requestId: string;
+  agentId: string;
+  status: 'polling' | 'approved' | 'rejected' | 'timeout';
+  approveUrl: string;
+} | null = null;
+
+const WALLET_BASE = () => process.env.WALLET_SERVER_URL || 'http://127.0.0.1:4242';
+
+// ── Socket Bootstrap ───────────────────────────────────────────────────
+
+interface HybridEnvelope {
+  v: number;
+  alg: string;
+  key: string;
+  iv: string;
+  tag: string;
+  data: string;
+}
+
+/**
+ * Decrypt an encrypted blob (token or credential) using our private key.
+ * Supports both direct RSA-OAEP and hybrid RSA-OAEP/AES-256-GCM envelopes.
+ */
+function decryptWithPrivateKey(encryptedBase64: string, privateKeyPem: string): string {
+  const decoded = Buffer.from(encryptedBase64, 'base64');
+  let envelope: HybridEnvelope;
+  try {
+    envelope = JSON.parse(decoded.toString('utf8')) as HybridEnvelope;
+  } catch {
+    // Direct RSA-OAEP ciphertext (small payloads)
+    return privateDecrypt(
+      { key: privateKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+      decoded,
+    ).toString('utf8');
+  }
+
+  if (envelope.v !== 1 || envelope.alg !== 'RSA-OAEP/AES-256-GCM') {
+    throw new Error(`Unexpected envelope: v=${envelope.v} alg=${envelope.alg}`);
+  }
+
+  const sessionKey = privateDecrypt(
+    { key: privateKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+    Buffer.from(envelope.key, 'base64'),
+  );
+  const decipher = createDecipheriv('aes-256-gcm', sessionKey, Buffer.from(envelope.iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
+  return Buffer.concat([
+    decipher.update(Buffer.from(envelope.data, 'base64')),
+    decipher.final(),
+  ]).toString('utf8');
+}
+
+// Ephemeral keypair for this session (used for bootstrap + credential reads)
+const { publicKey: ephemeralPubPem, privateKey: ephemeralPrivPem } = generateKeyPairSync('rsa', {
+  modulusLength: 2048,
+  publicKeyEncoding: { type: 'spki', format: 'pem' },
+  privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+});
+
+/** Token TTL from bootstrap (seconds). Used for refresh scheduling. */
+let tokenTtl = 3600;
+let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Bootstrap auth via Unix socket auto-approve.
+ * Returns true if successful.
+ */
+function bootstrapViaSocket(): Promise<boolean> {
+  const uid = process.getuid?.() ?? 'unknown';
+  const socketPaths = resolveAuraSocketCandidates({
+    uid,
+    serverUrl: WALLET_BASE(),
+    serverPort: process.env.WALLET_SERVER_PORT,
+  });
+
+  const trySocket = (socketPath: string): Promise<{ ok: boolean; connectionFailure: boolean }> =>
+    new Promise((resolve) => {
+      const socket = net.createConnection(socketPath);
+      let buffer = '';
+      let resolved = false;
+
+      const timeout = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          socket.destroy();
+          resolve({ ok: false, connectionFailure: true });
+        }
+      }, 5000);
+
+      socket.on('connect', () => {
+        socket.write(JSON.stringify({
+          type: 'auth',
+          agentId: 'mcp-stdio',
+          autoApprove: true,
+          pubkey: ephemeralPubPem,
+        }) + '\n');
+      });
+
+      socket.on('data', (data) => {
+        buffer += data.toString();
+        let newlineIndex;
+        while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.substring(0, newlineIndex);
+          buffer = buffer.substring(newlineIndex + 1);
+
+          if (!line.trim()) continue;
+          try {
+            const msg = JSON.parse(line.trim()) as {
+              type: string;
+              encryptedToken?: string;
+              ttl?: number;
+              message?: string;
+            };
+
+            if (msg.type === 'auth_approved' && msg.encryptedToken) {
+              token = decryptWithPrivateKey(msg.encryptedToken, ephemeralPrivPem);
+              tokenTtl = msg.ttl || 3600;
+              if (!resolved) {
+                resolved = true;
+                clearTimeout(timeout);
+                socket.destroy();
+                console.error(`[mcp] Bootstrapped via Unix socket (auto-approve path: ${socketPath})`);
+                resolve({ ok: true, connectionFailure: false });
+              }
+            } else if (msg.type === 'error') {
+              if (!resolved) {
+                resolved = true;
+                clearTimeout(timeout);
+                socket.destroy();
+                console.error(`[mcp] Socket bootstrap error: ${msg.message}`);
+                resolve({ ok: false, connectionFailure: false });
+              }
+            }
+          } catch { /* ignore parse errors */ }
+        }
+      });
+
+      socket.on('error', (err) => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          console.error(`[mcp] Socket bootstrap connection error: ${err.message} (code=${(err as NodeJS.ErrnoException).code})`);
+          resolve({ ok: false, connectionFailure: true });
+        }
+      });
+    });
+
+  return (async () => {
+    for (const socketPath of socketPaths) {
+      const result = await trySocket(socketPath);
+      if (result.ok) return true;
+      if (!result.connectionFailure) return false;
+    }
+    return false;
+  })();
+}
+
+/**
+ * Schedule a token refresh before expiry.
+ */
+function scheduleRefresh(): void {
+  if (refreshTimer) clearTimeout(refreshTimer);
+  // Refresh 60s before expiry, minimum 10s
+  const refreshMs = Math.max((tokenTtl - 60) * 1000, 10_000);
+  refreshTimer = setTimeout(() => attemptRefresh(0), refreshMs);
+}
+
+/** Retry token refresh with exponential backoff (30s, 60s, 120s, 240s, cap 300s). */
+async function attemptRefresh(attempt: number): Promise<void> {
+  console.error(`[mcp] Refreshing token (attempt ${attempt + 1})...`);
+  const ok = await bootstrapViaSocket();
+  if (ok) {
+    scheduleRefresh();
+  } else {
+    const backoffMs = Math.min(30_000 * Math.pow(2, attempt), 300_000); // cap at 5 min
+    console.error(`[mcp] Token refresh failed — retrying in ${backoffMs / 1000}s`);
+    refreshTimer = setTimeout(() => attemptRefresh(attempt + 1), backoffMs);
+  }
+}
+
+// ── MCP Server Setup ───────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'auramaxx',
+  version: '1.0.0',
+});
+
+// ── Resources ──────────────────────────────────────────────────────────
+
+function loadApiDocs(): string {
+  try { return readFileSync(join(__dirname, '..', '..', 'docs', 'API.md'), 'utf-8'); }
+  catch { return 'API documentation not found.'; }
+}
+
+function loadAuthDocs(): string {
+  try { return readFileSync(join(__dirname, '..', '..', 'docs', 'AUTH.md'), 'utf-8'); }
+  catch { return 'Auth documentation not found.'; }
+}
+
+function loadAgentGuide(): string {
+  try { return readFileSync(join(__dirname, '..', '..', 'skills', 'auramaxx', 'SKILL.md'), 'utf-8'); }
+  catch { return 'Agent guide not found.'; }
+}
+
+server.resource(
+  'api-reference', 'docs://api',
+  { description: 'Full AuraMaxx HTTP API reference — all endpoints, parameters, and examples' },
+  async () => ({ contents: [{ uri: 'docs://api', text: loadApiDocs(), mimeType: 'text/markdown' }] }),
+);
+
+server.resource(
+  'auth-reference', 'docs://auth',
+  { description: 'Authentication, permissions, and spending limits reference' },
+  async () => ({ contents: [{ uri: 'docs://auth', text: loadAuthDocs(), mimeType: 'text/markdown' }] }),
+);
+
+server.resource(
+  'agent-guide', 'docs://guide',
+  { description: 'Agent skill reference — setup, operations, hook modes, permissions, error recovery' },
+  async () => ({ contents: [{ uri: 'docs://guide', text: loadAgentGuide(), mimeType: 'text/markdown' }] }),
+);
+
+// ── Credential helpers ─────────────────────────────────────────────────
+
+/**
+ * Decrypt a credential payload encrypted to our ephemeral RSA key.
+ */
+async function fetchVaultNameMap(): Promise<Map<string, string>> {
+  const res = await fetch(`${WALLET_BASE()}/setup/vaults`, {
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) return new Map();
+  const data = await res.json() as { vaults?: Array<{ id: string; name: string }> };
+  return new Map((data.vaults || []).map((v) => [v.id, v.name]));
+}
+
+const PROJECT_SCOPE_MODE_CACHE_MS = 10_000;
+let cachedProjectScopeMode: ProjectScopeMode = 'auto';
+let cachedProjectScopeModeAt = 0;
+
+function normalizeProjectScopeMode(raw: unknown): ProjectScopeMode {
+  const value = String(raw || '').trim().toLowerCase();
+  if (value === 'strict') return 'strict';
+  if (value === 'off') return 'off';
+  return 'auto';
+}
+
+async function fetchProjectScopeMode(): Promise<ProjectScopeMode> {
+  const now = Date.now();
+  if (now - cachedProjectScopeModeAt < PROJECT_SCOPE_MODE_CACHE_MS) {
+    return cachedProjectScopeMode;
+  }
+  try {
+    const res = await fetch(`${WALLET_BASE()}/setup`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return cachedProjectScopeMode;
+    const data = await res.json() as { projectScopeMode?: unknown };
+    cachedProjectScopeMode = normalizeProjectScopeMode(data.projectScopeMode);
+    cachedProjectScopeModeAt = now;
+    return cachedProjectScopeMode;
+  } catch {
+    return cachedProjectScopeMode;
+  }
+}
+
+function decryptCredentialPayload(encryptedBase64: string): {
+  id: string;
+  vaultId: string;
+  type: string;
+  fields: Array<{ key: string; value: string; type?: string; sensitive?: boolean }>;
+} {
+  const plaintext = decryptWithPrivateKey(encryptedBase64, ephemeralPrivPem);
+  return JSON.parse(plaintext);
+}
+
+function extractErrorMessage(raw: string): string {
+  try {
+    const parsed = JSON.parse(raw) as { error?: unknown };
+    if (typeof parsed?.error === 'string' && parsed.error.trim()) return parsed.error;
+  } catch { /* plain-text payload */ }
+  return raw;
+}
+
+function extractExistingApproval(raw: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    const asRecord = parsed as Record<string, unknown>;
+    if (asRecord.requiresHumanApproval !== true) return null;
+    if (typeof asRecord.requestId !== 'string' || !asRecord.requestId) return null;
+    return asRecord;
+  } catch {
+    return null;
+  }
+}
+
+function buildPermissionEscalationResponse(input: {
+  operation: string;
+  status: number;
+  rawBody: string;
+  permissions: string[];
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  body?: Record<string, unknown>;
+}): { content: Array<{ type: 'text'; text: string }> } {
+  const existingApproval = extractExistingApproval(input.rawBody);
+  if (existingApproval) {
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify(existingApproval),
+      }],
+    };
+  }
+
+  const reason = extractErrorMessage(input.rawBody);
+  const dashboardBase = `http://localhost:${process.env.DASHBOARD_PORT || '4747'}`;
+  return {
+    content: [{
+      type: 'text' as const,
+      text: JSON.stringify({
+        error: `${input.operation} failed (${input.status}): permission denied`,
+        escalated: true,
+        requiresHumanApproval: true,
+        reason,
+        approveAt: dashboardBase,
+        nextStep: {
+          tool: 'api',
+          summary: input.operation,
+          permissions: input.permissions,
+          action: {
+            endpoint: input.endpoint,
+            method: input.method,
+            ...(input.body ? { body: input.body } : {}),
+          },
+        },
+        authFallback: {
+          endpoint: '/auth',
+          note: 'Request a new token via POST /auth with a profile that includes the required permissions.',
+        },
+      }),
+    }],
+  };
+}
+
+async function resolveDefaultVaultId(explicitVault?: string): Promise<string> {
+  if (explicitVault) return explicitVault;
+  try {
+    const { listVaults } = await import('../lib/cold');
+    const vaults = listVaults();
+    const agentVault = vaults.find(v => v.name === 'agent');
+    return agentVault ? agentVault.id : 'primary';
+  } catch {
+    return 'primary';
+  }
+}
+
+/**
+ * Resolve the vault for diary entries with fallback chain:
+ *   1. daily-logs vault (dedicated diary storage)
+ *   2. agent vault (general agent storage)
+ *   3. primary vault (last resort)
+ */
+async function resolveDiaryVaultId(explicitVault?: string): Promise<string> {
+  if (explicitVault) return explicitVault;
+  try {
+    const { listVaults, DAILY_LOGS_VAULT_NAME, AGENT_VAULT_NAME } = await import('../lib/cold');
+    const vaults = listVaults();
+    const dailyLogsVault = vaults.find(v => v.name === DAILY_LOGS_VAULT_NAME);
+    if (dailyLogsVault) return dailyLogsVault.id;
+    const agentVault = vaults.find(v => v.name === AGENT_VAULT_NAME);
+    if (agentVault) return agentVault.id;
+    return 'primary';
+  } catch {
+    return 'primary';
+  }
+}
+
+// ── get_secret rate limiter ─────────────────────────────────────────────
+const GET_SECRET_WINDOW_MS = 60_000; // 1 minute
+const GET_SECRET_MAX = 10; // max 10 requests per window
+const getSecretRequests: number[] = [];
+
+function isGetSecretRateLimited(): boolean {
+  const now = Date.now();
+  // Prune old entries
+  while (getSecretRequests.length > 0 && getSecretRequests[0] <= now - GET_SECRET_WINDOW_MS) {
+    getSecretRequests.shift();
+  }
+  if (getSecretRequests.length >= GET_SECRET_MAX) return true;
+  getSecretRequests.push(now);
+  return false;
+}
+
+// ── Shared credential resolver ──────────────────────────────────────────
+
+/**
+ * Search for a credential by name or tag and return its ID + name.
+ * Shared by get_secret, del_secret, inject_secret, share_secret.
+ */
+async function resolveCredentialByName(
+  name: string,
+): Promise<
+  | { credentialId: string; credentialName: string }
+  | { error: string; escalation?: ReturnType<typeof buildPermissionEscalationResponse> }
+> {
+  const base = WALLET_BASE();
+  try {
+    const vaultNames = await fetchVaultNameMap();
+    const projectScopeMode = await fetchProjectScopeMode();
+    for (const queryParam of [`q=${encodeURIComponent(name)}`, `tag=${encodeURIComponent(name)}`]) {
+      const res = await fetch(`${base}/credentials?${queryParam}`, {
+        headers: { 'Authorization': `Bearer ${token}` },
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.status === 403) {
+        const text = await res.text();
+        return {
+          error: `Permission denied searching for "${name}"`,
+          escalation: buildPermissionEscalationResponse({
+            operation: `Read secret "${name}"`,
+            status: res.status,
+            rawBody: text,
+            permissions: ['secret:read'],
+            endpoint: `/credentials?${queryParam}`,
+            method: 'GET',
+          }),
+        };
+      }
+      if (!res.ok) continue;
+
+      const data = await res.json() as { credentials: Array<{ id: string; name: string; vaultId: string }> };
+      if (!data.credentials || data.credentials.length === 0) continue;
+
+      const decision = evaluateProjectScopeAccess({
+        surface: 'mcp_get_secret',
+        requested: { vaultName: null, credentialName: name },
+        candidates: data.credentials.map((c) => ({
+          id: c.id,
+          name: c.name,
+          vaultName: vaultNames.get(c.vaultId) || null,
+        })),
+        actor: 'mcp-stdio',
+        projectScopeMode,
+      });
+
+      emitProjectScopeEvent({
+        actor: 'mcp-stdio',
+        surface: 'mcp_get_secret',
+        requestedCredential: { vaultName: null, credentialName: name },
+        decision,
+      });
+
+      if (!decision.allowed) {
+        return { error: `${decision.code}: ${decision.remediation}` };
+      }
+
+      const allowedIds = new Set(decision.allowedCandidates.map((c) => c.id).filter(Boolean));
+      const scopedCandidates = data.credentials.filter((c) => allowedIds.has(c.id));
+      if (scopedCandidates.length === 0) continue;
+
+      return { credentialId: scopedCandidates[0].id, credentialName: scopedCandidates[0].name };
+    }
+  } catch (err) {
+    return { error: `Search failed: ${err}` };
+  }
+  return { error: `No credential found matching "${name}"` };
+}
+
+// ── get_secret ─────────────────────────────────────────────────────────
+server.tool(
+  'get_secret',
+  'Look up a stored credential/secret by name or tag and return its decrypted value. Searches credential vaults for a matching entry and returns all fields (including sensitive ones like passwords, API keys, etc.).',
+  { name: z.string().describe('Name or tag to search for (e.g. "GitHub", "openai", "deploy")') },
+  async (input) => {
+    const { name } = input as { name: string };
+
+    if (isGetSecretRateLimited()) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'Rate limited — too many get_secret requests. Try again in 1 minute.' }) }] };
+    }
+    if (!token) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'No auth token — start AuraMaxx server for auto-bootstrap, or set AURA_TOKEN env var' }) }] };
+    }
+
+    const resolved = await resolveCredentialByName(name);
+    if ('error' in resolved) {
+      if ('escalation' in resolved && resolved.escalation) return resolved.escalation;
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: resolved.error }) }] };
+    }
+
+    const { credentialId, credentialName } = resolved;
+    const base = WALLET_BASE();
+    const readToken = token;
+
+    // Step 3: Read credential (encrypted to our ephemeral key)
+    try {
+      const res = await fetch(`${base}/credentials/${credentialId}/read`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${readToken}`,
+          'X-Secret-Surface': 'get_secret',
+          'X-Credential-Name': credentialName || name,
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+
+      if (!res.ok) {
+        const text = await res.text();
+        if (res.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Read secret "${credentialName || name}"`,
+            status: res.status,
+            rawBody: text,
+            permissions: ['secret:read'],
+            endpoint: `/credentials/${credentialId}/read`,
+            method: 'POST',
+            body: {},
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Read failed (${res.status}): ${text}` }) }] };
+      }
+
+      const data = await res.json() as { encrypted: string };
+      const decrypted = decryptCredentialPayload(data.encrypted);
+
+      // If credential has a TOTP field, generate current code
+      const totpField = decrypted.fields?.find((f: { key: string }) => f.key === 'totp' || f.key === 'otp');
+      let totpCode: string | undefined;
+      let totpRemaining: number | undefined;
+      if (totpField) {
+        try {
+          const totpRes = await fetch(`${base}/credentials/${credentialId}/totp`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${token}` },
+            signal: AbortSignal.timeout(5000),
+          });
+          if (totpRes.ok) {
+            const totpData = await totpRes.json() as { code: string; remaining: number };
+            totpCode = totpData.code;
+            totpRemaining = totpData.remaining;
+          }
+        } catch {
+          // TOTP generation failed — skip, still return credential
+        }
+      }
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            name: credentialName,
+            credentialId: decrypted.id,
+            type: decrypted.type,
+            fields: decrypted.fields,
+            ...(totpCode && { totpCode, totpRemaining }),
+          }),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Decryption failed: ${err}` }) }] };
+    }
+  },
+);
+
+// ── put_secret ─────────────────────────────────────────────────────────
+server.tool(
+  'put_secret',
+  'Store a new credential/secret with the given name and value. Creates a "note" type credential in the default vault with a single sensitive field.',
+  {
+    name: z.string().describe('Name for the credential (e.g. "OpenAI API Key", "GitHub Token")'),
+    value: z.string().describe('The secret value to store'),
+    vault: z.string().optional().describe('Vault ID to store in (defaults to "agent", falls back to "primary")'),
+    tags: z.array(z.string()).optional().describe('Optional tags for organization'),
+  },
+  async (input) => {
+    const { name, value, vault, tags } = input as { name: string; value: string; vault?: string; tags?: string[] };
+
+    if (!token) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'No auth token — start AuraMaxx server for auto-bootstrap, or set AURA_TOKEN env var' }) }] };
+    }
+
+    const base = WALLET_BASE();
+    const vaultId = await resolveDefaultVaultId(vault);
+    const createBody = {
+      vaultId,
+      type: 'note',
+      name,
+      meta: tags ? { tags } : {},
+      fields: [{ key: NOTE_CONTENT_KEY, value, type: 'secret', sensitive: true }],
+    };
+
+    try {
+      const res = await fetch(`${base}/credentials`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+        body: JSON.stringify(createBody),
+        signal: AbortSignal.timeout(5000),
+      });
+
+      const text = await res.text();
+      if (!res.ok) {
+        if (res.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Store secret "${name}"`,
+            status: res.status,
+            rawBody: text,
+            permissions: ['secret:write'],
+            endpoint: '/credentials',
+            method: 'POST',
+            body: createBody,
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Store failed (${res.status}): ${text}` }) }] };
+      }
+
+      const data = JSON.parse(text) as { credential: { id: string; name: string } };
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            credentialId: data.credential.id,
+            name: data.credential.name,
+            message: `Secret "${name}" stored successfully`,
+          }),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Store failed: ${err}` }) }] };
+    }
+  },
+);
+
+// ── write_diary ────────────────────────────────────────────────────────
+server.tool(
+  'write_diary',
+  'Append an entry to a daily diary note (YYYY-MM-DD_LOGS). Uses the daily-logs vault when available, falls back to agent vault, then primary vault.',
+  {
+    entry: z.string().min(1).describe('Diary text to append'),
+    date: z.string().optional().describe('Optional date in YYYY-MM-DD (defaults to today UTC)'),
+  },
+  async (input) => {
+    const { entry, date } = input as { entry: string; date?: string };
+
+    if (!token) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'No auth token — start AuraMaxx server for auto-bootstrap, or set AURA_TOKEN env var' }) }] };
+    }
+    if (!entry.trim()) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'entry must not be empty' }) }] };
+    }
+
+    const resolvedDate = resolveDiaryDate(date);
+    if (!resolvedDate) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'date must be YYYY-MM-DD' }) }] };
+    }
+
+    const base = WALLET_BASE();
+    const vaultId = await resolveDiaryVaultId();
+    const diaryName = getDiaryCredentialName(resolvedDate);
+    const legacyDiaryName = getLegacyDiaryCredentialName(resolvedDate);
+    const entryBlock = formatDiaryEntry(entry);
+
+    try {
+      const listRes = await fetch(
+        `${base}/credentials?vault=${encodeURIComponent(vaultId)}&q=${encodeURIComponent(resolvedDate)}`,
+        {
+          headers: { 'Authorization': `Bearer ${token}` },
+          signal: AbortSignal.timeout(5000),
+        },
+      );
+
+      if (!listRes.ok) {
+        const text = await listRes.text();
+        if (listRes.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Read diary "${diaryName}"`,
+            status: listRes.status,
+            rawBody: text,
+            permissions: ['secret:read'],
+            endpoint: `/credentials?vault=${encodeURIComponent(vaultId)}&q=${encodeURIComponent(resolvedDate)}`,
+            method: 'GET',
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Diary lookup failed (${listRes.status}): ${text}` }) }] };
+      }
+
+      const listed = await listRes.json() as {
+        credentials?: Array<{ id: string; name: string; vaultId: string }>;
+      };
+      const existing = (listed.credentials || []).find((c) => c.name === diaryName)
+        || (listed.credentials || []).find((c) => c.name === legacyDiaryName);
+
+      if (!existing) {
+        const createBody = {
+          vaultId,
+          type: 'note',
+          name: diaryName,
+          meta: { tags: ['diary', 'heartbeat'] },
+          fields: [{ key: NOTE_CONTENT_KEY, value: entryBlock, type: 'secret', sensitive: true }],
+        };
+
+        const createRes = await fetch(`${base}/credentials`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+          body: JSON.stringify(createBody),
+          signal: AbortSignal.timeout(5000),
+        });
+
+        const createText = await createRes.text();
+        if (!createRes.ok) {
+          if (createRes.status === 403) {
+            return buildPermissionEscalationResponse({
+              operation: `Create diary "${diaryName}"`,
+              status: createRes.status,
+              rawBody: createText,
+              permissions: ['secret:write'],
+              endpoint: '/credentials',
+              method: 'POST',
+              body: createBody,
+            });
+          }
+          return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Diary create failed (${createRes.status}): ${createText}` }) }] };
+        }
+
+        const created = JSON.parse(createText) as { credential: { id: string } };
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              success: true,
+              date: resolvedDate,
+              entryCount: 1,
+              credentialId: created.credential.id,
+              vaultId,
+            }),
+          }],
+        };
+      }
+
+      const readRes = await fetch(`${base}/credentials/${existing.id}/read`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${token}` },
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!readRes.ok) {
+        const text = await readRes.text();
+        if (readRes.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Read diary "${existing.name}"`,
+            status: readRes.status,
+            rawBody: text,
+            permissions: ['secret:read', 'secret:write'],
+            endpoint: `/credentials/${existing.id}/read`,
+            method: 'POST',
+            body: {},
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Diary read failed (${readRes.status}): ${text}` }) }] };
+      }
+
+      const readData = await readRes.json() as {
+        encrypted?: string;
+        fields?: Array<{ key: string; value: string; type?: string; sensitive?: boolean }>;
+      };
+      const decrypted = readData.encrypted
+        ? decryptCredentialPayload(readData.encrypted)
+        : {
+            id: existing.id,
+            vaultId: existing.vaultId,
+            type: 'note',
+            fields: readData.fields || [],
+          };
+      const previousText = getCredentialFieldValue('note', decrypted.fields, NOTE_CONTENT_KEY)
+        || decrypted.fields[0]?.value
+        || '';
+      const nextText = appendDiaryEntry(previousText, entryBlock);
+      const updateBody = {
+        name: diaryName,
+        sensitiveFields: [{ key: NOTE_CONTENT_KEY, value: nextText, type: 'secret', sensitive: true }],
+      };
+
+      const updateRes = await fetch(`${base}/credentials/${existing.id}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+        body: JSON.stringify(updateBody),
+        signal: AbortSignal.timeout(5000),
+      });
+
+      const updateText = await updateRes.text();
+      if (!updateRes.ok) {
+        if (updateRes.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Update diary "${diaryName}"`,
+            status: updateRes.status,
+            rawBody: updateText,
+            permissions: ['secret:read', 'secret:write'],
+            endpoint: `/credentials/${existing.id}`,
+            method: 'PUT',
+            body: updateBody,
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Diary update failed (${updateRes.status}): ${updateText}` }) }] };
+      }
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            date: resolvedDate,
+            name: diaryName,
+            entryCount: countDiaryEntries(nextText),
+            credentialId: existing.id,
+            vaultId: existing.vaultId || vaultId,
+          }),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `write_diary failed: ${err}` }) }] };
+    }
+  },
+);
+
+// ── del_secret ─────────────────────────────────────────────────────────
+server.tool(
+  'del_secret',
+  'Delete a stored credential/secret by name. Searches for the credential then deletes it from the active vault.',
+  {
+    name: z.string().describe('Name or tag of the credential to delete'),
+    location: z.enum(['active', 'archive', 'recently_deleted']).optional().describe('Credential location (default: active)'),
+  },
+  async (input) => {
+    const { name, location } = input as { name: string; location?: string };
+
+    if (!token) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'No auth token — start AuraMaxx server for auto-bootstrap, or set AURA_TOKEN env var' }) }] };
+    }
+
+    const resolved = await resolveCredentialByName(name);
+    if ('error' in resolved) {
+      if ('escalation' in resolved && resolved.escalation) return resolved.escalation;
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: resolved.error }) }] };
+    }
+
+    const base = WALLET_BASE();
+    const loc = location || 'active';
+    const qs = new URLSearchParams({ location: loc }).toString();
+
+    try {
+      const res = await fetch(`${base}/credentials/${encodeURIComponent(resolved.credentialId)}?${qs}`, {
+        method: 'DELETE',
+        headers: { 'Authorization': `Bearer ${token}` },
+        signal: AbortSignal.timeout(8000),
+      });
+
+      const text = await res.text();
+      if (!res.ok) {
+        if (res.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Delete secret "${resolved.credentialName}"`,
+            status: res.status,
+            rawBody: text,
+            permissions: ['secret:write'],
+            endpoint: `/credentials/${resolved.credentialId}`,
+            method: 'DELETE',
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Delete failed (${res.status}): ${text}` }) }] };
+      }
+
+      let data: Record<string, unknown> = {};
+      try { data = JSON.parse(text); } catch { /* plain text */ }
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            name: resolved.credentialName,
+            credentialId: resolved.credentialId,
+            action: data.action || 'deleted',
+          }),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `del_secret failed: ${err}` }) }] };
+    }
+  },
+);
+
+// ── inject_secret ──────────────────────────────────────────────────────
+server.tool(
+  'inject_secret',
+  'Look up a credential by name, extract its primary secret field, and either set it as a process env var or spawn a child command with the env var injected. Use stdio pipes to avoid MCP interference.',
+  {
+    name: z.string().describe('Name or tag of the credential to inject'),
+    envVar: z.string().describe('Environment variable name to set (e.g. "OPENAI_API_KEY")'),
+    command: z.array(z.string()).optional().describe('Optional command + args to spawn with the env var (e.g. ["node", "script.js"]). If omitted, sets the env var in the MCP server process.'),
+  },
+  async (input) => {
+    const { name, envVar, command } = input as { name: string; envVar: string; command?: string[] };
+
+    if (!token) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'No auth token — start AuraMaxx server for auto-bootstrap, or set AURA_TOKEN env var' }) }] };
+    }
+
+    if (isGetSecretRateLimited()) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'Rate limited — too many secret requests. Try again in 1 minute.' }) }] };
+    }
+
+    const resolved = await resolveCredentialByName(name);
+    if ('error' in resolved) {
+      if ('escalation' in resolved && resolved.escalation) return resolved.escalation;
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: resolved.error }) }] };
+    }
+
+    const base = WALLET_BASE();
+
+    // Read + decrypt credential
+    let secretValue: string;
+    try {
+      const res = await fetch(`${base}/credentials/${resolved.credentialId}/read`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${token}`,
+          'X-Secret-Surface': 'inject_secret',
+          'X-Secret-EnvVar': envVar,
+          'X-Credential-Name': resolved.credentialName || name,
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+
+      if (!res.ok) {
+        const text = await res.text();
+        if (res.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Read secret "${resolved.credentialName}" for injection`,
+            status: res.status,
+            rawBody: text,
+            permissions: ['secret:read'],
+            endpoint: `/credentials/${resolved.credentialId}/read`,
+            method: 'POST',
+            body: {},
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Read failed (${res.status}): ${text}` }) }] };
+      }
+
+      const data = await res.json() as { encrypted: string };
+      const decrypted = decryptCredentialPayload(data.encrypted);
+
+      // Extract primary secret field
+      const noteField = getCredentialFieldValue('note', decrypted.fields, NOTE_CONTENT_KEY);
+      const passwordField = decrypted.fields.find((f: { key: string; sensitive?: boolean }) => f.sensitive)?.value;
+      secretValue = noteField || passwordField || decrypted.fields[0]?.value || '';
+
+      if (!secretValue) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Credential "${name}" has no extractable secret value` }) }] };
+      }
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `inject_secret read failed: ${err}` }) }] };
+    }
+
+    // Set env var or spawn child
+    if (!command || command.length === 0) {
+      process.env[envVar] = secretValue;
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            envVar,
+            name: resolved.credentialName,
+            scope: 'mcp-server-process',
+            message: `Set ${envVar} in MCP server process. Use command param to inject into a child process.`,
+          }),
+        }],
+      };
+    }
+
+    // Spawn child process with injected env var (use pipe stdio to avoid MCP interference)
+    return new Promise((resolve) => {
+      const child = spawn(command[0], command.slice(1), {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env, [envVar]: secretValue },
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      child.stdout?.on('data', (data) => { stdout += data.toString(); });
+      child.stderr?.on('data', (data) => { stderr += data.toString(); });
+
+      child.on('error', (error) => {
+        resolve({
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({ error: `Failed to execute command: ${error.message}` }),
+          }],
+        });
+      });
+
+      child.on('exit', (code) => {
+        const truncated = (s: string) => s.length > 2000 ? s.slice(0, 2000) + '...[truncated]' : s;
+        resolve({
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              success: code === 0,
+              exitCode: code,
+              envVar,
+              command: command.join(' '),
+              stdout: truncated(stdout),
+              ...(stderr ? { stderr: truncated(stderr) } : {}),
+            }),
+          }],
+        });
+      });
+    });
+  },
+);
+
+// ── share_secret ───────────────────────────────────────────────────────
+server.tool(
+  'share_secret',
+  'Create a shareable link for a credential. Resolves by name, then creates a time-limited share URL with optional password protection.',
+  {
+    name: z.string().describe('Name or tag of the credential to share'),
+    expiresAfter: z.string().optional().describe('Expiry duration (e.g. "1h", "7d", "30m"). Default: server default.'),
+    accessMode: z.enum(['anyone', 'password']).optional().describe('Access mode: "anyone" (link only) or "password" (requires password)'),
+    password: z.string().optional().describe('Password for password-protected shares'),
+    oneTimeOnly: z.boolean().optional().describe('If true, share link can only be viewed once'),
+  },
+  async (input) => {
+    const { name, expiresAfter, accessMode, password, oneTimeOnly } = input as {
+      name: string;
+      expiresAfter?: string;
+      accessMode?: 'anyone' | 'password';
+      password?: string;
+      oneTimeOnly?: boolean;
+    };
+
+    if (!token) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'No auth token — start AuraMaxx server for auto-bootstrap, or set AURA_TOKEN env var' }) }] };
+    }
+
+    const resolved = await resolveCredentialByName(name);
+    if ('error' in resolved) {
+      if ('escalation' in resolved && resolved.escalation) return resolved.escalation;
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: resolved.error }) }] };
+    }
+
+    const base = WALLET_BASE();
+    const shareBody: Record<string, unknown> = { credentialId: resolved.credentialId };
+    if (expiresAfter) shareBody.expiresAfter = expiresAfter;
+    if (accessMode) shareBody.accessMode = accessMode;
+    if (password) shareBody.password = password;
+    if (oneTimeOnly !== undefined) shareBody.oneTimeOnly = oneTimeOnly;
+
+    try {
+      const res = await fetch(`${base}/credential-shares`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${token}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(shareBody),
+        signal: AbortSignal.timeout(8000),
+      });
+
+      const text = await res.text();
+      if (!res.ok) {
+        if (res.status === 403) {
+          return buildPermissionEscalationResponse({
+            operation: `Share secret "${resolved.credentialName}"`,
+            status: res.status,
+            rawBody: text,
+            permissions: ['secret:read', 'secret:share'],
+            endpoint: '/credential-shares',
+            method: 'POST',
+            body: shareBody,
+          });
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Share failed (${res.status}): ${text}` }) }] };
+      }
+
+      const data = JSON.parse(text) as { success?: boolean; share?: Record<string, unknown>; error?: string };
+      if (!data.success || !data.share) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: data.error || 'Share creation returned unexpected response' }) }] };
+      }
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            name: resolved.credentialName,
+            credentialId: resolved.credentialId,
+            share: data.share,
+          }),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `share_secret failed: ${err}` }) }] };
+    }
+  },
+);
+
+// ── auth ────────────────────────────────────────────────────────────────
+server.tool(
+  'auth',
+  'Request an authenticated session token. Sends an auth request to the server with an ephemeral RSA keypair, then polls for human approval. On approval, decrypts and activates the token for this MCP session. Times out after 120s.',
+  // NOTE: Returns immediately with the approval URL. Polling happens in background.
+  {
+    agentId: z.string().optional().describe('Agent identifier (default: "mcp-stdio")'),
+    profile: z.string().optional().describe('Permission profile name to request'),
+    profileVersion: z.string().optional().describe('Profile version'),
+    profileOverrides: z.record(z.unknown()).optional().describe('Profile permission overrides'),
+    action: z.object({
+      endpoint: z.string().describe('API endpoint to call (e.g. "/send")'),
+      method: z.string().describe('HTTP method (e.g. "POST")'),
+      body: z.record(z.unknown()).optional().describe('Request body for the action'),
+    }).optional().describe('Pre-computed action to auto-execute on approval'),
+  },
+  async (input) => {
+    const { agentId, profile, profileVersion, profileOverrides, action } = input as {
+      agentId?: string;
+      profile?: string;
+      profileVersion?: string;
+      profileOverrides?: Record<string, unknown>;
+      action?: { endpoint: string; method: string; body?: Record<string, unknown> };
+    };
+
+    const base = WALLET_BASE();
+    const resolvedAgentId = agentId || 'mcp-stdio';
+
+    // Step 1: Create auth request with our ephemeral pubkey
+    let requestId: string;
+    let secret: string;
+    let approveUrl: string | undefined;
+    try {
+      const authBody: Record<string, unknown> = {
+        agentId: resolvedAgentId,
+        pubkey: ephemeralPubPem,
+      };
+      if (profile) authBody.profile = profile;
+      if (profileVersion) authBody.profileVersion = profileVersion;
+      if (profileOverrides) authBody.profileOverrides = profileOverrides;
+      if (action) authBody.action = action;
+
+      const res = await fetch(`${base}/auth`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(authBody),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!res.ok) {
+        const text = await res.text();
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Auth request failed (${res.status}): ${text}` }) }] };
+      }
+
+      const data = await res.json() as { requestId: string; secret: string; approveUrl?: string };
+      requestId = data.requestId;
+      secret = data.secret;
+      if (data.approveUrl) approveUrl = data.approveUrl;
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Auth request failed: ${err}` }) }] };
+    }
+
+    const dashboardBase = `http://localhost:${process.env.DASHBOARD_PORT || '4747'}`;
+
+    // Step 2: Start background polling, return approval URL immediately
+    const timeoutMs = 120_000;
+    const intervalMs = 3_000;
+
+    // Track pending auth for get_token
+    const resolvedApproveUrl = approveUrl || `${dashboardBase}/approve/${encodeURIComponent(requestId)}`;
+    pendingAuth = { requestId, agentId: resolvedAgentId, status: 'polling', approveUrl: resolvedApproveUrl };
+
+    // Poll in background — token activates silently when approved
+    (async () => {
+      const startedAt = Date.now();
+      while (Date.now() - startedAt <= timeoutMs) {
+        try {
+          const pollRes = await fetch(
+            `${base}/auth/${encodeURIComponent(requestId)}?secret=${encodeURIComponent(secret)}`,
+            { signal: AbortSignal.timeout(5000) },
+          );
+
+          if (pollRes.status === 410 || pollRes.status === 403) {
+            if (pendingAuth?.requestId === requestId) pendingAuth.status = 'rejected';
+            return;
+          }
+
+          if (pollRes.ok) {
+            const pollData = await pollRes.json() as {
+              status?: string;
+              encryptedToken?: string;
+              ttl?: number;
+            };
+
+            if (pollData.status === 'rejected') {
+              if (pendingAuth?.requestId === requestId) pendingAuth.status = 'rejected';
+              return;
+            }
+
+            if (pollData.status === 'approved' && pollData.encryptedToken) {
+              try {
+                token = decryptWithPrivateKey(pollData.encryptedToken, ephemeralPrivPem);
+                tokenTtl = pollData.ttl || 3600;
+                scheduleRefresh();
+                if (pendingAuth?.requestId === requestId) pendingAuth.status = 'approved';
+                console.error(`[mcp] Auth approved — token activated for ${resolvedAgentId}`);
+              } catch { /* decryption failed */ }
+              return;
+            }
+          }
+        } catch { /* network error — retry */ }
+
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      }
+      // Timed out
+      if (pendingAuth?.requestId === requestId) pendingAuth.status = 'timeout';
+    })();
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          success: true,
+          message: `Auth request created. Approve at the link below, then retry your operation.`,
+          approveUrl: resolvedApproveUrl,
+          requestId,
+          agentId: resolvedAgentId,
+          polling: true,
+          note: 'Token will activate automatically once approved. Just retry your previous tool call.',
+        }),
+      }],
+    };
+  },
+);
+
+// ── get_token ──────────────────────────────────────────────────────────
+server.tool(
+  'get_token',
+  'Check if the MCP session has an active auth token. Use after calling `auth` to poll whether the human has approved the request yet.',
+  {},
+  async () => {
+    if (token) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            hasToken: true,
+            agentId: pendingAuth?.agentId || 'mcp-stdio',
+          }),
+        }],
+      };
+    }
+
+    if (pendingAuth) {
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            hasToken: false,
+            status: pendingAuth.status,
+            requestId: pendingAuth.requestId,
+            agentId: pendingAuth.agentId,
+            ...(pendingAuth.status === 'polling' && { approveUrl: pendingAuth.approveUrl }),
+            ...(pendingAuth.status === 'polling' && { note: 'Still waiting for human approval. Retry in a few seconds.' }),
+            ...(pendingAuth.status === 'rejected' && { note: 'Auth request was rejected. Call `auth` to create a new request.' }),
+            ...(pendingAuth.status === 'timeout' && { note: 'Auth request timed out. Call `auth` to create a new request.' }),
+          }),
+        }],
+      };
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          hasToken: false,
+          note: 'No auth request in progress. Call `auth` to request a token.',
+        }),
+      }],
+    };
+  },
+);
+
+// ── start ──────────────────────────────────────────────────────────────
+server.tool(
+  'start',
+  'Start the AuraMaxx server if not already running. Checks health first, then starts in headless mode if needed. Attempts socket bootstrap after start.',
+  {},
+  async () => {
+    const base = WALLET_BASE();
+
+    // Step 1: Check if server is already running
+    try {
+      const res = await fetch(`${base}/setup`, {
+        signal: AbortSignal.timeout(3000),
+      });
+      if (res.ok) {
+        // Already running — try socket bootstrap if no token
+        if (!token) {
+          const ok = await bootstrapViaSocket();
+          if (ok) scheduleRefresh();
+        }
+        return {
+          content: [{
+            type: 'text' as const,
+            text: JSON.stringify({
+              success: true,
+              message: 'Server is already running',
+              hasToken: !!token,
+              url: base,
+            }),
+          }],
+        };
+      }
+    } catch {
+      // Server not reachable — proceed to start
+    }
+
+    // Step 2: Import and call startServer
+    try {
+      const { startServer } = await import('../cli/lib/process');
+      startServer({ headless: true });
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Failed to start server: ${err}` }) }] };
+    }
+
+    // Step 3: Wait for server to become reachable (up to 15s)
+    const startedAt = Date.now();
+    const maxWaitMs = 15_000;
+    let serverReady = false;
+
+    while (Date.now() - startedAt < maxWaitMs) {
+      try {
+        const res = await fetch(`${base}/setup`, {
+          signal: AbortSignal.timeout(2000),
+        });
+        if (res.ok) {
+          serverReady = true;
+          break;
+        }
+      } catch {
+        // Not ready yet
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+
+    if (!serverReady) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'Server started but did not become reachable within 15 seconds' }) }] };
+    }
+
+    // Step 4: Attempt socket bootstrap
+    if (!token) {
+      const ok = await bootstrapViaSocket();
+      if (ok) scheduleRefresh();
+    }
+
+    return {
+      content: [{
+        type: 'text' as const,
+        text: JSON.stringify({
+          success: true,
+          message: 'Server started in headless mode',
+          hasToken: !!token,
+          url: base,
+        }),
+      }],
+    };
+  },
+);
+
+// ── unlock ─────────────────────────────────────────────────────────────
+server.tool(
+  'unlock',
+  'Unlock the vault with the provided password. Encrypts the password client-side using the server\'s RSA public key, then sends the encrypted payload. On success, activates an admin token for this MCP session. Optionally specify a vaultId to unlock a specific vault.',
+  {
+    password: z.string().describe('The vault password (plaintext — encrypted before transmission)'),
+    vaultId: z.string().optional().describe('Optional vault ID to unlock a specific vault (default: primary)'),
+  },
+  async (input) => {
+    const { password, vaultId } = input as { password: string; vaultId?: string };
+
+    if (!password.trim()) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'password is required' }) }] };
+    }
+
+    const base = WALLET_BASE();
+
+    // Step 1: Fetch server's RSA public key
+    let serverPubKey: string;
+    try {
+      const res = await fetch(`${base}/auth/connect`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Failed to fetch server public key (${res.status})` }) }] };
+      }
+      const data = await res.json() as { publicKey: string };
+      serverPubKey = data.publicKey;
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Server not reachable: ${err}` }) }] };
+    }
+
+    // Step 2: Encrypt password with server's RSA public key
+    let encrypted: string;
+    try {
+      const { publicEncrypt, constants: cryptoConstants } = await import('crypto');
+      encrypted = publicEncrypt(
+        { key: serverPubKey, padding: cryptoConstants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+        Buffer.from(password),
+      ).toString('base64');
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Encryption failed: ${err}` }) }] };
+    }
+
+    // Step 3: POST /unlock with encrypted password + our ephemeral pubkey
+    const endpoint = vaultId ? `/unlock/${encodeURIComponent(vaultId)}` : '/unlock';
+    try {
+      const res = await fetch(`${base}${endpoint}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ encrypted, pubkey: ephemeralPubPem }),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      const text = await res.text();
+      if (!res.ok) {
+        let errorMsg: string;
+        try { errorMsg = (JSON.parse(text) as { error?: string }).error || text; } catch { errorMsg = text; }
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Unlock failed (${res.status}): ${errorMsg}` }) }] };
+      }
+
+      const data = JSON.parse(text) as { success: boolean; token?: string; address?: string; message?: string };
+
+      // Activate the returned admin token for this MCP session
+      if (data.token) {
+        token = data.token;
+        scheduleRefresh();
+      }
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify({
+            success: true,
+            message: data.message || 'Vault unlocked',
+            address: data.address,
+            hasToken: !!token,
+            ...(vaultId ? { vaultId } : {}),
+          }),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Unlock request failed: ${err}` }) }] };
+    }
+  },
+);
+
+// ── doctor ─────────────────────────────────────────────────────────────
+server.tool(
+  'doctor',
+  'Run onboarding and runtime diagnostics (CLI equivalent: `auramaxx doctor --json`). Returns structured check results with pass/warn/fail status, findings, evidence, and remediation steps.',
+  {
+    strict: z.boolean().optional().describe('If true, treats warnings as failures (default: false)'),
+    fix: z.boolean().optional().describe('If true, attempts auto-fixes like shell fallback installation (default: false)'),
+  },
+  async (input) => {
+    const { strict, fix } = input as { strict?: boolean; fix?: boolean };
+
+    try {
+      const { runDoctor } = await import('../cli/commands/doctor');
+      const result = await runDoctor({ json: true, strict: !!strict, fix: !!fix });
+
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify(result),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Doctor failed: ${err}` }) }] };
+    }
+  },
+);
+
+// ── Register shared tools ──────────────────────────────────────────────
+
+for (const tool of TOOLS) {
+  const shape = jsonSchemaToZod(tool.parameters.properties, tool.parameters.required || []);
+
+  server.tool(
+    tool.name,
+    tool.description,
+    shape,
+    async (input) => {
+      const result = await executeTool(tool.name, input as Record<string, unknown>, token);
+      return { content: [{ type: 'text' as const, text: result }] };
+    },
+  );
+}
+
+// ── Main ───────────────────────────────────────────────────────────────
+
+async function main() {
+  // Bootstrap auth: try socket first, then env var
+  if (!token) {
+    const ok = await bootstrapViaSocket();
+    if (ok) {
+      scheduleRefresh();
+      console.error('[mcp] Auth: socket bootstrap');
+    } else if (process.env.AURA_TOKEN) {
+      token = process.env.AURA_TOKEN;
+      console.error('[mcp] Auth: AURA_TOKEN env var');
+    } else {
+      console.error('[mcp] Auth: none (tools will return auth errors until server is running)');
+    }
+  } else {
+    // Have AURA_TOKEN from env — still try socket for encrypted upgrade
+    console.error('[mcp] Auth: AURA_TOKEN env var (pre-configured)');
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('MCP server error:', err);
+  process.exit(1);
+});