feat(canary): remote MCP server backed by the REST API

[aperolschpritz]

Warning

Canary feature. The QuickStack MCP server is experimental. Its settings are only visible when the canary update channel is enabled (Settings → Platform → Updates → canary channel), and the endpoint is served only when canary and the MCP toggle are on. The server is disabled by default and must be explicitly enabled. Operations can change in future versions.

Summary

Adds a remote MCP server for QuickStack, exposed at /api/mcp and gated as a canary feature.

• Targets MCP spec revision 2026-07-28 via the stable v2 SDK @modelcontextprotocol/server, mounted as a web-standard handler in the Next.js app (no custom-server change).
• Derives an operation catalog from the existing Elysia REST routes: operationId, summary, description, tags, and the params/query/body/200 response schemas. New REST routes appear automatically.
• Exposes exactly three meta-tools to keep the model's context small:
  • search_operations - discover operations on demand (search term + detail level name/summary/full), reporting readOnly and the tool to call.
  • execute_read_operation - read-only operations (GET/HEAD), annotated readOnlyHint: true.
  • execute_operation - mutating operations, annotated destructiveHint: true, so hosts can ask for confirmation.
• Execution dispatches through the existing v1Api.handle(request), so parsing, validation, Shared Authorization Checks, the central error mapper and all business logic are reused. No schema or handler duplication.
• Auth reuses the existing REST API Key logic (getIdentityFromApiKeyHeader); the bearer credential is forwarded to the internal request.
• Host/Origin validation via the SDK helpers: cross-origin browser requests are rejected, same-origin and no-Origin MCP clients pass.
• Binary/streaming routes (agent sandbox file read/write) are detected and marked unsupported.

Canary gating

• Settings page /settings/developer/mcp and its sidebar entry are hidden unless useCanaryChannel is on; direct URL access returns notFound().
• /api/mcp requires canary and the MCP toggle; otherwise 404.
• mcpServerEnabled defaults to false; the server must be explicitly enabled in the settings page.
• The settings page carries a destructive alert describing the secret-exposure risk.

Files

• src/server/mcp/operation-registry.ts - route introspection to operation descriptors (incl. readOnly).
• src/server/mcp/operation-executor.ts - builds and dispatches the internal request.
• src/server/mcp/mcp-auth.ts - REST API Key auth resolver.
• src/server/mcp/mcp-server.factory.ts - MCP server, the three tools, and read/write routing.
• src/server/mcp/mcp-handler.ts - host/origin/auth gate + SDK handler.
• src/app/api/mcp/route.ts - Next.js mount, canary + enablement gate.
• src/app/settings/developer/mcp/ - settings page (toggle, warning, client guides).
• Unit + integration tests.
• package.json / yarn.lock - add @modelcontextprotocol/server.

Testing

• src/server/mcp/mcp-handler.unit.spec.ts (19 tests) drives the handler seam with a fixture Elysia app and injected auth resolver: tool listing, search/filter/detail levels, read/write classification/misrouting, permission and auth failures, origin handling, execution, argument mapping and error mapping.
• src/app/api/mcp/route.unit.spec.ts (3 tests) covers the canary + enablement gate.
• src/__tests__/integration/server/mcp/mcp-handler.integration.spec.ts runs against the real v1Api with a real REST API Key and the existing Prisma test harness.
• npx tsc --noEmit clean for new code. One pre-existing unrelated error remains in src/frontend/utils/format.utils.unit.spec.ts.
• yarn lint clean.
• Full jsdom suite passes (797). Container/k3s-based integration tests cannot run in this environment (no Docker), consistent with existing tests.

[biersoeckli]

relates to #97