codexport 0.3.0 → 0.3.2

package/README.md

@@ -12,6 +12,8 @@
 
 the master serves a content-hashed bundle from its `~/.codex` directory. followers pin the master's fingerprint on join, fetch updates over a Tailscale-reachable HTTP address, and apply updates at Codex `SessionStart` through a short best-effort hook.
 
+MCPs are exported as full definitions, including env needed by supported tools. command-based MCPs are written through a managed launcher, so followers run `npx -y codexport@latest mcp run <name>` and let `codexport` translate master-local paths into repairable package, Python tool, or source-built launchers.
+
 [npm](https://www.npmjs.com/package/codexport) | [github](https://github.com/Microck/codexport)
 
 ## why
@@ -21,6 +23,8 @@ if you keep a carefully tuned Codex setup on one machine and want the same defau
 - keep the master as the canonical Codex configuration source
 - let followers preserve local MCPs, local skills, trust entries, and path overrides
 - sync auth-bearing files through the private Tailscale path instead of a plaintext GitHub commit
+- export every master MCP definition instead of dropping machine-local entries
+- repair known MCP launchers on followers through npm, uvx, released binaries, or source builds
 - refresh followers at Codex session startup without interrupting active sessions
 - use content-hash revisions and pinned master fingerprints instead of blind file copies
 
@@ -113,6 +117,28 @@ present.
 runtime state such as logs, caches, sessions, history, compact handoffs, and
 SQLite databases is excluded.
 
+## MCP export and repair
+
+all master MCP definitions are exported into `~/.codexport/mcp-manifest.json` on followers. generated command MCP entries in `~/.codex/config.toml` point at the managed launcher:
+
+```toml
+[mcp_servers.example]
+command = "npx"
+args = [ "-y", "codexport@latest", "mcp", "run", "example" ]
+```
+
+when Codex starts an MCP, `codexport mcp run` reads the original manifest entry, restores transferred environment values, rewrites master paths to follower paths, and chooses a runnable target:
+
+| source shape | follower action |
+| --- | --- |
+| npm-backed MCPs | run with `npx -y <package>` |
+| Python MCP tools | run with `uvx --from <package> <binary>` and install `uv` when missing |
+| FFF MCP | download the matching upstream release binary when missing |
+| GitQuarry MCP | build `gitquarry-mcp` from its public source when missing and repair `GITQUARRY_CLI_PATH` |
+| URL MCPs | keep the URL config unchanged |
+
+unsupported local binaries are still kept in the manifest and generated config. if a follower cannot repair one, startup fails with the missing tool and repair step instead of silently removing the MCP.
+
 ## local follower state
 
 follower-local state lives under `~/.codexport`:
@@ -150,6 +176,7 @@ the follower's `local.toml` before writing the generated `~/.codex/config.toml`.
 | `codexport follower join` | enroll a follower from a join link or explicit master URL |
 | `codexport sync` | fetch the latest master bundle |
 | `codexport apply` | apply the last staged bundle |
+| `codexport mcp run <name>` | run or repair a synced command MCP from the follower manifest |
 | `codexport hook install` | install the follower-only Codex `SessionStart` hook |
 | `codexport status` | report role, master URL, fingerprint, revision, and reachability |
 

package/dist/index.js

@@ -11,7 +11,7 @@ import { homedir, platform } from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
-const VERSION = "0.3.0";
+const VERSION = "0.3.2";
 const DEFAULT_PORT = 17342;
 const DEFAULT_TIMEOUT_MS = 5_000;
 const CODEXPORT_DIR = ".codexport";
@@ -497,11 +497,52 @@ function portableMcpLauncher(name, command, args, sourceHome, server) {
     if (nodePackage) {
         return { command: "npx", args: ["-y", nodePackage.packageName, ...nodePackage.remainingArgs] };
     }
+    if (name === "qmd" || commandName === "qmd") {
+        const remainingArgs = allStrings(args) ? args : [];
+        return { command: "npx", args: ["-y", "-p", "@tobilu/qmd", "qmd", ...remainingArgs] };
+    }
     const npmPackage = npmPackageForPortableMcp(name, commandName);
     if (npmPackage) {
-        const remainingArgs = allStrings(args) ? args : [];
+        const remainingArgs = packageLauncherArgs(commandName, args);
         return { command: "npx", args: ["-y", npmPackage, ...remainingArgs] };
     }
+    const uvTool = uvToolForPortableMcp(name, commandName);
+    if (uvTool) {
+        const remainingArgs = allStrings(args) ? args : [];
+        return {
+            command: "uvx",
+            args: ["--from", uvTool.packageName, uvTool.binaryName, ...remainingArgs],
+            repair: {
+                whenMissing: "uvx",
+                command: "__codexport_install_uv",
+                args: []
+            }
+        };
+    }
+    if (name === "fff" || commandName === "fff-mcp") {
+        const remainingArgs = allStrings(args) ? args : [];
+        return {
+            command: "fff-mcp",
+            args: remainingArgs,
+            repair: {
+                whenMissing: "fff-mcp",
+                command: "__codexport_install_fff_mcp",
+                args: []
+            }
+        };
+    }
+    if (name === "gitquarry-mcp" || commandName === "gitquarry-mcp") {
+        const remainingArgs = allStrings(args) ? args : [];
+        return {
+            command: "gitquarry-mcp",
+            args: remainingArgs,
+            repair: {
+                whenMissing: "gitquarry-mcp",
+                command: "cargo",
+                args: ["install", "--git", "https://github.com/Microck/gitquarry-mcp.git", "--locked"]
+            }
+        };
+    }
     return undefined;
 }
 function mcpHasRequiredPortableEnv(name, command, server) {
@@ -523,16 +564,43 @@ function ensurePortablePathEnv(server) {
 }
 function npmPackageForPortableMcp(name, commandName) {
     const knownPackages = {
+        "camofox-browser-mcp": "camofox-browser-mcp",
         "dora": "@butttons/dora",
+        "grep-app": "@247arjun/mcp-grep",
         "kagi-mcp": "kagi-mcp",
+        "keywords-everywhere": "mcp-keywords-everywhere",
+        "mcp-grep": "@247arjun/mcp-grep",
+        "mcp-vnc": "@hrrrsn/mcp-vnc",
         "opensrc-mcp": "opensrc-mcp",
         "opensrc-mcp-stdio": "opensrc-mcp",
         "perplexity-webui": "perplexity-webui-mcp",
         "perplexity-webui-mcp": "perplexity-webui-mcp",
-        "reddit-mcp-buddy": "reddit-mcp-buddy"
+        "reddit-mcp-buddy": "reddit-mcp-buddy",
+        "xcodebuildmcp": "xcodebuildmcp"
     };
     return knownPackages[name] ?? knownPackages[commandName];
 }
+function packageLauncherArgs(commandName, args) {
+    if (!allStrings(args))
+        return [];
+    const remainingArgs = args;
+    const [entrypoint, ...afterEntrypoint] = remainingArgs;
+    if ((commandName === "node" || commandName === "bun") && typeof entrypoint === "string") {
+        const normalized = normalizePathForCompare(entrypoint);
+        if (isAbsoluteAnyPlatform(entrypoint) || normalized.endsWith(".js") || normalized.endsWith(".mjs") || normalized.endsWith(".ts")) {
+            return afterEntrypoint;
+        }
+    }
+    return remainingArgs;
+}
+function uvToolForPortableMcp(name, commandName) {
+    const knownTools = {
+        "discord-py-self": { packageName: "discord-py-self-mcp", binaryName: "discord-py-self-mcp" },
+        "discord-py-self-mcp": { packageName: "discord-py-self-mcp", binaryName: "discord-py-self-mcp" },
+        "markitdown-mcp": { packageName: "markitdown-mcp", binaryName: "markitdown-mcp" }
+    };
+    return knownTools[name] ?? knownTools[commandName];
+}
 function rewritePortableCommand(command, sourceRoot) {
     const sourceRelative = rewriteSourceRootPath(command, sourceRoot);
     if (sourceRelative !== command)
@@ -741,12 +809,15 @@ async function commandMcpRun(ctx, name) {
         : [];
     if (!command)
         throw new CliError(`MCP ${name} has no command.`, 1);
+    ensurePortablePathEnv(server);
     const launcher = mcpHasRequiredPortableEnv(name, command, server)
         ? portableMcpLauncher(name, command, args, sourceHome, server)
         : undefined;
     const runCommandName = launcher?.command ?? rewritePortableCommand(command, manifest.sourceRoot);
     const runArgs = launcher?.args ?? args;
     const childEnv = { ...process.env, ...portableServerEnv(server, manifest.sourceRoot, sourceHome, { ...localConfig, codexDir: ctx.codexDir }) };
+    await repairMcpLauncherIfNeeded(launcher, childEnv);
+    await repairGitquarryEnvIfNeeded(name, childEnv);
     await runCommandWithEnv(runCommandName, runArgs, childEnv);
 }
 function portableServerEnv(server, sourceRoot, sourceHome, localConfig) {
@@ -759,6 +830,133 @@ function portableServerEnv(server, sourceRoot, sourceHome, localConfig) {
     }
     return out;
 }
+async function repairMcpLauncherIfNeeded(launcher, env) {
+    if (!launcher?.repair)
+        return;
+    if (await executableExists(launcher.repair.whenMissing, env))
+        return;
+    if (launcher.repair.command === "__codexport_install_fff_mcp") {
+        await installFffMcp(env);
+    }
+    else if (launcher.repair.command === "__codexport_install_uv") {
+        await installUv(env);
+    }
+    else {
+        await runCommandWithEnv(launcher.repair.command, launcher.repair.args, env);
+    }
+    if (!(await executableExists(launcher.repair.whenMissing, env))) {
+        throw new CliError(`MCP repair completed but ${launcher.repair.whenMissing} is still not on PATH.`, 1);
+    }
+}
+async function installUv(env) {
+    if (platform() === "win32") {
+        await runCommandWithEnv("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command",
+            "irm https://astral.sh/uv/install.ps1 | iex"
+        ], env);
+    }
+    else {
+        await runCommandWithEnv("sh", ["-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], env);
+    }
+    const installHome = env.HOME ?? env.USERPROFILE ?? homedir();
+    const uvBinDir = platform() === "win32"
+        ? path.join(installHome, ".local", "bin")
+        : path.join(installHome, ".local", "bin");
+    const pathValue = env.PATH ?? "";
+    if (!pathValue.split(path.delimiter).includes(uvBinDir)) {
+        env.PATH = [uvBinDir, pathValue].filter(Boolean).join(path.delimiter);
+    }
+}
+async function installFffMcp(env) {
+    const target = fffReleaseTarget();
+    const releasesResponse = await fetch("https://api.github.com/repos/dmtrKovalenko/fff.nvim/releases");
+    if (!releasesResponse.ok) {
+        throw new CliError(`Failed to fetch FFF MCP releases: HTTP ${releasesResponse.status}.`, 1);
+    }
+    const releases = await releasesResponse.json();
+    const assetName = `fff-mcp-${target}${platform() === "win32" ? ".exe" : ""}`;
+    const release = releases.find((item) => item.assets?.some((asset) => asset.name === assetName));
+    const asset = release?.assets?.find((item) => item.name === assetName);
+    if (!asset?.browser_download_url) {
+        throw new CliError(`No FFF MCP release asset found for ${target}.`, 1);
+    }
+    const binaryResponse = await fetch(asset.browser_download_url);
+    if (!binaryResponse.ok) {
+        throw new CliError(`Failed to download ${assetName}: HTTP ${binaryResponse.status}.`, 1);
+    }
+    const installHome = env.HOME ?? env.USERPROFILE ?? homedir();
+    const installDir = path.join(installHome, ".local", "bin");
+    const binaryPath = path.join(installDir, platform() === "win32" ? "fff-mcp.exe" : "fff-mcp");
+    await ensureDir(installDir);
+    await writeFileReplacingExisting(binaryPath, Buffer.from(await binaryResponse.arrayBuffer()), { mode: 0o755 });
+    if (platform() !== "win32")
+        await chmod(binaryPath, 0o755);
+    const pathValue = env.PATH ?? "";
+    if (!pathValue.split(path.delimiter).includes(installDir)) {
+        env.PATH = [installDir, pathValue].filter(Boolean).join(path.delimiter);
+    }
+}
+function fffReleaseTarget() {
+    const os = platform();
+    const arch = process.arch;
+    if (os === "linux") {
+        if (arch === "x64")
+            return "x86_64-unknown-linux-musl";
+        if (arch === "arm64")
+            return "aarch64-unknown-linux-musl";
+    }
+    if (os === "darwin") {
+        if (arch === "x64")
+            return "x86_64-apple-darwin";
+        if (arch === "arm64")
+            return "aarch64-apple-darwin";
+    }
+    if (os === "win32") {
+        if (arch === "x64")
+            return "x86_64-pc-windows-msvc";
+        if (arch === "arm64")
+            return "aarch64-pc-windows-msvc";
+    }
+    throw new CliError(`Unsupported FFF MCP platform: ${os}/${arch}.`, 1);
+}
+async function repairGitquarryEnvIfNeeded(name, env) {
+    if (name !== "gitquarry-mcp")
+        return;
+    const current = env.GITQUARRY_CLI_PATH;
+    if (current && await executableExists(current, env))
+        return;
+    if (!(await executableExists("gitquarry", env))) {
+        await runCommandWithEnv("npm", ["install", "-g", "gitquarry"], env);
+    }
+    const resolved = await resolveExecutable("gitquarry", env);
+    if (!resolved) {
+        throw new CliError("MCP repair could not find gitquarry after installing the gitquarry npm package.", 1);
+    }
+    env.GITQUARRY_CLI_PATH = resolved;
+}
+async function executableExists(command, env) {
+    return Boolean(await resolveExecutable(command, env));
+}
+async function resolveExecutable(command, env) {
+    if (isAbsoluteAnyPlatform(command) || command.includes(path.sep) || command.includes("/") || command.includes("\\")) {
+        return await pathExists(command) ? command : undefined;
+    }
+    const pathValue = env.PATH ?? process.env.PATH ?? "";
+    const extensions = platform() === "win32"
+        ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")
+        : [""];
+    for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+        for (const extension of extensions) {
+            const candidate = path.join(dir, `${command}${extension}`);
+            if (await pathExists(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
 async function copyDirectory(source, target) {
     await ensureDir(target);
     for (const entry of await readdir(source, { withFileTypes: true })) {
@@ -1119,4 +1317,4 @@ if (isCliEntrypoint()) {
         process.exit(exitCode);
     });
 }
-export { applyBundle, buildBundle, buildJoinLink, computeRevision, defaultContext, installHook, mergeTomlText, parseJoinLink, verifyBundle };
+export { applyBundle, buildBundle, buildJoinLink, computeRevision, defaultContext, installHook, mergeTomlText, parseJoinLink, portableMcpLauncher, verifyBundle };

package/docs/prd.md

@@ -161,10 +161,20 @@ should make them portable through:
 - path variables such as home and workspace root
 - secret transfer over the Tailscale bundle
 - local overlays for follower-specific additions
+- a managed follower launcher that can repair known package, Python, binary,
+  and source-built MCPs
 
 Canonical MCP names are reserved. Local MCPs may add new names. A same-name
 local MCP should fail by default unless an explicit override is configured.
 
+The product goal is full export, not best-effort pruning. Command MCPs should
+remain present on followers even when their master command path is local to the
+master. Followers should route command MCPs through `codexport mcp run <name>`,
+store the original definitions in `~/.codexport/mcp-manifest.json`, and let the
+managed launcher translate or repair the runtime. If an MCP cannot be repaired,
+the failure should be explicit and actionable rather than silently disabling the
+MCP.
+
 ### Skills
 
 Master skills are canonical and synced by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexport",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "sync a canonical Codex setup from one master machine to follower machines",
   "author": "Microck <contact@micr.dev>",
   "license": "MIT",