Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
TEACH_ME_DEBUGNoSet to 1 to enable startup diagnostics. Diagnostics go to stderr. Off by default.
TEACH_ME_DATA_DIRNoData directory for guides and locks. Defaults to ~/.teach-me. Can also be set with --data-dir <path>.
TEACH_ME_FLOWS_DIRNoDirectory 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:

  1. create_guide (draft, locked for this process) -> add_section in order (repeat) -> edit_section as needed -> finish_guide.

  2. select_guide resumes a draft by name and acquires its edit lock; look_index/read_section inspect content without taking a lock.

  3. 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:

  1. list_guides -> start_guide on a finished guide -> teach one small chunk -> next_section -> explicit completion.

  2. 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

CapabilityDetails
tools
{
  "listChanged": true
}
prompts
{
  "listChanged": true
}
resources
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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

NameDescription
create_guideStart 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-codebaseStart 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-generalStart 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_meStart 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

NameDescription
teaching-flow-codebaseUse 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-flowA 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-generalUse 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-guidelinesThese 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

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