toolfactory 0.1.1 → 0.1.2

package/README.md

@@ -22,7 +22,7 @@ generated and every surface still installs, builds and publishes.
 - **Gemini CLI extension** — `gemini extensions install https://github.com/GoatInAHat/toolfactory`
 - **OpenClaw plugin** — `openclaw plugins install --link hosts/openclaw` from a checkout
 - **Hermes plugin** — `hermes plugins install https://github.com/GoatInAHat/toolfactory#hosts/hermes/toolfactory_hermes`
-- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.1.1.tgz`
+- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.1.2.tgz`
 - **Web app** — `npx -y toolfactory mcp --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.
@@ -55,8 +55,7 @@ None of it is required: with no GitHub, plain git or no git at all, everything b
 Use `--runtime none --surfaces skill,codex` when a plugin is only SKILL.md instructions for
 Codex. ToolFactory then emits no MCP server, operation snapshot, language scaffold, or consumer
 runtime dependency. `binding` remains required for config compatibility but is unused in this
-mode. Until this change is released, CI must invoke the checked-out ToolFactory source rather
-than resolve the published npm package.
+mode. This is available in the published npm package starting with ToolFactory 0.1.1.
 
 1. Write operations in `src/ops.ts` (TypeScript) or `src/<pkg>/ops.py` (Python). Each one is a
    name, a description, an input schema, an optional output schema, an optional `requires`
@@ -148,6 +147,12 @@ Inside OpenClaw, install the tool you are building with
 `hermes plugins install file://<repo>#hosts/hermes/<pkg>` — every `hermes` run is a fresh process,
 and `hermes gateway restart` is only for the messaging gateway.
 
+GSD uses the same skills, CLI and MCP server; no GSD-specific surface is needed. From a generated
+project, run `bash .agents/setup --all` so `.mcp.json` is rendered even on a GSD-only machine,
+then discover its server in an interactive GSD session before unattended use. GSD launched by
+OpenClaw or Hermes loads the child project's configuration separately from the outer agent.
+See [GSD compatibility](docs/gsd.md) for setup, runtime boundaries and the repeatable smoke test.
+
 ## The boundary
 
 Core logic is a pure function of JSON arguments, environment/config and the filesystem. An

package/dist/bindings/python.js

@@ -210,7 +210,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/dist/model.d.ts

@@ -82,6 +82,7 @@ export declare const ToolConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     codex: z.ZodOptional<z.ZodObject<{
         interface: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        mcp: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     browserExtension: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodOptional<z.ZodString>;

package/dist/model.js

@@ -100,7 +100,15 @@ 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/dist/project/gate.js

@@ -88,11 +88,18 @@ export function gateSteps(project) {
     const pm = commands(project);
     const cli = toolfactoryCli(project);
     const openclaw = has(project, "openclaw-native");
-    const steps = [
-        ...bootstrapSteps(project),
-        { name: "toolfactory check", run: `${cli} check` },
-        outputsStep(project),
-    ];
+    const steps = [...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",
@@ -202,27 +209,34 @@ export function packageSteps(project) {
     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/dist/project/history.d.ts

@@ -28,6 +28,7 @@ export declare function toolAtRef(root: string, ref: string): {
         scope?: string | undefined;
     } | undefined;
     codex?: {
+        mcp: boolean;
         interface?: Record<string, unknown> | undefined;
     } | undefined;
     browserExtension?: {

package/dist/surfaces/agents.js

@@ -58,6 +58,12 @@ export const RELOAD = [
         instructions: "`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/dist/surfaces/codex.js

@@ -39,7 +39,7 @@ export const surface = {
             license: identity.license,
             keywords: identity.keywords,
             skills: has(project, "skill") ? "./skills/" : undefined,
-            mcpServers: has(project, "mcp")
+            mcpServers: has(project, "mcp") && project.tool.codex?.mcp !== false
                 ? { [identity.name]: kernelLaunch(project, "${PLUGIN_ROOT}") }
                 : undefined,
             interface: codexInterface,

package/dist/surfaces/codex.test.js

@@ -64,4 +64,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/dist/surfaces/distribution.test.js

@@ -1,8 +1,12 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { buildPlan } from "../project/plan.js";
 import { surface as claude } from "./claude.js";
 import { surface as npm } from "./npm.js";
-import { MCP_NAME_BEGIN, MCP_NAME_END } from "./pypi.js";
+import { MCP_NAME_BEGIN, MCP_NAME_END, surface as pypi } from "./pypi.js";
 import { INSTALL_BEGIN, INSTALL_END, surface as readme } from "./readme.js";
 const echo = { name: "echo", inputSchema: { type: "object" }, requires: [] };
 function project(surfaces, overrides = {}) {
@@ -47,6 +51,115 @@ describe("npm", () => {
         });
         expect(npm.validate?.(project(["npm"])).map((command) => command.args.join(" "))).toContain("--yes publint --strict");
     });
+    it("makes a Python npm package a thin uvx launcher for its canonical PyPI distribution", () => {
+        const python = project(["npm", "pypi", "cli", "mcp"], {
+            tool: { ...project([]).tool, binding: "python", surfaces: ["npm", "pypi", "cli", "mcp"] },
+        });
+        const files = npm.plan(python);
+        const launcher = files.find((file) => file.path === "bin/hello.mjs");
+        const packageJson = files.find((file) => file.path === "package.json");
+        if (launcher?.kind !== "file" || packageJson?.kind !== "merge") {
+            throw new Error("expected a launcher and package metadata");
+        }
+        expect(launcher.content).toContain('spawnSync("uvx", ["--from", "hello==0.1.0", "hello"');
+        expect(launcher.content).toContain("...process.argv.slice(2)");
+        expect(packageJson.patch).toMatchObject({
+            name: "hello",
+            version: "0.1.0",
+            bin: { hello: "./bin/hello.mjs" },
+            files: ["bin", "README.md", "LICENSE"],
+        });
+        expect(region(python)).toContain("requires `uv`, and `hello` delegates to `uvx --from hello==0.1.0 hello`");
+    });
+    it("ships the built web page in Python's prebuilt wheel before release publication", () => {
+        const python = project(["pypi", "web"], {
+            tool: { ...project([]).tool, binding: "python", surfaces: ["pypi", "web"] },
+        });
+        const [file] = pypi.plan(python);
+        if (file?.kind !== "merge")
+            throw new Error("expected Python package metadata");
+        expect(file.patch).toMatchObject({
+            tool: {
+                hatch: {
+                    build: {
+                        artifacts: ["web/dist/**"],
+                        targets: {
+                            wheel: {
+                                "only-include": ["src/hello", "web/dist"],
+                                sources: { src: "", "web/dist": "hello/web" },
+                            },
+                        },
+                    },
+                },
+            },
+        });
+        expect(JSON.stringify(file.patch)).not.toContain("force-include");
+    });
+});
+const uv = spawnSync("uv", ["--version"], { encoding: "utf8" }).status === 0;
+describe.skipIf(!uv)("Python release source", () => {
+    it("stages the built page and metadata from the canonical sdist for a uv bundle", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-python-sdist-"));
+        mkdirSync(join(root, "src", "hello"), { recursive: true });
+        mkdirSync(join(root, "web", "dist"), { recursive: true });
+        writeFileSync(join(root, "pyproject.toml"), `[project]
+name = "hello"
+version = "0.1.0"
+readme = "README.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+artifacts = ["web/dist/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hello"]
+only-include = ["src/hello", "web/dist"]
+
+[tool.hatch.build.targets.wheel.sources]
+src = ""
+"web/dist" = "hello/web"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["pyproject.toml", "README.md", "LICENSE", "src/hello", "web/dist"]
+`);
+        writeFileSync(join(root, "README.md"), "# hello\n");
+        writeFileSync(join(root, "LICENSE"), "MIT\n");
+        writeFileSync(join(root, ".gitignore"), "dist/\n");
+        writeFileSync(join(root, "src", "hello", "__init__.py"), "");
+        mkdirSync(join(root, "web", "dist", "assets"), { recursive: true });
+        writeFileSync(join(root, "web", "dist", "index.html"), '<link rel="stylesheet" href="assets/app.css"><script src="assets/app.js"></script>\n');
+        writeFileSync(join(root, "web", "dist", "assets", "app.css"), "main{color:#000}\n");
+        writeFileSync(join(root, "web", "dist", "assets", "app.js"), "console.log('hello')\n");
+        const build = spawnSync("uv", ["build", "--out-dir", "dist/release/pypi"], {
+            cwd: root,
+            encoding: "utf8",
+        });
+        expect(build.status, build.stderr).toBe(0);
+        const wheel = spawnSync("unzip", ["-l", join(root, "dist", "release", "pypi", "hello-0.1.0-py2.py3-none-any.whl")], { encoding: "utf8" });
+        expect(wheel.status, wheel.stderr).toBe(0);
+        expect(wheel.stdout).toContain("hello/web/assets/app.css");
+        expect(wheel.stdout).toContain("hello/web/assets/app.js");
+        const stage = join(root, "dist", "mcpb");
+        mkdirSync(stage, { recursive: true });
+        const extract = spawnSync("tar", [
+            "-xzf",
+            join(root, "dist", "release", "pypi", "hello-0.1.0.tar.gz"),
+            "-C",
+            stage,
+            "--strip-components=1",
+        ], { encoding: "utf8" });
+        expect(extract.status, extract.stderr).toBe(0);
+        const sync = spawnSync("uv", ["sync", "--quiet", "--no-dev"], { cwd: stage, encoding: "utf8" });
+        expect(sync.status, sync.stderr).toBe(0);
+        expect(existsSync(join(stage, "README.md"))).toBe(true);
+        expect(existsSync(join(stage, "LICENSE"))).toBe(true);
+        expect(existsSync(join(stage, "web", "dist", "index.html"))).toBe(true);
+        expect(existsSync(join(stage, "web", "dist", "assets", "app.css"))).toBe(true);
+        expect(existsSync(join(stage, "web", "dist", "assets", "app.js"))).toBe(true);
+    });
 });
 describe("claude", () => {
     it("makes the repository its own single-plugin marketplace", () => {
@@ -91,12 +204,13 @@ describe("readme", () => {
         expect(body).toContain("`codex plugin add hello@hello`");
         expect(body).toContain("`gemini extensions install https://github.com/GoatInAHat/Hello-Tool`");
         expect(body).toContain("download `hello.mcpb` from the GitHub Release and double-click to install");
-        // The extension's three channels — unpacked from a checkout, the release assets (only the
-        // signed xpi installs itself), the store listings — and the pairing step that ends each.
+        // The extension's three channels — unpacked from a checkout, release assets (including an
+        // optional signed XPI), and store listings — and the pairing step that ends each.
         expect(body).toContain("Load unpacked → `hosts/browser/.output/chrome-mv3`");
         expect(body).toContain("web-ext run");
         expect(body).toContain("`hello-0.1.0-chrome.zip`, `hello-0.1.0-firefox.zip`, `hello-0.1.0-edge.zip`");
-        expect(body).toContain("Mozilla-signed `.xpi`");
+        expect(body).toContain("When Firefox signing credentials are configured, it also attaches a\n  Mozilla-signed `.xpi`");
+        expect(body).not.toContain("Chrome no longer keeps side-loaded unpacked");
         expect(body).toContain("`npx -y hello mcp --http --pair`");
     });
     it("names the one command that opens the web app, and only when that surface is selected", () => {

package/dist/surfaces/dsh.js

@@ -64,7 +64,10 @@ function patch(project, launch) {
     const serverName = projectName.dshServer(project.identity.name);
     const env = Object.fromEntries(Object.keys(configProperties(project)).map((key) => [
         envName(key),
-        jsExpression(`process.env.${envName(key)}`),
+        // Schemastery's dict rejects the empty object produced when every `!!js`
+        // value resolves to undefined. Keep every declared key string-valued;
+        // an absent optional credential remains the empty string for the child.
+        jsExpression(`process.env.${envName(key)} ?? ""`),
     ]));
     const row = {
         id: rowId(project),

package/dist/surfaces/dsh.test.js

@@ -61,8 +61,8 @@ describe("dsh", () => {
                             command: "npx",
                             args: ["-y", "hello.tool@0.1.0", "mcp"],
                             env: {
-                                APIKEY: "process.env.APIKEY",
-                                REGION: "process.env.REGION",
+                                APIKEY: 'process.env.APIKEY ?? ""',
+                                REGION: 'process.env.REGION ?? ""',
                             },
                             failOnStartupError: true,
                         },
@@ -72,7 +72,7 @@ describe("dsh", () => {
         ]);
         // DSH scrubs KEY/PASSWORD/SECRET/TOKEN names before spawning, so every config variable is
         // restated as the `!!js` expression DSH evaluates when it loads the patch.
-        expect(patch).toContain("APIKEY: !!js process.env.APIKEY");
+        expect(patch).toContain('APIKEY: !!js process.env.APIKEY ?? ""');
     });
     it("validates by booting the checkout keylessly, and carries only MCP tool calls", () => {
         // The local row is the same shape against this working tree, and stays out of `files`.

package/dist/surfaces/hermes-native.js

@@ -31,7 +31,7 @@ import { KERNEL_DIR } from "../bindings/typescript.js";
 import { projectName } from "../identity/name.js";
 import { isPortable } from "../model.js";
 import { includedOperations } from "../report/coverage.js";
-import { compact, configProperties, dataDirEnvName, envName, isSensitive, pypiName, requiredConfig, rootEnvName, } from "./shared.js";
+import { compact, configProperties, dataDirEnvName, envName, has, isSensitive, pypiName, requiredConfig, rootEnvName, } from "./shared.js";
 export const HOST_DIR = "hosts/hermes";
 /**
  * `hermes_cli/plugins.py` `SUPPORTED_MANIFEST_VERSION` is 2 and the loader parses every field
@@ -287,14 +287,16 @@ function importBlock(core) {
 /** Python core: the handler calls the author's own operation in-process. */
 function pythonCore(project) {
     const pkg = projectName.pythonPackage(project.identity.name);
+    const web = has(project, "web");
     return {
         stdlib: ["import asyncio", "import inspect"],
         external: [
             "from pydantic import BaseModel",
-            `from ${pkg}.ops import OPERATIONS`,
+            `from ${pkg}.ops import OPERATIONS${web ? " as AUTHORED_OPERATIONS" : ""}`,
             `from ${pkg}.toolfactory.config import context`,
+            ...(web ? [`from ${pkg}.toolfactory.web import OPERATION as WEB_OPERATION`] : []),
         ],
-        body: `def _operation(name: str) -> Any:
+        body: `${web ? "OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]\n\n\n" : ""}def _operation(name: str) -> Any:
     """Fail loudly if the core package and this plugin disagree on the operations."""
     for operation in OPERATIONS:
         if operation.name == name:

package/dist/surfaces/hermes-native.test.js

@@ -19,6 +19,12 @@ const echo = {
     requires: [],
 };
 const shoot = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+const web = {
+    name: "web",
+    description: "Open the generated operations page.",
+    inputSchema: { type: "object" },
+    requires: [],
+};
 function project(overrides = {}) {
     return {
         root: "/repo",
@@ -104,6 +110,21 @@ describe("hermes-native", () => {
         expect(pyproject.project.dependencies).toEqual(["hello>=1.2.0,<2"]);
         expect(pyproject.tool.uv.sources.hello).toEqual({ path: "../..", editable: true });
     });
+    it("gives a Python Hermes plugin the generated web operation used by its tool schema", () => {
+        const target = project({
+            tool: {
+                ...project().tool,
+                binding: "python",
+                surfaces: ["hermes-native", "cli", "mcp", "web"],
+            },
+            operations: [echo, web],
+        });
+        const native = emitted(target)[`${pluginDir(target)}/__init__.py`] ?? "";
+        expect(native).toContain("from hello.ops import OPERATIONS as AUTHORED_OPERATIONS");
+        expect(native).toContain("from hello.toolfactory.web import OPERATION as WEB_OPERATION");
+        expect(native).toContain("OPERATIONS = [*AUTHORED_OPERATIONS, WEB_OPERATION]");
+        expect(native).toContain('handler=_handler(schema["name"])');
+    });
     it("emits a fake-ctx test that registers and calls a real handler, no Hermes import", () => {
         const shim = emitted(project())[`${HOST_DIR}/tests/test_plugin.py`] ?? "";
         expect(shim).not.toMatch(/^\s*(import|from) hermes/m);

package/dist/surfaces/mcp-registry.js

@@ -7,6 +7,7 @@ import { pythonPackage } from "../bindings/python.js";
 import { KERNEL_DIR } from "../bindings/typescript.js";
 import { githubOwner, projectName } from "../identity/name.js";
 import { compact, configProperties, envName, has, isSensitive, json, npmName, pypiName, requiredConfig, } from "./shared.js";
+import { WEB_DIR } from "./web.js";
 export const SERVER_SCHEMA_ID = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json";
 /** `owner` from the identity file's GitHub repository, or the error every registry name needs it for. */
 function requireGithubOwner(identity) {
@@ -69,8 +70,18 @@ const DOCKER_PACKAGE_MANAGERS = {
  */
 export function dockerfileTemplate(project, label) {
     if (project.tool.binding === "python") {
+        const web = has(project, "web");
         return `# syntax=docker/dockerfile:1
-FROM ${UV_IMAGE} AS build
+${web
+            ? `FROM ${NODE_IMAGE} AS web
+WORKDIR /app
+COPY web/package.json web/package-lock.json ./web/
+RUN npm -C web ci
+COPY web ./web
+RUN npm -C web run build
+
+`
+            : ""}FROM ${UV_IMAGE} AS build
 WORKDIR /app
 COPY pyproject.toml ./
 COPY src ./src
@@ -82,7 +93,10 @@ WORKDIR /app
 COPY --from=build /app/.venv ./.venv
 COPY --from=build /app/src ./src
 COPY --from=build /app/pyproject.toml ./
-ENV PATH="/app/.venv/bin:$PATH"
+${web
+            ? `COPY --from=web /app/web/dist ./src/${pythonPackage(project)}/${WEB_DIR}
+`
+            : ""}ENV PATH="/app/.venv/bin:$PATH"
 ENTRYPOINT ${JSON.stringify(dockerEntrypoint(project))}
 `;
     }

package/dist/surfaces/mcp-registry.test.js

@@ -52,6 +52,11 @@ describe("mcp-registry Dockerfile", () => {
         expect(npmBuilt.Dockerfile).not.toContain("corepack enable");
         const py = files(project({ tool: { ...project().tool, binding: "python" } }));
         expect(py.Dockerfile).toContain('ENTRYPOINT ["python","-m","hello.toolfactory.mcp"]');
+        const pythonWeb = files(project({
+            tool: { ...project().tool, binding: "python", surfaces: ["mcp-registry", "web"] },
+        }));
+        expect(pythonWeb.Dockerfile).toContain("FROM node:24-alpine AS web");
+        expect(pythonWeb.Dockerfile).toContain("COPY --from=web /app/web/dist ./src/hello/web");
     });
 });
 describe("mcp-registry server.json oci package", () => {

package/dist/surfaces/mcpb.d.ts

@@ -8,4 +8,5 @@ export declare const MANIFEST_PATH = "hosts/mcpb/manifest.json";
 export declare const MCPB_PIN = "2.1.2";
 /** What `mcpb init` writes for a new bundle, and the floor the directory submission requires. */
 export declare const MANIFEST_VERSION = "0.2";
+export declare const UV_MANIFEST_VERSION = "0.4";
 export declare const surface: Surface;

package/dist/surfaces/mcpb.js

@@ -3,21 +3,21 @@
  * Anthropic's Connectors Directory takes a *local* server through.
  *
  * A bundle is a zip whose root is the server plus its dependencies plus a `manifest.json`. That
- * root is a staging tree, not the repository: the payload is exactly the npm tarball with
- * production dependencies installed into it, which `src/project/gate.ts` builds under
- * `dist/mcpb/` at package time. So this surface emits one tracked file — the manifest — and the
- * packaging step copies it in; nothing here duplicates what `npm pack` already decides ships.
+ * root is a staging tree, not the repository: TypeScript stages the npm tarball with production
+ * dependencies, while Python stages its `pyproject.toml` and source for host-managed uv. This
+ * surface emits one tracked file — the manifest — and the packaging step copies it in.
  *
- * `manifest_version` is `0.2`, which is what `mcpb init` itself writes for a new bundle (0.3 and
- * 0.4 exist, and add icon variants, localization and the `uv` server type — none of which this
- * projection uses) and the floor Anthropic's directory submission requires.
+ * TypeScript uses `manifest_version` `0.2`, the floor Anthropic's directory submission requires.
+ * Python uses v0.4's official `uv` server type, which keeps the bundle portable without shipping
+ * an interpreter or a virtual environment.
  *
  * `privacy_policies` (the URLs of the privacy policies of the services a bundle talks to, which
  * Anthropic's directory submission requires) comes from `tool.json` `mcpb.privacyPolicies`; a
  * homepage is not one, so nothing is invented when the key is absent.
  */
+import { kernelDir as pythonKernelDir, pythonPackage } from "../bindings/python.js";
 import { KERNEL_DIR, NODE_ENGINES } from "../bindings/typescript.js";
-import { compact, configProperties, envName, isSensitive, json, mcpVerdict } from "./shared.js";
+import { compact, configProperties, envName, has, isSensitive, json, mcpVerdict, } from "./shared.js";
 export const HOST_DIR = "hosts/mcpb";
 export const MANIFEST_PATH = `${HOST_DIR}/manifest.json`;
 /**
@@ -27,6 +27,7 @@ export const MANIFEST_PATH = `${HOST_DIR}/manifest.json`;
 export const MCPB_PIN = "2.1.2";
 /** What `mcpb init` writes for a new bundle, and the floor the directory submission requires. */
 export const MANIFEST_VERSION = "0.2";
+export const UV_MANIFEST_VERSION = "0.4";
 /**
  * The kernel's built `mcp` entry inside the bundle root — the same file the `mcp-registry`
  * surface's Dockerfile runs, because both start from the published package's `dist/`.
@@ -47,11 +48,9 @@ const USER_CONFIG_TYPES = new Set(["string", "number", "boolean"]);
 export const surface = {
     id: "mcpb",
     plan(project) {
-        if (project.tool.binding !== "typescript") {
-            // A python bundle would have to vendor an interpreter's site-packages into the bundle root
-            // (Claude Desktop ships Node, not Python), which `npm pack` plus `npm install` gives the
-            // TypeScript binding for free and `uv` gives no equivalent of.
-            throw new Error('Surface "mcpb" requires the typescript binding: a bundle root is the npm tarball with its production dependencies installed into it.');
+        const python = project.tool.binding === "python";
+        if (python && !has(project, "pypi")) {
+            throw new Error('Surface "mcpb" with the python binding requires the "pypi" surface, the canonical runtime distribution.');
         }
         const { identity } = project;
         const properties = configProperties(project);
@@ -70,7 +69,7 @@ export const surface = {
         // kernel reads its configuration from the same environment names it does everywhere else.
         const env = Object.fromEntries(Object.keys(properties).map((key) => [envName(key), `\${user_config.${key}}`]));
         const manifest = compact({
-            manifest_version: MANIFEST_VERSION,
+            manifest_version: python ? UV_MANIFEST_VERSION : MANIFEST_VERSION,
             name: identity.name,
             display_name: identity.name,
             version: identity.version,
@@ -83,15 +82,29 @@ export const surface = {
             privacy_policies: project.tool.mcpb?.privacyPolicies,
             keywords: identity.keywords,
             server: {
-                type: "node",
-                entry_point: entryPoint(),
+                type: python ? "uv" : "node",
+                entry_point: python ? `${pythonKernelDir(project)}/mcp.py` : entryPoint(),
                 // `${__dirname}` is the installed bundle's own directory: an install is an unzip
-                // somewhere else, so nothing in the launch may be repository-relative.
-                mcp_config: compact({
-                    command: "node",
-                    args: [`\${__dirname}/${entryPoint()}`],
-                    env: Object.keys(env).length ? env : undefined,
-                }),
+                // somewhere else, so nothing in the launch may be repository-relative. For `uv`, this
+                // delegates dependency resolution and Python provisioning to the host's supported runtime.
+                mcp_config: python
+                    ? compact({
+                        command: "uv",
+                        args: [
+                            "run",
+                            "--directory",
+                            "${__dirname}",
+                            "python",
+                            "-m",
+                            `${pythonPackage(project)}.toolfactory.mcp`,
+                        ],
+                        env: Object.keys(env).length ? env : undefined,
+                    })
+                    : compact({
+                        command: "node",
+                        args: [`\${__dirname}/${entryPoint()}`],
+                        env: Object.keys(env).length ? env : undefined,
+                    }),
             },
             // Exactly the operations the kernel's own `tools/list` serves (§4.3): the manifest is what
             // the install UI shows before the server ever runs, so it must not promise more.
@@ -99,7 +112,7 @@ export const surface = {
                 .filter((operation) => mcpVerdict(operation).kind !== "excluded")
                 .map((operation) => compact({ name: operation.name, description: operation.description })),
             user_config: userConfig.length ? Object.fromEntries(userConfig) : undefined,
-            compatibility: { runtimes: { node: NODE_ENGINES } },
+            compatibility: { runtimes: python ? { python: ">=3.11" } : { node: NODE_ENGINES } },
         });
         return [{ kind: "file", path: MANIFEST_PATH, content: json(manifest) }];
     },