PSA/docs/plans/2026-06-07-alga-mcp-mvp-release/SCRATCHPAD.md

SCRATCHPAD — MCP MVP Release Readiness

Closes the release gap after Phase 1 + Phase 2 (both built & live-verified). Prior plan + design: docs/plans/2026-06-06-alga-mcp-server/ (design.md §10, SCRATCHPAD).

Current state (what's already built & where)

CE (correct, keep):

• packages/agent-tooling — registry schema + ranked search + request-building + 3 meta-tool defs.
• packages/alga-mcp-connector — local stdio connector (npx).
• server/src/app/api/v1/meta/mcp-registry/route.ts + server/src/lib/mcp/loadRegistry.ts + registry.generated.ts — serves the registry to the connector.

EE governance — currently MISPLACED in CE server/ tree (this plan moves it):

• server/src/lib/mcp/{agents,idpToken,agentAudit,adminAuth,jsonRpcServer}.ts
• server/src/app/api/mcp/route.ts, server/src/app/api/v1/mcp/{agents,idp-providers,audit}/route.ts, server/src/app/.well-known/oauth-protected-resource/route.ts (all isEnterpriseEdition()-gated → 404 in CE)
• server/migrations/20260607120000_create_mcp_agents.cjs, 20260607130000_create_mcp_agent_audit.cjs → should be ee/server/migrations

Tables (built, no RLS — app-level isolation): agents, agent_idp_providers, agent_roles, mcp_agent_audit, api_keys.agent_id.

Key references / patterns

• Seam to mirror: packages/product-chat (oss/entry.tsx stub + ee/entry.tsx real) → routes await import('@product/chat/entry'); next.config.mjs aliases @product/chat/entry to oss vs ee per edition (search pkgChatEntry ~L649). Build a parallel @product/mcp.
• EE alias @ee/ → ee/server/src (used by product-chat/ee/entry).
• Migrations: server/scripts/run-ee-migrations.js merges CE (server/migrations) + EE (ee/server/migrations) into one dir under server/ and runs knex. EE-specific tables belong in ee/server/migrations.
• Live test harness (from Phase 2): mock IdP = RS256 keypair + a local JWKS HTTP server; register trusted IdP via POST /api/v1/mcp/idp-providers; provision agent via POST /api/v1/mcp/agents; sign JWT (iss/sub/aud=resource); drive POST /api/mcp with Bearer. Admin key minting + dev DB access: see project-mcp-local-testing memory.
• Dev server: PORT=3001 npm run dev (nx), NEXT_PUBLIC_EDITION=enterprise. next.config changes need a restart.

Decisions

• Relocation is the #1 release blocker — EE source must not ship in the open-core CE bundle. Route shells stay in server/src/app (Next requires it) but dynamic-import EE impl via @product/mcp; CE gets the stub.
• Admin provisioning UI is the headline user-journey gap (today: API-only). In scope for MVP.
• Phase 3 explicitly out: ABAC policy, approval gates, quotas, in-process dispatch.
• Testing 80/20: the post-relocation live E2E + CE-stub check + real-IdP smoke + connector install + UI happy-path are the high-value tests; favor live over mocked units.

IMPLEMENTATION STATUS (2026-06-07) — 22/27 features

Done + verified live (committed):

• EE relocation (F001-F009) → ee/server/src/lib/mcp/* behind a @product/mcp seam; route shells dynamic-import it; migrations in ee/server/migrations; next.config aliases mirror @product/chat. Parity E2E passed through the seam (agent dispatch + RBAC deny + untrusted-issuer + audit).
• Polish (F012/F026/F027) → configurable IdP subject claim (verified with an azp token), expired session-key sweep (5→0), audit allow/deny/error granularity.
• Admin UI (F019-F024) → MCP Server settings tab (EE-gated) + session-admin auth + roles endpoint. Click-through verified in-browser: logged in as admin → created a trusted IdP + provisioned an agent with a role, persisted to DB.
• Docs (F017/F018/F025) → docs/mcp-server.md (admin journey, auth model, limitations incl. instance-wide PRM).
• F016 → all MCP test artifacts purged (agents/idps/backing-users/test-keys = 0).

Remaining (5) — all external / release-gate, NOT implementable in this dev session:

• F010/F011 production EE+CE builds — heavy CI. Relocation is turbopack-dev-verified; CE/EE seam mirrors the working @product/chat. Run npm run build:ee + npm run build:ce in CI.
• F013 real-IdP smoke — needs a real Entra/Keycloak/Google tenant (mock-IdP fully verified incl. custom azp claim).
• F014/F015 publish @alga-psa/mcp-connector to npm — needs registry credentials + an explicit publish decision.

Browser-login note: automating the React-controlled signin form requires setting input.value via the native setter + dispatching input/change events (plain typing leaves React state empty → "Failed"). The dev admin (glinda) password rotates per server start.

Gotchas

• Moving migration files must NOT double-apply — same filenames stay recorded in knex_migrations (already applied to dev DB). Verify run-ee-migrations treats them as done.
• Real IdPs vary on the agent subject claim (sub vs azp vs client_id), audience, and key rotation → make the subject claim configurable per provider (F012).
• PRM currently lists ALL issuers across tenants (instance-wide) — fine for single-tenant appliance; multi-tenant SaaS needs per-tenant PRM (F025).
• Agent session keys (5-min) accumulate in api_keys — add a cleanup sweep (F026).
• Dev artifacts to remove before release: mcp-test-key api_key + mcp-agent-*@agents.alga.local users/agents (F016).