Skip to main content
Glama

CVC Storyboard MCP

A deterministic tool layer for SCGJ educational content: course storyboards as DOCX, 2.5-3 minute AI info video scripts per module, and exact Participant Handbook readings.

This server contains no AI model and no AI API key. It executes operations and returns structured results. All reasoning, orchestration and content generation happen in the connected client.

Antigravity IDE / Gemini CLI / Claude Code
        │   reasoning, orchestration, content generation
        ▼   MCP (stdio)
Storyboard MCP
        │
        ▼
Deterministic tools
  source retrieval (BM25)      timing parsing + validation
  template analysis            module crosswalk
  storyboard state + versions  DOCX clone + insert + export
  handbook outline + reading   video profile + character lock
  scene planning + word budgets  script validation + prompt composition

Client (Gemini / Antigravity)

This server

Which tools to call

✔

In what order

✔

What content to write

✔

How to fix validation errors

✔

Scoped source retrieval

✔

Authoritative durations

✔

Template fidelity

✔

Validation findings

✔

DOCX generation

✔

Scene budgets, self-containment and presenter consistency

✔

The three flows

They are kept strictly apart. A session records which flow it is in, and the tools of one flow cannot produce the output of another.

                start_flow   ← "hi", "start", "can we start", "let's get started"
                     │
     ┌───────────────┼───────────────────────────┐
     ▼               ▼                           ▼
1 Storyboard   2 Video Script          3 Handbook Reading
     │               │                           │
     ▼               ▼                           ▼
  programme       course                      subject
Entrepreneur   Entrepreneur                      │
Orientation    Orientation                       ▼
    CDR            │                          module
     │             ▼                             │
     ▼          subject                          ▼
  subject          │                            unit
     │             ▼                             │
     │          module                           ▼
     │             │                     reading_complete
     │             ▼
     │        video type
     │             │
     │             ▼
     │      presenter ×5 in one answer
     │             │
     │             ▼
     │        background
     │             │
     ▼             ▼
storyboard_ready  video_script_ready
generation begins  generation begins

The menu is three lines and nothing else: what each option produces is answered by the step that follows it, and explaining them up front made the first thing a user saw a wall of text about choices they had not made yet.

Only the storyboard asks which programme, and it asks first, because the three tracks are genuinely different documents — a different template, different sources, different module routing — and everything after that answer depends on it. The video flow asks its own course question over a different list — two options, not three, because CDR has no Participant Handbook and a video is built from one. The reading flow does not ask at all: a subject carries its own track.

The subject is the storyboard's last question. Nothing is asked about length, modules, format or confirmation, because none of it is open: the course's module count comes from its timing document, the shape from its template, and the loop that fills it runs without the user.

The flow asks only what it cannot work out. There is no "would you like to type or browse" question and no course-type question: a topic typed at any step is resolved to the unit that holds it, and course type is a label on each subject.

The video flow stops at the background question. Everything below it is settled: 150-180 seconds, 15-18 scenes of ten seconds, and which slice of which unit each scene introduces. No duration question is asked because there is nothing to choose — the four hard rules fix it. A scene shorter than ten seconds cannot hold twenty-two words, so every scene is ten; 150-180 seconds of those is 15-18 scenes.

Reading goes one level deeper than the module, to the unit, and returns its verbatim text. No generation step exists on that path.

What a video is. One 150-180 second introduction covering the whole module, as 15-18 scenes, each a separate generation:

Structure

opening → what the topic is (×2) → turn to learning → 9-12 learning-area scenes → consolidation → hand-over

Scene seconds

every scene exactly 10s. 15 scenes = 150s, 18 = 180s

Narration

22-25 words per scene, ~150 wpm, at most 3 sentences

Breathing

0.3-0.5s between sentences, 0.5s of silence before the cut

Self-contained

every sentence begins and ends inside its own scene

Unit coverage

each learning area gets 2-3 consecutive scenes, each with its own slice of that area's text

Each scene carries

purpose, location, visual, presenter action, camera framing and movement, teaching visuals, narration, citations

The server adds

the presenter, attire, voice, pace, pauses and speak-once directives — identically, every scene

Output

the script inline and a .txt file, plus one ready-to-paste generation prompt per scene

The presenter comes from a saved video profile — gender, age, skin tone, demographic appearance, attire, background — asked once and reused, so a learner taking several modules of a course meets the same instructor.

Say restart at any step, finished ones included, to clear the session and go back to the menu. back changes the previous answer. start_flow opens an independent session whenever you want one.

Shortcut. A user who names a topic skips the menus: read_ph_unit takes a heading, and plan_video_script takes a subject and a module directly.

Subjects. Nine across three programmes. Each reports exactly what it is waiting for, and the flow offers only the ones it can serve.

Entrepreneur

Orientation

CDR

Solar Photovoltaic ✅

ESG — Environmental, Social and Governance

CDR Biochar

Bio-Energy (Biofuels) ✅

GHG — Greenhouse Gas

Green Hydrogen ✅

GL — Green Logistics

Agri-Residue Aggregator ✅

BG — Biogas

✅ means a storyboard builds today: four approved documents on disk and a reviewed crosswalk. All four Entrepreneur subjects qualify. The Orientation subjects have their documents but no reviewed crosswalk yet; CDR's is blocked on its rewritten master file (see Known gaps).

Adding a subject: drop the PDFs in and pick it from the menu. Put ph.pdf (and qp.pdf, fg.pdf, timing.pdf for storyboards) into courses/<track>/<subject>/, and name that path in the course's directory in src/courses/course-config.ts. A handbook that is present but not yet indexed shows in the menu as a normal choice and is indexed the first time it is picked, which takes a few seconds once. Modules and units are derived from the handbook itself, so nothing about its structure is declared in code.

The folder need not be named for the course_id — Solar's documents arrive in courses/entrepreneur/solar while the course is solar-pv — because directory states the path outright. That is preferred to renaming the folder, because the folder is the thing that keeps arriving.

Templates are per track. Each track renders to templates/<track>/, and the template is chosen from the subject rather than passed in, so a course cannot be built to another track's document. The Entrepreneur and Orientation templates are not interchangeable: Orientation's carries an Instructional Design and Behavioral Analytics section that Entrepreneur's does not, and the table of contents is derived from whichever template is in use rather than assumed.

Module titles come from the handbook's own chapter headings where it prints them. A handbook that jumps straight to its first unit leaves modules titled Module 3; the menu then lists each module's unit titles, rather than inventing a title the handbook never gave. Filling in chapter_titles for that course replaces them. (A storyboard additionally needs a reviewed crosswalk.)

Related MCP server: marp-agent-mcp

Setup

Requires Node 22.13+ (for the built-in node:sqlite). No native compilation, no API keys.

npm install
cp .env.example .env

Then index the course documents once:

npm run ingest -- solar-pv

Add to Antigravity

Add this to your Antigravity MCP configuration:

{
  "mcpServers": {
    "storyboard": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "C:\\cvc-mcp"
    }
  }
}

For a compiled server, run npm run build and use "command": "node", "args": ["dist/src/mcp/server.js"].

The same config works for Gemini CLI and Claude Code — all three speak MCP over stdio.

Tools

Courses and documents

Tool

Purpose

list_courses

Registered courses and the status of their four approved documents

get_course_manifest

Course metadata plus the module crosswalk

ingest_course_documents

Extract, chunk and index the PDFs (idempotent)

search_course_content

BM25 search, scoped by course / document / chapter / NOS

get_source_chunk

Re-read one chunk verbatim by chunk_id

get_document_page

Every chunk on one PDF page, in reading order

Timing and crosswalk

Tool

Purpose

get_module_crosswalk

Map timing module → handbook chapter + NOS code

get_timing_allocation

Authoritative module and unit durations, with citations

validate_timing_allocation

Check the timing document's internal arithmetic

Template

Tool

Purpose

analyze_storyboard_template

Derived table shapes, headers, slide counts, styles

get_storyboard_field_spec

Which fields you write, which are read-only, citation rules

Storyboard

Tool

Purpose

create_storyboard_draft

Skeleton with structure and timing pre-filled

get_storyboard / list_storyboards

Read state, optionally one module

storyboard_next_module

One whole module to write, with its sources attached once

storyboard_submit_module

Write a whole module; commits one version, returns the next

validate_storyboard

Three-level mechanical validation

render_storyboard_docx

Populate the template and export

get_storyboard_history

Versions and change log

rollback_storyboard

Restore a version as a new version

modify_storyboard_timing

Refuses changes that conflict with the timing document

Guided flow

Tool

Purpose

start_flow

The two-option menu; returns a session_id

flow_choose

Answer the current step; also back and restart

get_flow

Re-render the current step (resume after a restart)

Handbook navigation

Tool

Purpose

list_video_subjects

Course types, subjects, and what each unavailable one needs

get_ph_outline

The handbook's own modules and units, derived from the document

find_ph_unit

Resolve a unit heading the user typed, across subjects

get_ph_unit_source

A unit's text split into citable blocks, for writing

Video script (two calls from plan to finished script)

Tool

Purpose

get_video_profile / set_video_profile

The saved presenter and background, or the six questions to ask

plan_video_script

The scenes, their seconds and word bands, what each must achieve, the handbook text behind them, the locked presenter, and the writing rules — all in one call

submit_video_script

All the scenes at once: validates, composes each scene's generation prompt, commits a version, writes the file

get_video_script / list_video_scripts / get_video_script_history

Read state and versions

Exact reading

Tool

Purpose

read_ph_unit

The unit's own text, verbatim. Takes no generation parameters

Typical flow

Storyboard — three answers from the user, then a loop the client runs alone:

start_flow → flow_choose ×3          (menu → programme → subject; stops there)
  → create_storyboard_draft           → artifact_id
  → storyboard_next_module            → WRITE_THIS + one module, sources attached once
  → loop: storyboard_submit_module    → commits one version, returns the next module
     until READY_TO_RENDER            (one call per module: 6–10 for a course)
  → validate_storyboard → render_storyboard_docx → give the user the .docx

The older hand-driven path still works and is what the task loop runs underneath:

list_courses → ingest_course_documents → get_course_manifest
  → get_timing_allocation → analyze_storyboard_template
  → get_storyboard_field_spec → create_storyboard_draft
  → per module: search_course_content → storyboard_submit_module
  → validate_storyboard → render_storyboard_docx

Video script — five answers from the user, then two calls:

start_flow → flow_choose ×5      (menu → course → subject → module → type,
                                  then the presenter and background questions)
  → plan_video_script             scenes, budgets, handbook text, presenter, rules
  → submit_video_script           validates, composes the prompts, writes the file

Exact reading:

find_ph_unit → read_ph_unit            returned unchanged; nothing else runs

Cost and speed

A storyboard is written by a model over many calls, so what governs how long it takes and what it costs is how many times the client is asked, not how fast the server answers. Every MCP round trip re-sends the tool list and the whole conversation so far and buys back one answer, so the number of calls multiplies everything.

The build loop was originally one call per row, which for a six-module course was 130 calls. Measured on Green Hydrogen:

per row (before)

per module (now)

Round trips for a 6-module course

132

10

Tool-result payload

~300K tokens

~110K

Client arguments

~29K tokens

~16K

Source text sent

~178K tokens

~70K

Chunk sends / distinct chunks

774 / 228 (3.4× each, worst 24×)

293 / 293 (1.00×)

Versions written

130, each rewriting the whole state

7

Conversation history re-sent

130 times, growing

10 times

Three things were being paid for repeatedly:

The asking. Per-row batching bought a few fields per call. A module is the natural batch — it is what the template repeats, what the crosswalk scopes, and what one writer can hold in mind at once — so the loop now hands out a whole module and takes it back in one call.

The same source text, again and again. Sources were retrieved per row, so a chunk was re-sent for every row whose wording happened to match it. A module's material is now retrieved once, deduplicated, and sent once.

Re-describing the tools. 54 tool schemas went out with every one of those 130 calls. The surface is now 44 tools, and the loop that uses them is 10 calls rather than 130.

Server-side work is not the bottleneck and never was — a complete course builds in 1.3–1.7s of server time — but two things there were genuinely wrong and are fixed:

Retrieval was scoped after the fact. The scope was a WHERE clause, so SQLite matched a query's terms against every chunk of every course, ranked all of them with bm25(), and only then discarded the out-of-scope 99% — and because a query is an OR of its terms, it matched 2494 of 2530 chunks. Cost grew with the whole corpus, so indexing a second course slowed retrieval for the first. The scope is now carried as indexed tokens inside the FTS index and ANDed into the MATCH, so postings lists intersect: 12.4 ms → 1.8 ms, and independent of how many other courses exist.

A module could not see the end of its own chapter. Scope listings were capped at the search limit of 50, and handbook and guide chunks interleaved, so a module whose chapter ran to 145 chunks got the first fifty of a mixed set — the material its last units are written from was simply absent. Sources are now budgeted per unit: every Part A row is a unit and gets its own slice, so coverage is guaranteed per row and the total scales with how many units a module has rather than with how long its chapter happens to be. A test asserts every row has source material about its own unit.

Tuning, if a course needs it: MODULE_CHUNKS_PER_UNIT (default 6) and MODULE_CONTEXT_CHUNKS (default 10) set how much source a module carries.

What the server enforces

These are structural, not advisory — the client cannot route around them.

Course isolation. Every retrieval query carries a mandatory course_id predicate. There is no code path that returns a chunk from another course, and an unregistered course_id throws rather than falling back.

The scope is carried inside the full-text index rather than applied to its output. Each chunk is indexed with opaque tokens naming its course, document, chapter, unit and NOS (see src/documents/scope-tokens.ts), and a query ANDs the ones it needs into the MATCH expression. As a WHERE clause the scope could only be applied after the fact: SQLite ranked every chunk of every course — a typical query, being an OR of its terms, matched 98% of the corpus — joined each one, and then discarded almost all of them. Cost therefore grew with the size of the whole corpus, so indexing a second course slowed retrieval for the first. Intersecting postings lists instead made a scoped query roughly seven times faster, and made it independent of how many other courses are indexed.

Timing is read-only. Durations are parsed from the Timing Allocation Document and carry a page citation. The build loop cannot write a duration. modify_storyboard_timing refuses any value that disagrees with the document and explains the conflict.

Parts B and C are spent out of the module's own time. They are fixed at 15 minutes each, so Part A is the module total less half an hour — a three-hour module gives Part A 2.5 hours. That is the template's own arithmetic: every Part A heading in it reads "(2.5 hours)" under the three-hour modules it states. Handing Part A the whole module made its heading disagree with the template and made the three parts sum to half an hour more than the module lasts.

The two tables agree about an activity by construction. An LMS Technical Mapping row's Unit and Activity Type are copied from that unit's Part A row rather than written again, because both tables describe the same activity. They are read from the state as just written, not from the work order — the work order is computed before the call, when Part A is still blank, so taking them from it left the Activity Type column empty in every module.

The table of contents is rebuilt as a field, from the document produced. The template's contents is a live TOC field: each entry is a hyperlink to a _Toc… bookmark, a right-aligned tab with a dot leader, and a PAGEREF. Rewriting those entries as plain text destroyed all three -- the output carried zero TOC fields, so w:updateFields had nothing to refresh, no page number or leader could ever appear, and the bare run left behind still carried the Hyperlink character style, so it rendered as blue underlined text. The renderer now discards the template's entries and emits one per Heading1 and Heading2 in the finished body, bookmarking each heading as it goes. Levels come from the heading styles, so a course with a different module count, and the glossary, are carried without a second list to keep in step.

The field is written \o "1-2", matching what the template's contents actually shows. Its own field instruction says "1-3", which disagrees with its cached entries -- there are ten Heading3 question-group headings and none is listed -- so refreshing under "1-3" would add eleven lines the reference document does not have.

The cover keeps its page break. It ends with one, in the same paragraph as the strapline, and that is what puts the contents on page two. Replacing a paragraph's text discarded every run in it, the page break included, so the contents rode up onto the cover. setParagraphText now carries page-break runs across the rewrite.

The template formats within a paragraph, and so does the output. A question stem is a bold green "1. " followed by a bold stem; an explanation is a bold-italic "Explanation: " followed by italic text; a Part A cell is a bold activity name followed by a plain description; a script cell is a bold speaker followed by plain dialogue. Each is one paragraph holding two differently-formatted runs. setParagraphText keeps only the first run's properties, so every one of those came out uniformly bold -- the label's formatting spread across the whole line. setParagraphParts maps part N onto run N instead, and inside table cells the split is read off the prototype: a cell whose first run is bold and whose later runs are not is a label-and-body cell, and its text is divided at the first ": ". The decision stays in the template rather than being repeated per column.

Every storyboard closes with a glossary. Terms and abbreviations are gathered a module at a time, from the sources that use them, so each carries that module's citations; the renderer merges them into one alphabetical Glossary of Terms and Abbreviations, deduplicated by term, and lists it in the contents. It renders as an Abbreviation / Full Form / Definition table built from the template's own three-column table, so its header fill, borders, padding, fonts and column widths are the template's. It is the only thing in the output that the template does not already contain -- a formatting diff of a generated storyboard against the template reports the glossary table and nothing else.

One folder per subject, holding one document. A render writes artifacts/<course_id>/<course_id>-storyboard.docx and removes any earlier render beside it. Version history stays in the database, which is where it is queryable; what is on disk is the deliverable, and there is exactly one of it. Naming the folder for the artifact and the file for the version meant every draft made a new directory and every render added a file.

The module crosswalk. The source documents disagree about module numbering. The client-authored timing document renumbers the SCGJ chapters:

Timing module

PH / FG chapter

NOS

1 Entrepreneurship & Biomass Basics (3h)

1

SGJ/N4102

2 Financial Budget & Business Plans (6h)

2

SGJ/N4103

3 Sales, Supply & Marketing (3h)

3

SGJ/N4103

4 Compliance (3h)

4

SGJ/N4104

5 Pellet Manufacturing, Elective 1 (3h)

7

SGJ/N4105

6 Small Biogas Plant, Elective 2 (6h)

8

SGJ/N4106

7 HSE (3h)

5

SGJ/N4050

8 Employability Skills (3h)

— none —

DGT/VSQ/N0102

Pass module_number to search_course_content and the crosswalk is applied for you. Getting this wrong yields content about the wrong subject under a correct-looking citation, so validate_storyboard also rejects any citation whose chunk belongs to the wrong chapter.

Template fidelity. The DOCX is never built from scratch. styles.xml (345 KB), theme1.xml, numbering.xml, header1.xml, footer1.xml and sectPr are carried over as untouched package parts, and every paragraph, row and table in the output is a clone of a real element from the template with only its <w:t> text replaced. Formatting is preserved by construction; a test asserts those parts are byte-identical.

Traceability. Every generated educational field must cite a chunk_id. Validation confirms each citation resolves to a real chunk, in the right course and chapter, and measures lexical overlap between the field and the text it cites.

Insufficient source. Where the approved documents cannot support content, the result is INSUFFICIENT_SOURCE_CONTENT, never invented material.

The outline is the handbook's own contents. Modules and units are read from the indexed handbook, and unit titles are taken from its table of contents, which is the one place every title is printed complete. Every module the handbook declares is listed — including one that has no units, like Biofuels module 6 (Employability Skills), which the handbook defers to an external DGT workbook. It is shown with its reason and cannot be selected. A test asserts the outline matches the contents page unit for unit.

A video's shape is arithmetic with one answer. Four rules are fixed — 150-180 seconds, no scene over 10 seconds, 22-25 words a scene, no sentence crossing a scene boundary — and a scene shorter than ten seconds cannot hold twenty-two words. So every scene is exactly ten seconds and the video is 15-18 of them. Six are the frame and the other 9-12 go to the units, two or three apiece, which is what makes it a complete module introduction rather than a teaser. A scene outside its word band is a validation error: over the band the generator cuts the last words off mid-sentence, which is not recoverable after rendering.

Every scene finishes what it starts. Each scene is a separate generation and may be watched with a beat between clips, so a sentence spanning two of them does not merely read awkwardly — it breaks. Validation rejects narration that ends without terminal punctuation, ends on a word that promises a continuation (and, so, which, to, …), or contains a fragment. At most three sentences a scene, because the breath between them and the half-second before the cut need somewhere to fit.

The pace follows from the word count, not the other way round. Twenty-two to twenty-five words inside ten seconds, with a breath between sentences and a beat of silence at the end, is about 150 wpm — not the 120-130 an earlier brief asked for. The word count and the scene length are the mandatory rules, so the pace is derived from them and stated in every prompt. Asking a generator for 130 wpm and 25 words in one clip simply produces a clip whose last words are cut off.

The presenter is the same person by construction, not by discipline. Each scene is a separate generation and the generator remembers nothing between calls, so a presenter described afresh per scene comes back as a different face, in different clothes, with a different voice. The description is therefore written once from the saved profile and the identical text is stamped into every scene prompt by the server — along with the voice, the delivery pace, the 0.5-1 second speech lead-in and the speak-this-line-once audio directive. The client is told not to write any of them, and validation reports those checks as guaranteed rather than sampled, because they cannot fail.

On-screen text is spelled out, enumerated and fenced. Misspelled burned-in text is the commonest way a finished clip comes back unusable — the shot looks right, the audio is right, and a learner sees CALORIFC VALUE in a training video. Every scene prompt therefore carries an ACCURACY block that names the exact strings permitted (the caption, character for character; the teaching visual's labels), forbids all other text including invented background lettering on walls, packaging and equipment, pins every number and unit to the value given, and — the escape hatch that matters — tells the generator that if text cannot be rendered cleanly it should render none, because missing text is recoverable and misspelled text is not. It appears on every scene, including scenes with no text at all, since those are exactly where invented signage slips through. The block adapts to the scene: a scene with a labelled diagram is never told "no text may appear", because a prompt that contradicts itself is resolved by the generator however it likes.

The prompt forecloses the errors rather than hoping. Each composed prompt is labelled blocks and a numbered eight-point audio contract, not prose: the spoken line quoted in full and marked as the entire audio, the pauses given in seconds, and an explicit DO NOT list (no second person, no music, no captions, no slow motion, no cutting away, no restyling the presenter). A generator does not infer — it fills gaps with whatever is statistically nearby, and every gap is a defect waiting to be rendered.

The topic is the hero. This is an LMS introduction, not a short film. The spec that ships with the plan rules out backstory, character development, drama, conversation and cinematic set pieces, and the composed prompt says so to the generator too. The presenter holds, points at and demonstrates things; that is the whole of their role.

A video script never mentions its source. No handbook, page, figure, table, unit number, module number, QR code or qualification code may appear in narration, on-screen text, the visual description, the location or the presenter's action — the viewer has none of those in front of them. It is an error, not a warning, and citations stay in each scene's sources.

Every teaching scene is grounded in its own allocation. A roadmap scene must cite chunk_ids, they must resolve in that subject's handbook, and they must belong to the units allocated to that scene — a citation borrowed from another part of the module is an error. The framing scenes cite nothing, because they speak about the module rather than from a passage of it.

A duplicated word is caught before it is spoken. "the the" in a narration line is what a stuttering generation sounds like, and written into the script it is guaranteed rather than likely, so it is an error.

One script per module, not one per request. The store is keyed on course, module and video type, so answering the flow twice for the same module continues the script that exists. The previous feature keyed on nothing and left a hundred empty rows behind.

The reading mode cannot generate. read_ph_unit takes a subject and a unit and nothing else — no length, no style, no audience. There is no parameter through which a summary could be requested, and the result carries a fidelity_note stating the only two mechanical differences from the printed page (removed running headers and folio numbers, removed indexing overlap).

Unit resolution refuses to guess. When a typed heading matches two units closely, find_ph_unit reports confident: false and the flow asks which was meant rather than picking one — reading out the wrong unit answers a question nobody asked.

Generation is two calls, deliberately. Every MCP round trip re-sends the tool list and the whole conversation and buys back one answer, so a feature that fetches a spec, then the source, then submits, then validates, then renders, then exports costs six times what a 90-second video needs. Everything the writer needs travels with the plan, and everything the server does with the result happens inside the submit.

Known gaps

Module 8 (Employability Skills, 3 of 30 hours) has no source content. Neither the Participant Handbook (p.292) nor the Faculty Guide (p.106) contains it — both defer to an external DGT workbook, and a keyword sweep of the 311-page handbook for the DGT/VSQ/N0102 topics returns nothing. The module renders as a flagged stub. Supply the DGT/VSQ/N0102 Employability Skills workbook as a fifth approved document and it will generate like any other module.

Validation grounding is lexical, not semantic. Without a model, the server can confirm a citation resolves, is correctly scoped, and shares wording with the field citing it. It cannot judge whether a sentence is a fair paraphrase — that assessment belongs to the client, and low_grounding_overlap is reported as a warning rather than an error to reflect that.

Page numbers need Word, and are resolved at generation time. The contents is a real TOC field with a PAGEREF per entry, and both are computed from where text falls on the page -- a layout pass this server cannot do. So the renderer emits the fields with an empty cached result and then hands the finished file to Word once, via COM, to update them and save. The numbers are in the file from that point, so a viewer that shows cached field results rather than resolving them displays them too.

That step is the one place the pipeline reaches outside itself, and it is deliberately last and soft: the byte-faithful document is already on disk before it runs, and a machine without Word gets a warning and a document whose page numbers fill in the first time it is opened in Word. Set REFRESH_FIELDS=false to skip it. Word rewrites the package when it saves, so the byte-identity check against the template applies to what the renderer wrote, before this runs -- which is what the suite asserts, with the refresh switched off.

Orientation has documents but no crosswalk. All four Orientation subjects have their PDFs on disk, so the reading flow serves them today. A storyboard additionally needs a reviewed crosswalk and chapter-title map in src/courses/course-config.ts, which is left empty for them rather than guessed at: an inferred crosswalk produces a storyboard about the wrong chapter under citations that look valid. The storyboard menu lists them and says so.

CDR's master file has been rewritten. courses/cdr-biochar/master.docx now declares five modules rather than seven, states each duration on the line after the module heading rather than on it, and names its reference documents by their on-disk filenames. src/cdr/master-file.ts still expects the previous shape and finds no module headings at all, so the CDR track cannot build and its generation tests are skipped with that reason. Nothing else depends on it.

Development

npm run typecheck
npm test                       # 155 tests
npm run flow                   # walk the guided flow by hand in the terminal
npm run flow -- "<heading>"    # the shortcut flow, from a unit heading
npm run parse-timing -- biofuels
npm run analyze-template
npx tsx scripts/render-skeleton.ts biofuels

npm test covers timing parsing and arithmetic, chapter attribution, FTS query escaping, run-preserving paragraph replacement, course isolation, crosswalk scoping, citation validation, question-bank numbering and rejection rules, version conflicts, rollback, and byte-identical preservation of the template's formatting parts. The handbook suite covers overlap-free unit reassembly, heading resolution and its refusal to guess, and the guided flow's step machine. The video suite covers the scene arithmetic (every scene ten seconds, seconds summing exactly, contiguous timecodes, the fixed 22-25 word band, every unit given two or three consecutive scenes with a distinct slice each), each validation rule against a script written to break it — including narration left open, ending on a dangling word, holding a fragment, or holding more sentences than the breaths fit — the identity of the presenter block across every composed prompt, and the flow's five questions including the five-in-one presenter answer.

Layout

src/
  mcp/server.ts          stdio MCP server
  mcp/tools/index.ts     the registry: assembles the lists below and dispatches
  mcp/tools/flow.ts      start_flow, flow_choose, get_flow -- the entry point
  mcp/tools/storyboard.ts  feature 1, the storyboard's course, timing and render tools
  mcp/tools/storyboard-build.ts  feature 1's build loop: one module out, one back
  mcp/tools/video-script.ts  feature 2, the 2.5-3 minute info video: plan and submit
  mcp/tools/reading.ts   feature 3, read_ph_unit
  mcp/tools/catalog.ts   handbook navigation
  catalog/               course types, subjects, and their readiness
  courses/               course registry, crosswalk, chapter titles
  documents/             PDF extraction, chunking, ingestion, BM25 retrieval
  documents/ph-outline   handbook structure, verbatim reading, heading resolution
  flow/                  the guided step machine, persisted per session
  timing/                timing parser and arithmetic validator
  docx/                  OOXML helpers, template analyzer, renderer
  storyboard/            skeleton builder, module work order, three-level validator
  videoscript/           profile and character lock, scene planning, prompt
                         composition, validation, rendering, store
  reading/               plain-text rendering of a handbook unit
  storage/               SQLite schema, artifact and version store
courses/<track>/<subject>/   qp.pdf ph.pdf fg.pdf timing.pdf
templates/<track>/           that track's storyboard template
scripts/timing/              author a Timing Allocation Document for a new course
scripts/cdr/                 regenerate the CDR course definitions from a master file
artifacts/<course_id>/       the finished storyboard, one document per subject
artifacts/video-scripts/<script_id>/   the finished video script, one file per version

Available Tools

54 tools
analyze_storyboard_templateAnalyze storyboard templateA

Inspects the storyboard DOCX template and returns its derived structure: per-module table shapes, exact column headers, slide counts, paragraph styles and the assessment section. Read this before generating content so the content you produce matches the shapes the template requires. Formatting is preserved automatically by the renderer; you never need to specify fonts, colours or layout.

Inputs: template_version.

create_storyboard_draftCreate storyboard draftA

Creates a new storyboard artifact as version 1, pre-populated with everything derivable from the approved documents: modules, unit codes and titles, authoritative durations with provenance, correlation NOS codes, and empty rows/slides of the correct shape. Content fields are left blank for you to fill via set_storyboard_content. Modules the sources cannot support are marked INSUFFICIENT_SOURCE_CONTENT rather than invented.

Inputs: course_id (required), note, modules, timing_strategy, +1 more.

export_module_packageExport the module package as filesA

Writes every deliverable for a finished package and returns their paths: the video script as .txt, the subtitle track as .srt, the deck as .pptx and as .txt. Call this whenever a module has been generated, and ATTACH THE RETURNED FILES so the user can download them from the conversation rather than copying a long script out of it. Refuses by default if validation has errors; pass allow_invalid to export a draft anyway.

Inputs: package_id (required), version, allow_invalid.

find_ph_unitFind a unit by headingA

Resolves a unit heading the user typed to the unit, the module and the subject that holds it, searching every indexed Participant Handbook. This is the entry point for both shortcut flows: "make a video script for " and "what does actually say". Ranking is deterministic term matching. When confident is false the top candidates are close -- ask the user which they meant rather than picking one.

Inputs: heading (required), limit, track, subject.

flow_chooseAnswer the current flow stepA

Applies the user's answer to the step a session is on and returns the next step, with its prompt and options. Pass what the user actually said. Each step accepts its option values, and the menu also accepts 1, 2 or 3. An answer that matches no option is tried as a topic name before it is rejected, so a user who types "quality control of biomass pellets" at the subject or module step is taken straight to the unit that holds it. An answer that matches neither re-asks the same step with an explanation rather than guessing. Two answers work everywhere, finished steps included: "back" changes the previous answer, and "restart" clears the session and returns to the menu. Follow the step's next_action exactly; when a step reports done, everything it needed has been asked, so generate without further questions.

Inputs: choice (required), session_id (required).

get_course_manifestGet course manifestA

Full manifest for one course: metadata, approved document status, and the module crosswalk. The crosswalk is essential -- it maps each Timing-Allocation module number to the Participant Handbook / Faculty Guide chapter and the NOS code that hold its content. These numbers disagree (timing module 5 is handbook chapter 7), so always scope retrieval using the crosswalk rather than the module number.

Inputs: course_id (required).

get_document_pageGet document pageA

Returns every chunk on one PDF page of one approved document, in reading order. Use it to widen context around a search hit, or to read a page a citation points at.

Inputs: pdf_page (required), course_id (required), document_type (required).

get_flowGet flow sessionA

Re-renders the step a session is on, with its prompt, options and selections so far. Use it to resume after a gap. It advances nothing.

Inputs: session_id (required).

get_module_content_specGet module content field specA

What to write into each video segment and each slide, what is fixed by the plan, and the standard the output is held to. Read this before submit_module_video or submit_module_slides.

Inputs: no named parameters.

get_module_crosswalkGet module crosswalkA

Resolves Timing-Allocation module numbers to the PH/FG chapter and NOS code that hold their source content, and flags modules the approved documents cannot support. Omit module_number for the whole table.

Inputs: course_id (required), module_number.

get_module_packageGet a module content packageA

Returns the package state: the plan, the segments and the slides written so far, with their citations. Use get_module_video_script or get_module_slides for the deliverables themselves.

Inputs: package_id (required), version.

get_module_package_historyGet module package historyB

Returns a package's version list. Versions are append-only and can be read back.

Inputs: package_id (required).

get_module_slidesGet the module slide deck as textA

Returns the 14 slides as plain text -- title, bullets, speaker notes -- for reading or copying. Call render_module_pptx for the .pptx file itself.

Inputs: package_id (required), version.

get_module_sourceGet a module package's source textA

Returns the Participant Handbook text behind a package: by default every unit of the module in full, and optionally the exact portion allocated to one video segment or one slide. The plan says which unit and portion each slot covers; this is the text to write it from. Content may present this material any way that teaches well, but may not go beyond it.

Inputs: package_id (required), slide_number, segment_number.

get_module_subtitlesGet the video subtitlesA

Builds the subtitle track from the segments' narration as a progressive, word-by-word typewriter reveal, synced to each segment's ten seconds. Format "srt" (the default) is a SubRip file to burn in or load into an editor; "cues" returns the timings as data. Word timing is estimated from word length -- there is no audio to align against -- so treat it as a starting point an editor nudges, not a finished sync.

Inputs: package_id (required), format, version.

get_module_unitsGet the units behind a moduleA

Lists the units of one handbook module with their lengths. The user-facing flow stops at the module, so this is for your own orientation and for answering a question about what a module contains -- not a menu to put in front of the user.

Inputs: subject (required), module_number (required).

get_module_video_scriptGet the module video scriptB

Returns the 3-minute script as eighteen self-contained 10-second segments in plain text, each ready to paste straight into the video generator: narration, scene, visual direction, on-screen text and the transition into the next segment. No page numbers or citations. Also writes the script to a .txt file and returns its path: ATTACH THAT FILE FOR THE USER TO DOWNLOAD alongside the text, since eighteen full segments are more than anyone wants to copy out of a chat window. Give the user the text as it stands.

Inputs: package_id (required), version.

get_ph_outlineGet Participant Handbook outlineA

Returns a subject's modules and units exactly as its Participant Handbook has them, derived from the indexed document rather than declared anywhere, so re-ingesting a revised handbook updates it. Module numbers here are the handbook's chapter numbers; where a reviewed crosswalk exists the Timing Allocation module number is reported alongside as timing_module, and the two are never interchangeable.

Inputs: subject (required), module_number.

get_ph_unit_sourceGet a unit's source text for generationA

Returns a unit's handbook text split into the citable blocks the scene plan allocates from, with each block's chunk_id and page. Use it while writing when you want more of the unit than one scene's allocation, or to check which chunk_id covers a passage. For showing the user what the unit says, use read_ph_unit instead -- that one is the reading flow and carries its handling rules.

Inputs: subject (required), unit_code (required).

get_source_chunkGet source chunkA

Fetches one indexed chunk verbatim by chunk_id, scoped to a course. Use it to re-read the exact text behind a citation, or to verify a citation resolves before committing content.

Inputs: chunk_id (required), course_id (required).

get_storyboardGet storyboardC

Returns a storyboard's state. Defaults to the current version. Narrow to one module to keep the payload small while filling content.

Inputs: artifact_id (required), version, module_number.

get_storyboard_field_specGet storyboard field specA

Describes exactly which fields you are expected to write for each section, what each one means in the reference document, and which fields are read-only because they come from the Timing Allocation Document. Read this before your first set_storyboard_content call.

Inputs: no named parameters.

get_storyboard_historyGet storyboard historyA

Returns the version list and change log for an artifact, so you can answer "what changed between version 1 and 4" or "what changed in module 3". Narrow with from_version / to_version.

Inputs: artifact_id (required), to_version, from_version.

get_timing_allocationGet timing allocationA

Parses the Timing Allocation Document and returns the authoritative durations: module totals, per-unit minutes, sub-topics, and a page citation for every value. This is the only source of timing -- never compute or assume a duration. Optionally narrow to one module.

Inputs: course_id (required), module_number.

get_video_transcriptGet video transcriptA

Returns the transcript. Format "script" (the default) is the finished scene-by-scene script as plain text, ready to copy straight into a teleprompter or editor: titles, timings, visuals and narration, with no page numbers, citations or word counts in it. Give the user this text as it is -- do not append sources to it. Format "production" adds the sourcing and budget annotations for a reviewer; "json" returns the structured state including the plan and every citation. This flow produces no file by design.

Inputs: transcript_id (required), format, version.

get_video_transcript_historyGet video transcript historyA

Returns a transcript's version list. Versions are append-only, so an earlier draft can always be read back with get_video_transcript and a version number.

Inputs: transcript_id (required).

get_video_transcript_specGet video transcript field specA

Describes what to write into each scene, what is fixed by the plan and may not be changed, and the grounding rules validation enforces. Read this before your first submit_video_transcript call.

Inputs: no named parameters.

ingest_course_documentsIngest course documentsA

Extracts, chunks and indexes a course's approved PDFs for retrieval. Idempotent: documents whose checksum is unchanged are skipped unless force is true. Must be run once per course before search_course_content returns anything.

Inputs: course_id (required), force, document_types.

list_coursesList coursesA

Lists every registered course with its QP code, NSQF level, module count and the presence/index status of its four approved source documents (QP, PH, FG, TIMING). Call this first to discover valid course_id values.

Inputs: no named parameters.

list_module_packagesList module content packagesA

Lists module packages, newest first, optionally for one subject.

Inputs: subject.

list_storyboardsList storyboardsA

Lists storyboard artifacts, optionally filtered by course.

Inputs: course_id.

list_video_subjectsList course types and subjectsA

Lists the two course types and their subjects, with whether each one's Participant Handbook is present and indexed. A subject that is not ready carries the one action that would make it ready. Call this before offering the user a choice, so an unavailable subject is never offered as though it worked.

Inputs: track.

list_video_transcriptsList video transcriptsB

Lists video transcripts, newest first, optionally for one subject.

Inputs: subject.

modify_storyboard_timingModify storyboard timingA

Attempts to change a module or unit duration. Permitted only when the requested value matches the Timing Allocation Document, which is authoritative for time. A conflicting request is refused with an explanation rather than applied -- durations may never come from model judgement.

Inputs: artifact_id (required), base_version (required), module_number (required), requested_minutes (required), +2 more.

plan_module_contentPlan a module content packageA

Plans the full 12 minutes of content for one Participant Handbook module. The video is three parts: Part 1 (segments 1-6, 60s) orients the learner to the whole module using the handbook's stated learning outcomes, Part 2 (segments 7-15, 90s) teaches every unit in handbook order, Part 3 (segments 16-18, 30s) consolidates. The deck is sized to the module rather than fixed: nine minutes across as many slides as it needs, never more than 30 seconds on any one slide. Returns a package_id, the plan, and a content map of the module's outcomes and units. Every segment and slide is told which unit it covers, which portion, which chunk_ids to cite and how many words fit its seconds. Accepts a module number, or a topic to resolve to the module that holds it. Ask the user nothing further: every duration and count is settled.

Inputs: title, topic, subject, module_number, +1 more.

plan_video_transcriptPlan a video transcriptA

Creates a video transcript draft for one Participant Handbook unit and returns its scene plan. The plan divides the requested duration into scenes, gives each scene a word budget at a stated speaking rate, and attaches to each scene the exact handbook text it must be built from and the chunk_ids it must cite. Accepts either subject + unit_code, or a heading to resolve -- which is the shortcut flow, where the user names a unit and skips the menus. The handbook is the source of truth: presentation, narration, examples and visual direction are yours to author, the educational content is not.

Inputs: duration (required), title, heading, subject, +3 more.

read_ph_unitRead a handbook unit exactlyA

Returns the Participant Handbook's own text for one unit, verbatim and complete, in document order. This is a reading operation, not a generation one: pass the text on to the user unchanged. Do not summarise, shorten, expand, paraphrase, re-order, re-format, correct or comment on it, and do not merge it with anything else. It carries a fidelity_note stating the only two mechanical differences from the printed page (removed running headers and folio numbers, removed indexing overlap); repeat that note if the user asks how exact this is. If the user afterwards wants a video, that is the separate video flow, not a rewrite of this text.

Inputs: heading, subject, unit_code.

render_module_pptxRender the module deck to PowerPointA

Writes the 14-slide deck to a .pptx file, with each slide's speaker notes attached as PowerPoint notes, and returns the path. Refuses by default if validation has errors; pass allow_invalid to render a draft anyway.

Inputs: package_id (required), version, allow_invalid.

render_storyboard_docxRender storyboard DOCXA

Renders the storyboard to .docx by cloning the template and inserting content. Template formatting is preserved by construction -- styles, theme, numbering, header, footer and section properties are carried over untouched. Returns the output path. Refuses by default if validation has errors; pass allow_invalid to render a draft anyway.

Inputs: artifact_id (required), version, allow_invalid.

rollback_storyboardRollback storyboardA

Restores a previous version's state as a new version. History is append-only: the versions between are preserved and the rollback can itself be rolled back.

Inputs: to_version (required), artifact_id (required), reason.

search_course_contentSearch course contentA

Deterministic BM25 search over one course's approved documents. Results are always scoped to the given course; there is no way to retrieve another course's content. Narrow further with document_types, and with either chapter (for PH/FG) or nos_code (for the QP) -- use get_module_crosswalk or module_number to get the right values. Each result carries a chunk_id, which is what you must cite in generated content.

Inputs: query (required), course_id (required), limit, chapter, +4 more.

set_assessment_contentSet assessment contentA

Writes the assessment strategy blueprint and the question bank, committing a new version. The template runs ten questions per module, grouped under a per-module heading. Every question must cite the chunk_ids that support its stem, correct answer and explanation; the three incorrect options are authored, since a source document contains no answer key, and the rendered document discloses that. Questions accumulate across calls, so you can submit one module at a time -- pass replace: true to start over. Question numbers are assigned automatically in module order unless you set them.

Inputs: artifact_id (required), base_version (required), note, remarks, +6 more.

set_module_storySet the film's story bibleA

Records the constants of the 3-minute film: the protagonist, the handful of locations, the light and camera language, the narrator, the three acts and the opening image the ending returns to. Write this BEFORE the segments. Each 10-second clip is generated separately and the generator remembers nothing between calls, so continuity exists only where it is written down -- and validation checks every segment against what you record here. Build the whole story first, then cut it into eighteen shots; do not write eighteen prompts and hope they join up.

Inputs: story (required), package_id (required), base_version (required), note, +1 more.

set_storyboard_contentSet storyboard contentA

Writes generated content into a storyboard and commits it as a new version. Address rows and slides by their row_id / slide_id from get_storyboard; anything you do not mention is left unchanged, so this is safe for incremental edits. Every content field should carry sources citing chunk_ids returned by search_course_content -- validate_storyboard checks that they resolve and are in the right chapter. Durations, unit codes and unit titles are not writable here: they come from the Timing Allocation Document. Use modify_storyboard_timing if a duration genuinely needs to change.

Inputs: artifact_id (required), base_version (required), module_number (required), note, +7 more.

start_flowShow the menuA

Returns the three things this server can do, as a menu, plus a session_id. CALL THIS FIRST whenever the user opens with an unscoped request -- "can we start", "let's start", "show me what you have", "what can you do", "hi", "begin" -- and whenever they finish one thing and want another. Show the three options to the user and wait for their pick; do not ask any question of your own before or after, and do not begin work until they have chosen. The options are: 1 video script + slide deck for a module, 2 read a handbook unit word for word, 3 course storyboard. Answer with flow_choose. Sessions are independent and cheap, so call this again rather than reusing a finished one.

Inputs: no named parameters.

storyboard_next_taskGet the next storyboard taskA

Returns the one next piece of the storyboard to write, with the handbook text to write it from already attached and the exact fields enumerated. Call this immediately after create_storyboard_draft, and again any time you lose track of where you are. The result is either status WRITE_THIS with a task, or status READY_TO_RENDER when nothing is left. You never need to choose a module, a row or a search query: the queue is ordered for you and the sources are scoped to the module the task belongs to.

Inputs: artifact_id (required).

storyboard_submit_taskSubmit a storyboard task and get the nextA

Writes the fields of the task you were given and returns the NEXT task, in the same shape. This is the whole build loop: submit, write what comes back, submit again, until status is READY_TO_RENDER. Pass one entry per field in task.fields, each with the field_id exactly as given. For a field marked requires_citation, pass chunk_ids taken from task.sources -- those chunks are already scoped to the right module, so citing any of them is correct. Nothing is committed if any entry is rejected, so a failed call can be corrected and resent unchanged otherwise.

Inputs: task_id (required), artifact_id (required), note, entries, +2 more.

submit_module_slidesSubmit the module slidesA

Writes the fourteen slides and commits a new version. Submit all fourteen together -- the deck is checked as one for unit coverage. The video half of the package is left untouched. Slide copy must be written from the unit content, not copied out of it.

Inputs: slides (required), package_id (required), base_version (required), note, +1 more.

submit_module_videoSubmit the module video segmentsA

Writes the eighteen 10-second segments and commits a new version. Submit all eighteen together -- they are one film and are checked as one. The slide half of the package is left untouched. Word counts and citation metadata are filled in from the plan and the handbook index; you supply the words and the chunk_ids.

Inputs: segments (required), package_id (required), base_version (required), note, +1 more.

submit_video_transcriptSubmit video transcript scenesA

Writes the authored scenes into a transcript and commits a new version. Scenes replace the previous set wholesale, so submit the complete script each time; base_version is the version you read, and a stale one is refused rather than overwriting newer work. Word counts and citation metadata are filled in from the plan and the handbook index -- you supply the words and the chunk_ids only.

Inputs: scenes (required), base_version (required), transcript_id (required), note, +1 more.

validate_module_packageValidate a module content packageA

Checks the package mechanically: all 18 segments and 14 slides written, every segment's narration short enough to fit its ten seconds, notes within their budget, every unit of the module covered by both the video and the deck, every citation resolving to a chunk of this module, and no reference to the handbook, a page, a figure or a unit number in any delivered text. Whether the writing is good is your judgement, not this tool's.

Inputs: package_id (required), version.

validate_storyboardValidate storyboardA

Runs all three validation levels and returns structured findings. Level 1 checks traceability mechanically: every content field carries a citation, each citation resolves to a real chunk in the correct course and chapter, and the wording measurably overlaps the cited text. Level 2 checks timing arithmetic against the Timing Allocation Document. Level 3 checks structural conformance to the template. Findings are reported, never auto-fixed -- decide how to address each one and resubmit via set_storyboard_content. Note that low_grounding_overlap is a lexical signal only, not a judgement about meaning.

Inputs: artifact_id (required), version, skip_content.

validate_timing_allocationValidate timing allocationA

Checks the Timing Allocation Document's internal arithmetic: unit minutes sum to their module total, module totals sum to the stated course total, and each unit's stated hours match its stated minutes. Reports discrepancies without repairing them.

Inputs: course_id (required).

validate_video_transcriptValidate video transcriptA

Checks a transcript mechanically: every planned scene written, each scene within its word budget, the whole script reading back in about the requested duration, and every citation resolving to a chunk of this unit of the Participant Handbook. Whether the narration is a fair rendering of the source is your judgement, not this tool's. Findings are reported and never auto-fixed.

Inputs: transcript_id (required), version.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 54 tools

    Disambiguation4/5

    Despite the high tool count, most tools target a distinct resource and action, and the descriptions are unusually explicit about which flow each belongs to. A few pairs—such as get_ph_unit versus get_ph_unit_source, or plan_module_content versus plan_video_transcript—require careful reading to disambiguate, but the intent is clear.

    Naming Consistency4/5

    The huge majority of tool names follow a recognizable get_/list_/set_/submit_/validate_ verb + noun pattern in snake_case, which is predictable. Minor deviations like flow_choose, storyboard_next_task, and storyboard_submit_task break the pattern enough to prevent a perfect score.

    Tool Count1/5

    At 54 tools, this is far beyond the typical well-scoped MCP surface and crosses the rubric's explicit 50+ extreme-mismatch threshold. Even though each tool appears to have a purpose, the sheer number would overwhelm an agent's tool-selection space and create unnecessary selection and orchestration risk.

    Completeness4/5

    The three main authoring flows—storyboards, module packages, and video transcripts—are covered end-to-end with plan, submit, validate, retrieve, render, export, and history tools. Minor gaps include the lack of rollback for module and transcript versions, and no delete or archive operations, though these are partially by design given the append-only history model.

    Related MCP Connectors

    Related MCP Servers