@ainote/mcp 1.1.0 → 1.2.0

package/lib/tools/dev-doc-tools.js

@@ -1,12 +1,21 @@
 import { toSuccessContent } from './internal/formatters.js';
+import { mapPathForCurrentPlatform, canonicalizePath, getPlatformInfo } from './internal/path-mapper.js';
+import { scanClaudeSubdir, readMcpServers, writeMcpServersSidecar, discoverSyncTargets } from './internal/claude-scanner.js';
+import { encryptText, decryptText, generateKeypair } from './internal/encryption.js';
+import { getAgeIdentity, setAgeIdentity, getAgeRecipients, addRecipient, storageBackend } from './internal/keychain.js';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
 
 function listDevDocsDefinition() {
   return {
     name: 'list_dev_docs',
-    description: `List dev documents under dev/ category hierarchy. Manage AI coding tool configs (CLAUDE.md, .cursorrules, etc.) and dev docs centrally.
+    description: `List your synced dev documents stored in AI Note cloud.
 
-Categories: claude, cursor, windsurf, copilot, docs, or custom subcategories.
-Supports markdown, json, yaml content types.`,
+Shows all documents under dev/ category including memory files, AI configs, and project docs.
+Use this to see what's synced and which files have local_path set for multi-device sync.
+
+Categories: memory, claude, cursor, windsurf, env, docs, or custom subcategories.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -47,9 +56,15 @@ function getDevDocDefinition() {
 function createDevDocDefinition() {
   return {
     name: 'create_dev_doc',
-    description: `Create a new dev document under dev/ category. Auto-creates subcategory if needed.
+    description: `Save a file to AI Note cloud for multi-device sync.
+
+PRIMARY USE CASES:
+- Memory files: ~/.claude/projects/.../memory/MEMORY.md
+- AI configs: CLAUDE.md, .cursorrules, .windsurfrules (not in git)
+- Project docs: architecture notes, planning docs
 
-Use this to store CLAUDE.md content, cursor rules, windsurf rules, API specs, architecture docs, etc.`,
+Set local_path to enable pull_dev_docs auto-sync on other devices.
+Categories: memory | claude | cursor | env | docs`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -63,6 +78,10 @@ Use this to store CLAUDE.md content, cursor rules, windsurf rules, API specs, ar
           type: 'string',
           enum: ['markdown', 'json', 'yaml', 'text'],
           description: 'Content type. Auto-detected from title extension if omitted.'
+        },
+        local_path: {
+          type: 'string',
+          description: 'Absolute local file path for multi-device sync (e.g., ~/.claude/projects/.../MEMORY.md)'
         }
       },
       required: ['title', 'content']
@@ -85,6 +104,10 @@ function updateDevDocDefinition() {
           type: 'string',
           enum: ['replace', 'append', 'prepend'],
           description: 'Update mode (default: replace)'
+        },
+        local_path: {
+          type: 'string',
+          description: 'Update the local file path for multi-device sync'
         }
       },
       required: ['content']
@@ -107,6 +130,172 @@ function deleteDevDocDefinition() {
   };
 }
 
+function pullDevDocsDefinition() {
+  return {
+    name: 'pull_dev_docs',
+    description: `Restore all synced files to THIS device. Writes files to their local paths on disk.
+
+USE THIS WHEN:
+- Setting up a new machine (desktop, laptop, WSL)
+- Switching between macOS / Windows / Linux
+- Want to sync latest versions of memory/config files from cloud
+
+WHAT HAPPENS:
+1. Fetches all dev docs with local_path set
+2. Auto-detects platform (macOS/WSL/Linux/Windows) and maps paths accordingly
+3. Creates missing parent directories
+4. Writes content to each mapped local_path on this machine
+
+CROSS-PLATFORM PATH MAPPING (automatic):
+- macOS ~/... ↔ WSL ~/... ↔ Linux ~/...
+- Claude project keys mapped per platform (e.g., -Users-seunghan ↔ -mnt-c-Users-Owner)
+
+Run once after installing ainote MCP on a new device to restore everything.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: {
+          type: 'string',
+          description: 'Subcategory filter. Omit to pull all docs with local_path.'
+        }
+      }
+    }
+  };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Claude environment sync tools (Phase A: server-untouched wrappers)
+// ─────────────────────────────────────────────────────────────
+
+function discoverClaudeSyncTargetsDefinition() {
+  return {
+    name: 'discover_claude_sync_targets',
+    description: `Preview what would be synced from ~/.claude/ to ainote cloud.
+
+Read-only. Shows file counts, sizes, and sample names for:
+- skills/      (directory bundles like ui-ux-pro-max/)
+- agents/      (single .md files)
+- commands/    (slash command definitions)
+- hooks/       (event handler scripts)
+- mcp_servers  (mcpServers section of ~/.claude.json)
+
+Run this BEFORE push_claude_* tools to see scope.`,
+    inputSchema: { type: 'object', properties: {} }
+  };
+}
+
+function pushClaudeFilesDefinition(name, description) {
+  return {
+    name,
+    description,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dry_run: {
+          type: 'boolean',
+          description: 'Preview without uploading. Default: false'
+        },
+        max_files: {
+          type: 'number',
+          description: `Max files to push (safety cap). Default: 500`
+        }
+      }
+    }
+  };
+}
+
+function pushClaudeMcpServersDefinition() {
+  return {
+    name: 'push_claude_mcp_servers',
+    description: `Snapshot ~/.claude.json mcpServers section to ainote cloud (mcp category).
+
+Stores as a single JSON dev_doc titled "mcp-servers-snapshot.json".
+Includes API keys/env vars currently — Phase B will add encryption.
+
+⚠️ Until encryption lands, only run when comfortable storing keys server-side
+(server is private to your account, but keys are not zero-knowledge yet).`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dry_run: { type: 'boolean', description: 'Preview only. Default: false' }
+      }
+    }
+  };
+}
+
+function pullClaudeMcpServersDefinition() {
+  return {
+    name: 'pull_claude_mcp_servers',
+    description: `Restore mcpServers snapshot from ainote cloud to a SIDECAR file.
+
+Writes to ~/.claude/mcp-servers.d/from-ainote.json (NOT ~/.claude.json directly).
+This avoids corrupting the live-written ~/.claude.json while Claude is running.
+
+After pull, to actually activate the servers you must either:
+  (a) merge manually: jq -s '.[0] * .[1]' ~/.claude.json ~/.claude/mcp-servers.d/from-ainote.json > new.json
+  (b) close Claude, then run a future merge tool (Phase B)
+
+Sidecar approach = safe always, manual merge step required.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sidecar_name: {
+          type: 'string',
+          description: 'Sidecar filename stem. Default: from-ainote'
+        }
+      }
+    }
+  };
+}
+
+async function pushClaudeFilesHandler(subdir, args, { apiClient }) {
+  const dryRun = args.dry_run === true;
+  const maxFiles = typeof args.max_files === 'number' ? args.max_files : 500;
+  const files = scanClaudeSubdir(subdir, { maxFiles });
+
+  if (files.length === 0) {
+    return [{ type: 'text', text: `No text files found under ~/.claude/${subdir}/` }];
+  }
+
+  if (dryRun) {
+    const list = files.slice(0, 20).map(f => `  ${f.title} (${f.size}b)`).join('\n');
+    const more = files.length > 20 ? `\n  ... and ${files.length - 20} more` : '';
+    return [{ type: 'text', text: `Would push ${files.length} files from ~/.claude/${subdir}/:\n${list}${more}` }];
+  }
+
+  const pushed = [];
+  const errors = [];
+  for (const f of files) {
+    try {
+      const created = await apiClient.callTool('create_dev_doc', {
+        title: f.title,
+        content: f.content,
+        category: subdir,
+        content_type: f.content_type,
+        local_path: f.local_path
+      });
+      // Server may return error inside content — surface it
+      const isErr = Array.isArray(created?.content) && created.content.some(c => c.type === 'text' && /error/i.test(c.text || ''));
+      if (isErr) {
+        errors.push(`⚠️ ${f.title}: ${created.content.map(c => c.text).join(' ').slice(0, 200)}`);
+      } else {
+        pushed.push(`✅ ${f.title}`);
+      }
+    } catch (e) {
+      errors.push(`❌ ${f.title}: ${e.message}`);
+    }
+  }
+
+  const summary = [
+    `Pushed ${pushed.length}/${files.length} files from ~/.claude/${subdir}/ → ainote (category: ${subdir})`,
+    pushed.length ? `\n${pushed.slice(0, 30).join('\n')}` : null,
+    pushed.length > 30 ? `... and ${pushed.length - 30} more` : null,
+    errors.length ? `\nErrors:\n${errors.join('\n')}` : null
+  ].filter(Boolean).join('\n');
+
+  return [{ type: 'text', text: summary }];
+}
+
 function listDevCategoriesDefinition() {
   return {
     name: 'list_dev_categories',
@@ -137,6 +326,10 @@ export function getDevDocTools() {
     {
       definition: createDevDocDefinition(),
       handler: async (args, { apiClient }) => {
+        // Canonicalize local_path (replace $HOME with ~) for portability
+        if (args.local_path) {
+          args.local_path = canonicalizePath(args.local_path);
+        }
         const result = await apiClient.callTool('create_dev_doc', args);
         return result;
       }
@@ -144,6 +337,9 @@ export function getDevDocTools() {
     {
       definition: updateDevDocDefinition(),
       handler: async (args, { apiClient }) => {
+        if (args.local_path) {
+          args.local_path = canonicalizePath(args.local_path);
+        }
         const result = await apiClient.callTool('update_dev_doc', args);
         return result;
       }
@@ -155,12 +351,293 @@ export function getDevDocTools() {
         return result;
       }
     },
+    {
+      definition: pullDevDocsDefinition(),
+      handler: async (args, { apiClient }) => {
+        const result = await apiClient.callTool('pull_dev_docs', args);
+
+        // Extract docs from resource data and write to local paths
+        let written = [];
+        let skipped = [];
+        let errors = [];
+
+        const platformInfo = getPlatformInfo();
+
+        try {
+          const resourceText = result?.content?.find(c => c.type === 'resource')?.resource?.text;
+          if (resourceText) {
+            const data = JSON.parse(resourceText);
+            for (const doc of data.docs || []) {
+              if (!doc.local_path || !doc.content) {
+                skipped.push(doc.title);
+                continue;
+              }
+              // Map stored path to current platform (macOS↔WSL↔Linux)
+              const mappedPath = mapPathForCurrentPlatform(doc.local_path);
+              try {
+                const dir = path.dirname(mappedPath);
+                fs.mkdirSync(dir, { recursive: true });
+                fs.writeFileSync(mappedPath, doc.content, 'utf8');
+                const pathChanged = mappedPath !== doc.local_path.replace(/^~/, process.env.HOME || '');
+                const arrow = pathChanged ? ` (mapped from ${doc.local_path})` : '';
+                written.push(`✅ ${doc.title} → ${mappedPath}${arrow}`);
+              } catch (e) {
+                errors.push(`❌ ${doc.title}: ${e.message}`);
+              }
+            }
+          }
+        } catch (e) {
+          errors.push(`Parse error: ${e.message}`);
+        }
+
+        const summary = [
+          `🖥️ Platform: ${platformInfo.platform} | Home: ${platformInfo.home} | Project key: ${platformInfo.homeProjectKey}`,
+          written.length ? `\nWritten (${written.length}):\n${written.join('\n')}` : null,
+          skipped.length ? `Skipped (no local_path): ${skipped.join(', ')}` : null,
+          errors.length ? `Errors:\n${errors.join('\n')}` : null,
+        ].filter(Boolean).join('\n\n');
+
+        return [{ type: 'text', text: summary || 'No docs with local_path found.' }];
+      }
+    },
     {
       definition: listDevCategoriesDefinition(),
       handler: async (_args, { apiClient }) => {
         const result = await apiClient.callTool('list_dev_categories', {});
         return result;
       }
+    },
+    {
+      definition: discoverClaudeSyncTargetsDefinition(),
+      handler: async () => {
+        const info = discoverSyncTargets();
+        const lines = [`🔍 Claude dir: ${info.claude_dir}\n`];
+        for (const [name, t] of Object.entries(info.targets)) {
+          if (t.error) {
+            lines.push(`  ${name.padEnd(14)} ⚠️  ${t.error}`);
+            continue;
+          }
+          const samples = t.samples?.length ? ` — ${t.samples.join(', ')}${t.samples.length < t.file_count ? ', ...' : ''}` : '';
+          lines.push(`  ${name.padEnd(14)} ${String(t.file_count).padStart(4)} items, ${t.total_bytes}b${samples}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+      }
+    },
+    {
+      definition: pushClaudeFilesDefinition(
+        'push_claude_skills',
+        `Push ~/.claude/skills/ tree (each file as a dev_doc, category=skills).
+
+Walks subdirectories. Each SKILL.md, reference, asset is uploaded separately
+with local_path set so pull_dev_docs can restore on another machine.`
+      ),
+      handler: (args, ctx) => pushClaudeFilesHandler('skills', args, ctx)
+    },
+    {
+      definition: pushClaudeFilesDefinition(
+        'push_claude_agents',
+        `Push ~/.claude/agents/ files (category=agents). Subagent definitions.`
+      ),
+      handler: (args, ctx) => pushClaudeFilesHandler('agents', args, ctx)
+    },
+    {
+      definition: pushClaudeFilesDefinition(
+        'push_claude_commands',
+        `Push ~/.claude/commands/ tree (category=commands). Slash command definitions.`
+      ),
+      handler: (args, ctx) => pushClaudeFilesHandler('commands', args, ctx)
+    },
+    {
+      definition: pushClaudeFilesDefinition(
+        'push_claude_hooks',
+        `Push ~/.claude/hooks/ tree (category=hooks). Event handler scripts.`
+      ),
+      handler: (args, ctx) => pushClaudeFilesHandler('hooks', args, ctx)
+    },
+    {
+      definition: pushClaudeMcpServersDefinition(),
+      handler: async (args, { apiClient }) => {
+        const dryRun = args.dry_run === true;
+        const { servers, source, exists } = readMcpServers();
+        if (!exists) {
+          return [{ type: 'text', text: `No ~/.claude.json found.` }];
+        }
+        const names = Object.keys(servers);
+        if (dryRun) {
+          return [{ type: 'text', text: `Would push mcpServers snapshot from ${source}\nServers (${names.length}): ${names.join(', ')}\n(would be encrypted: mcp category auto-encrypts)` }];
+        }
+        const plaintext = JSON.stringify({ mcpServers: servers }, null, 2);
+
+        // mcp 카테고리 자동 암호화
+        const recipients = await getAgeRecipients();
+        if (recipients.length === 0) {
+          return [{ type: 'text', text: `❌ No age recipients configured. Run sync_init_encryption (first machine) or sync_add_recipient (additional machines) before pushing secrets.` }];
+        }
+        const ciphertext = await encryptText(plaintext, { recipients });
+
+        const result = await apiClient.callTool('create_dev_doc', {
+          title: 'mcp-servers-snapshot.json',
+          content: ciphertext,
+          category: 'mcp',
+          content_type: 'text',
+          encrypted: true,
+          encryption_meta: { scheme: 'age-armored', recipient_count: recipients.length },
+          local_path: canonicalizePath(path.join(os.homedir(), '.claude/mcp-servers.d/from-ainote.json'))
+        });
+        return [{ type: 'text', text: `📤🔒 Pushed encrypted mcpServers snapshot (${names.length} servers, ${recipients.length} recipients): ${names.join(', ')}` }, ...(result?.content || [])];
+      }
+    },
+    {
+      definition: pullClaudeMcpServersDefinition(),
+      handler: async (args, { apiClient }) => {
+        const sidecarName = args.sidecar_name || 'from-ainote';
+        const result = await apiClient.callTool('get_dev_doc', {
+          title: 'mcp-servers-snapshot.json',
+          category: 'mcp'
+        });
+        const resourceText = result?.content?.find(c => c.type === 'resource')?.resource?.text;
+        let content;
+        let isEncrypted = false;
+        if (resourceText) {
+          try {
+            const parsedRes = JSON.parse(resourceText);
+            content = parsedRes.content || parsedRes.doc?.content;
+            isEncrypted = parsedRes.encrypted === true || parsedRes.doc?.encrypted === true;
+          } catch {}
+        }
+        if (!content) {
+          const textBlock = result?.content?.find(c => c.type === 'text')?.text;
+          content = textBlock;
+        }
+        if (!content) {
+          return [{ type: 'text', text: `❌ No mcp-servers-snapshot.json found in cloud (category: mcp). Run push_claude_mcp_servers first.` }];
+        }
+        // Auto-detect encryption if server didn't flag it (e.g. older docs)
+        if (!isEncrypted && /-----BEGIN AGE ENCRYPTED FILE-----/.test(content)) {
+          isEncrypted = true;
+        }
+        if (isEncrypted) {
+          try {
+            content = await decryptText(content);
+          } catch (e) {
+            return [{ type: 'text', text: `❌ Decryption failed: ${e.message}\nHint: ensure this machine's age identity is approved (sync_add_recipient on the original machine after re-push).` }];
+          }
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(content);
+        } catch (e) {
+          return [{ type: 'text', text: `❌ Snapshot is not valid JSON after decrypt: ${e.message}` }];
+        }
+        const servers = parsed.mcpServers || parsed;
+        const target = writeMcpServersSidecar(servers, { name: sidecarName });
+        const names = Object.keys(servers);
+        return [{
+          type: 'text',
+          text: [
+            `📥 Wrote sidecar: ${target}`,
+            `Servers (${names.length}): ${names.join(', ')}`,
+            '',
+            '⚠️  This does NOT activate the servers automatically.',
+            'To merge into ~/.claude.json (after closing Claude):',
+            `  jq -s '.[0] * .[1]' ~/.claude.json ${target} > ~/.claude.json.new && mv ~/.claude.json.new ~/.claude.json`
+          ].join('\n')
+        }];
+      }
+    },
+    {
+      definition: {
+        name: 'sync_init_encryption',
+        description: `Initialize age encryption on THIS machine (first-time setup).
+
+Generates an age keypair, stores the secret key in OS keychain (or ~/.config/ainote/ fallback),
+and sets this machine as the sole recipient. Run once per machine.
+
+After running on the FIRST machine, share its public key (recipient) with subsequent machines
+via sync_add_recipient so they can decrypt shared secrets.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            force: { type: 'boolean', description: 'Regenerate even if identity already exists. WARNING: invalidates existing ciphertexts unless old recipients retained.' }
+          }
+        }
+      },
+      handler: async (args) => {
+        const existing = await getAgeIdentity();
+        if (existing && !args.force) {
+          const recps = await getAgeRecipients();
+          return [{ type: 'text', text: `✅ Already initialized.\nBackend: ${storageBackend()}\nRecipients: ${recps.length}\nPass force=true to regenerate.` }];
+        }
+        const { identity, recipient } = generateKeypair();
+        await setAgeIdentity(identity);
+        await addRecipient(recipient);
+        return [{
+          type: 'text',
+          text: [
+            `🔐 Encryption initialized`,
+            `Backend: ${storageBackend()}`,
+            `Your public key (share with other machines via sync_add_recipient):`,
+            `  ${recipient}`,
+            ``,
+            `Next: on each other machine, run sync_init_encryption then back here run`,
+            `  sync_add_recipient <their_public_key>`,
+            `then re-push secrets so they're encrypted to all approved machines.`
+          ].join('\n')
+        }];
+      }
+    },
+    {
+      definition: {
+        name: 'sync_add_recipient',
+        description: `Add an age recipient (public key) to the encryption set for this machine.
+
+Future encryptions on this machine will include this recipient.
+Already-encrypted ciphertexts on the server are NOT re-encrypted retroactively —
+call push_claude_mcp_servers again to re-encrypt with the updated recipient list.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            recipient: { type: 'string', description: 'age public key (starts with age1...)' }
+          },
+          required: ['recipient']
+        }
+      },
+      handler: async (args) => {
+        const recipient = (args.recipient || '').trim();
+        if (!/^age1[a-z0-9]+$/i.test(recipient)) {
+          return [{ type: 'text', text: `❌ Invalid age recipient format. Expected: age1...` }];
+        }
+        const updated = await addRecipient(recipient);
+        return [{ type: 'text', text: `✅ Recipient added.\nTotal recipients: ${updated.length}\n${updated.map(r => '  ' + r).join('\n')}` }];
+      }
+    },
+    {
+      definition: {
+        name: 'sync_encryption_status',
+        description: 'Show encryption setup status (backend, identity present, recipients, age binary).',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      handler: async () => {
+        const identity = await getAgeIdentity();
+        const recipients = await getAgeRecipients();
+        let ageVer = 'not found';
+        try {
+          const { spawnSync } = await import('child_process');
+          const r = spawnSync('age', ['--version'], { encoding: 'utf8' });
+          if (r.status === 0) ageVer = (r.stdout || '').trim();
+        } catch {}
+        return [{
+          type: 'text',
+          text: [
+            `🔐 Encryption status`,
+            `  age binary:   ${ageVer}`,
+            `  backend:      ${storageBackend()}`,
+            `  identity:     ${identity ? 'present' : 'MISSING — run sync_init_encryption'}`,
+            `  recipients:   ${recipients.length}`,
+            ...recipients.map(r => `    - ${r}`)
+          ].join('\n')
+        }];
+      }
     }
   ];
 }

package/lib/tools/internal/claude-scanner.js

@@ -0,0 +1,150 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { canonicalizePath } from './path-mapper.js';
+
+const HOME = os.homedir();
+const CLAUDE_DIR = path.join(HOME, '.claude');
+
+const TEXT_EXTENSIONS = new Set([
+  '.md', '.txt', '.json', '.yaml', '.yml', '.toml',
+  '.js', '.ts', '.sh', '.py', '.rb', '.css', '.html'
+]);
+
+function isTextFile(p) {
+  return TEXT_EXTENSIONS.has(path.extname(p).toLowerCase());
+}
+
+function walkDir(root, maxFiles = 500) {
+  const out = [];
+  if (!fs.existsSync(root)) return out;
+
+  function visit(dir) {
+    if (out.length >= maxFiles) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        visit(full);
+      } else if (e.isFile() && isTextFile(e.name)) {
+        out.push(full);
+      }
+      if (out.length >= maxFiles) return;
+    }
+  }
+  visit(root);
+  return out;
+}
+
+function detectContentType(p) {
+  const ext = path.extname(p).toLowerCase();
+  if (ext === '.json') return 'json';
+  if (ext === '.yaml' || ext === '.yml') return 'yaml';
+  if (ext === '.md') return 'markdown';
+  return 'text';
+}
+
+/**
+ * Scan a Claude subdirectory (skills/agents/commands/hooks) and return file
+ * descriptors ready for create_dev_doc calls.
+ *
+ * Returns: [{ title, content, content_type, local_path, relative_path }]
+ *   - title:        unique per-file (e.g., "skills/ui-ux-pro-max/SKILL.md")
+ *   - local_path:   canonicalized (~/...) so pull works cross-platform
+ *   - relative_path: path relative to ~/.claude/<subdir>/
+ */
+export function scanClaudeSubdir(subdir, { maxFiles = 500 } = {}) {
+  const root = path.join(CLAUDE_DIR, subdir);
+  const files = walkDir(root, maxFiles);
+  const results = [];
+  for (const abs of files) {
+    let content;
+    try {
+      content = fs.readFileSync(abs, 'utf8');
+    } catch {
+      continue;
+    }
+    const relativeFromClaude = path.relative(CLAUDE_DIR, abs);
+    const relativeFromSubdir = path.relative(root, abs);
+    results.push({
+      title: relativeFromClaude.replace(/\\/g, '/'),
+      content,
+      content_type: detectContentType(abs),
+      local_path: canonicalizePath(abs),
+      relative_path: relativeFromSubdir.replace(/\\/g, '/'),
+      size: content.length
+    });
+  }
+  return results;
+}
+
+/**
+ * Read mcpServers section from ~/.claude.json.
+ * Returns the object (possibly empty) and the canonicalized source path.
+ */
+export function readMcpServers() {
+  const claudeJson = path.join(HOME, '.claude.json');
+  if (!fs.existsSync(claudeJson)) {
+    return { servers: {}, source: canonicalizePath(claudeJson), exists: false };
+  }
+  try {
+    const raw = fs.readFileSync(claudeJson, 'utf8');
+    const json = JSON.parse(raw);
+    return {
+      servers: json.mcpServers || {},
+      source: canonicalizePath(claudeJson),
+      exists: true
+    };
+  } catch (e) {
+    throw new Error(`Failed to parse ~/.claude.json: ${e.message}`);
+  }
+}
+
+/**
+ * Sidecar pattern: write mcpServers snapshot to ~/.claude/mcp-servers.d/<name>.json
+ * Never touches ~/.claude.json directly (avoids live-write corruption).
+ */
+export function writeMcpServersSidecar(servers, { name = 'from-ainote' } = {}) {
+  const sidecarDir = path.join(CLAUDE_DIR, 'mcp-servers.d');
+  fs.mkdirSync(sidecarDir, { recursive: true });
+  const target = path.join(sidecarDir, `${name}.json`);
+  const tmp = `${target}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify({ mcpServers: servers }, null, 2));
+  fs.renameSync(tmp, target);
+  return canonicalizePath(target);
+}
+
+/**
+ * Preview what would be synced. Read-only, fast.
+ */
+export function discoverSyncTargets() {
+  const result = {
+    claude_dir: canonicalizePath(CLAUDE_DIR),
+    targets: {}
+  };
+  for (const sub of ['skills', 'agents', 'commands', 'hooks']) {
+    const files = scanClaudeSubdir(sub);
+    result.targets[sub] = {
+      file_count: files.length,
+      total_bytes: files.reduce((a, b) => a + b.size, 0),
+      samples: files.slice(0, 3).map(f => f.title)
+    };
+  }
+  try {
+    const mcp = readMcpServers();
+    result.targets.mcp_servers = {
+      file_count: Object.keys(mcp.servers).length,
+      total_bytes: JSON.stringify(mcp.servers).length,
+      samples: Object.keys(mcp.servers).slice(0, 5)
+    };
+  } catch (e) {
+    result.targets.mcp_servers = { error: e.message };
+  }
+  return result;
+}