@yunsoft/yuncms-api 0.1.9 → 0.1.11

package/src/ai/tools.js

@@ -0,0 +1,304 @@
+import {
+  readManyWithRelations,
+  readOneWithRelations,
+} from '@yunsoft/yuncms-core';
+import * as z from 'zod/v4';
+
+import {
+  describeReadableCollection,
+  listReadableCollections,
+} from '../mcp.js';
+import { serviceOptionsFromRequest } from '../service-options.js';
+
+const SAFE_TOOL_ERROR_CODES = new Set([
+  'FORBIDDEN',
+  'FORBIDDEN_FIELD',
+  'COLLECTION_NOT_FOUND',
+  'INVALID_QUERY',
+  'QUERY_COST_LIMIT',
+  'QUERY_RELATION_DEPTH_LIMIT',
+  'QUERY_RELATION_ROW_LIMIT',
+  'INVALID_PAYLOAD',
+  'REQUIRED_FIELD_MISSING',
+  'FIELD_READ_ONLY',
+  'FILTER_REQUIRED',
+  'VALIDATION_FAILED',
+  'VALIDATION_BULK_LIMIT',
+  'FOREIGN_KEY_MISSING',
+  'FOREIGN_KEY_RESTRICTED',
+  'DUPLICATE_KEY',
+]);
+
+const collectionSchema = z.string()
+  .min(1)
+  .max(64)
+  .regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+const idSchema = z.union([z.string().min(1).max(191), z.number().finite()]);
+const delimitedSchema = z.union([
+  z.string().min(1).max(2_000),
+  z.array(z.string().min(1).max(191)).max(100),
+]);
+const filterSchema = z.record(z.string(), z.unknown());
+const aggregateSchema = z.record(
+  z.string(),
+  z.union([z.string().min(1), z.array(z.string().min(1)).max(20)]),
+);
+
+function toolError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function parseArguments(schema, args) {
+  const result = schema.safeParse(args ?? {});
+  if (result.success) return result.data;
+  throw toolError('AI_TOOL_ARGUMENTS_INVALID', 'The assistant generated invalid tool arguments');
+}
+
+function itemService(req, collection) {
+  const Service = req.context.services.ItemsService;
+  return new Service(collection, serviceOptionsFromRequest(req));
+}
+
+function readManySchema(maxItems) {
+  return z.object({
+    collection: collectionSchema,
+    fields: delimitedSchema.optional(),
+    expand: delimitedSchema.optional(),
+    filter: filterSchema.optional(),
+    search: z.string().max(200).optional(),
+    sort: delimitedSchema.optional(),
+    aggregate: aggregateSchema.optional(),
+    groupBy: delimitedSchema.optional(),
+    limit: z.number().int().min(1).max(maxItems).optional(),
+    offset: z.number().int().min(0).max(1_000_000).optional(),
+  }).strict();
+}
+
+const describeSchema = z.object({ collection: collectionSchema }).strict();
+const readOneSchema = z.object({
+  collection: collectionSchema,
+  id: idSchema,
+  fields: delimitedSchema.optional(),
+  expand: delimitedSchema.optional(),
+}).strict();
+const createSchema = z.object({
+  collection: collectionSchema,
+  data: z.record(z.string(), z.unknown()),
+}).strict();
+const updateSchema = z.object({
+  collection: collectionSchema,
+  id: idSchema,
+  data: z.record(z.string(), z.unknown()),
+}).strict();
+const deleteSchema = z.object({
+  collection: collectionSchema,
+  id: idSchema,
+}).strict();
+
+function toolDefinition(name, description, parameters) {
+  return {
+    type: 'function',
+    function: {
+      name,
+      description,
+      parameters: {
+        additionalProperties: false,
+        ...parameters,
+      },
+    },
+  };
+}
+
+function readToolDefinitions(maxItems) {
+  return [
+    toolDefinition(
+      'schema_list_collections',
+      'List project collections the current YunCMS user is allowed to read. Use this before guessing collection names.',
+      { type: 'object', properties: {}, required: [] },
+    ),
+    toolDefinition(
+      'schema_describe_collection',
+      'Describe readable fields, direct relations and CRUD capabilities for one collection using the current user permissions.',
+      {
+        type: 'object',
+        properties: { collection: { type: 'string' } },
+        required: ['collection'],
+      },
+    ),
+    toolDefinition(
+      'items_read_many',
+      'Read collection rows with YunCMS filtering, search, sorting, aggregates and relation-aware fields. Normal RBAC and query limits always apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          fields: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          expand: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          filter: { type: 'object' },
+          search: { type: 'string', maxLength: 200 },
+          sort: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          aggregate: { type: 'object' },
+          groupBy: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          limit: { type: 'integer', minimum: 1, maximum: maxItems },
+          offset: { type: 'integer', minimum: 0, maximum: 1_000_000 },
+        },
+        required: ['collection'],
+      },
+    ),
+    toolDefinition(
+      'items_read_one',
+      'Read one item by id with optional field and relation selection. Normal YunCMS read permissions apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          id: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+          fields: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+          expand: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, maxItems: 100 }] },
+        },
+        required: ['collection', 'id'],
+      },
+    ),
+  ];
+}
+
+function writeToolDefinitions({ deletesEnabled = false } = {}) {
+  const tools = [
+    toolDefinition(
+      'items_create',
+      'Create one YunCMS item. Use only when the user clearly asks to create data. Field permissions, validation, hooks and auditing apply.',
+      {
+        type: 'object',
+        properties: { collection: { type: 'string' }, data: { type: 'object' } },
+        required: ['collection', 'data'],
+      },
+    ),
+    toolDefinition(
+      'items_update',
+      'Update one YunCMS item by id. Use only when the user clearly asks to change data. Normal permissions and validation apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          id: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+          data: { type: 'object' },
+        },
+        required: ['collection', 'id', 'data'],
+      },
+    ),
+  ];
+  if (deletesEnabled) tools.push(toolDefinition(
+      'items_delete',
+      'Delete one YunCMS item by id. Use only when the user explicitly asks to delete that item. Normal delete permissions and hooks apply.',
+      {
+        type: 'object',
+        properties: {
+          collection: { type: 'string' },
+          id: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+        },
+        required: ['collection', 'id'],
+      },
+    ));
+  return tools;
+}
+
+export function aiToolDefinitions({
+  writesEnabled = false,
+  deletesEnabled = false,
+  maxItems = 100,
+} = {}) {
+  return writesEnabled
+    ? [...readToolDefinitions(maxItems), ...writeToolDefinitions({ deletesEnabled })]
+    : readToolDefinitions(maxItems);
+}
+
+export async function executeAiTool(req, name, args, {
+  writesEnabled = false,
+  deletesEnabled = false,
+  maxItems = 100,
+} = {}) {
+  if (name === 'schema_list_collections') {
+    parseArguments(z.object({}).strict(), args);
+    return { collections: await listReadableCollections(req, { maxItems }) };
+  }
+  if (name === 'schema_describe_collection') {
+    const input = parseArguments(describeSchema, args);
+    return describeReadableCollection(req, input.collection);
+  }
+  if (name === 'items_read_many') {
+    const { collection, ...query } = parseArguments(readManySchema(maxItems), args);
+    return readManyWithRelations({
+      collection,
+      query: { ...query, limit: query.limit ?? Math.min(100, maxItems) },
+      options: serviceOptionsFromRequest(req),
+      ItemsServiceClass: req.context.services.ItemsService,
+    });
+  }
+  if (name === 'items_read_one') {
+    const input = parseArguments(readOneSchema, args);
+    return readOneWithRelations({
+      collection: input.collection,
+      id: input.id,
+      query: {
+        ...(input.fields ? { fields: input.fields } : {}),
+        ...(input.expand ? { expand: input.expand } : {}),
+      },
+      options: serviceOptionsFromRequest(req),
+      ItemsServiceClass: req.context.services.ItemsService,
+    });
+  }
+
+  if (!writesEnabled) throw toolError('AI_TOOL_FORBIDDEN', 'Data-changing assistant tools are disabled');
+
+  if (name === 'items_create') {
+    const input = parseArguments(createSchema, args);
+    return itemService(req, input.collection).createOne(input.data);
+  }
+  if (name === 'items_update') {
+    const input = parseArguments(updateSchema, args);
+    return itemService(req, input.collection).updateOne(input.id, input.data);
+  }
+  if (name === 'items_delete') {
+    if (!deletesEnabled) throw toolError('AI_TOOL_FORBIDDEN', 'Assistant delete tools are disabled');
+    const input = parseArguments(deleteSchema, args);
+    return { deleted: await itemService(req, input.collection).deleteOne(input.id) };
+  }
+
+  throw toolError('AI_TOOL_UNKNOWN', 'The assistant requested an unknown tool');
+}
+
+export function safeAiToolError(error) {
+  const code = SAFE_TOOL_ERROR_CODES.has(error?.code)
+    || ['AI_TOOL_ARGUMENTS_INVALID', 'AI_TOOL_FORBIDDEN', 'AI_TOOL_UNKNOWN'].includes(error?.code)
+    ? error.code
+    : 'INTERNAL_ERROR';
+  return {
+    error: {
+      code,
+      message: code === 'INTERNAL_ERROR'
+        ? 'Tool execution failed'
+        : String(error?.message ?? 'Tool execution failed'),
+    },
+  };
+}
+
+export function serializeAiToolResult(value, maxBytes = 250_000) {
+  const text = JSON.stringify({ data: value });
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return text;
+  return JSON.stringify({
+    error: {
+      code: 'AI_TOOL_RESULT_TOO_LARGE',
+      message: `Tool result exceeds the configured ${maxBytes} byte limit. Narrow the query and try again.`,
+    },
+  });
+}
+
+export function operationSummary(name, args = {}, success = true) {
+  return {
+    operation: name,
+    collection: typeof args.collection === 'string' ? args.collection : null,
+    success,
+  };
+}

package/src/app.js

@@ -16,6 +16,7 @@ import { createItemsRouter } from './routes/items.js';
 import { createPermissionsRouter } from './routes/permissions.js';
 import { createRolesRouter } from './routes/roles.js';
 import { createSchemaRouter } from './routes/schema.js';
+import { createStudioNavigationRouter } from './routes/studio-navigation.js';
 import { createStudioSettingsRouter } from './routes/studio-settings.js';
 import { createSystemSchemaRouter } from './routes/system-schema.js';
 import { createUsersRouter } from './routes/users.js';
@@ -127,6 +128,7 @@ export function createApp({
   redisClient = null,
   externalAuthRegistry = null,
   endpointExtensions = [],
+  aiRouter = null,
   mcpRouter = null,
   studioRoot = undefined,
 }) {
@@ -187,7 +189,9 @@ export function createApp({
   const requestEvents = createRequestEvents(emitter);
   if (requestEvents) app.use(requestEvents);
 
+  if (aiRouter) app.use('/ai', aiRouter);
   if (mcpRouter) app.use('/mcp', mcpRouter);
+  app.use('/studio-navigation', createStudioNavigationRouter());
   app.use('/studio-settings', createStudioSettingsRouter());
   app.use('/auth', createAuthRouter({ mailer, config, logger, rateLimitStore, externalAuthRegistry }));
   app.use('/items', createItemsRouter());

package/src/error-response.js

@@ -15,6 +15,7 @@ const STATUS_BY_CODE = new Map([
   ['ROLE_NOT_FOUND', 404],
   ['PERMISSION_NOT_FOUND', 404],
   ['FILE_NOT_FOUND', 404],
+  ['NAVIGATION_GROUP_NOT_FOUND', 404],
   ['NOT_FOUND', 404],
   ['COLLECTION_EXISTS', 409],
   ['FIELD_EXISTS', 409],
@@ -28,6 +29,9 @@ const STATUS_BY_CODE = new Map([
   ['DUPLICATE_KEY', 409],
   ['FOREIGN_KEY_MISSING', 409],
   ['FOREIGN_KEY_RESTRICTED', 409],
+  ['SINGLETON_ITEM_EXISTS', 409],
+  ['SINGLETON_MULTIPLE_ITEMS', 409],
+  ['SINGLETON_BULK_CREATE_FORBIDDEN', 409],
   ['RATE_LIMITED', 429],
   ['PAYLOAD_TOO_LARGE', 413],
   ['INVALID_QUERY', 400],
@@ -43,6 +47,10 @@ const STATUS_BY_CODE = new Map([
   ['INVALID_FILE_CONTENT', 400],
   ['FILE_MIME_MISMATCH', 400],
   ['INVALID_MAIL_MESSAGE', 400],
+  ['INVALID_AI_REQUEST', 400],
+  ['INVALID_AI_CONFIG', 400],
+  ['INVALID_MCP_CONFIG', 400],
+  ['AI_TOOL_ARGUMENTS_INVALID', 400],
   ['STORAGE_NOT_FOUND', 400],
   ['STORAGE_INVENTORY_UNSUPPORTED', 400],
   ['UNSUPPORTED_SCHEMA_UPDATE', 400],
@@ -58,6 +66,14 @@ const STATUS_BY_CODE = new Map([
   ['FILTER_REQUIRED', 400],
   ['VALIDATION_FAILED', 400],
   ['VALIDATION_BULK_LIMIT', 400],
+  ['AI_PROVIDER_UNAVAILABLE', 502],
+  ['AI_PROVIDER_RESPONSE_INVALID', 502],
+  ['AI_TOOL_ROUND_LIMIT', 502],
+  ['AI_TOOL_CALL_LIMIT', 502],
+  ['AI_PROVIDER_TIMEOUT', 504],
+  ['AI_NOT_CONFIGURED', 503],
+  ['AI_SETTINGS_KEY_INVALID', 503],
+  ['AI_SECRET_DECRYPT_FAILED', 503],
   ['MAIL_NOT_CONFIGURED', 503],
   ['STORAGE_INVENTORY_FAILED', 503],
   ['DATABASE_MIGRATION_REQUIRED', 503],

package/src/mcp/config.js

@@ -0,0 +1,154 @@
+export const DEFAULT_MCP_SETTINGS = Object.freeze({
+  enabled: false,
+  writesEnabled: false,
+  requireAuthentication: true,
+  allowedOrigins: Object.freeze([]),
+  allowedHosts: Object.freeze([]),
+  maxItems: 100,
+  maxResultBytes: 1_000_000,
+});
+
+const PATCH_KEYS = new Set([
+  'enabled',
+  'writes_enabled',
+  'require_authentication',
+  'allowed_origins',
+  'allowed_hosts',
+  'max_items',
+  'max_result_bytes',
+]);
+
+function configError(message) {
+  const error = new Error(message);
+  error.code = 'INVALID_MCP_CONFIG';
+  return error;
+}
+
+function normalizeBoolean(value, name) {
+  if (typeof value !== 'boolean') throw configError(`${name} must be a boolean`);
+  return value;
+}
+
+function normalizeInteger(value, name, { min, max }) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    throw configError(`${name} must be an integer between ${min} and ${max}`);
+  }
+  return parsed;
+}
+
+function listValues(value, name) {
+  let source = value;
+  if (typeof source === 'string') {
+    const trimmed = source.trim();
+    if (trimmed.startsWith('[')) {
+      try {
+        source = JSON.parse(trimmed);
+      } catch {
+        throw configError(`${name} must be a list`);
+      }
+    } else {
+      source = source.split(/[\n,]/);
+    }
+  }
+  if (!Array.isArray(source)) throw configError(`${name} must be a list`);
+  const entries = source.map((entry) => {
+    if (typeof entry !== 'string') throw configError(`${name} entries must be strings`);
+    return entry.trim();
+  }).filter(Boolean);
+  if (entries.length > 50) throw configError(`${name} cannot contain more than 50 entries`);
+  return entries;
+}
+
+export function normalizeMcpOrigins(value) {
+  return [...new Set(listValues(value, 'allowed_origins').map((entry) => {
+    let url;
+    try {
+      url = new URL(entry);
+    } catch {
+      throw configError(`allowed_origins contains an invalid URL: ${entry}`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      throw configError(`allowed_origins must use http or https: ${entry}`);
+    }
+    if (url.username || url.password) {
+      throw configError(`allowed_origins cannot include credentials: ${entry}`);
+    }
+    return url.origin.toLowerCase();
+  }))];
+}
+
+export function normalizeMcpHosts(value) {
+  return [...new Set(listValues(value, 'allowed_hosts').map((entry) => {
+    if (/[:][/][/]|[\\/?#@\s\0]/.test(entry)) {
+      throw configError(`allowed_hosts contains an invalid host: ${entry}`);
+    }
+    let url;
+    try {
+      url = new URL(`http://${entry}`);
+    } catch {
+      throw configError(`allowed_hosts contains an invalid host: ${entry}`);
+    }
+    if (url.username || url.password || url.pathname !== '/' || url.search || url.hash || !url.host) {
+      throw configError(`allowed_hosts contains an invalid host: ${entry}`);
+    }
+    return url.host.toLowerCase();
+  }))];
+}
+
+export function normalizeMcpSettingsPatch(patch = {}) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    throw configError('MCP settings patch must be an object');
+  }
+  const keys = Object.keys(patch);
+  if (keys.length === 0 || keys.some((key) => !PATCH_KEYS.has(key))) {
+    throw configError('MCP settings patch contains unsupported properties');
+  }
+  const normalized = {};
+  if (Object.hasOwn(patch, 'enabled')) normalized.enabled = normalizeBoolean(patch.enabled, 'enabled');
+  if (Object.hasOwn(patch, 'writes_enabled')) normalized.writesEnabled = normalizeBoolean(patch.writes_enabled, 'writes_enabled');
+  if (Object.hasOwn(patch, 'require_authentication')) normalized.requireAuthentication = normalizeBoolean(patch.require_authentication, 'require_authentication');
+  if (Object.hasOwn(patch, 'allowed_origins')) normalized.allowedOrigins = normalizeMcpOrigins(patch.allowed_origins);
+  if (Object.hasOwn(patch, 'allowed_hosts')) normalized.allowedHosts = normalizeMcpHosts(patch.allowed_hosts);
+  if (Object.hasOwn(patch, 'max_items')) normalized.maxItems = normalizeInteger(patch.max_items, 'max_items', { min: 1, max: 500 });
+  if (Object.hasOwn(patch, 'max_result_bytes')) normalized.maxResultBytes = normalizeInteger(patch.max_result_bytes, 'max_result_bytes', { min: 10_000, max: 10_000_000 });
+  return normalized;
+}
+
+function rowList(value, name, normalize) {
+  try {
+    return normalize(value);
+  } catch (error) {
+    if (error?.code === 'INVALID_MCP_CONFIG') throw error;
+    throw configError(`${name} contains invalid saved data`);
+  }
+}
+
+export function mcpRuntimeSettingsFromRow(row) {
+  if (!row) throw configError('MCP settings are missing; run YunCMS bootstrap');
+  return Object.freeze({
+    enabled: Boolean(row.enabled),
+    writesEnabled: Boolean(row.writes_enabled),
+    requireAuthentication: Boolean(row.require_authentication),
+    allowedOrigins: Object.freeze(rowList(row.allowed_origins, 'allowed_origins', normalizeMcpOrigins)),
+    allowedHosts: Object.freeze(rowList(row.allowed_hosts, 'allowed_hosts', normalizeMcpHosts)),
+    maxItems: normalizeInteger(row.max_items, 'max_items', { min: 1, max: 500 }),
+    maxResultBytes: normalizeInteger(row.max_result_bytes, 'max_result_bytes', { min: 10_000, max: 10_000_000 }),
+  });
+}
+
+export function mcpAdminSettingsFromRow(row) {
+  const runtime = mcpRuntimeSettingsFromRow(row);
+  return {
+    enabled: runtime.enabled,
+    writes_enabled: runtime.writesEnabled,
+    require_authentication: runtime.requireAuthentication,
+    allowed_origins: [...runtime.allowedOrigins],
+    allowed_hosts: [...runtime.allowedHosts],
+    max_items: runtime.maxItems,
+    max_result_bytes: runtime.maxResultBytes,
+    updated_at: row.updated_at ?? null,
+  };
+}
+
+export { configError };

package/src/mcp/settings-store.js

@@ -0,0 +1,78 @@
+import {
+  mcpAdminSettingsFromRow,
+  mcpRuntimeSettingsFromRow,
+  normalizeMcpSettingsPatch,
+} from './config.js';
+
+function settingsError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function columnAssignments(normalized) {
+  const assignments = [];
+  const params = [];
+  const add = (column, value) => {
+    assignments.push(`${column} = ?`);
+    params.push(value);
+  };
+  if (Object.hasOwn(normalized, 'enabled')) add('enabled', normalized.enabled ? 1 : 0);
+  if (Object.hasOwn(normalized, 'writesEnabled')) add('writes_enabled', normalized.writesEnabled ? 1 : 0);
+  if (Object.hasOwn(normalized, 'requireAuthentication')) add('require_authentication', normalized.requireAuthentication ? 1 : 0);
+  if (Object.hasOwn(normalized, 'allowedOrigins')) add('allowed_origins', JSON.stringify(normalized.allowedOrigins));
+  if (Object.hasOwn(normalized, 'allowedHosts')) add('allowed_hosts', JSON.stringify(normalized.allowedHosts));
+  if (Object.hasOwn(normalized, 'maxItems')) add('max_items', normalized.maxItems);
+  if (Object.hasOwn(normalized, 'maxResultBytes')) add('max_result_bytes', normalized.maxResultBytes);
+  return { assignments, params };
+}
+
+export class McpSettingsStore {
+  constructor({ database } = {}) {
+    if (!database) throw new Error('MCP settings store requires database');
+    this.database = database;
+  }
+
+  async #row() {
+    const [rows] = await this.database.query(
+      `SELECT id, enabled, writes_enabled, require_authentication, allowed_origins,
+              allowed_hosts, max_items, max_result_bytes, updated_at
+       FROM yuncms_mcp_settings
+       WHERE id = 1
+       LIMIT 1`,
+    );
+    const row = rows[0];
+    if (!row) throw settingsError('DATABASE_MIGRATION_REQUIRED', 'MCP settings are missing; run YunCMS bootstrap');
+    return row;
+  }
+
+  async readAdmin() {
+    return mcpAdminSettingsFromRow(await this.#row());
+  }
+
+  async readRuntime() {
+    return mcpRuntimeSettingsFromRow(await this.#row());
+  }
+
+  async update(patch = {}) {
+    const normalized = normalizeMcpSettingsPatch(patch);
+    const current = await this.#row();
+    const { assignments, params } = columnAssignments(normalized);
+    if (assignments.length === 0) throw settingsError('INVALID_MCP_CONFIG', 'MCP settings patch has no effective changes');
+
+    const effectiveEnabled = Object.hasOwn(normalized, 'enabled') ? normalized.enabled : Boolean(current.enabled);
+    const effectiveAllowedHosts = Object.hasOwn(normalized, 'allowedHosts')
+      ? normalized.allowedHosts
+      : mcpRuntimeSettingsFromRow(current).allowedHosts;
+    if (effectiveEnabled && effectiveAllowedHosts.length === 0) {
+      throw settingsError('INVALID_MCP_CONFIG', 'Add at least one allowed host before enabling MCP');
+    }
+
+    params.push(1);
+    await this.database.query(
+      `UPDATE yuncms_mcp_settings SET ${assignments.join(', ')} WHERE id = ?`,
+      params,
+    );
+    return this.readAdmin();
+  }
+}

package/src/mcp.js

@@ -327,10 +327,55 @@ export function createMcpAccessGuard(mcpConfig = {}) {
   };
 }
 
-export function createMcpRouter({ config, logger = console } = {}) {
-  if (!config?.mcp?.enabled) return null;
+export function requireMcpAdministrator(req) {
+  if (req?.authMethod === 'public' || !req?.accountability?.user) {
+    const error = new Error('MCP settings require an authenticated YunCMS account');
+    error.code = 'UNAUTHORIZED';
+    throw error;
+  }
+  if (req.accountability?.admin === true || req.accountability?.system === true) return;
+  const error = new Error('MCP settings require administrator access');
+  error.code = 'FORBIDDEN';
+  throw error;
+}
+
+export function createMcpRouter({ settingsStore, logger = console } = {}) {
+  if (!settingsStore) throw new Error('MCP settings store is required');
   const router = express.Router();
-  router.use(createMcpAccessGuard(config.mcp));
+
+  router.get('/settings', async (req, res, next) => {
+    try {
+      requireMcpAdministrator(req);
+      return res.json({ data: await settingsStore.readAdmin(), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.patch('/settings', async (req, res, next) => {
+    try {
+      requireMcpAdministrator(req);
+      return res.json({ data: await settingsStore.update(req.body ?? {}), request_id: req.id });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.use(async (req, res, next) => {
+    try {
+      const mcpConfig = await settingsStore.readRuntime();
+      if (!mcpConfig.enabled) {
+        return res.status(404).json({
+          errors: [{ code: 'MCP_DISABLED', message: 'MCP is disabled', request_id: req.id ?? null }],
+        });
+      }
+      req.mcpConfig = mcpConfig;
+      return createMcpAccessGuard(mcpConfig)(req, res, next);
+    } catch (error) {
+      return next(error);
+    }
+  });
+
   router.all('/', (req, res, next) => {
     if (req.method === 'POST') return next();
     res.set('allow', 'POST');
@@ -344,7 +389,7 @@ export function createMcpRouter({ config, logger = console } = {}) {
       code: error?.code ?? null,
     });
     const handler = createMcpHandler(
-      () => createRequestMcpServer(req, config.mcp),
+      () => createRequestMcpServer(req, req.mcpConfig),
       { legacy: 'stateless', onerror: reportError },
     );
     const nodeHandler = toNodeHandler(handler, { onerror: reportError });