toolfactory 0.1.1 → 0.2.0

package/src/surfaces/mcp-registry.ts

@@ -6,7 +6,7 @@
 import { pythonPackage } from "../bindings/python.js";
 import { KERNEL_DIR } from "../bindings/typescript.js";
 import { githubOwner, projectName } from "../identity/name.js";
-import type { Project, Surface } from "../model.js";
+import type { PlannedFile, Project, Surface } from "../model.js";
 import {
   compact,
   configProperties,
@@ -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";
@@ -87,6 +88,44 @@ const DOCKER_PACKAGE_MANAGERS: Record<
   },
 };
 
+const DOCKERIGNORE_BEGIN = "# tf:dockerignore";
+const DOCKERIGNORE_END = "# /tf:dockerignore";
+
+/** Build context hygiene is generated, while the rest of `.dockerignore` stays author-owned. */
+function dockerignore(): PlannedFile {
+  return {
+    kind: "region",
+    path: ".dockerignore",
+    regions: [
+      {
+        begin: DOCKERIGNORE_BEGIN,
+        end: DOCKERIGNORE_END,
+        content: `
+.git/
+.env
+.env.*
+!.env.example
+node_modules/
+**/node_modules/
+.venv/
+**/.venv/
+dist/
+coverage/
+test-results/
+playwright-report/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+**/__pycache__/
+.vscode-test/
+`,
+      },
+    ],
+    template: `${DOCKERIGNORE_BEGIN}\n${DOCKERIGNORE_END}\n\n# Add local build inputs to exclude below.\n`,
+  };
+}
+
 /**
  * The root `Dockerfile`, stdio only (§4.1: no `--host` flag exists to bind past loopback), one
  * multi-stage build per binding. `label` is `server.json`'s own `name`, byte for byte — the MCP
@@ -94,20 +133,38 @@ 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 pyproject.toml ./
-COPY src ./src
-RUN uv sync --no-dev
+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
+# pyproject metadata can name README, license, and other package assets; copy the project without
+# assuming optional metadata files exist.
+COPY . .
+${web ? "COPY --from=web /app/web/dist ./web/dist\n" : ""}RUN uv sync --no-dev
+RUN mkdir /app/runtime && cp pyproject.toml /app/runtime/ && cp -R src /app/runtime/src && for path in README README.md README.rst LICENSE LICENSE.md LICENSE.txt NOTICE NOTICE.md NOTICE.txt; do if [ -f "$path" ]; then cp "$path" /app/runtime/; fi; done
 
 FROM ${PYTHON_IMAGE}
 LABEL io.modelcontextprotocol.server.name="${label}"
 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"
+COPY --from=build /app/runtime/ ./
+${
+  web
+    ? `COPY --from=web /app/web/dist ./src/${pythonPackage(project)}/${WEB_DIR}
+`
+    : ""
+}ENV PATH="/app/.venv/bin:$PATH"
 ENTRYPOINT ${JSON.stringify(dockerEntrypoint(project))}
 `;
   }
@@ -185,6 +242,7 @@ export const surface: Surface = {
     return [
       { kind: "file", path: "server.json", content: json(server) },
       { kind: "file", path: "Dockerfile", content: dockerfileTemplate(project, name) },
+      dockerignore(),
     ];
   },
 };

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/openclaw-native.test.ts

@@ -1,7 +1,11 @@
 import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { scaffoldDrift } from "../hosts/openclaw.js";
 import type { Operation, Project } from "../model.js";
+import { apply } from "../project/apply.js";
 import { computeCoverage, renderCoverageMarkdown } from "../report/coverage.js";
 import { HOST_DIR, OPENCLAW_ADDITIONS, OPENCLAW_SCAFFOLD, surface } from "./openclaw-native.js";
 
@@ -82,6 +86,39 @@ function emitted(target: Project): Record<string, string> {
 }
 
 describe("openclaw-native", () => {
+  it("keeps hand-authored package and manifest extensions through regeneration", () => {
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-openclaw-"));
+    const target = { ...project(), root };
+    apply(root, surface.plan(target), "0.1.0");
+    const packagePath = join(root, HOST_DIR, "package.json");
+    const manifestPath = join(root, HOST_DIR, "openclaw.plugin.json");
+    writeFileSync(
+      packagePath,
+      JSON.stringify({
+        ...JSON.parse(readFileSync(packagePath, "utf8")),
+        scripts: { custom: "node custom.mjs" },
+        exports: { "./native": "./src/native.ts" },
+      }),
+    );
+    writeFileSync(
+      manifestPath,
+      JSON.stringify({
+        ...JSON.parse(readFileSync(manifestPath, "utf8")),
+        contracts: { customProviders: ["native"] },
+        nativeField: true,
+      }),
+    );
+    apply(root, surface.plan(target), "0.1.0");
+    expect(JSON.parse(readFileSync(packagePath, "utf8"))).toMatchObject({
+      scripts: { custom: "node custom.mjs" },
+      exports: { "./native": "./src/native.ts" },
+    });
+    expect(JSON.parse(readFileSync(manifestPath, "utf8"))).toMatchObject({
+      contracts: { customProviders: ["native"] },
+      nativeField: true,
+    });
+  });
+
   it("projects only the operations OpenClaw can run and pins the scaffold in one place", () => {
     const files = emitted(project());
     const manifest = JSON.parse(files[`${HOST_DIR}/openclaw.plugin.json`] ?? "{}");

package/src/surfaces/openclaw-native.ts

@@ -238,7 +238,11 @@ function pluginInspector(project: Project, operations: Operation[]): Record<stri
   };
 }
 
-function packageJson(project: Project, operations: Operation[], kase?: E2eCase): string {
+function packageJson(
+  project: Project,
+  operations: Operation[],
+  kase?: E2eCase,
+): Record<string, unknown> {
   // The core is imported in-process only when an operation reaches this surface.
   const core =
     project.tool.binding === "typescript" && operations.length
@@ -246,32 +250,30 @@ function packageJson(project: Project, operations: Operation[], kase?: E2eCase):
       : undefined;
   const extra = project.tool.openclaw;
   const e2e = kase ? { "test:e2e": OPENCLAW_ADDITIONS.e2eScript } : undefined;
-  return json(
-    compact({
-      name: projectName.openclawPackage(project.identity.name),
-      version: project.identity.version ?? "0.0.0",
-      description: pluginDescription(project),
-      type: "module",
-      private: OPENCLAW_SCAFFOLD.private,
-      scripts: { ...OPENCLAW_SCAFFOLD.scripts, ...e2e },
-      files: OPENCLAW_SCAFFOLD.files,
-      peerDependencies: { openclaw: pluginApi(project), ...extra?.peerDependencies },
-      dependencies: { ...OPENCLAW_SCAFFOLD.dependencies, ...core, ...extra?.dependencies },
-      devDependencies: {
-        ...OPENCLAW_SCAFFOLD.devDependencies,
-        ...(kase ? { "@copilotkit/aimock": OPENCLAW_ADDITIONS.aimock } : {}),
-        ...extra?.devDependencies,
-      },
-      openclaw: {
-        extensions: [OPENCLAW_SCAFFOLD.entry],
-        compat: { pluginApi: pluginApi(project) },
-        build: { openclawVersion: OPENCLAW_SCAFFOLD.openclawVersion },
-      },
-      pluginInspector: expectedRegistrations(project, operations).length
-        ? pluginInspector(project, operations)
-        : undefined,
-    }),
-  );
+  return compact({
+    name: projectName.openclawPackage(project.identity.name),
+    version: project.identity.version ?? "0.0.0",
+    description: pluginDescription(project),
+    type: "module",
+    private: OPENCLAW_SCAFFOLD.private,
+    scripts: { ...OPENCLAW_SCAFFOLD.scripts, ...e2e },
+    files: OPENCLAW_SCAFFOLD.files,
+    peerDependencies: { openclaw: pluginApi(project), ...extra?.peerDependencies },
+    dependencies: { ...OPENCLAW_SCAFFOLD.dependencies, ...core, ...extra?.dependencies },
+    devDependencies: {
+      ...OPENCLAW_SCAFFOLD.devDependencies,
+      ...(kase ? { "@copilotkit/aimock": OPENCLAW_ADDITIONS.aimock } : {}),
+      ...extra?.devDependencies,
+    },
+    openclaw: {
+      extensions: [OPENCLAW_SCAFFOLD.entry],
+      compat: { pluginApi: pluginApi(project) },
+      build: { openclawVersion: OPENCLAW_SCAFFOLD.openclawVersion },
+    },
+    pluginInspector: expectedRegistrations(project, operations).length
+      ? pluginInspector(project, operations)
+      : undefined,
+  }) as Record<string, unknown>;
 }
 
 /**
@@ -281,7 +283,7 @@ function packageJson(project: Project, operations: Operation[], kase?: E2eCase):
  * config UI learns which keys to mask, from the same `x-toolfactory.sensitive` declaration every
  * other surface reads.
  */
-function pluginManifest(project: Project, operations: Operation[]): string {
+function pluginManifest(project: Project, operations: Operation[]): Record<string, unknown> {
   const sensitive = Object.entries(configProperties(project))
     .filter(([, property]) => isSensitive(property))
     .map(([key]) => [key, { sensitive: true }]);
@@ -289,21 +291,19 @@ function pluginManifest(project: Project, operations: Operation[]): string {
     registration.contract,
     registration.ids,
   ]);
-  return json(
-    compact({
-      id: project.identity.name,
-      name: displayName(project.identity.name),
-      description: pluginDescription(project),
-      version: project.identity.version ?? "0.0.0",
-      configSchema: configSchema(project),
-      uiHints: sensitive.length ? Object.fromEntries(sensitive) : undefined,
-      activation: activation(project),
-      contracts: {
-        tools: operations.map((operation) => operation.name),
-        ...Object.fromEntries(declared),
-      },
-    }),
-  );
+  return compact({
+    id: project.identity.name,
+    name: displayName(project.identity.name),
+    description: pluginDescription(project),
+    version: project.identity.version ?? "0.0.0",
+    configSchema: configSchema(project),
+    uiHints: sensitive.length ? Object.fromEntries(sensitive) : undefined,
+    activation: activation(project),
+    contracts: {
+      tools: operations.map((operation) => operation.name),
+      ...Object.fromEntries(declared),
+    },
+  }) as Record<string, unknown>;
 }
 
 function executeBody(project: Project, operation: Operation): string {
@@ -933,9 +933,10 @@ export const surface: Surface = {
     const kase = e2eCase(project, operations);
     return [
       {
-        kind: "file",
+        kind: "merge",
         path: `${HOST_DIR}/package.json`,
-        content: packageJson(project, operations, kase),
+        format: "json",
+        patch: packageJson(project, operations, kase),
       },
       {
         kind: "file",
@@ -955,9 +956,10 @@ export const surface: Surface = {
         content: OPENCLAW_SCAFFOLD.vitestConfig,
       },
       {
-        kind: "file",
+        kind: "merge",
         path: `${HOST_DIR}/openclaw.plugin.json`,
-        content: pluginManifest(project, operations),
+        format: "json",
+        patch: pluginManifest(project, operations),
       },
       {
         kind: "region",

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`,
+                      ],
+                    },
                   },
                 },
               },