cortex-sync 0.1.0 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@
 Claude Code stores your session history in `~/.claude/projects/` using absolute paths. Switch from your Mac to a Linux server and those sessions are gone — the paths don't match. `cortex` fixes that.
 
 ```bash
-npm install -g cortex-cli
+npm install -g cortex-sync
 ```
 
 ---
@@ -31,7 +31,7 @@ Machine A (Mac)                        Machine B (Linux)
 
 ```bash
 # 1. Install
-npm install -g cortex-cli
+npm install -g cortex-sync
 
 # 2. Configure on Machine A
 cortex init
@@ -59,6 +59,43 @@ Open any project on Machine B — Claude Code shows your full session history.
 | `cortex pull` | Download, decrypt, remap paths |
 | `cortex status` | Show what's out of sync (no download) |
 | `cortex convert <file> --to <target>` | Convert a Claude Code skill |
+| `cortex setup-mcp` | Register cortex as a Claude Code MCP server |
+
+---
+
+## Claude Code MCP integration
+
+Use `sync`, `pull`, `status`, `convert`, and `init` directly from the Claude Code chat — one command does everything:
+
+```bash
+npm install -g cortex-sync
+cortex init       # configure storage and passphrase
+cortex setup-mcp  # registers cortex in Claude Code automatically
+```
+
+That's it. Restart Claude Code and you're done.
+
+### What setup-mcp does
+
+`cortex setup-mcp` detects the binary path, prompts for your passphrase once, and runs `claude mcp add` with the correct arguments — no manual PATH configuration needed.
+
+### Available MCP tools
+
+| Tool | What it does |
+|---|---|
+| `sync` | Encrypt and upload `~/.claude/` |
+| `pull` | Download, decrypt, remap paths |
+| `status` | Show what's out of sync |
+| `convert` | Convert a skill to Antigravity or Cursor |
+| `init` | Configure storage (non-interactive) |
+
+### Environment variables (advanced / manual setup)
+
+| Variable | Required for |
+|---|---|
+| `CORTEX_PASSPHRASE` | `sync`, `pull`, `status` |
+| `ANTHROPIC_API_KEY` | `convert` |
+| `CORTEX_GITHUB_TOKEN` | `init` with GitHub storage |
 
 ---
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { createRequire } from "module";
 import { Command } from "commander";
 
 // src/commands/convert.ts
@@ -58,8 +59,8 @@ function decrypt(blob, derived) {
   if (!blob.subarray(0, MAGIC.length).equals(MAGIC)) {
     throw new Error("cortex blob has bad magic bytes");
   }
-  const version = blob[MAGIC.length];
-  if (version !== VERSION) throw new Error(`cortex blob version ${version} not supported`);
+  const version2 = blob[MAGIC.length];
+  if (version2 !== VERSION) throw new Error(`cortex blob version ${version2} not supported`);
   const ivStart = MAGIC.length + 1;
   const iv = blob.subarray(ivStart, ivStart + IV_LEN);
   const tag = blob.subarray(ivStart + IV_LEN, ivStart + IV_LEN + TAG_LEN);
@@ -85,7 +86,7 @@ async function readPassphrase() {
 
 // src/lib/api-key.ts
 var API_KEY_PATH = join2(CORTEX_DIR, "api-key.enc");
-async function loadApiKey() {
+async function loadApiKey(opts = {}) {
   if (process.env.ANTHROPIC_API_KEY) return process.env.ANTHROPIC_API_KEY;
   if (existsSync(API_KEY_PATH)) {
     const config = await loadConfig();
@@ -94,6 +95,11 @@ async function loadApiKey() {
     const enc = await readFile2(API_KEY_PATH);
     return decrypt(enc, derived).toString("utf-8").trim();
   }
+  if (opts.nonInteractive) {
+    throw new Error(
+      'ANTHROPIC_API_KEY environment variable is not set and no encrypted key found.\nSet it with: export ANTHROPIC_API_KEY="sk-ant-..."'
+    );
+  }
   const key = await password2({
     message: "Anthropic API key (sk-ant-...):",
     mask: "*",
@@ -257,10 +263,10 @@ async function convertCommand(skillPath, opts) {
   const skill = parseSkillMeta(source, fallbackName);
   console.log(`Converting "${skill.name}" \u2192 ${opts.to}
 `);
-  const apiKey = await loadApiKey();
+  const apiKey = opts.apiKey ?? await loadApiKey();
   const targets = opts.to === "all" ? ["antigravity", "cursor"] : [opts.to];
   for (const target of targets) {
-    process.stdout.write(`  ${target}\u2026 `);
+    console.log(`  ${target}\u2026`);
     let outPath;
     if (target === "antigravity") {
       outPath = await convertToAntigravity(skill, apiKey, outputDir);
@@ -465,7 +471,7 @@ async function initCommand() {
       mask: "*",
       validate: (v) => v.trim().startsWith("gh") || "Token should start with gh"
     });
-    process.stdout.write("Validating token\u2026 ");
+    console.log("Validating token\u2026");
     githubOwner = await fetchGitHubUser(githubToken.trim());
     console.log(`\u2713 Authenticated as ${githubOwner}`);
     githubRepo = await input({
@@ -473,7 +479,7 @@ async function initCommand() {
       default: "cortex-backup",
       validate: (v) => /^[a-zA-Z0-9_.-]+$/.test(v.trim()) || "Invalid repo name"
     });
-    process.stdout.write(`Creating private repo ${githubOwner}/${githubRepo}\u2026 `);
+    console.log(`Creating private repo ${githubOwner}/${githubRepo}\u2026`);
     await ensureGitHubRepo(githubToken.trim(), githubRepo.trim());
     console.log("\u2713 Ready");
     githubToken = githubToken.trim();
@@ -516,6 +522,50 @@ Detected tools: ${detected.length ? detected.join(", ") : "none"}`);
     console.log('Next step: Google Drive backend is not yet implemented \u2014 use --target <path> with "cortex sync" for now.');
   }
 }
+async function initNonInteractive(opts) {
+  if (!opts.email) throw new Error("email is required");
+  if (!opts.storage) throw new Error('storage is required: "github" or "local"');
+  if (opts.storage === "local" && !opts.target) {
+    throw new Error('target path is required when storage is "local"');
+  }
+  let githubToken;
+  let githubOwner;
+  let githubRepo;
+  if (opts.storage === "github") {
+    githubToken = process.env.CORTEX_GITHUB_TOKEN;
+    if (!githubToken) {
+      throw new Error(
+        'CORTEX_GITHUB_TOKEN environment variable is not set.\nCreate a PAT at: https://github.com/settings/tokens/new?scopes=repo\nThen set: export CORTEX_GITHUB_TOKEN="ghp_..."'
+      );
+    }
+    githubOwner = await fetchGitHubUser(githubToken);
+    console.log(`\u2713 Authenticated as ${githubOwner}`);
+    githubRepo = opts.githubRepo ?? "cortex-backup";
+    await ensureGitHubRepo(githubToken, githubRepo);
+    console.log(`\u2713 Repo ${githubOwner}/${githubRepo} ready`);
+  }
+  const detected = await detectInstalledTools();
+  await mkdir3(CORTEX_DIR2, { recursive: true });
+  const config = {
+    version: 1,
+    storage: opts.storage,
+    email: opts.email,
+    target: opts.target,
+    githubToken,
+    githubOwner,
+    githubRepo,
+    tools: detected,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeFile4(CONFIG_PATH2, JSON.stringify(config, null, 2), { mode: 384 });
+  await chmod2(CONFIG_PATH2, 384);
+  console.log(`\u2713 Configuration saved to ${CONFIG_PATH2}`);
+}
+
+// src/commands/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
 
 // src/commands/pull.ts
 import { input as input2 } from "@inquirer/prompts";
@@ -800,11 +850,14 @@ function extractCwdFromJsonl(input3) {
 }
 
 // src/commands/pull.ts
-async function resolveLocalPath(projectId, originalPath, mappings) {
+async function resolveLocalPath(projectId, originalPath, mappings, projectMappings, nonInteractive) {
   const key = projectId ?? originalPath;
+  if (projectMappings?.[key]) return projectMappings[key];
+  if (projectId && projectMappings?.[originalPath]) return projectMappings[originalPath];
   if (mappings[key]) return mappings[key];
   if (projectId && mappings[originalPath]) return mappings[originalPath];
   if (existsSync5(originalPath)) return originalPath;
+  if (nonInteractive) return null;
   console.log(`
 Project not found on this machine:`);
   console.log(`  Original path: ${originalPath}`);
@@ -836,6 +889,7 @@ async function pullCommand(opts = {}) {
   );
   const mappings = await loadMappings();
   const dirRemap = /* @__PURE__ */ new Map();
+  const pendingMappings = [];
   if (remote.projects) {
     let mappingsDirty = false;
     for (const [encodedDir, meta] of Object.entries(remote.projects)) {
@@ -844,8 +898,21 @@ async function pullCommand(opts = {}) {
         dirRemap.set(encodedDir, null);
         continue;
       }
-      const localPath = await resolveLocalPath(meta.projectId, meta.originalPath, mappings);
+      const localPath = await resolveLocalPath(
+        meta.projectId,
+        meta.originalPath,
+        mappings,
+        opts.projectMappings,
+        opts.nonInteractive
+      );
       if (localPath === null) {
+        if (opts.nonInteractive) {
+          pendingMappings.push({
+            encodedDir,
+            projectId: meta.projectId,
+            originalPath: meta.originalPath
+          });
+        }
         dirRemap.set(encodedDir, null);
         continue;
       }
@@ -893,6 +960,10 @@ async function pullCommand(opts = {}) {
   await saveManifest(MANIFEST_PATH, remote);
   console.log(`
 \u2713 Pull complete \u2014 ${toPull.length} files restored.`);
+  return {
+    filesRestored: toPull.length,
+    pendingMappings: pendingMappings.length > 0 ? pendingMappings : void 0
+  };
 }
 
 // src/commands/status.ts
@@ -1072,12 +1143,211 @@ async function syncCommand(opts = {}) {
   );
 }
 
+// src/commands/mcp.ts
+var logToStderr = (...args) => process.stderr.write(args.map(String).join(" ") + "\n");
+console.log = logToStderr;
+function requirePassphrase() {
+  if (!process.env.CORTEX_PASSPHRASE) {
+    throw new Error(
+      'CORTEX_PASSPHRASE environment variable is not set.\nRun "cortex init" from your terminal first, then set:\n  export CORTEX_PASSPHRASE="your-passphrase"'
+    );
+  }
+}
+async function captureOutput(fn) {
+  const lines = [];
+  const prev = console.log;
+  console.log = (...args) => lines.push(args.map(String).join(" "));
+  try {
+    const result = await fn();
+    console.log = prev;
+    return { result, output: lines.join("\n") };
+  } catch (e) {
+    console.log = prev;
+    throw e;
+  }
+}
+function ok(text) {
+  return { content: [{ type: "text", text }] };
+}
+function toolErr(e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  return { content: [{ type: "text", text: msg }], isError: true };
+}
+async function mcpCommand() {
+  const server = new McpServer({ name: "cortex", version: "0.1.0" });
+  server.registerTool(
+    "sync",
+    {
+      description: "Encrypt ~/.claude/ and upload to configured storage. Requires CORTEX_PASSPHRASE env var.",
+      inputSchema: z.object({
+        skipSecretsCheck: z.boolean().optional().describe("Skip the API key detection warning before encrypting"),
+        target: z.string().optional().describe("Override storage to a local folder path")
+      })
+    },
+    async ({ skipSecretsCheck, target }) => {
+      try {
+        requirePassphrase();
+        const { output } = await captureOutput(() => syncCommand({ skipSecretsCheck, target }));
+        return ok(output);
+      } catch (e) {
+        return toolErr(e);
+      }
+    }
+  );
+  server.registerTool(
+    "pull",
+    {
+      description: "Download from storage, decrypt, and remap paths into ~/.claude/. If pendingMappings is returned, call pull again with projectMappings populated.",
+      inputSchema: z.object({
+        target: z.string().optional().describe("Override storage to a local folder path"),
+        projectMappings: z.record(z.string(), z.string()).optional().describe("Map of projectId or originalPath to local path on this machine")
+      })
+    },
+    async ({ target, projectMappings }) => {
+      try {
+        requirePassphrase();
+        const result = await pullCommand({ target, projectMappings, nonInteractive: true });
+        if (result.pendingMappings?.length) {
+          const lines = result.pendingMappings.map(
+            (p) => `  "${p.originalPath}" (projectId: ${p.projectId ?? "none"})`
+          );
+          return ok(
+            `Restored ${result.filesRestored} files.
+
+These projects need a local path mapping.
+Call pull again with projectMappings, e.g.:
+  { "${result.pendingMappings[0].projectId ?? result.pendingMappings[0].originalPath}": "/your/local/path" }
+
+Pending projects:
+${lines.join("\n")}`
+          );
+        }
+        return ok(`Pull complete. ${result.filesRestored} files restored.`);
+      } catch (e) {
+        return toolErr(e);
+      }
+    }
+  );
+  server.registerTool(
+    "status",
+    {
+      description: "Show what is out of sync between local ~/.claude/ files and storage.",
+      inputSchema: z.object({
+        target: z.string().optional().describe("Override storage to a local folder path")
+      })
+    },
+    async ({ target }) => {
+      try {
+        requirePassphrase();
+        const { output } = await captureOutput(() => statusCommand({ target }));
+        return ok(output);
+      } catch (e) {
+        return toolErr(e);
+      }
+    }
+  );
+  server.registerTool(
+    "convert",
+    {
+      description: "Convert a Claude Code skill to Antigravity or Cursor format using the Anthropic API. Requires ANTHROPIC_API_KEY env var (or ~/.cortex/api-key.enc).",
+      inputSchema: z.object({
+        skillPath: z.string().describe("Absolute path to the Claude Code skill .md file"),
+        to: z.enum(["antigravity", "cursor", "all"]).describe("Target format"),
+        outputDir: z.string().optional().describe("Project root where output files are written (default: cwd)")
+      })
+    },
+    async ({ skillPath, to, outputDir }) => {
+      try {
+        let apiKey;
+        try {
+          apiKey = await loadApiKey({ nonInteractive: true });
+        } catch (e) {
+          return toolErr(e);
+        }
+        const { output } = await captureOutput(
+          () => convertCommand(skillPath, { to, outputDir, apiKey })
+        );
+        return ok(output);
+      } catch (e) {
+        return toolErr(e);
+      }
+    }
+  );
+  server.registerTool(
+    "init",
+    {
+      description: "Configure cortex storage. For GitHub, requires CORTEX_GITHUB_TOKEN env var.",
+      inputSchema: z.object({
+        email: z.string().describe("Email used as salt for key derivation"),
+        storage: z.enum(["github", "local"]).describe("Storage backend"),
+        githubRepo: z.string().optional().describe("GitHub repo name for backup (default: cortex-backup)"),
+        target: z.string().optional().describe('Local folder path \u2014 required when storage is "local"')
+      })
+    },
+    async (params) => {
+      try {
+        const { output } = await captureOutput(() => initNonInteractive(params));
+        return ok(output);
+      } catch (e) {
+        return toolErr(e);
+      }
+    }
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("cortex MCP server running on stdio\n");
+  process.on("SIGINT", async () => {
+    await server.close();
+    process.exit(0);
+  });
+}
+
+// src/commands/setup-mcp.ts
+import { password as password4 } from "@inquirer/prompts";
+import { existsSync as existsSync7 } from "fs";
+import { spawnSync } from "child_process";
+import { dirname as dirname6, join as join11 } from "path";
+async function setupMcpCommand() {
+  const cortexBin = join11(dirname6(process.execPath), "cortex");
+  if (!existsSync7(cortexBin)) {
+    throw new Error(
+      `cortex binary not found at ${cortexBin}.
+Make sure cortex-sync is installed globally: npm install -g cortex-sync`
+    );
+  }
+  console.log(`Found cortex at: ${cortexBin}`);
+  const passphrase = await password4({
+    message: "Encryption passphrase (same one used in cortex init):",
+    mask: "*",
+    validate: (v) => v.length >= 12 || "Minimum 12 characters"
+  });
+  const result = spawnSync(
+    "claude",
+    ["mcp", "add", "cortex", "-e", `CORTEX_PASSPHRASE=${passphrase}`, "--", cortexBin, "mcp"],
+    { stdio: "inherit" }
+  );
+  if (result.error) {
+    throw new Error(
+      `Failed to run "claude" CLI: ${result.error.message}
+Make sure Claude Code CLI is installed and "claude" is in your PATH.`
+    );
+  }
+  if (result.status !== 0) {
+    throw new Error('"claude mcp add" failed. Check the output above for details.');
+  }
+  console.log("\n\u2713 cortex MCP server registered in Claude Code.");
+  console.log("Restart Claude Code (or open a new session) to activate it.");
+  console.log("\nTo verify: claude mcp list");
+}
+
 // src/cli.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
 var program = new Command();
-program.name("cortex").description("Sync Claude Code context between machines with path remapping").version("0.0.1");
+program.name("cortex").description("Sync Claude Code context between machines with path remapping").version(version);
 program.command("init").description("Configure Cortex: pick storage, set passphrase, detect tools").action(initCommand);
 program.command("sync").description("Encrypt local files and upload to the configured storage").option("--target <path>", "Override storage to a local folder (overrides config)").option("--skip-secrets-check", "Skip the regex scan for API keys before encrypting").action(syncCommand);
-program.command("pull").description("Download from storage and restore into ~/.claude/").option("--target <path>", "Override storage to a local folder (overrides config)").action(pullCommand);
+program.command("pull").description("Download from storage and restore into ~/.claude/").option("--target <path>", "Override storage to a local folder (overrides config)").action((opts) => void pullCommand(opts));
 program.command("status").description("Show what is out of sync between local files and storage").option("--target <path>", "Override storage to a local folder (overrides config)").action(statusCommand);
 program.command("convert <skill-file>").description("Convert a Claude Code skill to Antigravity or Cursor format").requiredOption("--to <target>", "Target format: antigravity | cursor | all").option("--output-dir <path>", "Project root where output files are written (default: cwd)").action((skillFile, opts) => {
   const validTargets = ["antigravity", "cursor", "all"];
@@ -1087,4 +1357,6 @@ program.command("convert <skill-file>").description("Convert a Claude Code skill
   }
   return convertCommand(skillFile, { to: opts.to, outputDir: opts.outputDir });
 });
+program.command("mcp").description("Start the MCP server (for use with claude mcp add cortex -- cortex mcp)").action(mcpCommand);
+program.command("setup-mcp").description("Register cortex as a Claude Code MCP server automatically").action(setupMcpCommand);
 await program.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cortex-sync",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Sync Claude Code sessions between machines with automatic path remapping and skill conversion",
   "license": "AGPL-3.0",
   "type": "module",
@@ -36,7 +36,9 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.95.2",
     "@inquirer/prompts": "^7.0.0",
-    "commander": "^12.1.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^12.1.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",