284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
64 lines
5.1 KiB
Markdown
64 lines
5.1 KiB
Markdown
# PRD — AlgaPSA MCP Server: MVP Release Readiness
|
|
|
|
**Date:** 2026-06-07 · **Branch:** `feature/alga-mcp-server`
|
|
**Builds on:** `docs/plans/2026-06-06-alga-mcp-server/` (design.md §10 + SCRATCHPAD) — Phase 1 (local connector) and Phase 2 (remote EE governance) are **already built and live-verified**.
|
|
|
|
## Problem statement & value
|
|
|
|
The MCP server is functionally complete through Phase 2 and proven end-to-end against a live EE instance (IdP-delegated agent auth, RBAC dispatch, audit — incl. negative cases). This plan closes the **release-readiness gap** so it can ship as the MVP:
|
|
|
|
1. The EE governance code currently lives in the **CE `server/` tree** (only runtime-gated) — it must move into `ee/` so EE source doesn't ship in the open-core CE bundle.
|
|
2. It was verified on the **dev server with a mock IdP** — we need a production EE build and one **real IdP** round-trip.
|
|
3. Provisioning (trusted IdP, agents, roles, audit) is **API-only** — the user journey has no admin UI. This is the headline UX gap.
|
|
4. The free connector isn't **published**; dev test artifacts exist; admin **docs** are missing.
|
|
|
|
## Goals
|
|
|
|
- Clean CE/EE source boundary: EE MCP governance in `ee/` via the established `@product/*` seam; CE keeps only the connector, the shared engine, and the registry endpoint.
|
|
- A production **EE build** that compiles, and a **CE build** that stubs the EE surface (no leakage).
|
|
- One **real IdP** (Entra/Keycloak/Google) validated end-to-end.
|
|
- The connector **published** and `npx`-installable.
|
|
- An **admin provisioning UI** that closes the user-journey gap (register IdP, provision agents + roles, view/export audit).
|
|
- **Admin + connector setup docs**; dev artifacts removed.
|
|
|
|
## Non-goals (Phase 3 — note only)
|
|
|
|
ABAC policy for agents, approval gates (human-in-the-loop), quotas/rate-limits, in-process kernel dispatch (vs the current self-HTTP), and a full agent-lifecycle UX beyond MVP provisioning. These are explicitly **out of scope**.
|
|
|
|
## Target users / personas
|
|
|
|
- **MSP admin** — uses the new provisioning UI to register the tenant IdP, create agents, assign RBAC roles, and review the audit trail.
|
|
- **End user** — installs the free local connector.
|
|
- **External AI agent** — authenticates via the tenant IdP and operates within its assigned roles.
|
|
|
|
## Primary flows
|
|
|
|
1. **Relocation (engineering):** EE modules → `ee/server/src/lib/mcp/`; a new `@product/mcp` package (oss stub + ee entry); route shells in `server/src/app` dynamic-import the seam and 404/stub in CE; agent migrations → `ee/server/migrations` (run via `run-ee-migrations.js`). Re-run the live E2E for parity.
|
|
2. **Admin provisioning (UI — the gap):** MCP settings → add trusted IdP → create agent (name + IdP issuer/subject) → assign RBAC roles → (later) the agent connects → admin reviews/export audit.
|
|
3. **End-user activation:** create API key → configure MCP client with `npx @alga-psa/mcp-connector` → use.
|
|
|
|
## Data model / integration notes
|
|
|
|
- Existing endpoints (built): `POST /api/mcp` (JSON-RPC), `GET /.well-known/oauth-protected-resource` (PRM), `/api/v1/mcp/{agents,idp-providers,audit}`, `GET /api/v1/meta/mcp-registry`.
|
|
- Tables (built): `agents`, `agent_idp_providers`, `agent_roles`, `mcp_agent_audit`, `api_keys.agent_id`. **No RLS** (app-level tenant isolation).
|
|
- Seam pattern to mirror: `@product/chat` (`packages/product-chat` oss/ee entries + `next.config` aliasing + `await import('@product/chat/entry')`).
|
|
- Admin UI builds on existing settings UI patterns + RBAC permission gating; wires to the `/api/v1/mcp/*` endpoints (or server actions).
|
|
|
|
## Risks & mitigations
|
|
|
|
- **Relocation regressions** — moving EE modules + the seam could break the working `/api/mcp`. Mitigation: re-run the full live agent E2E (positive + 2 negatives + audit) after the move; parity is the gate.
|
|
- **Migration dir move** — the agent migrations are already applied to dev DB from `server/migrations`; moving the files to `ee/server/migrations` must not double-apply. Mitigation: same filenames remain recorded in `knex_migrations`; verify `run-ee-migrations.js` treats them as applied.
|
|
- **Real-IdP variance** — Entra/Keycloak/Google differ on subject/`azp`/`client_id` claims, audience, key rotation, clock skew. Mitigation: make the subject claim configurable; test one provider fully for MVP, document the rest.
|
|
- **Per-tenant PRM** — instance-wide issuer list leaks across tenants on SaaS. Mitigation: implement tenant-scoped PRM, or document the single-tenant-appliance limitation for MVP.
|
|
|
|
## Acceptance criteria / DoD
|
|
|
|
- No EE MCP source in a CE build; EE routes stub/404 in CE; `build:ee` compiles; live agent E2E passes post-relocation.
|
|
- One real IdP completes the full round-trip (token → dispatch → audit).
|
|
- An admin can, **entirely from the UI**, register an IdP, create an agent with roles, and view/export its audit — no curl.
|
|
- Connector is `npx`-installable from npm; dev artifacts removed; admin + connector docs published.
|
|
|
|
## Testing (80/20)
|
|
|
|
Favor **live/E2E over mocked units** (per saved feedback): the post-relocation live agent E2E, the CE-stub check, the real-IdP smoke, one connector install, and the UI provision-an-agent happy path are the high-value tests. Keep the list lean.
|