feat(mcp): MCP Server plugin — expose content as AI agent tools (#784) (#991)

* feat(mcp): MCP Server plugin for SonicJS (#784)

Implements a Model Context Protocol server as a first-class SonicJS
plugin, exposing content collections as JSON-RPC 2.0 tools for AI
agents (Claude Code, Cursor, etc).

- POST /mcp endpoint — initialize, tools/list, tools/call, resources/*
- Auth via existing API Keys plugin (Bearer sk_… header)
- Per-collection tools: list_, get_, create_, update_, publish_, delete_
- Auto-populates `user` type fields (e.g. author) with API key owner
- GET /admin/mcp dashboard — endpoint URL, exposed collections, Claude
  Code / Cursor integration snippets
- Sidebar "Author" field resolves created_by UUID to email in all
  content list and edit views
- Mounted at /mcp (not /api/mcp) to avoid /api/:collection catch-all
- E2E spec: tests/e2e/93-mcp-admin.spec.ts

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(mcp): address code review findings (XSS, D1 limit, slug miss, TOCTOU, N+1)

- R8 violation: add escapeHtml to Author sidebar in admin-content-form
- D1 100-param limit: chunk auth_user IN-clause lookup into 99-param batches
- execGet slug: replace O(N) list scan with direct getBySlug() repo query
- execDelete TOCTOU: reuse existence-check result instead of re-fetching
- execListCollections: remove N serial findById DB calls; types already
  resolved active by resolveMcpConfig — now a sync O(1) map

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(mcp): enforce redactFields on write, slug draft fallback, shared phase flags

Fresh-eyes review follow-ups on the MCP plugin:

- redactFields now stripped from create/update input, not just read output —
  a client can no longer populate a field it can never read back.
- getBySlug falls back to the current draft so a never-published doc is
  reachable by slug (parity with getById); published still preferred.
- PHASE_FLAGS hoisted to a single exported const in tools/registry so the
  admin dashboard tool list can't drift from what the endpoint serves.
- execList documents its post-ACL truncation tradeoff.
- Corrected stale /api/mcp endpoint comments (actual mount is /mcp).
- Integration tests for slug-draft resolution + redact-on-write.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(mcp): live JSON-RPC endpoint E2E — key mint + slug-draft resolution

Drives POST /mcp the way an agent does: mints a one-time API key via the
api-keys admin route, then Bearer-auths JSON-RPC. Pins the review fix that
get_* by slug resolves a never-published draft. Covers unauthenticated
rejection, initialize handshake, and tools/list advertising.

Verified locally against a running dev server (4/4). CI runs it on PR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(deps): resync package-lock with npm 10 for CI npm ci

The lockfile was authored by npm 11 (node 24), which resolves optional
platform deps differently than the CI matrix (node 20/22 → npm 10). npm ci
on CI rejected it as out of sync (missing better-sqlite3@12.11.1,
@emnapi/*, esbuild@0.28.1). Regenerated under node 22 / npm 10 so the
lock matches what CI installs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: lane711

docs/ai/plans/mcp-plugin-plan.md

@@ -13,6 +13,7 @@ import {
   createSonicJSApp,
   emailReconciliationPlugin,
   getHookSystem,
+  mcpPlugin,
   redirectPlugin,
   registerCollections,
 } from '@sonicjs-cms/core';
@@ -34,7 +35,7 @@ const config: SonicJSConfig = {
   plugins: {
     // Add plugins to this array to activate them. Each plugin's register()
     // runs synchronously at startup; onBoot() runs async on first request.
-    register: [redirectPlugin, examplePlugin],
+    register: [redirectPlugin, examplePlugin, mcpPlugin()],
     disableAll: false,
   },
 };

my-sonicjs-app/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * AUTO-GENERATED FILE - DO NOT EDIT
  * Generated by: scripts/generate-migrations.ts
- * Generated at: 2026-07-02T22:07:06.083Z
+ * Generated at: 2026-07-02T23:45:16.345Z
  *
  * This file contains all migration SQL bundled for use in Cloudflare Workers
  * where filesystem access is not available at runtime.

package-lock.json

@@ -373,6 +373,10 @@ export { OAuthService, BUILT_IN_PROVIDERS } from './plugins/core-plugins/oauth-p
 export { userProfilesPlugin, createUserProfilesPlugin, defineUserProfile, getUserProfileConfig } from './plugins/core-plugins/user-profiles'
 export type { ProfileFieldDefinition, UserProfileConfig } from './plugins/core-plugins/user-profiles'
 
+// MCP Server Plugin (opt-in)
+export { mcpPlugin, createMcpPlugin } from './plugins/core-plugins/mcp-plugin'
+export type { McpConfigInput, McpConfig } from './plugins/core-plugins/mcp-plugin'
+
 // ============================================================================
 // Version
 // ============================================================================

packages/core/src/db/migrations-bundle.ts

@@ -43,6 +43,8 @@ export { stripePlugin, createStripePlugin, SubscriptionService, StripeAPI, requi
 export { dashboardPlugin, createDashboardPlugin } from './dashboard-plugin'
 export { multiTenantPlugin, createMultiTenantPlugin, TenantService } from './multi-tenant-plugin'
 export { versioningPlugin, createVersioningPlugin } from './versioning-plugin'
+export { mcpPlugin, createMcpPlugin } from './mcp-plugin'
+export type { McpConfigInput, McpConfig } from './mcp-plugin'
 export { menuPlugin, createMenuPlugin } from './menu-plugin'
 
 // Core plugins list - now imported from auto-generated registry

packages/core/src/index.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { resolveMcpConfig } from '../config'
+import type { CollectionRecord } from '../../../../services/collection-registry'
+
+function col(name: string, displayName?: string): CollectionRecord {
+  return {
+    id: name,
+    name,
+    displayName: displayName ?? name,
+    schema: { type: 'object', properties: {} },
+  } as CollectionRecord
+}
+
+const ALL = [col('posts', 'Posts'), col('pages', 'Pages'), col('products', 'Products')]
+
+describe('resolveMcpConfig', () => {
+  it('exposes every active collection by default with read+write', () => {
+    const r = resolveMcpConfig({}, ALL)
+    expect(r.types.map((t) => t.typeId)).toEqual(['posts', 'pages', 'products'])
+    expect(r.types.every((t) => t.read && t.write)).toBe(true)
+    expect(r.listLimit).toBe(50)
+    expect(r.redactFields).toEqual([])
+  })
+
+  it('applies the expose allowlist', () => {
+    const r = resolveMcpConfig({ expose: ['posts'] }, ALL)
+    expect(r.types.map((t) => t.typeId)).toEqual(['posts'])
+  })
+
+  it('applies per-type read/write overrides', () => {
+    const r = resolveMcpConfig({ types: { pages: { read: true, write: false } } }, ALL)
+    const pages = r.types.find((t) => t.typeId === 'pages')!
+    expect(pages.write).toBe(false)
+    expect(pages.read).toBe(true)
+  })
+
+  it('carries redactFields and listLimit through', () => {
+    const r = resolveMcpConfig({ redactFields: ['a', 'b'], listLimit: 10 }, ALL)
+    expect(r.redactFields).toEqual(['a', 'b'])
+    expect(r.listLimit).toBe(10)
+  })
+
+  it('resolves display names from the registry', () => {
+    const r = resolveMcpConfig({ expose: ['products'] }, ALL)
+    expect(r.types[0]!.displayName).toBe('Products')
+  })
+
+  it('caps listLimit at 200', () => {
+    expect(() => resolveMcpConfig({ listLimit: 999 }, ALL)).toThrow()
+  })
+})

packages/core/src/plugins/core-plugins/index.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest'
+import { fieldToJsonSchema, collectionToJsonSchema } from '../schema/field-to-jsonschema'
+import type { CollectionSchema } from '../../../../types/collection-config'
+
+describe('fieldToJsonSchema', () => {
+  it('maps string-like types to string with constraints', () => {
+    expect(fieldToJsonSchema({ type: 'string', minLength: 2, maxLength: 5, pattern: '^a' })).toEqual({
+      type: 'string',
+      minLength: 2,
+      maxLength: 5,
+      pattern: '^a',
+    })
+    expect(fieldToJsonSchema({ type: 'slug' })).toEqual({ type: 'string' })
+    expect(fieldToJsonSchema({ type: 'richtext' })).toEqual({ type: 'string' })
+    expect(fieldToJsonSchema({ type: 'email' })).toEqual({ type: 'string' })
+  })
+
+  it('maps number with min/max', () => {
+    expect(fieldToJsonSchema({ type: 'number', min: 1, max: 10 })).toEqual({
+      type: 'number',
+      minimum: 1,
+      maximum: 10,
+    })
+  })
+
+  it('maps boolean and checkbox', () => {
+    expect(fieldToJsonSchema({ type: 'boolean' })).toEqual({ type: 'boolean' })
+    expect(fieldToJsonSchema({ type: 'checkbox' })).toEqual({ type: 'boolean' })
+  })
+
+  it('maps date/datetime to date-time string', () => {
+    expect(fieldToJsonSchema({ type: 'datetime' })).toEqual({ type: 'string', format: 'date-time' })
+  })
+
+  it('maps select/radio to enum string', () => {
+    expect(fieldToJsonSchema({ type: 'select', enum: ['a', 'b'] })).toEqual({
+      type: 'string',
+      enum: ['a', 'b'],
+    })
+  })
+
+  it('maps multiselect to array of enum strings', () => {
+    expect(fieldToJsonSchema({ type: 'multiselect', enum: ['a', 'b'] })).toEqual({
+      type: 'array',
+      items: { type: 'string', enum: ['a', 'b'] },
+    })
+  })
+
+  it('maps array with nested items', () => {
+    expect(fieldToJsonSchema({ type: 'array', items: { type: 'number' } })).toEqual({
+      type: 'array',
+      items: { type: 'number' },
+    })
+  })
+
+  it('maps object with nested properties', () => {
+    expect(fieldToJsonSchema({ type: 'object', properties: { a: { type: 'string' } } })).toEqual({
+      type: 'object',
+      properties: { a: { type: 'string' } },
+    })
+  })
+
+  it('carries title and description through', () => {
+    expect(fieldToJsonSchema({ type: 'string', title: 'Name', description: 'Full name' })).toEqual({
+      type: 'string',
+      title: 'Name',
+      description: 'Full name',
+    })
+  })
+})
+
+describe('collectionToJsonSchema', () => {
+  const schema: CollectionSchema = {
+    type: 'object',
+    properties: {
+      id: { type: 'string' },
+      created_at: { type: 'datetime' },
+      title: { type: 'string', required: true },
+      body: { type: 'richtext' },
+      secret: { type: 'string' },
+    },
+    required: ['title'],
+  }
+
+  it('produces an object schema with all properties by default', () => {
+    const out = collectionToJsonSchema(schema)
+    expect(out.type).toBe('object')
+    expect(Object.keys(out.properties as object)).toEqual(['id', 'created_at', 'title', 'body', 'secret'])
+    expect(out.required).toEqual(['title'])
+  })
+
+  it('strips system fields when forWrite', () => {
+    const out = collectionToJsonSchema(schema, { forWrite: true })
+    const keys = Object.keys(out.properties as object)
+    expect(keys).not.toContain('id')
+    expect(keys).not.toContain('created_at')
+    expect(keys).toContain('title')
+  })
+
+  it('omits redacted fields', () => {
+    const out = collectionToJsonSchema(schema, { redactFields: ['secret'] })
+    expect(Object.keys(out.properties as object)).not.toContain('secret')
+  })
+
+  it('unions field-level and schema-level required', () => {
+    const out = collectionToJsonSchema({
+      type: 'object',
+      properties: { a: { type: 'string', required: true }, b: { type: 'string' } },
+      required: ['b'],
+    })
+    expect((out.required as string[]).sort()).toEqual(['a', 'b'])
+  })
+
+  it('omits required key entirely when nothing is required', () => {
+    const out = collectionToJsonSchema({ type: 'object', properties: { a: { type: 'string' } } })
+    expect('required' in out).toBe(false)
+  })
+})

packages/core/src/plugins/core-plugins/mcp-plugin/__tests__/config.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { parseJsonRpc, rpcResult, rpcError, JSON_RPC } from '../jsonrpc'
+
+describe('parseJsonRpc', () => {
+  it('accepts a well-formed request and defaults params to {}', () => {
+    const r = parseJsonRpc({ jsonrpc: '2.0', id: 1, method: 'tools/list' })
+    expect('error' in r).toBe(false)
+    if (!('error' in r)) {
+      expect(r.method).toBe('tools/list')
+      expect(r.id).toBe(1)
+      expect(r.params).toEqual({})
+    }
+  })
+
+  it('preserves provided params', () => {
+    const r = parseJsonRpc({ jsonrpc: '2.0', id: 'a', method: 'tools/call', params: { name: 'x' } })
+    if (!('error' in r)) expect(r.params).toEqual({ name: 'x' })
+  })
+
+  it('normalizes a missing id to null', () => {
+    const r = parseJsonRpc({ jsonrpc: '2.0', method: 'initialize' })
+    if (!('error' in r)) expect(r.id).toBeNull()
+  })
+
+  it('rejects a non-object body', () => {
+    const r = parseJsonRpc('nope')
+    expect('error' in r && r.error.code).toBe(JSON_RPC.INVALID_REQUEST)
+  })
+
+  it('rejects an array body', () => {
+    const r = parseJsonRpc([{ jsonrpc: '2.0', method: 'x' }])
+    expect('error' in r && r.error.code).toBe(JSON_RPC.INVALID_REQUEST)
+  })
+
+  it('rejects a wrong jsonrpc version', () => {
+    const r = parseJsonRpc({ jsonrpc: '1.0', method: 'x' })
+    expect('error' in r && r.error.code).toBe(JSON_RPC.INVALID_REQUEST)
+  })
+
+  it('rejects a missing/empty method', () => {
+    expect('error' in parseJsonRpc({ jsonrpc: '2.0', id: 1 })).toBe(true)
+    expect('error' in parseJsonRpc({ jsonrpc: '2.0', id: 1, method: '' })).toBe(true)
+  })
+})
+
+describe('rpc envelopes', () => {
+  it('builds a success envelope', () => {
+    expect(rpcResult(1, { ok: true })).toEqual({ jsonrpc: '2.0', id: 1, result: { ok: true } })
+  })
+
+  it('coerces undefined id to null', () => {
+    expect(rpcResult(undefined as any, {}).id).toBeNull()
+    expect(rpcError(undefined as any, JSON_RPC.INTERNAL_ERROR, 'x').id).toBeNull()
+  })
+
+  it('builds an error envelope and only includes data when provided', () => {
+    expect(rpcError(2, JSON_RPC.METHOD_NOT_FOUND, 'nope')).toEqual({
+      jsonrpc: '2.0',
+      id: 2,
+      error: { code: JSON_RPC.METHOD_NOT_FOUND, message: 'nope' },
+    })
+    expect(rpcError(2, JSON_RPC.INVALID_PARAMS, 'bad', { field: 'x' }).error.data).toEqual({ field: 'x' })
+  })
+})