@mediamonks/canopy-cli 0.7.31 → 0.7.32

package/dist/{deploy-B-znPE-v.mjs → deploy-Ka2lHkyy.mjs}

@@ -2,6 +2,7 @@ import { a as projectDirArgs, c as resolveProject, l as stagingUrl, n as siteCon
 import { i as apiRequest, n as apiDataRequest, o as withContext, r as apiDownload } from "./api-C4rMhE7i.mjs";
 import { a as unwrap, r as reportErrors, t as formatDateTime } from "./ui-C_jSc1Kz.mjs";
 import { n as migrateProject, r as readMigrationFiles, t as describeMigrateResult } from "./migrations-Czlcddyz.mjs";
+import { builtinModules } from "node:module";
 import { defineCommand } from "citty";
 import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -27,7 +28,7 @@ async function bundleWorker(projectDir, entry) {
 			format: "esm",
 			target: "es2022",
 			packages: "bundle",
-			external: ["node:*"],
+			plugins: [nodeBuiltins],
 			logLevel: "silent"
 		});
 		return new Uint8Array(readFileSync(outfile));
@@ -38,6 +39,115 @@ async function bundleWorker(projectDir, entry) {
 		});
 	}
 }
+/** Bare names Node resolves to a built-in (`fs`, `fs/promises`, …). */
+const BARE_BUILTINS = new Set(builtinModules.filter((name) => !name.startsWith("_")));
+/**
+* Built-ins both hosts provide, each with a default export: Node, and workerd
+* at the dispatch scripts' compatibility date (2026-05-01, nodejs_compat —
+* probed with a worker importing every one; several are stubs that throw only
+* when called). Missing on workerd: `sea`, `test/reporters`. Left out on
+* purpose: `sqlite` (experimental on Node) and `test`.
+*/
+const HOSTED_BUILTINS = /* @__PURE__ */ new Set([
+	"assert",
+	"assert/strict",
+	"async_hooks",
+	"buffer",
+	"child_process",
+	"cluster",
+	"console",
+	"constants",
+	"crypto",
+	"dgram",
+	"diagnostics_channel",
+	"dns",
+	"dns/promises",
+	"domain",
+	"events",
+	"fs",
+	"fs/promises",
+	"http",
+	"http2",
+	"https",
+	"inspector",
+	"inspector/promises",
+	"module",
+	"net",
+	"os",
+	"path",
+	"path/posix",
+	"path/win32",
+	"perf_hooks",
+	"process",
+	"punycode",
+	"querystring",
+	"readline",
+	"readline/promises",
+	"repl",
+	"stream",
+	"stream/consumers",
+	"stream/promises",
+	"stream/web",
+	"string_decoder",
+	"sys",
+	"timers",
+	"timers/promises",
+	"tls",
+	"trace_events",
+	"tty",
+	"url",
+	"util",
+	"util/types",
+	"v8",
+	"vm",
+	"wasi",
+	"worker_threads",
+	"zlib"
+]);
+const REQUIRE_NAMESPACE = "canopy-node-require";
+/**
+* Node built-ins are the host's, not the bundle's: the GCP runtime is Node and
+* Cloudflare dispatch scripts run with nodejs_compat. A `neutral` build cannot
+* resolve them at all, so every import of one — `node:fs` or bare `fs`, as Node
+* itself treats them — stays external under its `node:` name.
+*
+* A CommonJS `require()` of one cannot simply stay external: in an ESM bundle
+* esbuild turns it into a `__require` shim that throws "Dynamic require of …
+* is not supported" when it runs. Neither host offers a `require` to an ES
+* module, so the call is routed to a tiny ES module that re-exports the
+* built-in through a static `import`. The AI SDK needs this: `ai` reaches
+* `@vercel/oidc`, whose CommonJS build requires `fs`, `os` and `path` at load.
+*
+* That turns a lazy require — often an optional one in a try/catch — into an
+* import made at load, and Cloudflare refuses a script importing a module it
+* lacks. So only HOSTED_BUILTINS are rewritten; a require of any other
+* built-in keeps the throwing shim, which fails only if that line runs.
+*/
+const nodeBuiltins = {
+	name: "canopy-node-builtins",
+	setup(build) {
+		build.onResolve({ filter: /^(node:)?[a-z_][a-z0-9_/]*$/ }, (args) => {
+			const prefixed = args.path.startsWith("node:");
+			const name = prefixed ? args.path.slice(5) : args.path;
+			if (!prefixed && !BARE_BUILTINS.has(name)) return void 0;
+			if (args.kind === "require-call" && HOSTED_BUILTINS.has(name)) return {
+				path: name,
+				namespace: REQUIRE_NAMESPACE
+			};
+			return {
+				path: `node:${name}`,
+				external: true
+			};
+		});
+		build.onLoad({
+			filter: /.*/,
+			namespace: REQUIRE_NAMESPACE
+		}, (args) => ({
+			contents: `export * from "node:${args.path}";\nexport { default } from "node:${args.path}";\n`,
+			loader: "js"
+		}));
+	}
+};
 //#endregion
 //#region src/deploy.ts
 /**

package/dist/docs/agent-tools.md

@@ -101,7 +101,7 @@ wrote for another MCP server carry over as they are.
 A tool set you already use with the AI SDK works too. Put it in the same list:
 
 ```ts
-import { tool } from "@ai-sdk/provider-utils";
+import { tool } from "ai";
 
 const aiTools = {
   weather: tool({
@@ -114,9 +114,7 @@ const aiTools = {
 mountMcpTools(app, [...myTools, aiTools]);
 ```
 
-Import `tool` from `@ai-sdk/provider-utils` in a backend: the full `ai`
-package doesn't bundle for Canopy backends yet. Tools without `execute` (ones
-the AI provider runs itself) are left out.
+Tools without `execute` (ones the AI provider runs itself) are left out.
 
 ## Write good tools
 
@@ -210,4 +208,5 @@ an agent (`agent`), in any route. Two limits apply to your own server:
   60 seconds.
 - Agent calls show up in your backend's logs like any other request.
 
-See [canopy mcp](https://docs.canopy.website/cli/mcp) for every flag.
+See the [SDK reference](https://docs.canopy.website/sdk/mcp) for every option and [canopy mcp](https://docs.canopy.website/cli/mcp)
+for every flag.

package/dist/docs/index.json

@@ -363,6 +363,11 @@
           "title": "Realtime",
           "summary": "Live updates between the people using your app — subscribe to a topic, publish to it, no backend needed."
         },
+        {
+          "slug": "sdk-mcp",
+          "title": "Agent tools (MCP)",
+          "summary": "\"@mediamonks/canopy/mcp — serve your backend's tools to AI agents: mountMcpTools, createMcpToolsHandler, MCP_PATH and mcpCaller.\""
+        },
         {
           "slug": "sdk-google",
           "title": "Google",

package/dist/docs/sdk-mcp.md

@@ -0,0 +1,222 @@
+---
+title: Agent tools (MCP)
+description: "@mediamonks/canopy/mcp — serve your backend's tools to AI agents: mountMcpTools, createMcpToolsHandler, MCP_PATH and mcpCaller."
+---
+
+`@mediamonks/canopy/mcp` turns your backend into a set of MCP tools that AI
+agents call through `canopy mcp serve`, always as the signed-in Monk running
+them. It is a separate entry of the SDK, for backend code only: browser
+bundles never include it.
+
+```ts
+import { createMcpToolsHandler, MCP_PATH, mcpCaller, mountMcpTools } from "@mediamonks/canopy/mcp";
+```
+
+For the why and the how-to, read the [Agent tools guide](https://docs.canopy.website/guides/agent-tools).
+This page lists the exports and what they accept.
+
+## mountMcpTools(app, tools, options?)
+
+Serves `tools` at `MCP_PATH` on a Hono app. Route tools run this same app's
+routes.
+
+```ts
+import { mountMcpTools } from "@mediamonks/canopy/mcp";
+import { z } from "zod";
+
+mountMcpTools(app, [
+  {
+    name: "list_notes",
+    description: "List the current user's notes, newest first",
+    route: "GET /api/notes",
+    annotations: { readOnlyHint: true },
+  },
+  {
+    name: "summarise",
+    description: "Summarise a note",
+    inputSchema: z.object({ id: z.string() }),
+    handler: async ({ id }, ctx) => summarise(ctx.env, id),
+  },
+]);
+```
+
+- `app` — your Hono app, or anything with `all(path, handler)` and
+  `fetch(request, env, ctx)`.
+- `tools` — a list of [tool definitions](#tool-definitions) and
+  [AI SDK tool sets](#vercel-ai-sdk-tool-sets), mixed.
+- `options` — optional `{ name?, version? }`: the server name and version MCP
+  clients see. The name defaults to your project's slug.
+
+## createMcpToolsHandler(tools, options?)
+
+The same thing without Hono: returns a handler you route `MCP_PATH` to
+yourself.
+
+```ts
+import { createMcpToolsHandler, MCP_PATH } from "@mediamonks/canopy/mcp";
+
+const tools = createMcpToolsHandler(myTools, { app });
+
+export default {
+  fetch(request, env, ctx) {
+    if (new URL(request.url).pathname === MCP_PATH) return tools(request, env, ctx);
+    return app.fetch(request, env, ctx);
+  },
+};
+```
+
+**Returns** `(request, env?, executionCtx?) => Promise<Response>`. Pass the
+backend's `env` so handlers and route tools see `env.USER`, `env.CANOPY` and
+your secrets.
+
+**Options:** `{ app?, name?, version? }`. `app` is required when the list has
+route tools: they run its routes.
+
+Each request gets a fresh, stateless MCP server built on the official
+`@modelcontextprotocol/server`. It speaks both the current MCP protocol and
+the 2025 revision, so older clients work too.
+
+## Tool definitions
+
+A tool is an object in the MCP specification's shape, plus either a `handler`
+or a `route`:
+
+| Field          | Type                           |                                                                                       |
+| -------------- | ------------------------------ | ------------------------------------------------------------------------------------- |
+| `name`         | `string`                       | Required. Unique; letters, digits, `_`, `-` and `.`, at most 128.                     |
+| `description`  | `string`                       | What it does and when to use it. The agent reads this.                                |
+| `title`        | `string`                       | A display name.                                                                       |
+| `inputSchema`  | JSON Schema or Standard Schema | The arguments. Defaults to "no arguments".                                            |
+| `outputSchema` | JSON Schema or Standard Schema | Shape of the structured result, if you want clients to rely on it.                    |
+| `annotations`  | `McpToolAnnotations`           | Hints: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`. |
+| `handler`      | `(args, ctx) => unknown`       | Runs the tool.                                                                        |
+| `route`        | `"<METHOD> /path"`             | Runs one of your routes instead.                                                      |
+
+**Schemas** can be plain JSON Schema or any schema that implements Standard
+Schema with JSON Schema output: Zod 4, Valibot (with `toStandardJsonSchema`),
+ArkType. Arguments are validated against `inputSchema` before your handler or
+route runs. Invalid arguments come back to the agent as an error naming the
+field.
+
+**Annotations** matter to agents. Mark tools that change nothing with
+`readOnlyHint: true`. Unmarked tools are treated as possibly destructive, and
+clients usually ask the user before calling them.
+
+### Handler tools
+
+```ts
+{
+  name: "add_comment",
+  inputSchema: z.object({ noteId: z.string(), text: z.string().max(2000) }),
+  handler: async ({ noteId, text }, ctx) => {
+    const env = ctx.env as Env; // your backend's Env type
+    const canopy = createCanopy({ fetch: env.CANOPY.fetch.bind(env.CANOPY) });
+    return canopy.db.collection("comments").insert({ noteId, text, by: ctx.user?.email });
+  },
+}
+```
+
+What the handler returns becomes the result:
+
+- an object — sent as structured content, with a JSON text copy;
+- a string — sent as text;
+- an MCP `CallToolResult` (`{ content, structuredContent?, isError? }`) —
+  sent as is;
+- nothing — an empty result.
+
+Throw to report a failure. The agent gets a tool error with your message.
+
+**`ctx`** (`McpToolContext`):
+
+- `user` — the signed-in Monk (`{ sub, email, name }`), or `null`.
+- `agent` — `true` when an AI agent made the call through `canopy mcp`.
+- `toolCallId` — this call's id, for logs.
+- `signal` — an `AbortSignal`, aborted when the agent cancels.
+- `request` — the HTTP request the call arrived on, without platform
+  credentials.
+- `env` — your backend's env, as routes get it. Typed `unknown`: cast it to
+  your `Env`.
+
+`canopy.*` calls from a handler act as the user, as they would for that
+person's browser.
+
+### Route tools
+
+```ts
+{ name: "get_note", route: "GET /api/notes/:id", inputSchema: z.object({ id: z.string() }) }
+```
+
+The route runs in-process, with the same `env` and identity:
+
+- `:name` segments of the path are filled from the argument of that name. A
+  missing one is a tool error.
+- `GET` and `DELETE`: the other arguments become the query string (arrays
+  repeat the key, objects are sent as JSON).
+- `POST`, `PUT`, `PATCH`: the other arguments become a JSON body.
+- A 2xx JSON response becomes the result (structured when it's an object).
+  Other 2xx bodies become text.
+- Any other status becomes a tool error: `HTTP 403: {"error":"not_owner"}`.
+
+### Vercel AI SDK tool sets
+
+Put a tool set in the list as it is. Each key becomes a tool name:
+
+```ts
+import { tool } from "ai";
+
+const aiTools = {
+  weather: tool({
+    description: "Weather in a city",
+    inputSchema: z.object({ city: z.string() }),
+    execute: async ({ city }) => ({ city, tempC: 21 }),
+  }),
+};
+
+mountMcpTools(app, [...myTools, aiTools]);
+```
+
+`execute` gets the arguments and `{ toolCallId, abortSignal, messages: [] }`.
+Tools without `execute` are skipped. If the result is a stream, its last value
+is the answer.
+
+## MCP_PATH
+
+`"/__canopy/mcp"` — the one path on your backend that agents reach. Mount your
+own MCP server there if you don't use `mountMcpTools`. It must answer on that
+single URL with MCP's streamable HTTP transport.
+
+## mcpCaller(request, env?)
+
+Who is calling, in any route or in your own MCP server:
+
+```ts
+app.get("/api/notes", (c) => {
+  const { user, agent } = mcpCaller(c.req.raw, c.env);
+  // agent is true for a tools call that ran this route
+});
+```
+
+**Returns** `McpCaller`: `{ user: McpUser | null, agent: boolean }`.
+`user` comes from `env.USER`. Without `env`, it falls back to the identity the
+platform attached to the request.
+
+## When the tool list is wrong
+
+The list is checked on the first request. A duplicate or invalid name, a tool
+with neither or both of `handler` and `route`, a route tool without `app`, or
+a schema that can't describe itself as JSON Schema makes the tools endpoint
+answer `500 invalid_tools`, naming the tool. `canopy mcp add` shows that
+message. The rest of your backend keeps working.
+
+## Limits
+
+`canopy mcp serve` holds back tools whose description is over 2,048
+characters or whose input schema is over 16 KB, shows at most 64 tools, turns
+results over 512 KB into an error, and stops a call after 60 seconds.
+
+## Types
+
+All exported from `@mediamonks/canopy/mcp`: `McpTool`, `McpHandlerTool`,
+`McpRouteTool`, `McpToolAnnotations`, `McpToolContext`, `McpToolsInput`,
+`McpToolsOptions`, `McpCaller`, `McpUser`, `AiSdkToolSet`, `ToolSchema`,
+`JsonSchema`, `StandardSchemaLike`, `FetchApp`, `HttpMethod`.

package/dist/{docs-YD4z70gq.mjs → docs-CtNH5kbN.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-CiKTWo0_.mjs";
+import { t as version } from "./package-YGjjin4p.mjs";
 import { n as siteConfig } from "./site-DM2J10CB.mjs";
 import { i as latestKnownVersion, r as compareSemver } from "./version-check-CcsA1QjI.mjs";
 import { r as reportErrors } from "./ui-C_jSc1Kz.mjs";

package/dist/{feedback-Cd7Rvg9a.mjs → feedback-_L3vqktY.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-CiKTWo0_.mjs";
+import { t as version } from "./package-YGjjin4p.mjs";
 import { a as projectDirArgs, c as resolveProject, d as tryResolveProject, n as siteConfig, u as tryReadCanopyJson } from "./site-DM2J10CB.mjs";
 import { a as apiUpload, i as apiRequest, r as apiDownload } from "./api-C4rMhE7i.mjs";
 import { r as reportErrors, t as formatDateTime } from "./ui-C_jSc1Kz.mjs";

package/dist/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as version } from "./package-CiKTWo0_.mjs";
+import { t as version } from "./package-YGjjin4p.mjs";
 import { r as siteHeaderLine, t as setInvocationProfile } from "./site-DM2J10CB.mjs";
 import { a as notifyOfUpdate, o as runRefresh } from "./version-check-CcsA1QjI.mjs";
 import { defineCommand, runMain } from "citty";
@@ -70,25 +70,25 @@ const main = defineCommand({
 		projects: () => import("./projects-CN2YhCZn.mjs").then((m) => m.projectsCommand),
 		delete: () => import("./projects-CN2YhCZn.mjs").then((m) => m.deleteCommand),
 		dev: () => import("./dev-MoHHjQh1.mjs").then((m) => m.devCommand),
-		deploy: () => import("./deploy-B-znPE-v.mjs").then((m) => m.deployCommand),
-		promote: () => import("./deploy-B-znPE-v.mjs").then((m) => m.promoteCommand),
+		deploy: () => import("./deploy-Ka2lHkyy.mjs").then((m) => m.deployCommand),
+		promote: () => import("./deploy-Ka2lHkyy.mjs").then((m) => m.promoteCommand),
 		staging: () => import("./staging-BZVty57b.mjs").then((m) => m.stagingCommand),
-		rollback: () => import("./deploy-B-znPE-v.mjs").then((m) => m.rollbackCommand),
-		download: () => import("./deploy-B-znPE-v.mjs").then((m) => m.downloadCommand),
+		rollback: () => import("./deploy-Ka2lHkyy.mjs").then((m) => m.rollbackCommand),
+		download: () => import("./deploy-Ka2lHkyy.mjs").then((m) => m.downloadCommand),
 		token: () => import("./token-HHlUR0CF.mjs").then((m) => m.tokenCommand),
 		egress: () => import("./egress-If_Gsx_M.mjs").then((m) => m.egressCommand),
 		secrets: () => import("./secrets-BSEjZnxg.mjs").then((m) => m.secretsCommand),
 		schedule: () => import("./schedule-C5lMf3ny.mjs").then((m) => m.scheduleCommand),
-		feedback: () => import("./feedback-Cd7Rvg9a.mjs").then((m) => m.feedbackCommand),
+		feedback: () => import("./feedback-_L3vqktY.mjs").then((m) => m.feedbackCommand),
 		db: () => import("./db-BB6O6085.mjs").then((m) => m.dbCommand),
 		usage: () => import("./usage-CUYrWxv0.mjs").then((m) => m.usageCommand),
 		ai: () => import("./ai-DHLnyqfq.mjs").then((m) => m.aiCommand),
 		open: () => import("./open-DcaQKi1v.mjs").then((m) => m.openCommand),
-		docs: () => import("./docs-YD4z70gq.mjs").then((m) => m.docsCommand),
-		skill: () => import("./skill-BWmXiJAz.mjs").then((m) => m.skillCommand),
-		upgrade: () => import("./upgrade-Cexs9KYX.mjs").then((m) => m.upgradeCommand),
+		docs: () => import("./docs-CtNH5kbN.mjs").then((m) => m.docsCommand),
+		skill: () => import("./skill-CM7R-4Bq.mjs").then((m) => m.skillCommand),
+		upgrade: () => import("./upgrade-ChcSZW8i.mjs").then((m) => m.upgradeCommand),
 		logs: () => import("./logs-DQQOawOG.mjs").then((m) => m.logsCommand),
-		mcp: () => import("./mcp-GKwctfHN.mjs").then((m) => m.mcpCommand)
+		mcp: () => import("./mcp-RcN17Z2v.mjs").then((m) => m.mcpCommand)
 	}
 });
 const quiet = process.argv[2] === "mcp" && process.argv[3] === "serve";

package/dist/{mcp-GKwctfHN.mjs → mcp-RcN17Z2v.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-CiKTWo0_.mjs";
+import { t as version } from "./package-YGjjin4p.mjs";
 import { d as tryResolveProject, l as stagingUrl, n as siteConfig, s as projectUrl } from "./site-DM2J10CB.mjs";
 import { i as apiRequest, t as ApiError } from "./api-C4rMhE7i.mjs";
 import { t as liveDevServer } from "./dev-server-file-Dk9pk4AR.mjs";

package/dist/{package-CiKTWo0_.mjs → package-YGjjin4p.mjs}

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.7.31";
+var version = "0.7.32";
 //#endregion
 export { version as t };

package/dist/{skill-BWmXiJAz.mjs → skill-CM7R-4Bq.mjs}

@@ -1,4 +1,4 @@
-import { t as version } from "./package-CiKTWo0_.mjs";
+import { t as version } from "./package-YGjjin4p.mjs";
 import { r as reportErrors } from "./ui-C_jSc1Kz.mjs";
 import { defineCommand } from "citty";
 import { cpSync, existsSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";

package/dist/{upgrade-Cexs9KYX.mjs → upgrade-ChcSZW8i.mjs}

@@ -112,7 +112,7 @@ const upgradeCommand = defineCommand({
 		const spec = `${PACKAGE_NAME}@${args.version ?? "latest"}`;
 		const command = pmCommand(pm);
 		const cmd = installArgs(pm, spec);
-		const { skillInstalled } = await import("./skill-BWmXiJAz.mjs");
+		const { skillInstalled } = await import("./skill-CM7R-4Bq.mjs");
 		const { homedir } = await import("node:os");
 		const refreshGlobal = skillInstalled(homedir());
 		const refreshRepo = process.cwd() !== homedir() && skillInstalled(process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mediamonks/canopy-cli",
-  "version": "0.7.31",
+  "version": "0.7.32",
   "description": "Canopy CLI — create, develop and deploy Canopy projects.",
   "bin": {
     "canopy": "./dist/index.mjs"
@@ -27,6 +27,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
+    "ai": "^7.0.82",
     "typescript": "^7.0.2",
     "vite-plus": "0.2.5",
     "@mediamonks/canopy-pages": "0.0.0"