toolfactory 0.1.1 → 0.1.2

package/src/surfaces/distribution.test.ts

@@ -1,9 +1,13 @@
+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 type { Operation, Project, SurfaceId } from "../model.js";
 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: Operation = { name: "echo", inputSchema: { type: "object" }, requires: [] };
@@ -52,6 +56,134 @@ describe("npm", () => {
       "--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", () => {
@@ -103,14 +235,17 @@ describe("readme", () => {
     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`");
   });
 

package/src/surfaces/dsh.test.ts

@@ -68,8 +68,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,
             },
@@ -79,7 +79,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", () => {

package/src/surfaces/dsh.ts

@@ -71,7 +71,10 @@ function patch(project: Project, launch: { command: string; args: string[] }): s
   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 = {

package/src/surfaces/hermes-native.test.ts

@@ -21,6 +21,12 @@ const echo: Operation = {
   requires: [],
 };
 const shoot: Operation = { name: "shoot", inputSchema: { type: "object" }, requires: ["browser"] };
+const web: Operation = {
+  name: "web",
+  description: "Open the generated operations page.",
+  inputSchema: { type: "object" },
+  requires: [],
+};
 
 function project(overrides: Partial<Project> = {}): Project {
   return {
@@ -128,6 +134,22 @@ describe("hermes-native", () => {
     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/src/surfaces/hermes-native.ts

@@ -36,6 +36,7 @@ import {
   configProperties,
   dataDirEnvName,
   envName,
+  has,
   isSensitive,
   pypiName,
   requiredConfig,
@@ -333,14 +334,16 @@ interface PluginCore {
 /** Python core: the handler calls the author's own operation in-process. */
 function pythonCore(project: Project): PluginCore {
   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/src/surfaces/mcp-registry.test.ts

@@ -65,6 +65,14 @@ describe("mcp-registry Dockerfile", () => {
 
     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");
   });
 });
 

package/src/surfaces/mcp-registry.ts

@@ -18,6 +18,7 @@ import {
   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";
@@ -94,8 +95,20 @@ const DOCKER_PACKAGE_MANAGERS: Record<
  */
 export function dockerfileTemplate(project: Project, label: string): string {
   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
@@ -107,7 +120,12 @@ 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/src/surfaces/mcpb.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { NODE_ENGINES } from "../bindings/typescript.js";
 import type { Operation, Project } from "../model.js";
-import { MCPB_PIN, surface as mcpb } from "./mcpb.js";
+import { MCPB_PIN, surface as mcpb, UV_MANIFEST_VERSION } from "./mcpb.js";
 
 const echo: Operation = {
   name: "echo",
@@ -95,11 +95,38 @@ describe("mcpb", () => {
     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 = {
+      ...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/src/surfaces/mcpb.ts

@@ -3,22 +3,30 @@
  * 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 type { Project, Surface } from "../model.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`;
@@ -31,6 +39,7 @@ 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`
@@ -55,12 +64,10 @@ const USER_CONFIG_TYPES = new Set(["string", "number", "boolean"]);
 export const surface: Surface = {
   id: "mcpb",
   plan(project: 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.
+    const python = project.tool.binding === "python";
+    if (python && !has(project, "pypi")) {
       throw new Error(
-        'Surface "mcpb" requires the typescript binding: a bundle root is the npm tarball with its production dependencies installed into it.',
+        'Surface "mcpb" with the python binding requires the "pypi" surface, the canonical runtime distribution.',
       );
     }
     const { identity } = project;
@@ -82,7 +89,7 @@ export const surface: Surface = {
       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,
@@ -95,15 +102,29 @@ export const surface: 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.
@@ -111,7 +132,7 @@ export const surface: 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) }];
   },

package/src/surfaces/npm.ts

@@ -4,9 +4,9 @@
  */
 
 import { githubSlug } from "../hosts/github.js";
-import type { Surface } from "../model.js";
+import type { Project, Surface } from "../model.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";
 
 /**
@@ -22,14 +22,31 @@ function repositoryField(
   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: Project): string {
+  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: 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,
@@ -41,21 +58,36 @@ export const surface: Surface = {
       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" as const, path: launcher, content: pythonLauncher(project) }]
+        : []),
+      {
+        kind: "merge" as const,
+        path: "package.json",
+        format: "json" as const,
+        patch,
+        owned: ["bin", "files"],
+      },
+    ];
   },
   validate(project) {
     return [

package/src/surfaces/pypi.ts

@@ -29,19 +29,43 @@ export const surface: 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`,
+                      ],
+                    },
                   },
                 },
               },