senegal-mohebs-tlm-server

An MCP server that gives the Senegalese MOHEBS teaching-materials pipeline a shared memory layer — so AI-generated documents stay consistent (characters, terminology, concept coverage) and deliberately varied (rotating example domains: fruits → legumes → …), across any grade and subject.

It works on one grade + subject at a time (e.g. ci / maths); you pick the pair with set_context. The knowledge graph lives in a Firestore node/edge store — the single source of truth — with a draft → review → publish curator loop; you add a graph with import-kg and back it up with export-kg. Generated .docx files and their history live in Firebase Storage (so the generating agent, the server, and you never need a shared disk). The only local per-subject input is the terminology.json glossary fallback (under assets/). Auth is a Supabase JWT.

Going deeper: the full operational manual is docs/technical-reference/; the architecture summary + working conventions are in CLAUDE.md; the production runbook is DEPLOY.md.

What lives where

Object hashing uses the GCS object md5 from metadata — the server never hashes a local file, which removes the cross-host mismatch that used to break log_generation.

Related MCP server: myBrAIn

Where the graph lives

The knowledge graph is only in the Firestore store — there is no on-disk sources/ copy and no KG_SOURCE toggle (see firestore-only-store). Add a graph on demand:

npm run import:kg-store -- <workspace> <grade> <subject> path/to/knowledge_graph.json

The JSON is a raw Learning-Commons envelope ({ nodes, relationships }). get_context discovers installed pairs from the store (the namespaces that have a graph). Making the tools work also needs a registered subject profile (src/adapters/profiles/, one declarative literal per subject) — a namespace with no registered adapter is rejected by set_context. See Adding a grade/subject.

The only per-subject files on disk are static assets under assets/<workspace>/<grade>/<subject>/ — currently just the optional terminology.json (FR/Wolof glossary fallback). Realistic graphs for the test suite live under test/fixtures/ as committed test data.

Quickstart

The server is a self-contained package under backend/ (the frontend/ explorer UI is its own package). Run these from backend/, and read the assets/…, test/…, src/… paths elsewhere in this README as relative to it.

cd backend
npm install
npm run build          # check-cycles (layering) + tsc → dist/
npm test               # vitest
npm start              # stdio MCP server (dist/index.js)
npm run start:http     # HTTP MCP server (dist/http.js) — remote / Cloud Run

Required env: SERVICE_ACCOUNT_KEY_PATH (Firebase service-account JSON) · FIREBASE_STORAGE_BUCKET.

Common optional env: TLM_GRADE / TLM_SUBJECT (pre-select a pair at startup) · TLM_WORKSPACE · TLM_BUCKET_PREFIX (namespace everything under a prefix) · TLM_ASSETS_DIR · TLM_DOMAIN_NEIGHBORHOOD_K. Full list and semantics: technical reference → Configuration.

Firestore KG store + curator loop

The knowledge graph lives in a generic Firestore node/edge store with a double-buffered draft/published model and a curator/approver edit → review → publish loop (generic graph verbs add_node/move_node/edit_node and batched add_nodes/create_edges, all two-phase-confirmed and audited). Import a graph, and export it for backup/interchange:

npm run import:kg-store -- <workspace> <grade> <subject> knowledge_graph.json   # add a namespace
npm run export:kg-store -- <workspace> <grade> <subject> out.json               # dump it back out

Full lifecycle, roles, verbs, integrity rules, and audit: technical reference → KG node/edge store.

The generation flow (in brief)

1. set_context(grade, subject) — pick what you're working on.

2. get_generation_context(unit, deliverable) — curriculum slice, established characters, terminology, coverage, fresh example-domain suggestion.

3. Generate the .docx.

4. create_upload_url(relPath) → PUT the file to the signed URL (no large payloads through MCP).

5. log_generation(unit, deliverable, relPath, content) — records what you produced (md5 read from storage).

The outward-writing tools (create_upload_url, log_generation, record_document_content) are gated by a confirmation step. Details, preview generation, ingestion, and reconciliation: technical reference.

Tools

• Context: set_context, get_context.

• Subject-agnostic: get_terminology, terminology_sections, get_prompt, reconcile, list_documents, create_upload_url, create_download_url, get_document_text, get_capabilities.

• Curator loop (role-gated): diff_draft, upsert_property, create_node/link_nodes/unlink_nodes/delete_node, add_lesson/add_chapter/move_lesson/split_chapter/renumber, publish_draft, discard_draft, read_audit.

• Subject-shaped payloads: list_units, get_curriculum, get_generation_context, record_document_content, log_generation, preview_generation, create_preview_upload_url, and (CI maths only) suggest_fresh_domain, domain_usage.

Documentation

• CLAUDE.md — architecture summary, module layering, conventions (the working guide).

• docs/technical-reference/ — the full operational manual: KG store & curator loop, integrity/audit, the read-only KG explorer, buckets, generation/preview flow, deployment & hosting.

• DEPLOY.md — production deployment runbook.

• Design notes (docs/design-notes/ — the why behind each subsystem): multi-subject architecture · KG mutations framework · preview generation · KG explorer findings · read-audit findings.