senegal-mohebs-tlm-server
It is an MCP server for authoring Senegal maths teaching & learning materials: pick a grade/subject, read curriculum and terminology, generate or ingest .docx documents, and track them in history.
Context & curriculum: set/get grade and subject; list units; fetch a unit's curriculum (lessons, tasks, progression); get the generation prompt and a preloaded generation context for a deliverable.
Terminology: search the FR/Wolof glossary and list terminology sections.
Example-domain rotation: suggest fresh or least-recently-used example domains and show domain usage per chapter.
Document storage: create signed upload/download URLs for .docx files, read an existing document's text, and record/log its parsed content into history.
History & reconciliation: list tracked documents and diff the storage bucket against history to find untracked, missing, or duplicated documents.
Safety: content-logging and upload tools require explicit user confirmation before writing.
Provides integration with Firebase Storage for storing and retrieving generated documents, history, and other data, using a service account for authentication and signing URLs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@senegal-mohebs-tlm-server set context to CI maths"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
senegal-mohebs-tlm-server
A remote MCP server ("Senegal Maths — TLM") that helps curriculum experts author teaching & learning materials — pupil manuals, teacher guides, lesson sheets — from a curriculum knowledge graph. It exposes MCP tools, not a UI: the server holds the graph, the authoring loop, the reusable pedagogy catalog and the document history; the calling LLM writes the actual .docx.
Work is always scoped to one (workspace, grade, subject) at a time, chosen with set_context. A workspace is the tenant that owns a set of graphs — it is the first segment of every namespace and every storage key, and roles are granted per workspace. Eight subjects across six workspaces are registered today (senegal/ci/maths, senegal/ce1/reading, nigeria/primary-1-3/maths, rwanda/primary-1-3/maths, cbse/class-9-10/science, ghana/basic-1-3/english, ghana/basic-4-6/maths, madhi/class-1-5/maths).
The knowledge graph lives only in a Firestore node/edge store, in raw Learning Commons (LC) ontology, behind a draft → review → publish curator loop. Generated .docx files and their history live in Firebase Storage (so the generating agent, the server, and you never need a shared disk). Auth is a Supabase JWT.
Going deeper: the operational manual is
docs/technical-reference/; the architecture summary + working conventions are inCLAUDE.md; the production runbook isDEPLOY.md; the why behind each subsystem is indocs/design-notes/.
Repo layout
Package | What it is |
The MCP server — its own | |
The read-only KG explorer (Vite + TS), served by Firebase Hosting against the server's | |
The expert-facing user guide (MkDocs), published to GitHub Pages by | |
The Cowork plugin (French workflow commands, skills and agents) shipped through the repo-root marketplace. | |
Technical reference, design notes, and the canonical LC ontology reference. |
Paths written as src/…, scripts/…, test/…, assets/… below are relative to backend/.
Related MCP server: myBrAIn
What lives where
Thing | Location |
Knowledge graph (curriculum, catalog, glossary) | Firestore node/edge store — the single source of truth ( |
Subject profile + authoring guide | Firestore, as a per-slot config cell that rides the same draft/published pointer ( |
| Local |
Generated | Firebase Storage, under |
Converted graphs staged for import | Local |
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.
Quickstart
cd backend
npm install
npm run build # check-cycles (layering) + tsc → dist/
npm test # vitest — no credentials needed (memory store + fake storage)
npm start # stdio MCP server (dist/index.js)
npm run start:http # HTTP MCP server (dist/http.js) — remote / Cloud RunEnvironment
Required (both modes): SERVICE_ACCOUNT_KEY_PATH (or SERVICE_ACCOUNT_KEY_JSON where mounting a file is impractical) · FIREBASE_STORAGE_BUCKET.
Required in HTTP mode: SUPABASE_URL · SUPABASE_ANON_KEY · PUBLIC_URL. The server refuses to start without SUPABASE_URL unless ALLOW_UNAUTHENTICATED=1 — never set that in production. TLM_SUPER_ADMINS (comma-separated JWT subs or emails) is the root of trust: it must be set before any workspace exists, because only a super admin can create the first one.
Optional: TLM_WORKSPACE / TLM_GRADE / TLM_SUBJECT (pre-select a context at startup) · TLM_BUCKET_PREFIX (namespace all storage under a prefix — match it in the CLI scripts) · TLM_SEEDS_DIR · GEMINI_API_KEY / GEMINI_MODEL (the translate tool) · SUPABASE_SERVICE_ROLE_KEY (enables list_unaffiliated_users) · KG_EXPLORER_PUBLIC=1 (anonymous published explorer reads; it can never reach a draft) · KG_ALLOWED_ORIGINS · TLM_ALLOW_SELF_APPROVE=0 (strict separation of duties) · PORT · the response-size caps TLM_MAX_RESPONSE_BYTES / TLM_WALK_MAX_PAGE_BYTES / TLM_SUBTREE_MAX_BYTES / TLM_DOCUMENT_MAX_BYTES · TLM_CONFIRM_TTL_MS / TLM_CONFIRM_STORE_BYTES · TLM_DEBUG / TLM_TIMING.
Full semantics: technical reference → deployment.
The Firestore KG store + the curator loop
The graph lives in a generic Firestore node/edge store, double-buffered: two slots behind a pointer { publishedSlot, draftSlot }. Reads and generation resolve to published; every edit stages onto the draft; publish_draft is an atomic pointer flip. Every mutation is two-phase — a dry-run returns a diff, warnings and an opaque confirmationToken and changes nothing; the confirm re-checks the token and applies to the draft only — and every mutation and denial lands in an append-only audit.
Roles are per workspace: curator may edit, apply and discard; approver also publishes; admin also manages members; an env-rooted super_admin spans every workspace. Published curriculum reads are open to anyone signed in — what membership buys is the workspace's live assets (its documents bucket, generation history, and the metered translator) and the draft.
Import a graph, or export it for backup/interchange:
npm run import:kg-store -- <workspace> <grade> <subject> knowledge_graph.jsonnpm run export:kg-store -- <workspace> <grade> <subject> out.jsonFull lifecycle, verbs, integrity rules and audit: technical reference → KG store.
Adding a new workspace
A workspace is a tenant: a short slug that becomes the first segment of every namespace and storage key it owns. Creating it is what lets people enter it with set_context; loading its curriculum is a separate step.
There are two paths, and they perform the same writes.
1. Through MCP (super admin). The normal path when the server is already deployed:
create_workspace(id: "kenya", displayName: "Kenya")Then grant people roles — by email if they have never signed in (it becomes a pending invite claimed at first login):
add_member(workspace: "kenya", email: "someone@example.org", role: "curator")For a whole organisation, set_domain_rule(workspace, domain, role: "curator") auto-admits anyone signing in with a verified address at that domain. It only applies to providers that vouch for the address (Google today) — a password signup at that domain still needs an invite. list_members, invite_member / revoke_invite, remove_member and remove_domain_rule round out the surface.
2. From the CLI — when you have Firebase credentials but no super-admin MCP session:
node scripts/create-workspace.mjs kenya "Kenya" --member <userId> --role admin --dry-runDrop --dry-run to write for real. The CLI is its own trust boundary (it bypasses the MCP authz path, exactly like import-kg), and it still appends the audit record. Set the same TLM_BUCKET_PREFIX the server runs with, so the audit namespace lines up.
A new workspace is empty until you add at least one subject.
Adding a new subject
A subject is one graph plus one profile, both keyed by (workspace, grade, subject). The registry is keyed on all three because two tenants can own the "same" grade/subject with genuinely different graphs — Nigeria and Rwanda both sit at primary-1-3/maths.
1. Get the graph into the canonical envelope. import-kg consumes a raw Learning-Commons envelope: { nodes, relationships }, where a node is { id, labels: [LClabel], properties: { …camelCase } } and a relationship is { id, type, start, end, properties }. If you are starting from an EIDU/CASE JSONL export (one node per line, one relationship per line, snake_case, heavy extraction provenance), convert it first:
node scripts/convert-eidu-jsonl.mjs nodes.jsonl relationships.jsonl imports/kenya/primary-1/maths/knowledge_graph.jsonStage converted graphs under imports/<workspace>/<grade>/<subject>/ — deliberately not under test/fixtures/, so the test matrix does not pick them up. Check node/edge labels against docs/reference/learning-commons/ before importing; a non-canonical label parses into the wrong kind.
2. Author a subject profile under src/adapters/profiles/<workspace>/<grade>-<subject>.ts. A profile is data, not code — an id plus a parse descriptor — and the generic factory in src/adapters/build.ts turns it into the adapter. Most of the parse is already generic (a node's kind comes from its own canonical LC fields: groupName for groupings, statementType for standards, the label for content leaves), so a standards-only graph often needs nothing but the id:
export const RWANDA_MATHS_PROFILE: SubjectProfile = {
id: "rwanda-maths/lc-graph-v1",
parse: {}, // no ordinal field → sequence comes from traversal order
};The knobs that exist are the genuine per-subject differences: numberFrom (order | position | description — where a unit's ordinal lives), containerEdge / supportEdge / progressionEdge / dependencyEdge, and a named prune strategy. The schema is .strict(): an unrecognised key is a hard refusal, not a silent ignore, so a typo can never look like it took effect.
3. Register it in src/adapters/index.ts under the "<workspace>/<grade>/<subject>" key. Two keys may point at the same profile when the graphs share a shape — the builder still stamps each with its own identity.
4. Write the authoring guide at seeds/<workspace>/<grade>/<subject>/GRAPH_GUIDE.md — authored markdown that the authoring/generating LLM reads (via get_graph_guide) to interpret and modify the graph, including the subject's coverage expectations in prose. It ships as a data file, never a code literal, and is composed at seed time with the shared seeds/AUTHORING_CONVERSATION.md so the conversation rules cannot drift across subjects. It is a seed: once the namespace exists, the guide in force lives in its config cell and is edited with edit_profile. The workspace's FR/Wolof lexicon is authored separately, in its _glossary namespace (add_terms).
5. Dry-run, then import. The dry-run parses the graph against your profile in memory and writes nothing:
npm run import:kg-store -- kenya primary-1 maths imports/kenya/primary-1/maths/knowledge_graph.json --dry-runDrop --dry-run to write. The import parses the graph, serialises it to the store (ids verbatim), writes the subject-profile config cell ({ core, guide }, taken from the in-repo literal + GRAPH_GUIDE.md unless you pass --profile p.json), and initialises the pointer. Re-importing an existing namespace needs --replace-published, which writes the currently-published slot in place, delta-only — without it the import lands on the non-published slot and readers see nothing change. It is refused while a draft is open.
6. Deploy the code, then check it live. The profile is code, so a data-only re-import is not enough: the running server must also carry the new profile module or set_context will refuse the namespace ("no subject adapter is registered"). Deploy via the Deploy to Cloud Run workflow, then set_context(workspace, grade, subject) and namespace_stats against the live server.
7. Say what its pages look like — as data on its formatters, never as code. Once the graph carries a document (create_document, add_section) and a formatter (use_formatter), three bags on that formatter drive production, all validated at edit_nodes time and all changed live without a deploy:
render— the geometry: page, type, block styles, image sizes, page budget (design note);layout— the structure: templates the composer fills from the graph, one per section shape, with placeholders ({{covered.title}}, an attached picture by name, a fixed asset by rank) and, where a section's own lines are wanted,{kind: "guide"};layout.guide— the guide grammar: how a section's assembly guide reads as page lines — which line prefixes print and in which voice, how a phrase of the repertoire is called and what it says, how a picture is named and marked, which inline assets a line may carry (design note).
Plus lintRules, the subject's own line checks (design note). compose_section then produces the page from the graph with no model, lint_content checks it, render_document lays it out and measures it. The server knows block kinds, placeholders, three grammar motifs and matching; it knows no prefix, phrase or glyph of any subject, so a new subject with line-structured guides declares its own grammar and nothing under src/ changes. A subject whose guides are prose declares none: its sections come back as holes for a model to compose. The CI-maths teacher sheet's bags are the worked example: backend/test/fixtures/senegal-fiche-layout.json (templates + grammar + the 32-phrase repertoire) and senegal-fiche-lint-rules.json.
Note on where the profile really lives. The in-repo literal is the registration check and the seed source. On a live server,
activateContextbuilds the adapter from the namespace's stored config cell — the store is the source of truth. Edit a live profile or guide throughedit_profile(curator-gated, two-phase, publishes with the graph).scripts/write-profile.mjsis the repair path for a cell too invalid to activate.
Fuller walkthrough: technical reference → architecture & extending.
The generation flow (in brief)
set_context(workspace, grade, subject)— pick what you're working on.start_hereorients you: where you are, what your role allows, what is unfinished.Read what you're generating —
walk_documentfor a whole document,walk_document_sectionfor a single piece — each returns the subtree plus the instructional routines and formatters that apply.get_terminologysupplies the glossary.Produce the page:
compose_sectionfills the formatter's templates and compiles the section guides from the graph (no model — what it cannot fill it reports asunfilledorproblems),lint_contentchecks the tree against the graph and the formatter's rules,render_documentlays it out into a.docx, measures it and can return a picture of each page.create_upload_url(relPath)→PUTthe file to the signed URL (no large payloads through MCP).log_generation(nodeId, relPath, content)— records what you produced against the scope node the document covers (md5 read from storage).evaluate_documentscores it against the evaluation rubrics attached to that document.
The outward-writing tools (create_upload_url, log_generation, record_document_content) are gated by a confirmation step. preview_generation closes the editing loop instead: it resolves from the draft slot and writes to a segregated previews/ prefix, invisible to reconcile / list_documents and never touching history. Details: technical reference → generation & storage.
Tools
The live surface is mirrored by get_capabilities; this is the map.
Orientation & context:
ping,start_here,set_context,get_context,get_capabilities,namespace_stats.Graph reads (generic):
walk_graph(directional, filtered, paginated BFS — the traversal primitive),find_node(a name → node ids, with the path that tells two same-named nodes apart),get_standards,export_graph_view.Generation reads:
walk_document,walk_document_section,get_terminology.Authoring (role-gated):
add_nodes,create_edges,edit_nodes,move_node,delete_nodes,delete_edges, plus the two task verbscreate_documentandadd_section.Draft lifecycle (role-gated):
diff_draft,check_draft(mechanical wiring lint),lint_content(consistency lint — does an authored statement contradict another),review_draft(bundles the guide's expectations for the calling model to judge),undo_last,request_review,publish_draft,discard_draft,read_audit.Subject profile & guide:
get_profile,edit_profile,get_graph_guide.Catalog — reusable routines, formatters & rubrics:
list_catalog,get_catalog_entry,add_to_catalog,duplicate_entry,use_routine,use_formatter,use_rubric.Glossary & translation:
add_terms,edit_term,remove_terms,translate(FR↔Wolof via Gemini, glossary-grounded).Documents & generation output:
list_documents,create_upload_url,create_download_url,get_document_text,record_document_content,log_generation,reconcile,evaluate_document,preview_generation,create_preview_upload_url.Rendering & round-trip:
render_document(a composed block tree + the node's formatter stack → a.docx, optionally measured),check_stale(has the graph moved under a rendered document),propose_from_document(take an expert's corrections in a document back into the graph as staged edits).Workspaces (tenant admin):
list_workspaces,create_workspace,add_member,remove_member,list_members,invite_member,revoke_invite,set_domain_rule,remove_domain_rule,list_unaffiliated_users.
The connector also publishes four named French workflow prompts — Créer un nouveau document, Appliquer un style, Créer une routine pédagogique, Préparer une relecture. They are French because a prompt is the expert's first turn; every server-authored string is English and relayed in the expert's working language.
Documentation
CLAUDE.md— architecture summary, module layering, conventions (the working guide).docs/technical-reference/— the operational manual: KG store & curator loop · explorer · generation & storage · rendering · deployment · architecture & extending.docs/reference/learning-commons/— the canonical LC ontology (node data models, every relationship, enums). Check it before adding or retyping any node or edge.docs/design-notes/— the why behind each subsystem. Each note carries a Status line; heed the "Historical / superseded" ones. Start with graph-native authoring · self-serve authoring · authorable catalog · workspaces · member onboarding · KG mutations.DEPLOY.md— production deployment runbook.
Available Tools
17 toolscreate_download_urlCreate document download URLA
Get a short-lived signed URL to download an EXISTING .docx from the bucket with an HTTP GET (no auth header needed). relPath is documents-relative, like 'chapitre_05/Manuel - Chapitre 5.docx' — the same path used by create_upload_url and get_document_text. Use this to fetch the original binary file (with its images and formatting intact) so you can edit it and re-upload via create_upload_url. Returns { url, objectKey, expiresAt, exists }; exists is false when there is no such object.
Inputs: relPath (required).
create_upload_urlCreate document upload URLA
Get a short-lived signed URL to upload a generated .docx to the bucket. Upload with an HTTP PUT, Content-Type application/vnd.openxmlformats-officedocument.wordprocessingml.document. relPath is like 'chapitre_05/Manuel - Chapitre 5.docx'. After uploading, call log_generation with the same relPath. REQUIRES CONFIRMATION: called without confirm:true it only returns a needsConfirmation notice — ask the user to approve the upload, then call again with confirm:true.
Inputs: relPath (required), confirm.
domain_usageExample-domain usageB
Which example domains have been used, and in which chapters. Maths-specific (example-domain rotation).
Inputs: no named parameters.
get_contextGet grade & subjectA
Return the currently selected grade/subject (null if none is set yet) and every installed grade/subject option. Use this to discover what's available, then set_context.
Inputs: no named parameters.
get_curriculumGet unit curriculumA
The curriculum slice for one unit (for maths: a chapter's ordered lessons with components and tasks, the bilan lesson, and cross-unit progression). 'unit' is the unit's scope value (maths: the chapter number).
Inputs: unit (required).
get_document_textGet document textA
Extract the plain text of a document in the bucket (by its documents-relative path) so you can read an UNTRACKED document and then record its content. When identifying characters, read the WHOLE document — characters appear in the opening scene AND in the activities and bilan, not only the amorce.
Inputs: relPath (required).
get_generation_contextGet generation contextC
One call to load before generating: curriculum for the unit, plus subject-specific context (for maths: established characters, a fresh example-domain suggestion, and — for the teacher guide — the manual to build on). 'unit' is the scope value (maths: chapter number); 'deliverable' is a deliverable key (maths: 'manual' or 'lessons').
Inputs: unit (required), deliverable (required).
get_promptGet generation promptA
Return the generation prompt for one of the active subject's deliverables (its DeliverableSpec.promptFile). 'deliverable' is a deliverable key — for maths, 'manual' or 'lessons'.
Inputs: deliverable (required).
get_terminologyGet terminology (FR/Wolof)A
Search the MOHEBS French/Wolof terminology used as the fallback when the KG lacks a term's wording. Returns [] if nothing matches — then say the wording is missing rather than invent it.
Inputs: query (required), limit.
list_documentsList tracked documentsC
Current history: one canonical entry per document, with its known content.
Inputs: no named parameters.
list_unitsList curriculum unitsB
All top-level curriculum units for the active subject (for maths: chapters — number, title, domain). Numbering may skip.
Inputs: no named parameters.
log_generationLog a generated documentA
Call after uploading a generated .docx to the bucket (via create_upload_url). Reads the object's hash from storage and records what you produced so it feeds future consistency + variety. Log each character with details like {name, type} (e.g. {name:'Awa', type:'child'}), not just the name. No local file needed. 'unit' is the scope value (maths: chapter number); 'deliverable' is a deliverable key (maths: 'manual' or 'lessons'). REQUIRES CONFIRMATION: called without confirm:true it only returns a needsConfirmation notice — ask the user to approve writing to history, then call again with confirm:true.
Inputs: unit (required), content (required), relPath (required), deliverable (required), +1 more.
reconcileReconcile bucket with historyA
List the documents in Firebase Storage and diff against history: tracked docs, UNTRACKED docs needing ingestion, entries dropped because their object is gone, and duplicate resolutions.
Inputs: no named parameters.
record_document_contentRecord parsed document contentA
After reading an UNTRACKED document's text, store the structured content you extracted into history so it is never re-parsed. For characters, include every one found ANYWHERE in the document (opening scene and activities/bilan), each with details like {name, type}. The object must already be in the bucket. 'unit' is the scope value (maths: chapter number); 'deliverable' is a deliverable key (maths: 'manual' or 'lessons'). REQUIRES CONFIRMATION: called without confirm:true it only returns a needsConfirmation notice — ask the user to approve writing to history, then call again with confirm:true.
Inputs: unit (required), content (required), relPath (required), deliverable (required), +1 more.
set_contextSet grade & subjectA
Choose the grade (e.g. 'ci') and subject (e.g. 'maths') to work on. This selects which local sources load and which Firebase namespace documents and history live under, and MUST be set before any other tool. If you don't know which to use, call get_context to list the installed options, then ask the user.
Inputs: grade (required), subject (required).
suggest_fresh_domainSuggest fresh example domainA
Suggest an unused (or least-recently-used) example domain so chapters rotate object families. Maths-specific (example-domain rotation).
Inputs: no named parameters.
terminology_sectionsTerminology sectionsA
List terminology sections and entry counts.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool has a clearly distinct purpose. For example, set_context and get_context handle context, get_curriculum and get_generation_context are different in scope, and create_upload_url, create_download_url, get_document_text, record_document_content, log_generation each cover distinct steps in document management. No two tools appear to do the same thing.
Most tool names follow a verb_noun pattern (e.g., get_prompt, list_units, create_upload_url). The main exception is 'terminology_sections', which uses noun_verb. Overall, the naming is mostly consistent with minor deviations.
17 tools is slightly above the typical ideal range of 3-15, but each tool serves a specific function in a multi-step generation workflow. The count is justified by the complexity of the domain and does not feel excessive.
The tool surface covers the full lifecycle: context setting, curriculum access, terminology, prompt retrieval, domain rotation, document management (upload, download, read, record, log), and reconciliation. Minor gaps exist, such as no explicit tool to list deliverables or delete documents, but these are manageable.
Maintenance
Related MCP Connectors
An MCP memory server. One memory your agents share — across models, devices and apps.
Cloud-hosted MCP server for durable AI memory
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA production-ready MCP server that enables multiple AI agents to collaborate through a shared, concurrency-safe memory space. It supports advanced search, full CRUD operations, and automatic backups to facilitate asynchronous communication between agents.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that provides persistent memory and contextual awareness to language models, enabling project onboarding, recall of architectural rules, and code consistency across sessions.32MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that dynamically extracts and manages user memory from LLM conversations, enabling consistent personalization across different models.7-
- AlicenseNot gradedqualityDmaintenanceA portable MCP server providing a shared intelligent memory system for any MCP-compatible AI tool, enabling storage, retrieval, extraction, and governance of memories across sessions.MIT