teach-me-ai
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| TEACH_ME_DEBUG | No | Set to 1 to enable startup diagnostics. Diagnostics go to stderr. Off by default. | |
| TEACH_ME_DATA_DIR | No | Data directory for guides and locks. Defaults to ~/.teach-me. Can also be set with --data-dir <path>. | |
| TEACH_ME_FLOWS_DIR | No | Directory containing custom flow templates. Defaults to the bundled teaching_flows/ directory. Can also be set with --flows-dir <path>. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
teach-me stores durable teaching guides as local JSON and Markdown files.
Authoring state machine:
create_guide (draft, locked for this process) -> add_section in order (repeat) -> edit_section as needed -> finish_guide.
select_guide resumes a draft by name and acquires its edit lock; look_index/read_section inspect content without taking a lock.
Drafts are editable but cannot be taught. finish_guide is read-only and writes portable teaching-guide.md.
Edit locks:
A draft has at most one editing server process. create_guide and select_guide acquire a persisted lock; add_section, edit_section, and finish_guide require this process to own it.
A second process selecting or mutating the same draft gets CONFLICT with the owning pid/owner and retry guidance. Reads remain available.
finish_guide releases the lock automatically. Call release_guide when switching a draft to another process.
Locks from crashed processes are detected by pid and recovered automatically on the next selection; graceful shutdown releases held locks.
Teaching state machine:
list_guides -> start_guide on a finished guide -> teach one small chunk -> next_section -> explicit completion.
Use the selected section id with next_section. Never skip states or teach a draft.
Every guide id and section id is stable across restarts. Data is stored in the configured data directory; no database is used.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| create_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. |
| add_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). |
| select_guideA | 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. |
| look_indexA | 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. |
| read_sectionA | Return the full stored Markdown content of one section, with guide and section metadata. Works for drafts and finished guides. |
| edit_sectionA | 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. |
| finish_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. |
| release_guideA | 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. |
| list_guidesA | 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. |
| start_guideA | 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. |
| next_sectionA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| create_guide | Start an adaptive authoring session using an editable teaching flow. Surveys the sources, assesses the learner, chooses a learning shape, and drives create_guide/add_section/finish_guide. |
| create-guide-codebase | Start an adaptive authoring session using the "codebase" teaching flow (Codebase learning flow). Surveys the sources, assesses the learner, chooses a learning shape, and drives create_guide/add_section/finish_guide. |
| create-guide-general | Start an adaptive authoring session using the "general" teaching flow (General source learning flow). Surveys the sources, assesses the learner, chooses a learning shape, and drives create_guide/add_section/finish_guide. |
| teach_me | Start a coaching session from a finished guide. Loads the shared teaching guidelines, resolves the guide, and drives start_guide/next_section with small chunks and understanding checks. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| teaching-flow-codebase | Use this flow when the guide's source is a software repository, a project folder, a library, or a code-heavy system. The goal is a learner who can navigate the codebase, explain its architecture, make a safe change, and verify that change with evidence. |
| teaching-flow-custom-flow | A teaching flow is an editable Markdown instruction template that shapes how an agent analyzes sources and drafts a guide. Built-in flows are `codebase.md` and `general.md`. `teaching-guidelines.md` is shared coaching guidance used for every flow and copied into generated guides. |
| teaching-flow-general | Use this flow for books, papers, PDFs, documentation sets, courses, notes, specifications, or a mix of sources that is not primarily a codebase. The goal is durable understanding, not a summary. |
| teaching-flow-teaching-guidelines | These guidelines apply to every teaching session, regardless of subject or flow. They are also copied into each generated `teaching-guide.md` so the guide remains useful outside this MCP server. |
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.