teach-me-ai
# teach-me-ai MCP
A local-first [Model Context Protocol](https://modelcontextprotocol.io) server for **authoring durable teaching guides** and then **teaching from them** with an AI coach.
Guides are stored as inspectable local JSON and Markdown files. There is no database, no network service, and no hidden state: drafts, finished guides, section bodies, and the portable `teaching-guide.md` survive restarts and can be backed up or versioned like any other folder. Section and guide IDs are stable.
#### TBH: there are repos which are significantly adavanced than this but I built this one the way I wanted it to be..
## Features
- **Authoring state machine:** `create_guide` → `add_section` (repeated, ordered) → `edit_section` as needed → `finish_guide`.
- **Learner-calibrated authoring:** a short, one-question-at-a-time intake covers the target outcome, prior knowledge, preferred style, time, and accessibility needs. One or two lightweight diagnostics calibrate depth, and learners can accept defaults or skip intake.
- **Cumulative journeys:** sections move from outcome and prerequisites through mental model, mechanism, worked example, guided practice, independent transfer, and synthesis. Optional depth is marked, duplication is removed, and the reason for the order is explained.
- **Resume by name:** `select_guide` returns metadata plus the last four sections with truncated previews.
- **Exclusive draft editing:** `create_guide` and `select_guide` acquire a persisted per-draft edit lock. Only the owning server process can mutate the draft; other processes get a clear `CONFLICT` naming the owner and how to retry. `finish_guide` and `release_guide` hand the draft back.
- **Crash-safe locks:** stale locks from processes that exited are detected by PID and recovered automatically on the next selection. Graceful shutdown releases held locks.
- **Safe editing:** replace a whole section, or replace an exact substring only when it occurs exactly once.
- **Read-only finished guides:** finishing validates the guide, freezes it, and writes a portable `teaching-guide.md` with teaching guidelines, the ordered learning journey, and every section exactly as authored — including embedded diagrams, code labs, output, and references.
- **Teaching state machine:** `list_guides` → `start_guide` → repeated `next_section` with an explicit completion result. The coach orients the learner, teaches one chunk at a time, asks one focused question, and waits; it advances only after a response showing understanding or an explicit request to skip/advance.
- **Adaptive, durable learning:** retrieval practice with varied question types, faded worked examples, teach-back, transfer, and synthesis. Feedback names the correct reasoning, the precise gap, why it matters, and a next hint before rechecking. Confidence is treated as data, never as proof of mastery.
- **Accessible by default:** jargon is explained on first use, diagrams are described in words, meaning never depends on color alone, and coaches offer an alternate representation when a learner is stuck.
- **Rich, self-contained sections:** prompts and flows require inline Mermaid diagrams when useful, embedded runnable labs with expected output and observation notes, source citations kept in the section, and honest separation of observed from expected output. Non-code topics use genuine artifacts rather than decorative code.
- **Editable instruction templates:** shared teaching guidelines, codebase and general source/PDF flows, and custom-flow authoring guidance, exposed as MCP prompts and resources.
- **Clear invalid transitions:** drafts cannot be taught, finished guides cannot be edited, a second process cannot edit a locked draft, duplicate names and malformed IDs are rejected.
- **Durable local storage:** atomic manifest and output writes, exclusive lock creation, validated names/paths, and no database.
## Requirements
- Node.js **20.6 or newer** (developed and verified on Node 24)
- npm 9+ (verified on npm 11)
## Install and build
```bash
npm install
npm run build
npm test
```
Run directly over stdio:
```bash
node dist/index.js
# or, after npm install, with a local link:
npm link
teach-me-mcp
```
The process speaks MCP over stdin/stdout. Diagnostics, when enabled, go to stderr so the protocol stream stays clean.
### Configuration
| Setting | CLI | Environment | Default |
| --- | --- | --- | --- |
| Data directory | `--data-dir <path>` | `TEACH_ME_DATA_DIR` | `~/.teach-me` |
| Flow templates | `--flows-dir <path>` | `TEACH_ME_FLOWS_DIR` | bundled `teaching_flows/` |
| Startup diagnostics | — | `TEACH_ME_DEBUG=1` | off |
Examples:
```bash
node dist/index.js --data-dir ./local-data
TEACH_ME_DATA_DIR=/srv/teaching-guides node dist/index.js
TEACH_ME_FLOWS_DIR=./my-flows node dist/index.js
```
`--help` and `--version` print to stdout and exit without starting the server.
## Client configuration
Use the absolute path to `dist/index.js` in any MCP stdio client. Example (Claude Desktop / generic `mcpServers` configuration):
```json
{
"mcpServers": {
"teach-me": {
"command": "node",
"args": ["/absolute/path/to/teach-me/dist/index.js"],
"env": {
"TEACH_ME_DATA_DIR": "/absolute/path/to/teaching-data"
}
}
}
}
```
If you installed globally or linked the package:
```json
{
"mcpServers": {
"teach-me": {
"command": "teach-me-mcp",
"env": { "TEACH_ME_DATA_DIR": "/absolute/path/to/teaching-data" }
}
}
}
```
After adding the server, restart the client so it can discover tools, prompts, and resources. Clients that do not support MCP prompts can use the same workflow through tools directly; the bundled flow markdown is then available through `teaching-flow://...` resources if resources are supported, or by reading the files in `teaching_flows/`.
## Tools
All tools return human-readable text plus `structuredContent`. Errors are returned as MCP tool errors (`isError: true`) with a stable code such as `INVALID_INPUT`, `INVALID_STATE`, `NOT_FOUND`, `CONFLICT`, or `CORRUPT_DATA`.
### Authoring
| Tool | Arguments | Behavior |
| --- | --- | --- |
| `create_guide` | `name`, optional `project`, `source` | Creates a draft with a unique (case-insensitive) name and acquires its edit lock for this server process. Returns a stable `g_...` guide id. |
| `add_section` | `guide_id`, `title`, `description`, `content` | Appends a section in teaching order (`s_...` id) to a **draft** this process has locked. Description is one short line used in the journey. `content` is the complete lesson: keep diagrams, labs, expected output, observation notes, and citations inside this Markdown rather than in separate files. |
| `select_guide` | `name` | Looks up a guide by name and returns metadata plus the last four sections, each previewed to 600 characters. Selecting a **draft** acquires its edit lock; selecting a finished guide is read-only and lock-free. A live lock owned by another process returns `CONFLICT` with the owner and retry guidance. |
| `look_index` | `guide_id`, optional `section_id` | Returns metadata and the ordered index without content. If `section_id` is supplied, includes that section's full content. Never requires an edit lock. |
| `read_section` | `guide_id`, `section_id` | Returns one full section body and metadata. Never requires an edit lock. |
| `edit_section` | `guide_id`, `section_id`; either `content` **or** `old_string` + `new_string`; optional `title`, `description` | Whole-section replacement or exact substring replacement. `old_string` must be unique and is rejected with no mutation when absent or ambiguous. Draft-only and requires this process to own the draft's edit lock. |
| `finish_guide` | `guide_id` | Validates at least one non-empty section and consistent ordering, marks the guide **finished** (read-only), writes `teaching-guide.md` atomically, and releases the edit lock. |
| `release_guide` | `guide_id` | Explicitly releases this process's edit lock on a draft (for example when switching drafts or handing authoring to another process). Idempotent when no lock is held and refuses to release a lock owned by another process. |
`content` and `old_string`/`new_string` cannot be combined. Empty edits, empty section content, path-like names, control characters, and oversized fields are rejected before writing.
#### Draft edit locks
A draft has at most one editing server process. `create_guide` and `select_guide` acquire a persisted lock (`locks/<guide_id>.lock`) with an atomic exclusive create; `add_section`, `edit_section`, and `finish_guide` verify that the persisted lock is still owned by this process. Reads (`look_index`, `read_section`, `list_guides`, teaching a finished guide) never take a lock.
If another live process owns the draft, selection and mutation fail with `CONFLICT` describing the owning `pid`, owner id, host, and acquisition time, plus how to retry: release the lock there with `release_guide`, finish the guide, or let that process exit. If the owner process crashed, the next `select_guide` detects the dead PID and recovers the lock automatically. Graceful shutdown releases every lock this process holds. Lock files from another host are treated as live because a remote PID cannot be verified safely.
### Teaching
| Tool | Arguments | Behavior |
| --- | --- | --- |
| `list_guides` | optional `status` (`draft` or `finished`) | Summaries sorted by most recently updated. Defaults to all. The response always ends with: “Didn't find the guide you are looking for? Ask the user whether they would like to create one with create_guide.” The coach asks first and waits for the user's answer before authoring. |
| `start_guide` | `guide_id`, optional `section_id` | Requires a **finished** guide. Returns the shared teaching guidelines and the selected/first full section, plus position and next step. |
| `next_section` | `guide_id`, `section_id` (current) | Returns the next full section, or an explicit `completed: true` result with a final coaching instruction. |
Teaching tools are read-only. A draft produces an `INVALID_STATE` error explaining that it must be finished first. A finished guide produces `INVALID_STATE` for authoring edits.
## Example workflow
1. In your MCP client's prompt list, choose the dedicated **`create-guide-codebase`** or **`create-guide-general`** prompt (if the client maps prompts to slash commands, these may appear as `/create-guide-codebase` and `/create-guide-general`). Supply `name`, `project`, and `source`. Alternatively call the generic **`create_guide` prompt** with those arguments and an explicit `flow`. The agent surveys the sources and runs a short intake — outcome/use case, prior knowledge, preferred style, time, and accessibility — one question at a time. It may use one or two lightweight diagnostics, then proposes a cumulative journey and states which parts are optional depth. Whether a prompt is shown as a slash command or a menu item depends on the client.
2. It calls `create_guide`, then `add_section` for each small section in order. Each section states its outcome and prerequisites, builds on the previous idea, embeds its own diagrams, worked example or runnable lab, expected output, observation notes, and citations, and ends with one focused check. No separate code files are created.
3. Review with `look_index`; use `read_section` for full content.
4. Refine with `edit_section`:
- whole replacement: `{ "content": "..." }`
- unique substring: `{ "old_string": "old phrase", "new_string": "new phrase" }`
5. Call `finish_guide` when ready. This writes `teaching-guide.md`, makes the guide immutable, and releases the draft's edit lock.
6. Call the **`teach_me` prompt** with the guide name/id. The coach calls `list_guides` → `start_guide`, orients you to the outcome and roadmap, then teaches one small chunk — one idea, one artifact, the reasoning, one question — and waits. It adapts vocabulary, pace, depth, examples, and feedback to your answers; uses prediction, explanation, application, comparison, and diagnosis; asks for teach-back or transfer before advancing; and calls `next_section` only when you demonstrate understanding or explicitly ask to skip/advance.
7. At the end, `next_section` reports completion instead of inventing another section. The coach synthesizes the journey, asks one confidence question and one transfer question, suggests next steps, and stops.
If more than one MCP server process uses the same data directory, call `release_guide` on a draft before switching editors, or finish it. The other process then acquires the lock with `select_guide`; until then it gets a `CONFLICT` that names the current owner.
A minimal raw tool sequence:
```text
create_guide { "name": "Understanding the scheduler", "project": "my-app" }
add_section { "guide_id": "g_...", "title": "Orient", "description": "Why scheduling matters", "content": "# ..." }
add_section { "guide_id": "g_...", "title": "Main path", "description": "From queue to worker", "content": "# ..." }
finish_guide { "guide_id": "g_..." }
start_guide { "guide_id": "g_..." }
next_section { "guide_id": "g_...", "section_id": "s_..." }
```
## MCP prompts and editable flows
Prompt registration is dynamic. The generic **`create_guide`** and **`teach_me`** prompts are always available. At startup the server enumerates every selectable flow and registers a dedicated `create-guide-<flow>` prompt, so the bundled flows appear as **`create-guide-codebase`** and **`create-guide-general`**. `teaching-guidelines.md` and `custom-flow.md` are documentation, not selectable flows, so they do not get dedicated prompts.
| Prompt | Arguments | Behavior |
| --- | --- | --- |
| `create_guide` | `name`, `project`, `source`, `flow` (all optional) | Generic authoring prompt. Loads the selected flow and shared guidelines. If `flow` is omitted, a project selects `codebase`; otherwise `general` is used. |
| `create-guide-codebase` | `name`, `project`, `source` (all optional) | Dedicated authoring prompt with the `codebase` flow fixed internally. There is no `flow` argument. |
| `create-guide-general` | `name`, `project`, `source` (all optional) | Dedicated authoring prompt with the `general` flow fixed internally. There is no `flow` argument. |
| `create-guide-<flow>` | `name`, `project`, `source` (all optional) | One dedicated prompt per additional selectable `teaching_flows/<flow>.md` file present at server startup. The flow is fixed internally. |
| `teach_me` | `guide`, `section` (optional) | Coaching prompt for a **finished** guide. |
All authoring prompts give the agent the same operating protocol: inspect the sources, run a short one-question-at-a-time intake, calibrate with one or two lightweight diagnostics, propose a cumulative journey with prerequisites and optional depth, then use `create_guide`/`add_section`. They inject the section content contract and quality checklist: one observable outcome per section, a mental-model-to-transfer arc, inline Mermaid when useful, embedded labs with expected output and observation notes, precise local citations, no external code files, accessible explanations, and no unverified run claims. The only difference is which flow is loaded; the dedicated prompts simply fix it so you do not have to choose one. `teach_me` loads the teaching guidelines and gives the coach an explicit session protocol: resolve a finished guide, call `start_guide` once (supporting a requested section start), orient, then teach in short chunks using one idea, one artifact, the reasoning, one focused question, and a stop. It preserves and explains the section's diagrams and labs, asks for prediction before execution when useful, distinguishes observed from expected output, never claims an unperformed run, adapts feedback and representation, uses varied retrieval and transfer, honors skip/advance requests, and calls `next_section` only after a learner response showing understanding or an explicit request.
### Using an authoring prompt
MCP clients that support prompts discover these names through the protocol's prompt list and expose them in their own UI. Pick **`create-guide-codebase`** or **`create-guide-general`** from that list and supply the guide `name` (plus optional `project` and `source`). If your client maps MCP prompts to slash commands, the same prompt can be started by typing its name, for example `/create-guide-codebase` or `/create-guide-general`. The slash form is a client-side convenience: this server only advertises standard MCP prompts, and slash-command presentation — including in ChatGPT — is not guaranteed by the server and depends on the client's MCP prompt support.
Use the generic **`create_guide`** prompt when you want to pass `flow` explicitly or load a custom flow that has no dedicated prompt yet.
Each Markdown file in the flows directory is also exposed as a resource:
```text
teaching-flow://teaching-guidelines
teaching-flow://codebase
teaching-flow://general
teaching-flow://custom-flow
teaching-flow://<your-flow>
```
### Bundled templates
- `teaching_flows/teaching-guidelines.md` — shared coaching behavior copied into every generated guide. Defines learner intake and calibration, cumulative journey design, the section content contract, when to use or omit Mermaid and labs, observed-vs-expected output honesty, non-code artifacts, accessibility, citation formats, the dialogic chunk-and-wait teaching turn, feedback and retrieval practice, teach-back and transfer, learner skip/advance agency, and authoring/teaching quality gates.
- `teaching_flows/codebase.md` — designs for the learner's outcome, privately scratchpads repository analysis, then surveys architecture, dependency direction, data flow, packages, folder relationships, and key files/functions top-down. Requires labeled Mermaid maps with prose descriptions, compact executable labs for important paths/functions/tests, exact run instructions, output interpretation, a guided-to-independent arc, and one variation exercise. No sidecar files; scratchpads are not evidence; optional deep dives are marked.
- `teaching_flows/general.md` — surveys all sources, states contradictions honestly, scratchpads observations and a proposed workflow, explains top-down / bottom-up / spiral / problem-first with concrete examples, and asks the learner's preference before drafting. Chooses source-appropriate artifacts (argument maps, timelines, process diagrams, data traces, worked examples) and uses executable labs only when they genuinely help, with the same output/observation contract. Requires page/section/document citations, accessibility, transfer, and synthesis.
- `teaching_flows/custom-flow.md` — documentation for adding your own flow. Specifies the required audience/outcomes, intake/diagnosis, source treatment, artifact standards, section sequence with rationale, citation/verification, adaptation/accessibility, teaching handoff, and checklist sections, and explains that custom flows inherit the shared guidelines.
### Customize
Create `teaching_flows/<name>.md` with a `# Title`, a one-line description, and your instructions. A selectable custom flow that exists **before server startup** gets its own `create-guide-<name>` prompt (for example `create-guide-systems-thinking`) and a `teaching-flow://<name>` resource. Use `TEACH_ME_FLOWS_DIR` or `--flows-dir` to keep custom flows outside the package. Prompt names and the **resource list** are enumerated at startup, so restart the server after adding a flow to expose its dedicated prompt and resource. Until you restart, the generic `create_guide` prompt can still select the new flow with `flow: "<name>"` because flow files are read on demand; edits to existing flow files are likewise picked up without a restart. The directory must contain `teaching-guidelines.md`. `custom-flow.md` is documentation and cannot be selected as a flow, and `teaching-guidelines.md` is shared guidance rather than a selectable flow; neither gets a dedicated prompt.
Edits to guidelines affect newly finished guides and future teaching sessions; already-generated `teaching-guide.md` files keep their snapshot.
## Section content contract
Every `add_section` body is a self-contained mini-lesson. The prompts and editable flows require authors to follow this contract, and the coaching prompt requires teachers to use the embedded material rather than replace it:
- **One artifact.** The section Markdown is the lesson. Never create separate code files, scripts, fixtures, or attachments. Code lives in fenced blocks inside the section.
- **One outcome and a cumulative arc.** State the question, observable outcome, and prerequisites in the first paragraph. Build from mental model to mechanism to worked example to guided practice to independent transfer and a short synthesis, linking back instead of repeating. Mark optional depth.
- **Diagrams when useful.** Use valid fenced Mermaid for dependency direction, sequence, state, classes, entities, or chronology. Label nodes, participants, and arrows; state the arrow convention; describe the meaning in words. Do not force a diagram into every section.
- **Embedded lab for code topics.** Include purpose, prerequisites, exact run instructions and working directory, the code, expected output, observation notes, one variation, and one prediction/application question. Keep it small, safe, reproducible, and relevant. Do not include an answer key.
- **Honest verification.** If the agent actually ran the lab in an appropriate environment, label captured output **Observed output** and compare it with **Expected output**. If it could not run, it must write "Not executed in this session" and must not claim verification.
- **Real artifacts for non-code topics.** Use a worked example, argument map, data trace, timeline, process diagram, comparison matrix, or close reading instead of artificial code.
- **Precise citations in the section.** Repository path plus symbol/line, PDF page and section, URL with access date, or the supplied reference label. Never invent a source location; surface contradictions and uncertainty.
- **Accessibility.** Expand jargon on first use, describe visuals in words, never rely on color alone, and offer an equivalent table or trace when useful.
- **One understanding check.** End with a single prediction, explanation, application, discrimination, or debugging question — not recall alone and not a battery of questions.
Author checklist:
- [ ] The section is teachable from its Markdown alone.
- [ ] The outcome, prerequisites, and connection to the previous section are explicit.
- [ ] Mermaid and code fences are present, closed, labeled, accurate, and described in words.
- [ ] The lab has all eight parts, includes no answer key, and creates no files.
- [ ] Expected and observed output are clearly distinguished; unrun code is labeled.
- [ ] Non-code sections use a genuine artifact rather than decorative code.
- [ ] Citations are local to the claim, verifiable, and honest about contradictions.
- [ ] Optional depth is marked and the section does not repeat earlier material.
- [ ] Jargon is explained and the section is accessible without relying on color.
- [ ] The ending is one question requiring reasoning or transfer.
A section can combine a small diagram with a compact lab. For example:
> **Question:** How does a failed lookup move through the layers?
>
> An arrow means "calls". This map is grounded in `src/service.ts` and `src/store.ts`.
```mermaid
flowchart LR
UI["UI"] -->|"requests"| SVC["Service"]
SVC -->|"looks up"| STORE["Store"]
STORE -->|"miss"| ERR["NotFound error"]
SVC -->|"maps to response"| UI
```
**Try it — see what a missing key returns**
**Purpose:** observe that a store miss is reported as a typed error rather than `undefined`.
**Prerequisites:** Node.js 20+; run from the repository root; this creates no files.
```js
const store = new Map([["a", 1]]);
function get(key) {
if (!store.has(key)) throw new Error("NOT_FOUND");
return store.get(key);
}
try {
console.log(get("b"));
} catch (error) {
console.log(error.message);
}
```
Run it:
```bash
node -e 'const store=new Map([["a",1]]); const get=(k)=>{if(!store.has(k)) throw new Error("NOT_FOUND"); return store.get(k)}; try{console.log(get("b"))}catch(e){console.log(e.message)}'
```
**Expected output:**
```text
NOT_FOUND
```
**What to notice:** `get("b")` throws before returning a value; the message names the failure; the `catch` turns control flow into observable output.
**Experiment:** call `get("a")` and predict whether the `catch` block runs. **Question:** why is a typed error safer here than returning `undefined`?
When the guide is finished, `teaching-guide.md` contains this section body exactly as authored — the Mermaid fence, code fence, expected output, observations, and citations are copied into the portable artifact. The agent must not create external files to make the example work.
## Storage layout
```text
$TEACH_ME_DATA_DIR/
├── guides/
│ └── g_0123456789ab/
│ ├── guide.json # manifest: metadata, state, ordered section index
│ ├── sections/
│ │ ├── 0001-s_0123456789ab.md # section body (Markdown)
│ │ └── 0002-s_fedcba987654.md
│ └── teaching-guide.md # portable output, created by finish_guide
└── locks/
└── g_0123456789ab.lock # exclusive draft edit lock (owner id, pid, host)
```
The manifest is the source of truth for state and order. Section bodies are separate Markdown files for easy inspection and diffing. Writes go to a temporary file in the same directory, are flushed, then renamed into place; the containing directory is synced on a best-effort basis. Mutations are serialized in-process, and draft edit locks coordinate separate server processes sharing the data directory. Paths and IDs are validated so a name or id cannot escape the data directory.
Lock files are created atomically with exclusive semantics and contain the owner's server-instance id, OS pid, hostname, and acquisition time. They are removed on `finish_guide`, `release_guide`, and graceful shutdown. A lock whose pid no longer exists on the same host is considered stale and is recovered on the next selection; an unreadable lock left by a crash is recovered after a short grace period. Never delete a lock file manually while its owner is still editing.
Back up or version-control the data directory normally. Finished guides are intentionally immutable; create a new guide to revise material.
## Testing
```bash
npm test
```
This builds the project, then runs the test files:
- `test/guides.test.ts` — ordered authoring, preview truncation, unique-substring and whole-section edits, invalid transitions, validation, generated output content, and persistence across a fresh store. It also covers draft edit locks: created-draft locking, cross-instance selection/mutation conflicts, explicit release and handoff, finish release, persisted-lock verification, stale crashed-process recovery, abandoned incomplete lock recovery, and graceful shutdown/restart.
- `test/content-contract.test.ts` — checks that the shared guidelines, codebase/general/custom flows, and authoring/teaching prompts require adaptive intake and diagnostics, one-question-at-a-time dialogue, short chunks and waiting, cumulative journeys with optional depth, specific feedback, retrieval and transfer, teach-back, synthesis, accessibility, learner agency and skip/advance overrides, source honesty, precise local citations, embedded labs with expected/observed output, no external code files, and explicit tool-order constraints. It also verifies that Mermaid and code fences survive into `teaching-guide.md`.
- `test/protocol.test.ts` — **real MCP stdio client/server smoke tests**: discovery of 11 tools, the generic and per-flow prompts, and flow resources; create/add/select/look_index/edit/finish/list/start/next/release; draft rejection; generated Markdown; completion semantics; lock file creation/release; and a full process restart against the same data directory. It verifies that `create_guide` and `teach_me` remain available, that `create-guide-codebase` and `create-guide-general` are registered without a `flow` argument and load their fixed flow's instructions, and that the generic `create_guide` still accepts `flow`. A custom-flow test starts the server against a flows directory containing an extra selectable Markdown flow and checks its dedicated prompt, while documentation-only flows are excluded. It also asserts that the served create/teach prompts and flow resources carry the rich-content and dialogic teaching contract. A further test runs two server processes on one data directory and verifies `CONFLICT` ownership messages, cross-process reads, explicit lock handoff, and lock release on finish.
## Limitations
- **Local stdio only.** There is no HTTP transport, authentication, or multi-user access control. Any number of processes may read the same data directory, but each draft has a single editor enforced by a persisted lock. Locks are verified by PID on the local host; a lock from another host (for example a shared network directory) is treated as live because a remote PID cannot be checked safely.
- **No source ingestion.** PDFs, websites, repositories, and books are read by the agent/client using its own tools. This server stores the authored guide; it does not extract text, OCR, embed, or search sources.
- **No editing finished guides.** This is deliberate. Authors can create a new guide (or manually copy the storage directory) to revise.
- **No section reordering or deletion.** Sections append in order; use `edit_section` to change content. To reorganize, create a new guide.
- **Bounded previews.** `select_guide` previews the last four sections at 600 characters each. Use `read_section` for full content.
- **Local files are trusted.** Hand-editing manifests or lock files can corrupt a guide or strand a lock; malformed JSON/schema data is reported as `CORRUPT_DATA`, and an old unreadable lock is recovered automatically. Never delete a lock manually while its owner is editing.
- **No full-text search or tags.** Use names, metadata, and `list_guides`.
- **Single-line titles/descriptions.** Newlines and control characters are rejected in names, titles, descriptions, and metadata because they are rendered as Markdown headings/lines.
- **Size cap.** A single section body is limited to 2,000,000 characters.
- **Prompts are guidance, not enforcement.** The agent is instructed to follow the section content contract and teaching guidelines; the server enforces storage, locking, and state transitions, but cannot force a model to cite sources, run a lab honestly, or ask good questions. Always check embedded claims and output before trusting them.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
TDQS
Scored across 11 tools
Most tools target clearly different lifecycle stages: discovery, draft authoring, section editing, finishing, locking, and teaching. The main overlap is among retrieval tools (list_guides, select_guide, look_index, read_section), where the agent must choose based on summary vs metadata/index vs full content and lock behavior; descriptions clarify but still add some cognitive load.
All names use snake_case and are mostly action_resource pairs such as create_guide, add_section, read_section, and finish_guide. next_section and look_index are slightly less predictable as verb_noun names, but the convention is still largely consistent.
The 11 tools are well-scoped for a guide authoring and teaching workflow, with separate tools for listing, selecting, authoring, editing, finishing, locking, and teaching. Each tool appears to earn its place without obvious redundant bloat.
The surface covers discovery, draft creation, section authoring/editing, finishing, lock release, and teaching progression. Notable gaps include deleting/removing or reordering sections, deleting guides, and updating guide-level metadata after creation, but the core workflow is covered.