toolfactory 0.1.1 → 0.1.2

package/dist/surfaces/mcpb.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { NODE_ENGINES } from "../bindings/typescript.js";
-import { MCPB_PIN, surface as mcpb } from "./mcpb.js";
+import { MCPB_PIN, surface as mcpb, UV_MANIFEST_VERSION } from "./mcpb.js";
 const echo = {
     name: "echo",
     description: "Echoes.",
@@ -90,8 +90,36 @@ describe("mcpb", () => {
         // No privacy_policies unless tool.json names them (see the module docs).
         expect(manifestFile.content).not.toContain("privacy_policies");
     });
-    it("declares the kernel's own Node floor, and refuses a binding whose package is not the bundle", () => {
-        expect(() => mcpb.plan({ ...project, tool: { ...project.tool, binding: "python" } })).toThrow(/requires the typescript binding/);
+    it("uses the official v0.4 uv bundle contract for Python, with its canonical PyPI surface", () => {
+        const pythonProject = {
+            ...project,
+            tool: { ...project.tool, binding: "python", surfaces: ["mcp", "pypi", "mcpb"] },
+        };
+        const [file] = mcpb.plan(pythonProject);
+        if (file?.kind !== "file")
+            throw new Error("expected one whole file");
+        expect(JSON.parse(file.content)).toMatchObject({
+            manifest_version: UV_MANIFEST_VERSION,
+            server: {
+                type: "uv",
+                entry_point: "src/hello_tool/toolfactory/mcp.py",
+                mcp_config: {
+                    command: "uv",
+                    args: [
+                        "run",
+                        "--directory",
+                        "${__dirname}",
+                        "python",
+                        "-m",
+                        "hello_tool.toolfactory.mcp",
+                    ],
+                },
+            },
+            compatibility: { runtimes: { python: ">=3.11" } },
+        });
+        expect(() => mcpb.plan({ ...pythonProject, tool: { ...pythonProject.tool, surfaces: ["mcp", "mcpb"] } })).toThrow(/requires the "pypi" surface/);
+    });
+    it("declares the kernel's own Node floor and validates with the pinned official CLI", () => {
         expect(mcpb.validate?.(project)).toEqual([
             {
                 label: "mcpb validate",

package/dist/surfaces/npm.js

@@ -4,7 +4,7 @@
  */
 import { githubSlug } from "../hosts/github.js";
 import { registryName } from "./mcp-registry.js";
-import { compact, has, npmName } from "./shared.js";
+import { compact, has, npmName, pypiName } from "./shared.js";
 import { WEB_DIR } from "./web.js";
 /**
  * npm's object form. A bare URL string is only valid as one of npm's shorthands, so `publint`
@@ -17,14 +17,30 @@ function repositoryField(repository) {
     const slug = githubSlug(repository);
     return { type: "git", url: slug ? `git+https://github.com/${slug}.git` : repository };
 }
+/**
+ * A deliberately thin cross-registry bridge: npm supplies discovery and a familiar `npx` entry,
+ * while uvx resolves the canonical Python distribution. `uvx` owns Python acquisition, caching,
+ * and the package install; the npm package never downloads an interpreter itself.
+ */
+function pythonLauncher(project) {
+    const { identity } = project;
+    return `#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+const child = spawnSync("uvx", ["--from", ${JSON.stringify(`${pypiName(project)}==${identity.version}`)}, ${JSON.stringify(identity.name)}, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+if (child.error) throw child.error;
+process.exit(child.status ?? 1);
+`;
+}
 export const surface = {
     id: "npm",
     plan(project) {
-        if (project.tool.binding !== "typescript") {
-            throw new Error('Surface "npm" requires the typescript binding.');
-        }
         const { identity } = project;
         const authored = project.tool.identity === "package.json";
+        const python = project.tool.binding === "python";
+        const launcher = `bin/${identity.name}.mjs`;
         const patch = compact({
             name: authored ? undefined : npmName(project),
             version: authored ? undefined : identity.version,
@@ -35,21 +51,36 @@ export const surface = {
             keywords: authored ? undefined : identity.keywords,
             type: "module",
             bin: has(project, "cli") || has(project, "mcp")
-                ? { [identity.name]: "./dist/toolfactory/cli.js" }
+                ? {
+                    [identity.name]: python ? `./${launcher}` : "./dist/toolfactory/cli.js",
+                }
                 : undefined,
             // `web/dist` only with the `web` surface: the kernel serves the built page from inside
             // the installed package, so `npx <tool> mcp --http --open` works without a checkout.
-            files: [
-                "dist",
-                "src",
-                "schemas",
-                ...(has(project, "web") ? [`${WEB_DIR}/dist`] : []),
-                "README.md",
-                "LICENSE",
-            ],
+            files: python
+                ? ["bin", "README.md", "LICENSE"]
+                : [
+                    "dist",
+                    "src",
+                    "schemas",
+                    ...(has(project, "web") ? [`${WEB_DIR}/dist`] : []),
+                    "README.md",
+                    "LICENSE",
+                ],
             mcpName: has(project, "mcp-registry") ? registryName(project) : undefined,
         });
-        return [{ kind: "merge", path: "package.json", format: "json", patch, owned: ["bin"] }];
+        return [
+            ...(python && (has(project, "cli") || has(project, "mcp"))
+                ? [{ kind: "file", path: launcher, content: pythonLauncher(project) }]
+                : []),
+            {
+                kind: "merge",
+                path: "package.json",
+                format: "json",
+                patch,
+                owned: ["bin", "files"],
+            },
+        ];
     },
     validate(project) {
         return [

package/dist/surfaces/pypi.js

@@ -26,19 +26,43 @@ export const surface = {
                     ? { [project.identity.name]: cliEntryPoint(project) }
                     : undefined,
             }),
-            // The kernel serves the built page from inside its own package, so the wheel has to
-            // carry it: `packages` only copies the package tree, `force-include` maps anything else.
+            // Hatch ignores a missing `only-include` path, unlike `force-include`, which makes
+            // `uv sync` work in a fresh checkout before the optional page is built. At package time,
+            // the gate builds `web/dist` first and Hatch maps it into the installed package.
             ...(has(project, "web")
                 ? {
                     tool: {
                         hatch: {
                             build: {
+                                // Hatch's normal file selection honors .gitignore; `web/dist` is ignored in
+                                // every generated project, so artifacts is the standard explicit opt-in for
+                                // the release build's compiled page.
+                                artifacts: [`${WEB_DIR}/dist/**`],
                                 targets: {
                                     wheel: {
-                                        "force-include": {
+                                        "only-include": [`src/${pythonPackage(project)}`, `${WEB_DIR}/dist`],
+                                        sources: {
+                                            src: "",
                                             [`${WEB_DIR}/dist`]: `${pythonPackage(project)}/${WEB_DIR}`,
                                         },
                                     },
+                                    // This is the source MCPB stages, so include every declared project metadata
+                                    // file alongside the package and built page. `only-include` ignores absent
+                                    // legal files without making fresh checkouts fail.
+                                    sdist: {
+                                        "only-include": [
+                                            "pyproject.toml",
+                                            "README.md",
+                                            "LICENSE",
+                                            "LICENSE.md",
+                                            "LICENSE.txt",
+                                            "NOTICE",
+                                            "NOTICE.md",
+                                            "NOTICE.txt",
+                                            `src/${pythonPackage(project)}`,
+                                            `${WEB_DIR}/dist`,
+                                        ],
+                                    },
                                 },
                             },
                         },

package/dist/surfaces/readme.js

@@ -114,16 +114,15 @@ function installLines(project) {
     }
     if (has(project, "browser-extension")) {
         // Three channels, in the order a reader needs them: build-and-load from a checkout, the
-        // release assets (only Mozilla's signed xpi is a real self-hosted install — Chrome drops
-        // side-loaded unpacked extensions), the store listings. Pairing is the last step of each.
+        // release assets (the signed Firefox XPI depends on configured signing credentials), and
+        // store listings. Pairing is the last step of each.
         const zips = ["chrome", "firefox", "edge"].map((browser) => `\`${zipName(project, browser)}\``);
         lines.push([
             `- **Browser extension** — from a checkout: \`npm --prefix ${BROWSER_HOST_DIR} install && npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt build\`,`,
             `  then \`chrome://extensions\` → developer mode → Load unpacked → \`${BROWSER_HOST_DIR}/.output/chrome-mv3\``,
             `  (Firefox: \`npm --prefix ${BROWSER_HOST_DIR} exec --no -- web-ext run\`). Each GitHub Release attaches the`,
-            `  store uploads ${zips.join(", ")}, and the Mozilla-signed \`.xpi\`,`,
-            "  which is the only download-and-install channel now that Chrome no longer keeps side-loaded unpacked",
-            "  extensions; the Chrome Web Store, Firefox Add-ons and Edge Add-ons listings appear once the release's",
+            `  store uploads ${zips.join(", ")}. When Firefox signing credentials are configured, it also attaches a`,
+            "  Mozilla-signed `.xpi`; the Chrome Web Store, Firefox Add-ons and Edge Add-ons listings appear once the release's",
             `  submit step has each store's credentials. Then pair it: \`${mcpCommand(project)} --http --pair\``,
             "  prints the `<url>#<token>` the extension's options page accepts.",
         ].join("\n"));
@@ -133,8 +132,12 @@ function installLines(project) {
         // tool already is. The same listener answers `/mcp`, so the page needs nothing else running.
         lines.push(`- **Web app** — \`${mcpCommand(project)} --http --open\` serves the operations page beside the`, "  MCP endpoint on one port and opens it; over MCP or a skill, the `web` operation does the same and", "  returns the URL.");
     }
-    if (has(project, "npm"))
-        lines.push(`- **npm package** — \`npm install ${npmName(project)}\``);
+    if (has(project, "npm")) {
+        const pythonBridge = project.tool.binding === "python"
+            ? `; requires \`uv\`, and \`${identity.name}\` delegates to \`uvx --from ${pypiName(project)}==${identity.version} ${identity.name}\``
+            : "";
+        lines.push(`- **npm package** — \`npm install ${npmName(project)}\`${pythonBridge}`);
+    }
     if (has(project, "pypi"))
         lines.push(`- **PyPI package** — \`uv add ${pypiName(project)}\``);
     return lines;

package/dist/surfaces/registry.js

@@ -36,9 +36,9 @@ const registry = {
     cli,
     mcp,
     "mcp-registry": mcpRegistry,
-    // The bundle root is the npm tarball with its production dependencies installed into it, and
-    // its one row launches the kernel MCP server: without either surface there is nothing to pack.
-    mcpb: { ...mcpb, requires: ["mcp", "npm"] },
+    // TypeScript bundles stage their npm tarball; Python `uv` bundles stage the PyPI project's
+    // source. The projector enforces that binding-specific distribution dependency.
+    mcpb: { ...mcpb, requires: ["mcp"] },
     npm,
     skill,
     "hermes-native": hermesNative,

package/dist/surfaces/workflows.js

@@ -408,7 +408,9 @@ function releaseDocument(project) {
     };
     const priorLegs = [];
     if (npmSelected) {
-        const tarball = `${RELEASE_ARTIFACT}/${npmTarball(project)}`;
+        // npm treats a slash-containing bare operand as a Git spec; make the downloaded archive a
+        // filesystem path explicitly.
+        const tarball = `./${RELEASE_ARTIFACT}/${npmTarball(project)}`;
         jobs["publish-npm"] = compact({
             needs: ["gate", "package"],
             if: gated("npm"),
@@ -442,18 +444,20 @@ function releaseDocument(project) {
     }
     if (pypiSelected) {
         jobs["publish-pypi"] = compact({
-            needs: "gate",
+            needs: ["gate", "package"],
             if: gated("pypi"),
             "runs-on": "ubuntu-latest",
             environment: "pypi",
             permissions: { "id-token": "write" },
             steps: [
-                checkoutStep(RELEASE_SHA),
-                { uses: "astral-sh/setup-uv@v6" },
-                { run: "uv build" },
+                {
+                    uses: "actions/download-artifact@v8",
+                    with: { name: RELEASE_ARTIFACT, path: RELEASE_ARTIFACT },
+                },
                 {
                     name: "Publish package distributions to PyPI",
                     uses: "pypa/gh-action-pypi-publish@release/v1",
+                    with: { "packages-dir": `${RELEASE_ARTIFACT}/pypi/` },
                 },
             ],
         });
@@ -616,7 +620,10 @@ function releaseDocument(project) {
                     // A tag the dispatch is cutting does not exist yet: the Release creates it here.
                     target_commitish: RELEASE_SHA,
                     generate_release_notes: true,
-                    files: `${RELEASE_ARTIFACT}/*`,
+                    // PyPI distributions live one level below the other release assets.
+                    files: has(project, "pypi")
+                        ? `${RELEASE_ARTIFACT}/*\n${RELEASE_ARTIFACT}/pypi/*`
+                        : `${RELEASE_ARTIFACT}/*`,
                     fail_on_unmatched_files: true,
                 },
             },

package/dist/surfaces/workflows.test.js

@@ -120,6 +120,73 @@ describe("workflows", () => {
         });
         expect(steps.some((s) => s.run === "uv run --with pytest pytest -q")).toBe(true);
     });
+    it("installs a native Python core into Hermes only in validation jobs", () => {
+        const python = project(["cli", "mcp", "hermes-native"], {
+            tool: {
+                ...project(["cli"]).tool,
+                binding: "python",
+                surfaces: ["cli", "mcp", "hermes-native"],
+            },
+        });
+        const files = emitted(python);
+        const ci = yamlParse(files[".github/workflows/ci.yml"]);
+        const release = yamlParse(files[".github/workflows/release.yml"]);
+        const command = 'uv pip install --python "$HOME/.hermes/hermes-agent/venv/bin/python" --editable .';
+        const ciRuns = ci.jobs.test.steps.map((step) => step.run);
+        const gateRuns = release.jobs.gate.steps.map((step) => step.run);
+        const packageRuns = release.jobs.package.steps.map((step) => step.run);
+        const ciValidate = ciRuns.findIndex((run) => run?.endsWith(" validate"));
+        const gateValidate = gateRuns.findIndex((run) => run?.endsWith(" validate"));
+        expect(ciRuns.indexOf(command)).toBeGreaterThan(ciRuns.indexOf("uv sync"));
+        expect(ciRuns.indexOf(command)).toBeLessThan(ciValidate);
+        expect(gateRuns.indexOf(command)).toBeGreaterThan(gateRuns.indexOf("uv sync"));
+        expect(gateRuns.indexOf(command)).toBeLessThan(gateValidate);
+        expect(packageRuns).not.toContain(command);
+        const withoutHermes = project(["cli", "mcp"], {
+            tool: { ...project(["cli"]).tool, binding: "python", surfaces: ["cli", "mcp"] },
+        });
+        const typescriptHermes = project(["cli", "mcp", "hermes-native"]);
+        expect(emitted(withoutHermes)[".github/workflows/ci.yml"]).not.toContain(command);
+        expect(emitted(typescriptHermes)[".github/workflows/ci.yml"]).not.toContain(command);
+    });
+    it("publishes the package job's prebuilt Python distributions", () => {
+        const python = project(["pypi", "web"], {
+            tool: { ...project([]).tool, binding: "python", surfaces: ["pypi", "web"] },
+        });
+        const release = yamlParse(emitted(python)[".github/workflows/release.yml"] ?? "");
+        const publish = release.jobs["publish-pypi"];
+        expect(publish.needs).toEqual(["gate", "package"]);
+        expect(publish.steps).toEqual([
+            {
+                uses: "actions/download-artifact@v8",
+                with: { name: "release-assets", path: "release-assets" },
+            },
+            {
+                name: "Publish package distributions to PyPI",
+                uses: "pypa/gh-action-pypi-publish@release/v1",
+                with: { "packages-dir": "release-assets/pypi/" },
+            },
+        ]);
+        expect(release.jobs.release.steps.at(-1)?.with.files).toBe("release-assets/*\nrelease-assets/pypi/*");
+        expect(packageSteps(python).find((step) => step.name === "web build")).toBeDefined();
+        expect(packageSteps(python).find((step) => step.name === "python distributions")?.run).toBe("uv build --out-dir dist/release/pypi");
+        const mcpbPython = project(["pypi", "mcp", "mcpb", "web"], {
+            tool: {
+                ...project([]).tool,
+                binding: "python",
+                surfaces: ["pypi", "mcp", "mcpb", "web"],
+            },
+        });
+        const mcpb = packageSteps(mcpbPython).find((step) => step.name === "MCPB bundle")?.run;
+        expect(packageSteps(mcpbPython).map((step) => step.name)).toEqual(expect.arrayContaining(["python distributions", "MCPB bundle"]));
+        expect(packageSteps(mcpbPython)
+            .map((step) => step.name)
+            .indexOf("python distributions")).toBeLessThan(packageSteps(mcpbPython)
+            .map((step) => step.name)
+            .indexOf("MCPB bundle"));
+        expect(mcpb).toContain("tar -xzf dist/release/pypi/*.tar.gz -C dist/mcpb --strip-components=1");
+        expect(mcpb).not.toContain("cp -R src dist/mcpb/src");
+    });
     it("release.yml runs the legs in the forced order npm -> oci -> mcp-registry -> clawhub, each gated on what the gate decided", () => {
         const files = emitted(project(["npm", "mcp-registry", "clawhub", "openclaw-native", "skill", "claude", "web", "mcp"], {
             identity: {
@@ -265,8 +332,8 @@ describe("workflows", () => {
         // configured publisher selects OIDC; otherwise the stored token is a fallback. A re-dispatch
         // after adding either credential must not attempt to republish an immutable version.
         expect(release.jobs["publish-npm"].steps.some((s) => s.run?.includes("npm view hello@0.1.0 version") &&
-            s.run?.includes('elif [ "$NPM_TRUSTED_PUBLISHER" = true ]; then npm publish release-assets/hello-0.1.0.tgz --access public') &&
-            s.run?.includes('NODE_AUTH_TOKEN="$NPM_TOKEN" npm publish release-assets/hello-0.1.0.tgz --access public'))).toBe(true);
+            s.run?.includes('elif [ "$NPM_TRUSTED_PUBLISHER" = true ]; then npm publish ./release-assets/hello-0.1.0.tgz --access public') &&
+            s.run?.includes('NODE_AUTH_TOKEN="$NPM_TOKEN" npm publish ./release-assets/hello-0.1.0.tgz --access public'))).toBe(true);
         // The oci leg pushes the very image server.json's oci entry names.
         const meta = release.jobs["publish-oci"].steps.find((s) => s.id === "meta");
         expect(meta?.with?.images).toBe("ghcr.io/acme/hello");
@@ -491,7 +558,7 @@ describe("gate", () => {
         ]);
         const runs = packageSteps(target).map((step) => step.run);
         expect(runs).toContain("npm pack --pack-destination dist/release");
-        expect(runs).toContain("uv build --out-dir dist/release");
+        expect(runs).toContain("uv build --out-dir dist/release/pypi");
         expect(runs.some((run) => run.includes("npm pack ./hosts/openclaw"))).toBe(true);
         expect(runs).toContain('set -- skills .claude-plugin; for path in LICENSE LICENSE.md LICENSE.txt NOTICE NOTICE.md NOTICE.txt; do if [ -f "$path" ]; then set -- "$@" "$path"; fi; done; zip -qr dist/release/hello-plugin.zip "$@"');
         const webBuild = runs.findIndex((run) => run.includes("npm -C web run build"));

package/dist/toolfactory/cli.js

@@ -11,7 +11,7 @@ const operations = [...authored, web];
 const program = new Command()
     .name("toolfactory")
     .description("Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.")
-    .version("0.1.1");
+    .version("0.1.2");
 for (const op of operations) {
     if (!serves(op, "cli"))
         continue;

package/dist/toolfactory/mcp.js

@@ -30,7 +30,7 @@ const operations = [...authored, web];
 const introspecting = Boolean(process.env.TOOLFACTORY_INTROSPECT);
 /** Builds one server instance with every servable operation registered; called once for stdio, once per HTTP request. */
 function createServer() {
-    const server = new McpServer({ name: "toolfactory", version: "0.1.1" });
+    const server = new McpServer({ name: "toolfactory", version: "0.1.2" });
     for (const op of operations) {
         if (!introspecting && !serves(op, "mcp"))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfactory",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.",
   "license": "MIT",
   "repository": {

package/src/bindings/python.ts

@@ -236,7 +236,7 @@ def env_route(token: "str | None") -> Route:
   return `
 
 def web_dist() -> "Path | None":
-    """The built page: the wheel force-includes \`${WEB_DIR}/dist\` here, a checkout has it in place."""
+    """The wheel maps \`${WEB_DIR}/dist\` here at package time; a checkout has it in place."""
     package = Path(__file__).resolve().parent.parent
     for candidate in (package / "${WEB_DIR}", package.parent.parent / "${WEB_DIR}" / "dist"):
         if candidate.is_dir():

package/src/model.ts

@@ -129,7 +129,17 @@ export const ToolConfigSchema = z
       .default({ examples: {} })
       .describe("Example arguments per operation, used by the generated surface-smoke tests."),
     npm: z.object({ scope: z.string().optional() }).optional(),
-    codex: z.object({ interface: jsonObject.optional() }).optional(),
+    codex: z
+      .object({
+        interface: jsonObject.optional(),
+        mcp: z
+          .boolean()
+          .default(true)
+          .describe(
+            "Whether the Codex plugin manifest eagerly configures the generated MCP server.",
+          ),
+      })
+      .optional(),
     browserExtension: z
       .object({
         endpoint: z

package/src/project/gate.ts

@@ -121,11 +121,18 @@ export function gateSteps(project: Project): GateStep[] {
   const pm = commands(project);
   const cli = toolfactoryCli(project);
   const openclaw = has(project, "openclaw-native");
-  const steps: GateStep[] = [
-    ...bootstrapSteps(project),
-    { name: "toolfactory check", run: `${cli} check` },
-    outputsStep(project),
-  ];
+  const steps: GateStep[] = [...bootstrapSteps(project)];
+  if (!typescript && has(project, "hermes-native")) {
+    // Hermes' launcher clears PYTHONPATH and runs its own venv. Its plugin dependency
+    // declaration is advisory, so Doctor can import a native Python core only after the
+    // project is installed into that interpreter. Run after bootstrap's `uv sync` on CI.
+    steps.push({
+      name: "Install core into Hermes",
+      run: 'uv pip install --python "$HOME/.hermes/hermes-agent/venv/bin/python" --editable .',
+      when: "ci",
+    });
+  }
+  steps.push({ name: "toolfactory check", run: `${cli} check` }, outputsStep(project));
   if (has(project, "claude")) {
     steps.push({
       name: "Install Claude Code CLI",
@@ -232,27 +239,35 @@ export function packageSteps(project: Project): GateStep[] {
   if (has(project, "npm")) {
     steps.push({ name: "npm tarball", run: `npm pack --pack-destination ${RELEASE_DIR}` });
   }
+  if (has(project, "pypi")) {
+    // Keep the wheel and sdist apart from the release's npm tarballs, plugin bundles and web
+    // archive: PyPA's publisher accepts only Python distribution files. The MCPB stage below
+    // unpacks this same canonical sdist rather than reproducing its source-file selection.
+    steps.push({ name: "python distributions", run: `uv build --out-dir ${RELEASE_DIR}/pypi` });
+  }
   if (has(project, "mcpb")) {
-    // A bundle root is the published package with its production dependencies installed into
-    // it, so it is built from the tarball `npm pack` just wrote rather than from the checkout:
-    // whatever ships to npm is exactly what ships to Claude Desktop. `--ignore-scripts` because
-    // nothing in a bundle root may run a build; the tarball already carries `dist/`.
     const stage = "dist/mcpb";
-    const tarball = npmTarball(project);
     steps.push({
       name: "MCPB bundle",
-      run: [
-        `rm -rf ${stage} && mkdir -p ${stage}`,
-        `tar -xzf ${RELEASE_DIR}/${tarball} -C ${stage} --strip-components=1`,
-        `npm --prefix ${stage} install --omit=dev --ignore-scripts`,
-        `cp ${MCPB_MANIFEST_PATH} ${stage}/manifest.json`,
-        `npx -y @anthropic-ai/mcpb@${MCPB_PIN} pack ${stage} ${RELEASE_DIR}/${name}.mcpb`,
-      ].join(" && "),
+      run:
+        project.tool.binding === "python"
+          ? [
+              `rm -rf ${stage} && mkdir -p ${stage}`,
+              `tar -xzf ${RELEASE_DIR}/pypi/*.tar.gz -C ${stage} --strip-components=1`,
+              `cp ${MCPB_MANIFEST_PATH} ${stage}/manifest.json`,
+              `npx -y @anthropic-ai/mcpb@${MCPB_PIN} pack ${stage} ${RELEASE_DIR}/${name}.mcpb`,
+            ].join(" && ")
+          : [
+              // The Node bundle root is the published package with production dependencies
+              // installed, so whatever ships to npm is exactly what ships to Claude Desktop.
+              `rm -rf ${stage} && mkdir -p ${stage}`,
+              `tar -xzf ${RELEASE_DIR}/${npmTarball(project)} -C ${stage} --strip-components=1`,
+              `npm --prefix ${stage} install --omit=dev --ignore-scripts`,
+              `cp ${MCPB_MANIFEST_PATH} ${stage}/manifest.json`,
+              `npx -y @anthropic-ai/mcpb@${MCPB_PIN} pack ${stage} ${RELEASE_DIR}/${name}.mcpb`,
+            ].join(" && "),
     });
   }
-  if (has(project, "pypi")) {
-    steps.push({ name: "python distributions", run: `uv build --out-dir ${RELEASE_DIR}` });
-  }
   if (has(project, "openclaw-native")) {
     // ClawHub's reusable workflow has no build step of its own, so the tarball it publishes has
     // to arrive already built (`package_artifact_name`).

package/src/surfaces/agents.ts

@@ -89,6 +89,13 @@ export const RELOAD: Reload[] = [
       "`hermes skills trust` once in this repo, then a new conversation: the resolved skill directories are stable for a conversation.",
     line: "Run `hermes skills trust` once in this repo, then start a new Hermes conversation — every invocation re-scans plugins, skills and AGENTS.md. `/reload-mcp` only affects an already-open session; `hermes gateway restart` is only for the messaging gateway.",
   },
+  {
+    harness: "GSD",
+    env: [],
+    mcp: "`python3 .agents/sync.py --all` renders the shared `.mcp.json` even on a GSD-only machine. Refresh with `mcp_servers(refresh=true)`; start a new session after changing a connected server. Approve `mcp_discover` interactively once before unattended stdio use.",
+    instructions:
+      "Reads `AGENTS.md` and `.agents/skills/` natively; `/reload` refreshes resources. `--bare` omits them.",
+  },
   {
     harness: "Gemini CLI",
     env: [],

package/src/surfaces/codex.test.ts

@@ -68,4 +68,14 @@ describe("codex", () => {
     expect(JSON.parse(manifest.content)).toMatchObject({ skills: "./skills/" });
     expect(JSON.parse(manifest.content)).not.toHaveProperty("mcpServers");
   });
+
+  it("can omit the eager MCP server while retaining the plugin skill", () => {
+    const target = project(["skill", "codex", "mcp"]);
+    target.tool.codex = { mcp: false };
+    const manifest = codex.plan(target).find((entry) => entry.path === ".codex-plugin/plugin.json");
+    if (manifest?.kind !== "file") throw new Error("expected a manifest");
+    const parsed = JSON.parse(manifest.content);
+    expect(parsed.skills).toBe("./skills/");
+    expect(parsed).not.toHaveProperty("mcpServers");
+  });
 });

package/src/surfaces/codex.ts

@@ -43,9 +43,10 @@ export const surface: Surface = {
       license: identity.license,
       keywords: identity.keywords,
       skills: has(project, "skill") ? "./skills/" : undefined,
-      mcpServers: has(project, "mcp")
-        ? { [identity.name]: kernelLaunch(project, "${PLUGIN_ROOT}") }
-        : undefined,
+      mcpServers:
+        has(project, "mcp") && project.tool.codex?.mcp !== false
+          ? { [identity.name]: kernelLaunch(project, "${PLUGIN_ROOT}") }
+          : undefined,
       interface: codexInterface,
     });
     // `source: "local"` + `path: "."` is the marketplace root itself: one repository, one