{ "nodes": [ { "id", "label", "kind", "nt", "st","st_en", "code", "desc","desc_en", "dom","pal","sem","chapN","chapT", "src","ref","statut", "srcKey", ... } ], "edges": [ { "s", "t", "r", "o" } ], // r ∈ {hasChild, buildsTowards}; o = sibling order "meta": { "ns", "label", "publishedSlot", "generatedAt", "counts": { "nodes", "edges", "byKind" }, "sources": ["RECE","Rwanda P1", ...], // distinct srcKeys present → source-filter chips "viewConfig": { "views": [ { "id","label","shape","params" } ] } } } ``` **Auth** (decision: Supabase login). When `SUPABASE_URL` is set, `/kg/namespaces` and `/kg` require a valid Supabase Bearer JWT — the same trust channel as `/mcp`. The static page runs a small `supabase-js` email/password login (mirroring `/oauth/consent`) and sends the token. In `ALLOW_UNAUTHENTICATED=1` (local only) the routes are open. **CORS.** Allow-listed to the Firebase Hosting origin(s); override with `KG_ALLOWED_ORIGINS` (comma-separated). `localhost`/`127.0.0.1` are always allowed for local dev. The deployed page does not actually need CORS — Firebase Hosting **rewrites** `/kg/**` → the Cloud Run service (`firebase.json`), so the browser calls same-origin and Hosting proxies to Cloud Run (the JWT passes through). CORS covers direct/local access. ### The raw-LC → display transform The store holds a NORMALIZED graph (generic `{type, properties:{code,title,text,order,isAssessment,raw}}`). `toDisplayNode` maps each stored node to the explorer's display schema, reading `properties.raw.*` with both CI maths (camelCase) and CE1 reading (snake_case) spellings: | display field | source | display field | source | |---|---|---|---| | `label` | derived from `kind` | `dom`/`dom_en` | `raw.domaine`/`_en` | | `kind` | store `type` | `pal`/`sem` | `raw.palier`/`raw.semaine` | | `code` | `properties.code` (`raw.statementCode`) | `chapN`/`chapT` | `raw.chapitreNum`/`raw.chapitreTitre` | | `desc`/`desc_en` | `properties.text`/`raw.osTexte`/`raw.description` | `os`/`os_en` | `raw.osTexte`/`_en` | | `st`/`st_en` | `raw.statementType`/`_en` | `src`/`ref`/`statut` | `raw.source`/`reference`/`statut` | | `nt` | `raw.normalizedType`/`raw.contentType` | `srcKey` | `raw.sourceKey` | | `ex`/`ex_en`, `apt`, `comm` | `raw.examples`/`aptitudeCI`/`commentaireProgression` | `strand`,`genre` | `raw.strand`,`raw.genre` (CE1 reading) | Edges are the stored `hasChild` + `buildsTowards` as `{s,t,r,o}`. Domaine/Palier/Semaine grouping is **synthesized client-side** from node properties (as the original explorer already did for Palier/Semaine) — the server emits only spine nodes + edges. ### Data-driven views (`meta.viewConfig`) The frontend is generic and renders whatever views `meta.viewConfig` declares — no per-namespace `if` anywhere. Two view **shapes**: - `grouped-spine` — nested grouping synthesized from `groupBy` props read off `anchorKind` nodes, then those anchors, then the `hasChild` subtree (optionally stopping at `stopKind`). CI maths declares three: *thematic* (Domaine→Chapitre→OS→composant→tâche), *planning* (Palier→Semaine→OS), *chapters* (Domaine→Chapitre→OS). - `node-type` — the generic floor, works for ANY namespace: each node type → its nodes → their outgoing relations. A namespace gets the rich grouped-spine views **only when its data carries the needed fields** (chapters with `dom`, lessons with `pal`/`sem`); every namespace always gets the `node-type` view. So `ci/maths` shows four tabs, `ce1/reading` shows one (generic) — with no hardcoding. ### Adding a new KG Seed it into Firestore (see [Seed](#seed)). It then appears in the selector automatically. If its data has the CI maths-shaped fields it gets the rich views; otherwise it renders via the generic `node-type` view — no frontend change. To give a differently-shaped KG its own rich views, extend `buildViewConfig` in `src/kg-export.ts` with a new detection + a new view `shape` in the frontend. ### Data-scope finding (what's in the graph vs. was only in the old HTML) **Verified against live Firestore, both namespaces are SPINE-ONLY.** The seed pipeline runs each adapter's `parse()` → normalized model → store, which keeps only the curriculum spine (`ci/maths`: chapter→lesson→component→task via `hasChild` + chapter→chapter `buildsTowards`; `ce1/reading`: week→standard→component). The RECE framework and the six derived-source family branches from the old inline-`DATA` explorer are **not** stored as nodes, and the raw graph's `supports`/`relatesTo` edges are dropped. But every raw field survives in `properties.raw` — including `sourceKey` (all seven tags present on CI maths components/tasks), so the source-filter chips still work, and Domaine/Palier/Semaine are re-synthesized from properties. What does NOT render: the RECE/derived branches as separate roots, and the modal's `supports`/`relatesTo` cross-link blocks. See `docs/kg-explorer-findings.md` §1 for the full table and the (a) ship-spine / (b) ingest-more decision (shipped: **a**). ### Deploy the explorer ```bash firebase deploy --only hosting --project senegal-ci-maths # → https://senegal-ci-maths.web.app ``` `firebase.json` rewrites `/kg/**` to the `senegal-mohebs-tlm` Cloud Run service (region `europe-west1`). Local dev: run the server (`node dist/http.js` with `ALLOW_UNAUTHENTICATED=1`) and open the page with `?api=http://localhost:` so it hits the local endpoint directly. ## Bucket layout ``` gs:/// _state/.json # per-user active grade/subject (HTTP mode) // documents/ chapitre_05/.docx chapitre_05/.docx previews/ # throwaway preview .docx (draft-resolved); NOT canonical chapitre_05/.docx history.json ``` `previews/` is a **sibling** of `documents/`, never inside it — reconciliation only scans `documents/`, so a preview object can never enter the tracked history (see *Preview generation* below). Document identity is `scope:deliverable` (e.g. `5:manual`, `5:lessons`) **within a grade/subject**; the scope is the first integer in the subfolder name, and the active subject's adapter classifies the filename into a deliverable (for CI maths: a file named "Fiches de leçons …" is the lesson-sheets doc, anything else is the manual). ## The generation flow (cross-host, no shared disk) 0. `set_context(grade, subject)` — pick what you're working on. `get_context` lists the installed pairs and the current selection. 1. `get_generation_context(unit, deliverable)` — curriculum slice, established characters, terminology guidance, coverage, and (for the teacher guide) the manual to build on. `unit` is the scope value (for CI maths, the chapter number) and `deliverable` is a deliverable key (`manual`/`lessons`). For example-domain variety it returns `exampleDomains: { suggested, avoidNearby }`: `suggested` is a fresh object family to use, and `avoidNearby` maps each *nearby* chapter number (within ±`TLM_DOMAIN_NEIGHBORHOOD_K`) to the domains it used — so adjacent chapters don't repeat the same family. This is a bounded window, not the whole book; use `domain_usage` for the full log. 2. Generate the `.docx`. 3. `create_upload_url(relPath, confirm)` → the server returns a short-lived **signed URL**. Upload the file with an HTTP `PUT` (Content-Type `application/vnd.openxmlformats-officedocument.wordprocessingml.document`). No large payloads go through the MCP channel. **Requires confirmation** — see below. 4. `log_generation(unit, deliverable, relPath, content, confirm)` — the server reads the uploaded object's md5 from storage and records what you produced. History updated; no local file needed. **Requires confirmation** — see below. > **Confirmation gate.** The three tools that write outward — `create_upload_url` (gates the upload), `log_generation`, and `record_document_content` — never act without approval, using the strongest gate the client supports: > - **Client supports MCP elicitation** → the server asks the **user** directly via an elicitation dialog. This is a hard gate: the agent cannot bypass it (even passing `confirm: true` won't skip it — a declined dialog blocks the action). > - **Otherwise** → an agent-mediated two-step: the first call performs no side effect and returns the shared confirmation envelope `{ needsConfirmation: true, action, message }` (`action` states the stakes; `message` tells the agent to re-call with `confirm: true`); the agent asks the user, then re-calls with `confirm: true`. > > Input validation (e.g. unknown deliverable) runs before the gate, so bad calls fail first. All read-only tools are ungated. Note: in a fully headless run (no user, no elicitation) these tools cannot get approval by design — drive them only where a human is reachable. > > **Two lifecycles share only the envelope shape.** Document tools write **live** to the bucket / history — the confirm is the ONLY gate, and the `action` field says "writes NOW … no draft, no undo". Graph mutations (see below) **stage a draft edit** — the same envelope, but the `action` says "STAGES a draft edit … nothing reaches generation until you separately publish". Uniform mechanics; deliberately different stakes. ## Preview generation (draft-resolved, isolated from published) An expert who has staged a draft edit can generate a **preview** of the teaching material that edit would produce — reading the **draft** instead of published — **without touching published, the canonical documents bucket, or the canonical generation history.** This closes the editing loop: the dry-run (per-mutation diff) and `diff_draft` show the **graph change**; preview shows the **result** — the material that change yields. - **`preview_generation(unit, deliverable)`** — the draft-resolved analog of `get_generation_context`. It resolves the unit's curriculum from the **draft slot** (the same slot `diff_draft` reads) via the store-bridge and the subject adapter, then runs the adapter's *own* `buildGenerationContext` on that model. Same inputs and same output shape as the published path, but the returned context is **tagged `preview`** and carries the label *"PREVIEW — generated from an unpublished draft, not a published deliverable."* Read-only on the draft — it does **not** mutate the graph. - **`create_preview_upload_url(relPath)`** — the preview **output** path. Signs short-lived (10 min) write + read URLs for a throwaway `.docx` under the **segregated `previews/` prefix**. Never the canonical `documents/` bucket, never `log_generation`, never `list_documents`/`reconcile`. `PUT` the generated file to `uploadUrl`, hand the human `downloadUrl`. **Isolation guarantees** (all covered by `src/server/preview.test.ts`): - A preview reflects a staged-but-unpublished edit, while published generation still reflects the old wording. - After a preview run, the published slot, the pointer, the canonical bucket, `history.json`, and `log_generation` records are **byte-for-byte unaffected**; the only audit added is a distinct **`preview`** event (never an `apply`/`publish`/real-generation record). - Preview output lives under `previews/` — structurally invisible to the tracked document history. **No draft?** `preview_generation` returns a clear *"no draft to preview"* notice (and no output) rather than silently previewing published — which would be misleading. **Who?** Same trust tier as `diff_draft`: **curators and approvers** may preview; unknown / no-role callers are blocked (and the denial is audited). It is read-like, so there is no two-phase confirm and no token. **Scope.** A preview always targets **one unit + one deliverable** — there is no implicit whole-curriculum preview (generation is LLM-driven and costly). **Deferred.** A draft-vs-published output *comparison* (previewing both for the same scope so the expert sees exactly what changes in the material) is a follow-on — it doubles LLM cost, and the graph-level change is already available via `diff_draft`. `get_capabilities` advertises this under a `preview` block, so an agent can offer "want to see what this generates before publishing?". ## Ingesting a doc authored elsewhere (e.g. an expert wrote chapter 2) 1. The file is in the bucket (uploaded any way you like), under the grade/subject's `documents/`. 2. `reconcile` surfaces it as untracked. 3. `get_document_text(relPath)` returns its plain text (server downloads from the bucket and extracts via mammoth — it never calls an LLM). 4. Extract the structured content and call `record_document_content(...)` (**requires confirmation** — call with `confirm: true` after the user approves). Tracked from then on. ## Reconciliation Run on startup (when a context is active) and via the `reconcile` tool: present + md5 matches history → tracked (skipped); new/changed md5 → untracked (needs ingestion); in history but gone from the bucket → dropped; duplicates for one identity → the object matching the tracked md5 wins, else most-recently-updated. ## Tools **Context (subject-agnostic):** `set_context`, `get_context`. **Subject-agnostic** — work the same for any grade/subject: `get_terminology`, `terminology_sections`, `get_prompt`, `reconcile`, `list_documents`, `create_upload_url`, `create_download_url`, `get_document_text`, `get_capabilities`. **Curator loop (subject-agnostic, role-gated):** `diff_draft`, `upsert_property` (wording), `create_node` / `link_nodes` / `unlink_nodes` / `delete_node` (raw structural verbs), `add_lesson` / `add_chapter` / `move_lesson` / `split_chapter` / `renumber` (composite curriculum recipes — available where the adapter declares a `recipeProfile`), `publish_draft`, `discard_draft`. **Subject-specific payloads** — generically named, but what they accept/return is shaped by the active subject's adapter: - `list_units`, `get_curriculum`, `get_generation_context`, `record_document_content`, `log_generation`. These take a `unit` (the subject's scope value — a chapter for CI maths, a week for CE1 reading) and, where relevant, a `deliverable` key. The shapes are subject-specific: CI maths returns `chapitreNum`/`leconNum` etc., and the `content` payload (characters, example domains, amorce/bilan) follows the CI maths storybook model — all fields optional. - `preview_generation` (draft-resolved generation context, role-gated to curator/approver) and `create_preview_upload_url` (segregated, short-lived, non-canonical preview output) — see *Preview generation* above. Isolated from published, the canonical bucket, `list_documents`, and `log_generation`. - *Capability-specific* (`exampleDomainRotation`, CI maths only) — `suggest_fresh_domain`, `domain_usage`. Example-domain rotation is a CI maths storybook feature; they are gated on the capability, so for a subject whose adapter doesn't enable it they return a `notApplicable` message instead of running. ## Setup ```bash npm install npm run build ``` ### Production deployment (current state) The server is **live on Cloud Run**: project `senegal-ci-maths`, region `europe-west1`, service `senegal-mohebs-tlm`, capped at one instance. - **Users connect** via a Claude custom connector pointing at `https://senegal-mohebs-tlm-148764688487.europe-west1.run.app/mcp`. First use runs an OAuth login (Supabase project `senegal-tlm-auth`, IDinsight org) on a consent page this server hosts at `/oauth/consent`. - **Accounts** are created in the Supabase dashboard (Authentication → Users → *Create new user*, auto-confirm on). The invite-email flow is **not** supported yet — its link expects a password-setup page that hasn't been built. - **A user's grade/subject selection is sticky per person** (persisted at `_state/.json` in the bucket) because web clients open a fresh MCP session per tool call. - **Merging to `main` does NOT deploy.** CI builds and tests only. To ship an update, from the repo root on `main`: ```bash gcloud run deploy senegal-mohebs-tlm --source . --region europe-west1 --project senegal-ci-maths ``` Existing env vars and public-access settings are preserved. Full runbook incl. first-time setup, Supabase dashboard config, and post-deploy smoke checks: [`DEPLOY.md`](DEPLOY.md). ### Remote (HTTP) mode — central hosting `npm run start:http` starts a Streamable HTTP server (for e.g. Cloud Run) instead of stdio. Each MCP session gets its own active context and caches, so concurrent users can work on different grades/subjects without interfering. Stdio mode (`npm start`) is unchanged. | Env | Meaning | |---|---| | `PORT` | Listen port (default 8080) | | `PUBLIC_URL` | This server's public base URL (required when auth is on) | | `SUPABASE_URL` | `https://.supabase.co` — enables OAuth (Supabase Auth is the authorization server; this server only validates its JWTs) | | `ALLOW_UNAUTHENTICATED` | `1` to run without auth — local testing only | With auth on, unauthenticated calls get a 401 pointing at `/.well-known/oauth-protected-resource`, which advertises the Supabase authorization server — MCP clients (e.g. Claude connectors) discover the login flow from there. Every tool call is logged with the caller's identity. `GET /healthz` is unauthenticated. #### Per-request actor identity Every MCP request is bound to a request-scoped `Actor` derived **only** from the verified Supabase JWT (`sub`, `email`, `iss`) — see [`src/actor.ts`](src/actor.ts). Tool handlers read the caller via `currentActor()` (nested inside the existing `runInSession` context); tool arguments, request bodies, and client-settable headers are never trusted for identity. Each non-GET request emits one structured JSON audit line to stderr — `{ actor, tool, grade, subject, … }` — as the seed for the audit store planned in a later phase. **Defaulted decision — unknown-actor policy.** With `SUPABASE_URL` set the bearer middleware 401s any unverified caller before we resolve an actor, so `actor.unknown` is only reachable via `ALLOW_UNAUTHENTICATED=1` (local testing). In that mode, unknown actors currently proceed since no roles are enforced yet. Flip this by editing the `unknown-actor policy` block in [`src/http.ts`](src/http.ts) — it is the one place to change. ### Wiring into a host (e.g. Claude Desktop) ```jsonc { "mcpServers": { "senegal-mohebs-tlm": { "command": "node", "args": ["/absolute/path/to/dist/index.js"], "env": { "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccount.json", "FIREBASE_STORAGE_BUCKET": "your-project.appspot.com", "TLM_SOURCES_DIR": "/absolute/path/to/sources", "TLM_GRADE": "ci", "TLM_SUBJECT": "maths" } } } }

senegal-mohebs-tlm-server

Installation