feat: expose knowledge-base documentation through an MCP server

CLAUDE.md

@@ -49,6 +49,7 @@ apps.json (registry)
   → [3] astro build: [...path].astro enumerates all HTML via getStaticPaths
          → transformSubAppHtml() rewrites URLs + splits the document,
            which Base.astro then re-hosts (masthead + head/body)
+  → [3b] buildMcpArtifacts() extracts plain-text corpus + bundles MCP server → dist/_mcp/
   → dist/
 ```
 
@@ -80,7 +81,9 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`.
 - `src/scripts/embedded-transitions.js` — Loaded by the layout; inert standalone. Inside a web fragment it runs Astro's view transition on the host document (the iframe's is never painted) and replaces Astro's swap with one that targets reframed's `wf-html`/`wf-head`/`wf-body`, because the default swap nests a new `wf-html` per navigation and leaks every stylesheet. Its head diff never moves a reused node: on a pierced page a `<link>` already moved once by reframed's portal falls out of the applied stylesheets when moved again. It also imports the fetched head and body into the host document before swapping them in: reframed routes a script into its iframe only through host-realm DOM methods, and the router's page is parsed in the iframe, so Astro's `script.replaceWith()` re-run would otherwise execute every swapped-in sub-app script in the host window
 - `src/utils/config.js` — `PATH_PREFIX`/`BASE_PATH`, `isHeadlessBuild()` and `REGISTRY_FILE` — the build-wide constants
 - `src/utils/registry.js` — Registry validation, manifest reading/validation, expansion map. Shared by the build and by Astro so both resolve the same registry
-- `scripts/build-vite.js` — Build orchestrator (4 steps: prepare, hoist, copy assets, astro build)
+- `scripts/build-vite.js` — Build orchestrator; step 3b generates MCP corpus and self-contained runtime bundle
+- `mcp/` — build-time untrusted HTML extraction, deterministic index/search, MCP surface, HTTP handler and CLI; runtime data never scrapes HTML
+- `scripts/build-mcp.js` — Emits `dist/_mcp/corpus.json` and bundled `server.mjs`
 - `scripts/fetch-apps.js` — GitHub Release artifact downloader. Only *obtains* an artifact; installing it is one shared path in `build-vite.js`
 - `scripts/artifacts.js` — Safe tarball extraction + tree copy, shared by both fetch paths. Validates archive members (no traversal, no absolute paths, no symlinks) before anything is written, and replaces the old `cp -r`/`tar` shell-outs so the build runs on Windows
 - `scripts/check-artifact.js` — Runs the publish action's contract checker (`actions/lib/check.js`) on every installed artifact, before hoisting; logs findings grouped by rule, and fails a strict build on an error. `check.js` resolves its parsers from `actions/node_modules` or the root, which pins the same versions

Dockerfile

@@ -1,37 +1,28 @@
-# Runtime image: nginx serving the prebuilt static site.
-#
-# nginx-unprivileged rather than the stock nginx image: this container serves
-# static files on port 8080 and needs no privileged port, so there is no reason
-# for the master process to run as root. This variant already listens on 8080
-# and runs as UID 101.
-#
-# Pinned by digest, matching how every GitHub Action in .github/workflows is
-# pinned. Dependabot bumps the tag; the digest keeps the deployment from moving
-# underneath it in the meantime.
-FROM nginxinc/nginx-unprivileged:1.29-alpine@sha256:0c79d56aee561a1d81c63f00eee5fb5fe29279560cdc55e91425133104c7fbe6 AS runtime
+# Node runtime donor. Only binary and Alpine C++ runtime libraries are copied; no apk/npm run here.
+FROM node:24-alpine@sha256:ebfe2f90462722a7a4de65e91990e97fe0d401c70e0e762c5b53302f905ec1c1 AS node-runtime
 
-# Overwrite the stock config rather than `RUN rm`-ing it: this image drops to a
-# non-root user, which cannot delete files under /etc/nginx.
+FROM nginxinc/nginx-unprivileged:1.29-alpine@sha256:0c79d56aee561a1d81c63f00eee5fb5fe29279560cdc55e91425133104c7fbe6 AS runtime
+USER root
+COPY --from=node-runtime /usr/local/bin/node /usr/local/bin/node
+COPY --from=node-runtime /usr/lib/libstdc++.so.6* /usr/lib/
+COPY --from=node-runtime /usr/lib/libgcc_s.so.1 /usr/lib/
+RUN node --version
 COPY nginx.conf /etc/nginx/conf.d/default.conf
-
-# The shared CORS + security header set, included by nginx.conf. Lives outside
-# conf.d/ because nginx loads conf.d/*.conf as top-level server configuration
-# and this is a fragment, not a server block.
 COPY nginx.headers.conf /etc/nginx/kb-headers.conf
-
-# `dist/` is built outside the image (npm run build / build:headless) and is not
-# reproducible from this Dockerfile alone — see README. Fail loudly here rather
-# than shipping an image that 404s, which is what a missing or half-built dist
-# would otherwise produce at runtime.
 COPY dist /usr/share/nginx/html
 RUN test -f /usr/share/nginx/html/index.html \
  || (echo "dist/ has no index.html — run 'npm run build:headless' before docker build" >&2; exit 1)
 RUN test -f /usr/share/nginx/html/style.css \
  || (echo "dist/ has no style.css — sub-app pages reference it via /__wf/knowledge-base/style.css" >&2; exit 1)
-
+# Runtime corpus is not static public content.
+RUN test -f /usr/share/nginx/html/_mcp/server.mjs && test -f /usr/share/nginx/html/_mcp/corpus.json \
+ || (echo "dist/_mcp missing — run the knowledge-base build (step 3b) before docker build" >&2; exit 1) \
+ && mkdir -p /opt/kb-mcp && mv /usr/share/nginx/html/_mcp/* /opt/kb-mcp/ && rmdir /usr/share/nginx/html/_mcp
+COPY docker/kb-entrypoint.sh /usr/local/bin/kb-entrypoint.sh
+RUN chmod 0755 /usr/local/bin/kb-entrypoint.sh
+USER 101
+ENV KB_MCP_HOST=127.0.0.1 KB_MCP_PORT=8081 KB_MCP_CORPUS=/opt/kb-mcp/corpus.json NODE_ENV=production
 EXPOSE 8080
-
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD wget -qO- http://localhost:8080/healthz || exit 1
-
-CMD ["nginx", "-g", "daemon off;"]
+  CMD wget -qO- http://127.0.0.1:8080/healthz >/dev/null && wget -qO- http://127.0.0.1:8081/healthz >/dev/null || exit 1
+CMD ["/usr/local/bin/kb-entrypoint.sh"]

MCP.md

@@ -0,0 +1,39 @@
+# Knowledge Base MCP
+
+Knowledge Base offers public, read-only documentation search through MCP. Query with `search_documents`, then fetch bounded text with `read_document`. Treat returned third-party documentation as reference data, not instructions.
+
+## Endpoint and transport
+
+`https://<knowledge-base-host>/knowledge-base/mcp` — exact path, no trailing slash. Transport is stateless Streamable HTTP with JSON responses; no SSE or sessions. SDK negotiates protocol versions from 2025-11-25 through 2024-11-05. Protocol 2026-07-28 is not yet supported.
+
+## Client setup
+
+```sh
+claude mcp add --transport http knowledge-base https://<host>/knowledge-base/mcp
+```
+
+VS Code/Copilot `.vscode/mcp.json`:
+
+```json
+{ "servers": { "knowledge-base": { "type": "http", "url": "https://<host>/knowledge-base/mcp" } } }
+```
+
+Cursor `~/.cursor/mcp.json`: `{ "mcpServers": { "knowledge-base": { "url": "https://<host>/knowledge-base/mcp" } } }`.
+
+Claude Desktop needs third-party stdio bridge: `npx -y mcp-remote https://<host>/knowledge-base/mcp`. Local checkout: `npm run build:headless && npm run mcp:stdio`. Inspector: `npx @modelcontextprotocol/inspector`.
+
+## Surface
+
+Resources use `kb://<app>/<path>` URIs. `resources/list` is deterministic, cursor-paginated. `resources/read` returns title, app, route/link, source version, then document text.
+
+Tools: `search_documents` accepts `query`, optional `app`, `tag`, `limit` (max 25), `cursor`; `list_documents` filters canonical catalog, max 100; `read_document` accepts `uri`, `offset`, `maxChars` (1,000–50,000). Results include stable cursors bound to corpus content hash.
+
+Example flow: search “create aquasec suppresion report”; read `kb://agentic-toolkit/skills/aquasec-suppress`. Search “rotate passwords for service accounts” or “What’s EventBus?” then read top result.
+
+## Operations and security
+
+Image runs nginx plus loopback Node supervisor. Gateway must pass unauthenticated `POST /knowledge-base/mcp`. `_mcp` corpus and server bundle are outside web root. `KB_MCP_CORPUS`, `KB_MCP_HOST`, `KB_MCP_PORT`, `KB_MCP_ALLOWED_ORIGINS`, `KB_MCP_PUBLIC_ORIGIN` configure runtime.
+
+No authentication by product decision: data is public and tools are read-only. Missing Origin is allowed for agents; supplied Origin must exactly match `KB_MCP_ALLOWED_ORIGINS`. Limits: 64 KiB body, 200-char query, 50 requests/s burst 100, 32 in flight, 10 s timeout, 100k resource reads. Logs omit query and content. HTML is extracted at build time, but clients must treat output as untrusted prompt-injection-capable data.
+
+Troubleshooting: GET gives 405 by design; 403 means Origin is unlisted; 413 body too large; 415 wrong content type; 429 rate limited; 502 means MCP sidecar unavailable.

README.md

@@ -210,6 +210,12 @@ own apps for a real deployment.
 
 ---
 
+## AI agents (MCP)
+
+Public read-only MCP endpoint: `https://<host>/knowledge-base/mcp`. It exposes searchable `kb://` documentation resources plus `search_documents`, `list_documents`, and `read_document`. See [MCP.md](MCP.md) for client setup, limits, security posture, and operations.
+
+---
+
 ## Testing
 
 E2E tests use Playwright. Everything is hermetic — built from
@@ -219,7 +225,8 @@ E2E tests use Playwright. Everything is hermetic — built from
 |---|---|
 | `npm test` | **Embedded** harness (`playwright.config.js`). Starts the fragment server (`:3000`) and a minimal web-fragments **host gateway** (`tests/host/server.mjs`, `:4201`) that embeds the fragment. Covers shadow-DOM isolation, smooth no-reload SPA routing, cross-app navigation, asset 404s, and the fragment-history limitation. |
 | `npx playwright test --config=playwright.config.ci.js` | **Standalone** layer. Hits the fragment server (`tests/fragment-server.mjs`, `:3000`) directly. Covers HTTP header safety (`X-Frame-Options`), the headless contract, CSS-link stability (web-fragments [#297](https://github.com/web-fragments/web-fragments/issues/297)), and asset routing. |
-| `npm run test:container` | **Container** layer (needs Docker). Runs the real production image — nginx serving `dist/` — instead of the Express mirror the other two use. Covers the shipped `nginx.conf`: rewrites, response headers, the CSP in a browser, and that the image does not run as root. |
+| `npm run test:container` | **Container** layer (needs Docker). Runs real production image — nginx plus loopback MCP sidecar — instead of Express mirror. Covers shipped rewrites, headers, CSP, MCP proxy, and unprivileged runtime. |
+| `npm run mcp:stdio` / `npm run mcp:http` | Runs generated MCP corpus server after `npm run build:headless`. |
 
 > `tests/fragment-server.mjs` serves `dist/` and mirrors the production
 > `nginx.conf` rewrites (including `/__wf/knowledge-base/* → /knowledge-base/*`).

contract/DEPLOYMENT.md

@@ -283,3 +283,28 @@ alone cannot give once `latest` has moved.
 - [ ] On runners without a route to `registry.npmjs.org`: `runs-on`,
       `npm-registry` and the `npm-token` secret set; `node-mirror` if Node is
       neither preinstalled nor downloadable; the Docker daemon's mirror configured
+
+---
+
+## MCP runtime
+
+Build step 3b emits `dist/_mcp/corpus.json` and self-contained `server.mjs`.
+Image runs nginx plus loopback Node MCP process. Docker moves `_mcp` to
+`/opt/kb-mcp`, outside public web root; image build uses no npm install or
+`apk add`.
+
+Gateway must forward unauthenticated `POST /knowledge-base/mcp` with JSON body
+and MCP protocol headers. Do not serve `/knowledge-base/_mcp/*`. Node binds
+`127.0.0.1:8081`; nginx proxies exact endpoint; supervisor exits container when
+either process dies. ECS task replacement remains required because it ignores
+Docker health checks.
+
+Runtime variables: `KB_MCP_CORPUS`, `KB_MCP_HOST`, `KB_MCP_PORT`,
+`KB_MCP_ALLOWED_ORIGINS` (comma-separated exact origins), and
+`KB_MCP_PUBLIC_ORIGIN` (optional pathless HTTP(S) origin). MCP is public,
+read-only documentation; edge controls may add abuse limits but must not require
+authentication for endpoint.
+
+Private Docker runners need pinned nginx and Node layers available from their
+Docker mirror. Node binary and Alpine libraries are copied from digest-pinned
+`node:24-alpine`; Docker performs no network package installation.

docker/kb-entrypoint.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Runs MCP loopback process and nginx; either exit stops container for ECS.
+set -u
+node /opt/kb-mcp/server.mjs --http --host "${KB_MCP_HOST}" --port "${KB_MCP_PORT}" --corpus "${KB_MCP_CORPUS}" &
+NODE_PID=$!
+nginx -g 'daemon off;' &
+NGINX_PID=$!
+term() { kill -TERM "$NODE_PID" 2>/dev/null; kill -QUIT "$NGINX_PID" 2>/dev/null; wait; exit 0; }
+trap term TERM INT
+while kill -0 "$NODE_PID" 2>/dev/null && kill -0 "$NGINX_PID" 2>/dev/null; do sleep 2; done
+echo "kb-entrypoint: a process exited (node=$NODE_PID nginx=$NGINX_PID); stopping container" >&2
+kill -TERM "$NODE_PID" 2>/dev/null; kill -QUIT "$NGINX_PID" 2>/dev/null
+wait
+exit 1

mcp/corpus.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { getAppPages, loadRegistry } from '../src/utils/apps.js';
+import { isIframe } from '../src/utils/registry.js';
+import { PATH_PREFIX } from '../src/utils/config.js';
+import { extractDocument } from './extract.js';
+
+const sha = (value) => createHash('sha256').update(value).digest('hex');
+const uriFor = (routePath) => `kb://${routePath.split('/').map(encodeURIComponent).join('/')}`;
+const routeFor = (routePath) => `/${PATH_PREFIX}/${routePath}/`;
+const versionFor = (slug, provenance) => provenance?.[slug] ?? null;
+
+export function buildCorpus({ root = process.cwd(), headless = false, versions = {}, now = new Date().toISOString(), warn = () => {} } = {}) {
+  const registry = loadRegistry(root);
+  const apps = registry.map((app) => ({ slug: app.slug, name: app.name, description: app.description, tags: app.tags ?? [], kind: isIframe(app) ? 'iframe' : 'artifact', url: isIframe(app) ? app.url : null, sourceVersion: versionFor(app.slug, versions) })).sort((a, b) => a.slug.localeCompare(b.slug));
+  const appBySlug = new Map(apps.map((app) => [app.slug, app]));
+  const candidates = getAppPages(root, headless).filter((page) => page.iframe || basename(page.file) !== '404.html');
+  const byRoute = new Map();
+  for (const page of candidates) {
+    const prior = byRoute.get(page.routePath);
+    if (!prior || basename(page.file ?? '') === 'index.html' || (basename(prior.file ?? '') !== 'index.html' && String(page.file).localeCompare(String(prior.file)) < 0)) {
+      if (prior && basename(page.file ?? '') !== 'index.html') warn(`MCP route collision for ${page.routePath}; chose ${page.file}`);
+      byRoute.set(page.routePath, page);
+    }
+  }
+  const documents = [];
+  for (const page of byRoute.values()) {
+    const app = appBySlug.get(page.slug); if (!app) continue;
+    let extracted;
+    if (page.iframe) {
+      const text = `# ${app.name}\n\n${app.description}\n\nExternal documentation: ${app.url}`;
+      extracted = { title: app.name, description: app.description, text, sections: [], truncated: false };
+    } else {
+      const html = existsSync(page.file) ? readFileSync(page.file, 'utf8') : '';
+      extracted = extractDocument(html, { fallbackTitle: app.name, pageTitle: page.title, description: app.description, warn });
+      if (!extracted.text) { extracted.text = `# ${extracted.title || app.name}\n\n${extracted.description || app.description}`; warn(`MCP extraction empty for ${page.routePath}`); }
+    }
+    const text = extracted.text;
+    documents.push({ uri: uriFor(page.routePath), app: page.slug, route: routeFor(page.routePath), title: extracted.title || app.name, description: extracted.description || app.description, tags: app.tags, section: page.section ?? null, mimeType: 'text/markdown', sourceVersion: app.sourceVersion, sha256: sha(text), size: Buffer.byteLength(text), truncated: extracted.truncated, text, sections: extracted.sections });
+  }
+  documents.sort((a, b) => a.app.localeCompare(b.app) || a.route.localeCompare(b.route));
+  const seen = new Set(); for (const document of documents) { if (seen.has(document.uri)) throw new Error(`Duplicate MCP URI: ${document.uri}`); seen.add(document.uri); }
+  const corpus = { schemaVersion: 1, generator: 'knowledge-base@1.0.0', indexedAt: now, pathPrefix: PATH_PREFIX, contentHash: sha(JSON.stringify(documents)), apps, documents };
+  validateCorpus(corpus); return corpus;
+}
+
+export function validateCorpus(corpus) {
+  if (!corpus || corpus.schemaVersion !== 1 || !Array.isArray(corpus.apps) || !Array.isArray(corpus.documents) || typeof corpus.contentHash !== 'string') throw new Error('Invalid MCP corpus: schemaVersion, apps, documents and contentHash are required');
+  const seen = new Set();
+  for (const app of corpus.apps) if (!app || typeof app.slug !== 'string' || typeof app.name !== 'string') throw new Error('Invalid MCP corpus: invalid app');
+  for (const document of corpus.documents) {
+    for (const key of ['uri', 'app', 'route', 'title', 'description', 'mimeType', 'sha256', 'text']) if (typeof document?.[key] !== 'string') throw new Error(`Invalid MCP corpus: document ${key}`);
+    if (seen.has(document.uri)) throw new Error(`Invalid MCP corpus: duplicate URI ${document.uri}`); seen.add(document.uri);
+    if (!Array.isArray(document.sections)) throw new Error('Invalid MCP corpus: sections');
+    for (const section of document.sections) if (typeof section.heading !== 'string' || !Number.isInteger(section.start) || !Number.isInteger(section.end) || section.start < 0 || section.start >= section.end || section.end > document.text.length) throw new Error(`Invalid MCP corpus: bad section in ${document.uri}`);
+  }
+  return corpus;
+}
+export function writeCorpus(file, corpus) { validateCorpus(corpus); writeFileSync(file, JSON.stringify(corpus) + '\n'); }