Docs: unblock local docs build without AI Search (#1107)

* Docs: unblock local docs build without AI Search

* Docs: deduplicate MCP tool definition

* style: format

* Docs: clarify local AI Search fallback config

* style: format

---------

Co-authored-by: emdashbot[bot] <emdashbot[bot]@users.noreply.github.com>

Author: richardjoo

docs/README.md

@@ -8,8 +8,28 @@ Documentation site for EmDash, built with [Starlight](https://starlight.astro.bu
 pnpm dev
 ```
 
+If you're running in a remote or API-token-only environment that cannot access the
+Cloudflare AI Search instance, keep using `pnpm dev` for local content work and
+use the local-only Wrangler config for built-worker preview checks instead:
+
+```bash
+pnpm build
+pnpm exec wrangler dev --config wrangler.local.jsonc
+```
+
+The `/mcp` endpoint still works, but it returns a helpful message until a
+Cloudflare AI Search binding is configured.
+
 ## Build
 
 ```bash
 pnpm build
 ```
+
+For remote docs preview/deploy checks that require production bindings, run the
+main config as usual:
+
+```bash
+pnpm exec wrangler dev
+pnpm exec wrangler deploy
+```

docs/astro.config.mjs

@@ -10,6 +10,7 @@ export default defineConfig({
 		starlight({
 			title: "EmDash",
 			tagline: "The Astro-native CMS",
+			disable404Route: true,
 			components: {
 				SkipLink: "./src/components/SkipLink.astro",
 			},
@@ -237,5 +238,5 @@ export default defineConfig({
 		}),
 	],
 
-	adapter: cloudflare(),
+	adapter: cloudflare({ remoteBindings: false, prerenderEnvironment: "node" }),
 });

docs/src/pages/404.astro

@@ -0,0 +1,18 @@
+---
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+
+export const prerender = true;
+
+const frontmatter = {
+	title: "404",
+	template: "splash",
+	editUrl: false,
+	pagefind: false,
+	hero: {
+		tagline: Astro.locals.t("404.text"),
+		actions: [],
+	},
+};
+---
+
+<StarlightPage frontmatter={frontmatter} />

docs/src/worker.ts

@@ -8,66 +8,73 @@ import { z } from "zod";
  * underlying transport asserts that the server is not already connected, so we
  * cannot reuse a single server instance across requests.
  */
+const searchDocsTool = {
+	title: "Search EmDash documentation",
+	description:
+		"Search the EmDash CMS documentation. Returns relevant chunks with source URLs and similarity scores.",
+	inputSchema: {
+		query: z.string().min(1).max(1000).describe("Natural-language query against the EmDash docs."),
+		max_results: z
+			.number()
+			.int()
+			.min(1)
+			.max(20)
+			.optional()
+			.describe("Maximum number of chunks to return. Defaults to 8."),
+	},
+};
+
 function buildMcpServer(env: Env): McpServer {
 	const server = new McpServer({
 		name: "emdash-docs",
 		version: "1.0.0",
 	});
+	const aiSearch = (env as { AI_SEARCH?: Env["AI_SEARCH"] }).AI_SEARCH;
+	if (!aiSearch) {
+		server.registerTool("search_docs", searchDocsTool, async () => ({
+			content: [
+				{
+					type: "text",
+					text: "Docs search is unavailable in this environment. Configure Cloudflare AI Search in the Workers binding to enable this tool.",
+				},
+			],
+		}));
 
-	server.registerTool(
-		"search_docs",
-		{
-			title: "Search EmDash documentation",
-			description:
-				"Search the EmDash CMS documentation. Returns relevant chunks with source URLs and similarity scores.",
-			inputSchema: {
-				query: z
-					.string()
-					.min(1)
-					.max(1000)
-					.describe("Natural-language query against the EmDash docs."),
-				max_results: z
-					.number()
-					.int()
-					.min(1)
-					.max(20)
-					.optional()
-					.describe("Maximum number of chunks to return. Defaults to 8."),
-			},
-		},
-		async ({ query, max_results }) => {
-			const limit = max_results ?? 8;
+		return server;
+	}
 
-			const results = await env.AI_SEARCH.search({
-				messages: [{ role: "user", content: query }],
-				ai_search_options: {
-					retrieval: { max_num_results: limit },
-				},
-			});
+	server.registerTool("search_docs", searchDocsTool, async ({ query, max_results }) => {
+		const limit = max_results ?? 8;
 
-			if (!results.chunks.length) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "No matching docs found.",
-						},
-					],
-				};
-			}
+		const results = await aiSearch.search({
+			messages: [{ role: "user", content: query }],
+			ai_search_options: {
+				retrieval: { max_num_results: limit },
+			},
+		});
 
+		if (!results.chunks.length) {
 			return {
-				content: results.chunks.map((chunk) => {
-					const source = chunk.item.key;
-					const score = typeof chunk.score === "number" ? chunk.score.toFixed(3) : "n/a";
-					return {
-						type: "text" as const,
-						text: `<result source="${source}" score="${score}">\n${chunk.text}\n</result>`,
-					};
-				}),
+				content: [
+					{
+						type: "text",
+						text: "No matching docs found.",
+					},
+				],
 			};
-		},
-	);
+		}
+
+		return {
+			content: results.chunks.map((chunk) => {
+				const source = chunk.item.key;
+				const score = typeof chunk.score === "number" ? chunk.score.toFixed(3) : "n/a";
+				return {
+					type: "text" as const,
+					text: `<result source="${source}" score="${score}">\n${chunk.text}\n</result>`,
+				};
+			}),
+		};
+	});
 
 	return server;
 }

docs/wrangler.local.jsonc

@@ -0,0 +1,15 @@
+{
+	// Keep shared fields in sync with wrangler.jsonc.
+	"$schema": "node_modules/wrangler/config-schema.json",
+	"compatibility_date": "2026-03-01",
+	"compatibility_flags": ["global_fetch_strictly_public", "nodejs_compat"],
+	"name": "docs",
+	"main": "./src/worker.ts",
+	"assets": {
+		"directory": "./dist",
+		"binding": "ASSETS",
+	},
+	"observability": {
+		"enabled": true,
+	},
+}