codexport 0.2.0 → 0.3.1

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.2.0";
+const VERSION = "0.3.1";
 const DEFAULT_PORT = 17342;
 const DEFAULT_TIMEOUT_MS = 5_000;
 const CODEXPORT_DIR = ".codexport";
@@ -21,6 +21,8 @@ const MCPS_LOCAL_FILE = "mcps.local.toml";
 const LAST_BUNDLE_FILE = "last-bundle.json";
 const CACHE_BUNDLE_FILE = "bundle.json";
 const APPLIED_FILES_FILE = "applied-files.json";
+const MCP_MANIFEST_FILE = "mcp-manifest.json";
+const MANAGED_MCP_PACKAGE = "codexport@latest";
 const INCLUDE_ROOTS = [
     "AGENTS.md",
     "RTK.md",
@@ -410,10 +412,31 @@ function rewritePortableConfig(canonical, sourceRoot, sourceEnv = {}) {
             continue;
         const server = rawServer;
         mergeSourceEnvForMcp(name, server, sourceEnv);
-        rewritePortableMcpServer(name, server, sourceRoot, sourceHome);
+        rewriteManagedMcpServer(name, server, sourceRoot, sourceHome);
     }
     return stringifyToml(parsed);
 }
+function buildMcpManifest(canonical, sourceRoot, sourceEnv = {}) {
+    let parsed;
+    try {
+        parsed = parseTomlObject(canonical, "canonical config.toml");
+    }
+    catch {
+        return undefined;
+    }
+    const mcpServers = parsed.mcp_servers;
+    if (!mcpServers || typeof mcpServers !== "object" || Array.isArray(mcpServers))
+        return undefined;
+    const servers = {};
+    for (const [name, rawServer] of Object.entries(mcpServers)) {
+        if (!rawServer || typeof rawServer !== "object" || Array.isArray(rawServer))
+            continue;
+        const server = structuredClone(rawServer);
+        mergeSourceEnvForMcp(name, server, sourceEnv);
+        servers[name] = server;
+    }
+    return { version: 1, sourceRoot, sourceEnv, servers };
+}
 function mergeSourceEnvForMcp(name, server, sourceEnv) {
     if (name !== "kagi-mcp")
         return;
@@ -439,25 +462,12 @@ function rewritePortableTableKeys(table, sourceRoot, sourceHome) {
         table[key] = value;
     }
 }
-function rewritePortableMcpServer(_name, server, sourceRoot, sourceHome) {
+function rewriteManagedMcpServer(name, server, sourceRoot, sourceHome) {
     if (typeof server.url === "string")
         return;
-    const command = typeof server.command === "string" ? server.command : undefined;
     const args = Array.isArray(server.args) ? server.args : [];
-    const launcher = command && mcpHasRequiredPortableEnv(_name, command, server) ? portableMcpLauncher(_name, command, args, sourceHome, server) : undefined;
-    if (launcher) {
-        server.command = launcher.command;
-        server.args = launcher.args.map((arg) => rewritePortablePath(arg, sourceRoot, sourceHome));
-    }
-    else if (command && isAbsoluteAnyPlatform(command)) {
-        server.enabled = false;
-    }
-    else if (command) {
-        server.command = rewritePortableCommand(command, sourceRoot);
-    }
-    if (!launcher && args.length) {
-        server.args = args.map((arg) => typeof arg === "string" ? rewritePortablePath(arg, sourceRoot, sourceHome) : arg);
-    }
+    server.command = "npx";
+    server.args = ["-y", MANAGED_MCP_PACKAGE, "mcp", "run", name];
     if (server.env && typeof server.env === "object" && !Array.isArray(server.env)) {
         for (const [key, value] of Object.entries(server.env)) {
             if (typeof value === "string") {
@@ -489,9 +499,46 @@ function portableMcpLauncher(name, command, args, sourceHome, server) {
     }
     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: platform() === "win32" ? "py" : "python3",
+                args: ["-m", "pip", "install", "--user", "uv"]
+            }
+        };
+    }
+    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) {
@@ -513,16 +560,44 @@ 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"
+        "qmd": "qmd-cli",
+        "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)
@@ -691,6 +766,10 @@ async function applyBundle(ctx, bundle) {
     if (configEntry) {
         const canonicalConfig = decodeFile(configEntry).toString("utf8");
         const localMcpText = await readTextIfExists(path.join(ctx.stateDir, MCPS_LOCAL_FILE));
+        const manifest = buildMcpManifest(canonicalConfig, bundle.sourceRoot, bundle.sourceEnv);
+        if (manifest) {
+            await writeJsonAtomic(path.join(ctx.stateDir, MCP_MANIFEST_FILE), manifest);
+        }
         const generated = mergeTomlText(canonicalConfig, localMcpText, { ...localConfig, codexDir: ctx.codexDir }, bundle.sourceRoot, bundle.sourceEnv);
         const configPath = path.join(ctx.codexDir, "config.toml");
         if (await pathExists(configPath)) {
@@ -708,6 +787,147 @@ async function applyBundle(ctx, bundle) {
     await writeLocalConfig(ctx, { ...localConfig, lastRevision: bundle.revision, codexDir: ctx.codexDir });
     await writeJsonAtomic(path.join(ctx.stateDir, APPLIED_FILES_FILE), bundle.files.map((file) => file.path));
 }
+async function commandMcpRun(ctx, name) {
+    const manifest = await readJsonIfExists(path.join(ctx.stateDir, MCP_MANIFEST_FILE));
+    if (!manifest?.servers?.[name]) {
+        throw new CliError(`No managed MCP named ${name}. Run codexport sync --apply first.`, 1);
+    }
+    const localConfig = await readLocalConfig(ctx);
+    const sourceHome = inferHomeFromCodexDir(manifest.sourceRoot);
+    const server = structuredClone(manifest.servers[name]);
+    mergeSourceEnvForMcp(name, server, manifest.sourceEnv ?? {});
+    rewritePortableTableKeys(server, manifest.sourceRoot, sourceHome);
+    if (typeof server.url === "string") {
+        throw new CliError(`MCP ${name} is URL-based and should not be launched through codexport mcp run.`, 2);
+    }
+    const command = typeof server.command === "string" ? expandPathVariables(server.command, { ...localConfig, codexDir: ctx.codexDir }) : undefined;
+    const args = Array.isArray(server.args)
+        ? server.args.map((arg) => typeof arg === "string" ? expandPathVariables(rewritePortablePath(arg, manifest.sourceRoot, sourceHome), { ...localConfig, codexDir: ctx.codexDir }) : String(arg))
+        : [];
+    if (!command)
+        throw new CliError(`MCP ${name} has no command.`, 1);
+    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) {
+    const env = server.env && typeof server.env === "object" && !Array.isArray(server.env) ? server.env : {};
+    const out = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (typeof value === "string") {
+            out[key] = expandPathVariables(rewritePortablePath(value, 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 {
+        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 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 })) {
@@ -749,6 +969,23 @@ function runCommand(command, args) {
         });
     });
 }
+function runCommandWithEnv(command, args, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: "inherit", env });
+        child.on("error", (error) => {
+            const message = error.code === "ENOENT"
+                ? `MCP launcher program not found: ${command}. Install it on this follower or add it to PATH.`
+                : asError(error).message;
+            reject(new CliError(message, 1));
+        });
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new CliError(`${command} ${args.join(" ")} exited with ${code}`, code ?? 1));
+        });
+    });
+}
 async function installMasterService(ctx, port, dryRun) {
     const command = `${process.execPath} ${realpathSync(fileURLToPath(import.meta.url))} master serve --port ${port}`;
     if (platform() === "linux") {
@@ -1016,6 +1253,10 @@ async function main(argv) {
     program.command("apply")
         .description("Apply the last staged bundle.")
         .action(async (_options, command) => commandApply(contextFromCommand(command)));
+    const mcp = program.command("mcp").description("Run managed follower MCP launchers.");
+    mcp.command("run <name>")
+        .description("Run a synced MCP through codexport's managed launcher.")
+        .action(async (name, _options, command) => commandMcpRun(contextFromCommand(command), name));
     const hook = program.command("hook").description("Manage follower Codex hooks.");
     hook.command("install")
         .description("Install a follower-only Codex SessionStart sync hook.")
@@ -1047,4 +1288,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.2.0",
+  "version": "0.3.1",
   "description": "sync a canonical Codex setup from one master machine to follower machines",
   "author": "Microck <contact@micr.dev>",
   "license": "MIT",