Skip to main content
Glama

teach-me-ai MCP

A local-first Model Context Protocol 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.

Related MCP server: devcoach

Requirements

  • Node.js 20.6 or newer (developed and verified on Node 24)

  • npm 9+ (verified on npm 11)

Install and build

npm install
npm run build
npm test

Run directly over stdio:

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:

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):

{
  "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:

{
  "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:

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:

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.

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.

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:

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:

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

$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

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 file for details.

Available Tools

11 tools
add_sectionAdd guide sectionA

Append a section to a draft guide in teaching order. Requires title, a short one-line description, and Markdown content. Draft-only; this server process must hold the draft's edit lock (acquired by create_guide or select_guide).

Inputs: title (required), content (required), guide_id (required), description (required).

create_guideCreate teaching guideA

Create a new draft teaching guide with a unique name and optional project/source metadata, and acquire its exclusive edit lock for this server process. Returns a stable guide_id. Next: add sections in teaching order with add_section.

Inputs: name (required), source, project.

edit_sectionEdit sectionA
Destructive

Edit a draft section by whole-section replacement (content) or exact substring replacement (old_string + new_string; old_string must occur exactly once). Optionally update title/description. Draft-only; this server process must hold the draft's edit lock.

Inputs: guide_id (required), section_id (required), title, content, +3 more.

finish_guideFinish guideA

Validate a draft guide, mark it finished (read-only), and generate a portable teaching-guide.md containing teaching guidelines, the ordered contents journey, and all section content. Requires this server process to hold the draft's edit lock and releases that lock on success. Invalid for empty guides or guides already finished.

Inputs: guide_id (required).

list_guidesList guidesA
Read-only

List guide summaries sorted by most recently updated, optionally filtered to drafts or finished guides. Always include the invitation to ask whether the user wants to create a missing guide with create_guide.

Inputs: status.

look_indexInspect guide indexA
Read-only

Return guide metadata and the ordered section index (no content), or include one full section by passing section_id. Works for drafts and finished guides.

Inputs: guide_id (required), section_id.

next_sectionAdvance to next sectionA
Read-only

Given the current section id in a finished guide, return the next section or an explicit completion result at the end. Advance only on learner request or demonstrated understanding.

Inputs: guide_id (required), section_id (required).

read_sectionRead section contentA
Read-only

Return the full stored Markdown content of one section, with guide and section metadata. Works for drafts and finished guides.

Inputs: guide_id (required), section_id (required).

release_guideRelease draft edit lockA
Idempotent

Explicitly release this server process's edit lock on a draft, for example when switching to another draft or handing authoring to another teach-me process. Idempotent when no lock is held; refuses to release a lock owned by another process. Finished guides do not need a lock.

Inputs: guide_id (required).

select_guideResume draft by nameA
Idempotent

Look up a guide by name and return metadata plus the last four sections with truncated content. Selecting a draft acquires its exclusive edit lock for this server process and reports a conflict with the current owner if another process holds it. Finished guides are inspected read-only without a lock.

Inputs: name (required).

start_guideStart teaching a guideA
Read-only

Begin a teaching session on a finished guide. Returns the teaching guidelines and the selected section (or the first section). Optionally choose a section_id to resume. Drafts cannot be taught.

Inputs: guide_id (required), section_id.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI-assisted learning through structured courses with Socratic guidance, evaluating user answers against rubrics and managing learning progress locally.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables local, progressive technical coaching inside MCP-compatible AI agents, delivering short targeted lessons calibrated to the user's knowledge after each completed task while storing everything in a local SQLite file.
      1,395 npm
      5
      AGPL 3.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables an active learning tutor that runs in MCP clients like Codex or Claude Code, letting the AI create and manage lessons, read student attempts, and give feedback while the student practices in a local browser panel.
      -