fix(mcp): serve site_list_documents headlessly over MCP (CoreBunch#186)

RemiAsselin42 · DavidBabinec · web-flow · commit d697742e39d5 · 2026-07-10T23:03:33.000+02:00
* fix(mcp): serve site_list_documents headlessly over MCP

The site-scope `site_list_documents` handler reads `ctx.snapshot`, which is
null over MCP (no chat turn, no editor snapshot). `asSnap` is an unchecked
cast, so `asSnap(null).currentDocument` throws a TypeError — any MCP client
calling the tool crashes instead of receiving the document catalog.

Add a headless `documentMcpTools` set that assembles the catalog directly from
the draft site document (`getDraftSiteDocument` + `describeAgentDocuments`) and
order it ahead of `siteTools` in the MCP registry so it wins the name de-dup,
mirroring how `styleMcpTools` already shadows `site_list_breakpoints`. No editor
focus exists server-side, so nothing is marked current; `get_context` still
reports the live editor.

* fix(mcp): scope site_list_documents to site.read and use a valid current-doc sentinel

Address review feedback on the headless site_list_documents:

- `requiredCapabilities` matches ANY-OF (see `toolAllowedForCapabilities`), so
  the previous five-capability list let a caller holding only an edit capability
  (e.g. `pages.edit`) but not `site.read` list documents. Narrow it to
  `['site.read']`, matching the site-scope tool it shadows.
- The "no current document" sentinel used an empty id, violating
  `AgentDocumentRefSchema` (`minLength: 1`). Use a clearly-nonexistent,
  non-empty id instead so it never matches a real document and stays
  schema-valid if surfaced.

* fix(mcp): finalize headless document catalog

---------

Co-authored-by: DavidBabinec &lt;hello@davidbabinec.com&gt;
diff --git a/docs/features/mcp-connectors.md b/docs/features/mcp-connectors.md
@@ -12,7 +12,7 @@ The server is implemented with the official `@modelcontextprotocol/sdk`. That pa
 
 - **Instatic is an MCP server.** One Streamable-HTTP endpoint at `/_instatic/mcp` serves both local and remote clients (local is just `localhost`).
 - **Thin adapter over the existing tool engine.** No tool logic is duplicated. MCP is a new *caller* alongside the built-in agent and the plugin host; tool dispatch reuses `executeAiTool`.
-- **Tool surface = the full catalog.** Server-resolved tools (content reads + `site_read_styles`) run headless — no editor needed. Every browser-execution tool the agent panel has (structure edits, insert HTML, apply CSS, assign classes, set design tokens, manage pages, content CRUD, code assets, live-DOM reads) is exposed too, **relayed to an open editor via the live editor bridge** — the single source of truth for page editing. If the connector owner has no editor open, those tools return a clear "open the editor" error; the headless reads still work.
+- **Tool surface = the full catalog.** Server-resolved tools (content reads + `site_list_documents` + `site_read_styles`) run headless — no editor needed. Every browser-execution tool the agent panel has (structure edits, insert HTML, apply CSS, assign classes, set design tokens, manage pages, content CRUD, code assets, live-DOM reads) is exposed too, **relayed to an open editor via the live editor bridge** — the single source of truth for page editing. If the connector owner has no editor open, those tools return a clear "open the editor" error; the headless reads still work.
 - **Bearer-token auth, one secret per connector.** The token is shown once on creation and stored only as a SHA-256 hash. New tokens expire after 90 days by default; admins can choose a custom TTL or explicitly create a non-expiring token. Revocable.
 - **Capability-gated.** A connector carries a granted capability subset; the same gate the built-in agent uses (`toolAllowedForCapabilities`) filters the toolset. An MCP caller can never invoke a tool the granting capabilities couldn't authorize over HTTP.
 - **Privilege floor.** An admin can only grant capabilities they themselves hold.
@@ -36,9 +36,9 @@ server/ai/mcp/server.ts               low-level SDK Server; tools filtered by ca
         │
 server/ai/mcp/registry.ts             AiTool registry → MCP tools (TypeBox inputSchema sent verbatim as JSON Schema)
         │
-executeAiTool(...) / treeService      in-process, ctx { db, userId, capabilities }
+executeAiTool(...) / live editor bridge
         ▼
-repositories (data_rows, media) + applyTreeOperation + saveDataRowDraft
+repositories (headless reads) / live editor store (browser tools)
 ```
 
 ### Module layout — `server/ai/mcp/`
@@ -48,15 +48,14 @@ repositories (data_rows, media) + applyTreeOperation + saveDataRowDraft
 | `transports/http.ts` | Mounts the SDK's Web-standard Streamable-HTTP transport; stateless per request (`enableJsonResponse`). |
 | `auth.ts` | Bearer resolution → `{ connectorId, userId, capabilities }`; spec-correct 401 with an RFC 9728 `resource_metadata` pointer. |
 | `server.ts` | Builds a capability-scoped low-level `Server` (`ListTools` / `CallTool` handlers). Uses the low-level `Server`, not `McpServer.registerTool`, because the latter needs Zod (banned) — this lets the TypeBox `inputSchema` pass through verbatim. |
-| `registry.ts` | The exposable toolset = full catalog (content + site + page-tree), deduped by name, filtered by `toolAllowedForCapabilities`. |
+| `registry.ts` | Headless reads plus the browser-relayed site/content catalog, deduped by name and filtered by `toolAllowedForCapabilities`. |
+| `tools/documentTools.ts` | `site_list_documents` — pages, templates, and visual components, headless from the DB. |
 | `tools/styleTools.ts` | `site_read_styles` — the design system as a CSS stylesheet, headless from the DB. |
 | `editorBridge.ts` | Per-user live editor bridge registry + `createEditorBridgeStream`; `getEditorBridgeForUser` routes browser tools to the owner's open editor. |
 | `handlers/editorBridge.ts` | `GET /admin/api/ai/editor-bridge` — the NDJSON stream the editor holds open. |
 | `connectors/` | `types.ts` (server-only record), `token.ts` (generate + SHA-256 hash), `store.ts` (CRUD + `toConnectorView`). |
 | `handlers/connectors.ts` | `/admin/api/ai/mcp/connectors` CRUD, gated by `ai.providers.manage`. |
 
-The headless page-tree path (load → `applyTreeOperation` → persist) lives in `server/ai/content/treeService.ts` and is shared with the plugin RPC `cms.content.tree.mutate` — neither caller duplicates the engine. Gated by `plugin-content-tree-via-engine.test.ts`.
-
 ---
 
 ## Tool surface
@@ -68,6 +67,7 @@ MCP exposes the **full tool catalog** (deduped by name), capability-filtered. To
 **Headless (server-resolved) — work with no editor open:**
 - Content reads — list/read collections, entries, data rows, media.
 - `get_context({ entryId? })` — orientation in one call: is a live editor connected (browser tools need it), which "everywhere"/post-type templates wrap pages, site name. Call it first if a browser tool returns "open the editor."
+- `site_list_documents` — editable pages, templates, and visual components with document references, root node ids, template metadata, and summaries. Nothing is marked active/current because headless calls have no editor focus.
 - `site_read_styles({ format?, className?, includeTokens? })` — the design system as a **CSS stylesheet**: design tokens (CSS custom properties) + every class/ambient rule, read straight from the DB via the publisher's emitters. `format:"summary"` returns a compact class catalog (selector + referenced token vars, no declarations) to scan first. Symmetric with reading pages as HTML / writing CSS via `site_apply_css`. Replaces the old snapshot-dependent `list_tokens`.
 - `site_list_breakpoints` — configured viewport ids/labels/widths (the first is the base), so `site_render_snapshot` can target one deliberately. Headless version replaces the snapshot-dependent one.
 
@@ -155,7 +155,6 @@ An admin cannot grant a capability they do not hold (enforced in `handlers/conne
 ## Tests
 
 - `server/ai/mcp/connectors/{token,store}.test.ts` — token hashing, expiry, and store CRUD.
-- `server/ai/content/treeService.test.ts` — headless load/mutate/persist.
-- `server/ai/mcp/{registry,auth,server,transports/http}.test.ts` — capability filtering, bearer auth + 401, full MCP round-trip (list/read/mutate), HTTP handshake.
+- `server/ai/mcp/{registry,auth,server,transports/http}.test.ts` and `server/ai/mcp/tools/documentTools.test.ts` — capability filtering, headless document listing, bearer auth + 401, full MCP round-trip (list/read/mutate), HTTP handshake.
 - `src/__tests__/ai/mcpConnectorsHandler.test.ts` — CRUD, privilege floor, capability gating.
 - `src/__tests__/architecture/ai-mcp-connectors-never-leak.test.ts` — token never serialized.
diff --git a/server/ai/mcp/registry.ts b/server/ai/mcp/registry.ts
@@ -3,8 +3,8 @@
  * filtered to the connector's granted capabilities.
  *
  * Two execution classes are exposed:
- *   - server-resolved tools (content reads + `site_read_styles`) run in-process and
- *     work with NO editor open;
+ *   - server-resolved tools (content reads + `site_list_documents` +
+ *     `site_read_styles`) run in-process and work with NO editor open;
  *   - browser tools (structure edits, HTML/CSS authoring, design tokens, page
  *     lifecycle, content CRUD, code assets, live-DOM reads) are relayed to the
  *     connector owner's open editor via the live editor bridge
@@ -29,19 +29,24 @@ import { contentTools } from '../tools/content'
 import { siteTools } from '../tools/site'
 import { styleMcpTools } from './tools/styleTools'
 import { contextMcpTools } from './tools/contextTool'
+import { documentMcpTools } from './tools/documentTools'
 
 // Server-resolved site read tools whose handlers read the browser-posted
-// `ctx.snapshot`, which is null over MCP — they'd silently return nothing.
-// `site_read_styles` (headless) replaces `site_list_tokens`. The snapshot-based
-// `site_list_breakpoints` is excluded too; a headless `site_list_breakpoints` is provided
-// by `styleMcpTools` (which is ordered first, so it wins the de-dup).
+// `ctx.snapshot`, which is null over MCP — they'd return nothing or throw.
+// Each is handled one of two ways:
+//   - `site_list_tokens` → excluded; `site_read_styles` (headless) replaces it.
+//   - `site_list_breakpoints` → shadowed by a headless version in `styleMcpTools`.
+//   - `site_list_documents` → shadowed by a headless version in `documentMcpTools`
+//     (the snapshot-based one throws on `null.currentDocument`).
+// The headless tool sets are ordered ahead of `siteTools` below, so they win
+// the de-dup for any shared name.
 const MCP_EXCLUDED_TOOLS = new Set<string>(['site_list_tokens'])
 
 function allMcpTools(): AiTool[] {
-  // De-dup by tool name. Order matters: the headless style + content tools win
-  // over the site toolset for any shared name (e.g. `list_documents`), so the
-  // version that works without an open editor is the one exposed.
-  const ordered = [...contextMcpTools, ...styleMcpTools, ...contentTools, ...siteTools]
+  // De-dup by tool name. Order matters: the headless MCP-specific + content
+  // tools win over the site toolset for shared names, so the version that works
+  // without an open editor is the one exposed.
+  const ordered = [...contextMcpTools, ...styleMcpTools, ...documentMcpTools, ...contentTools, ...siteTools]
   const byName = new Map<string, AiTool>()
   for (const tool of ordered) {
     if (MCP_EXCLUDED_TOOLS.has(tool.name)) continue
diff --git a/server/ai/mcp/tools/documentTools.test.ts b/server/ai/mcp/tools/documentTools.test.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it, beforeEach } from 'bun:test'
+import { createSqliteClient } from '../../../db/sqlite'
+import { sqliteMigrations } from '../../../db/migrations-sqlite'
+import { runMigrations } from '../../../db/runMigrations'
+import type { DbClient } from '../../../db/client'
+import type { ToolContext } from '../../runtime/types'
+import { mcpToolsForCapabilities } from '../registry'
+
+const PAGE_TREE = {
+  rootNodeId: 'root',
+  nodes: {
+    root: { id: 'root', moduleId: 'base.body', props: {}, breakpointOverrides: {}, classIds: [], children: [] },
+  },
+}
+
+async function freshDb(): Promise<DbClient> {
+  const db = createSqliteClient(':memory:')
+  await runMigrations(db, sqliteMigrations)
+  // The default site shell row is created at first-run setup, not by migrations.
+  await db`
+    insert into site (id, name, settings_json)
+    values ('default', 'Test', ${{ cmsSiteSchemaVersion: 1, site: {} }})
+  `
+  // Seed one page row into the (already-seeded) `pages` system table.
+  const cells = JSON.stringify({ title: 'Home', slug: 'index', body: PAGE_TREE })
+  await db`
+    insert into data_rows (id, table_id, cells_json, slug, status)
+    values ('home', 'pages', ${cells}, 'index', 'draft')
+  `
+  return db
+}
+
+function headlessCtx(db: DbClient): ToolContext {
+  return {
+    db,
+    userId: 'u1',
+    capabilities: ['site.read'],
+    scope: 'site',
+    conversationId: 'mcp:test',
+    snapshot: null, // MCP has no browser-posted snapshot — this is the crash case.
+    signal: new AbortController().signal,
+  }
+}
+
+describe('mcp site_list_documents (headless)', () => {
+  let db: DbClient
+  beforeEach(async () => {
+    db = await freshDb()
+  })
+
+  it('the MCP registry exposes a server-resolved site_list_documents that does not need a snapshot', async () => {
+    const tool = mcpToolsForCapabilities(['site.read']).find((t) => t.name === 'site_list_documents')
+    if (!tool?.handler) throw new Error('Expected site_list_documents handler')
+    expect(tool.execution).toBe('server')
+
+    // The site-scope (chat) version throws on `null.currentDocument`; the headless
+    // one resolves the catalog from the DB. Over MCP this must not throw.
+    const result = (await tool.handler({}, headlessCtx(db))) as {
+      currentDocument: unknown
+      documents: {
+        document: { type: string; id: string }
+        slug?: string
+        active: boolean
+        current: boolean
+      }[]
+    }
+
+    expect(Array.isArray(result.documents)).toBe(true)
+    expect(result.documents.some((d) => d.slug === 'index')).toBe(true)
+    // No open-editor focus server-side, so nothing is reported as current.
+    expect(result.currentDocument).toBeNull()
+    expect(result.documents.every((document) => !document.active && !document.current)).toBe(true)
+  })
+
+  it('does not expose the catalog to an edit-only connector without site.read', () => {
+    const tool = mcpToolsForCapabilities(['pages.edit']).find(
+      (candidate) => candidate.name === 'site_list_documents',
+    )
+    expect(tool).toBeUndefined()
+  })
+})
diff --git a/server/ai/mcp/tools/documentTools.ts b/server/ai/mcp/tools/documentTools.ts
@@ -0,0 +1,39 @@
+/**
+ * Headless site-document catalog for MCP.
+ *
+ * `site_list_documents` lists editable documents — pages, templates, and visual
+ * components — so an MCP agent can orient itself before reading or editing
+ * (the site system prompt tells it to call this first for chrome/template work).
+ *
+ * The site-scope `site_list_documents` in `../../tools/site/readTools.ts` resolves
+ * from the browser-posted `ctx.snapshot`, which is null over MCP (no chat turn,
+ * no editor snapshot) — calling it there throws on `snap.currentDocument`. This
+ * headless version assembles the catalog straight from the DB
+ * (`getDraftSiteDocument`) and is ordered ahead of the site toolset in the MCP
+ * registry so it wins the de-dup. There is no open-editor focus server-side, so
+ * no document is marked active/current; `get_context` reports the live editor.
+ */
+import { Type } from '@core/utils/typeboxHelpers'
+import { describeAgentDocuments } from '@core/ai'
+import type { AiTool, ToolContext } from '../../runtime/types'
+import { getDraftSiteDocument } from '../../../repositories/publish'
+
+export const documentMcpTools: AiTool[] = [
+  {
+    name: 'site_list_documents',
+    description:
+      'List editable documents: pages, templates, and visual components. Use the returned document refs with site_read_document/site_open_document. Each item includes rootNodeId, template metadata, and a short summary. Headless — no editor needed.',
+    scope: 'site',
+    execution: 'server',
+    inputSchema: Type.Object({}, { additionalProperties: false }),
+    requiredCapabilities: ['site.read'],
+    handler: async (_input, ctx: ToolContext) => {
+      const site = await getDraftSiteDocument(ctx.db)
+      if (!site) return { ok: false, error: 'No site found.' }
+      return {
+        currentDocument: null,
+        documents: describeAgentDocuments(site, null, null),
+      }
+    },
+  },
+]
diff --git a/src/core/ai/documentRefs.ts b/src/core/ai/documentRefs.ts
@@ -26,8 +26,8 @@ export function documentRefEquals(a: AgentDocumentRef | null | undefined, b: Age
 
 export function describeAgentDocuments(
   site: SiteDocument,
-  activePageId: string,
-  currentDocument: AgentDocumentRef,
+  activePageId: string | null,
+  currentDocument: AgentDocumentRef | null,
 ): AgentDocumentDescriptor[] {
   const descriptors: AgentDocumentDescriptor[] = []
 
