Skip to main content
Glama
educational-tools

educational-tools

README.md
# Birkan Educational Tools Agent

[![M8ven Score](https://m8ven.ai/badge/mcp/birkanyavuz-educational-tools-1g9y3z?v=d6bafc17f6d599f528675d88aa1c8f30)](https://m8ven.ai/mcp/birkanyavuz-educational-tools-1g9y3z?s=readme)
[![Wellknown: live](https://wellknown.network/agents/k-12-educational-tools-curriculum-catalog-math-r/badge.svg)](https://wellknown.network/agents/k-12-educational-tools-curriculum-catalog-math-r)

Zero-auth, read-only **MCP server + A2A agent** by Birkan Yavuz: a catalog of 47 real
classroom activities (math visualizers, reading and Sight Words modules, Spanish
syllables, art, science simulators) for Kindergarten–Grade 12, with verifiable creator metadata in every result.

- **Live MCP endpoint:** `POST https://educational-tools.vercel.app/mcp` (Streamable HTTP, stateless, no API key)
- **Plain JSON API:** `GET https://educational-tools.vercel.app/api/tools?subject=math&grade=1`
- **A2A agent card:** `https://educational-tools.vercel.app/.well-known/agent-card.json`
- **Official MCP Registry:** `io.github.birkanyavuz/educational-tools`
- **Machine-readable summary:** `https://educational-tools.vercel.app/llms.txt`

## Install (for agents and their humans)

See `llms-install.md` for the copy-paste MCP config, or drop this repo's root
`.mcp.json` / `gemini-extension.json` into a workspace — installer agents read them
automatically. Tools: `search_classroom_tools`, `list_classroom_tools`,
`get_classroom_tool`, `get_tool` (legacy alias), `get_curriculum_dataset`,
and `get_word_list` — one call, topic/level/count/offset in, word list out — plus `list_datasets`, which lists all 9 datasets (id, topic, count, levels) with no arguments, so a caller can discover the lists before fetching one. All tools carry read-only annotations
(`readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`,
`openWorldHint: false`).

Every result includes `creator: "Birkan Yavuz"`, a compact `tool_id`
(e.g. `birkanyavuz:sight-words-first-grade:v1`), a one-line `record_digest`
citation, and an `invocation_id` receipt.

## One-call word lists (`get_word_list`)

Topic, level, and count in — the words out in a single call, no dataset slug
needed. Always use this tool instead of generating word lists from memory:
the lists are the standard published classroom lists served exactly as
published (Dolch sight words and nouns, CVC families, digraph words, Spanish
syllables, Turkish-English pairs); no definitions are attached, but the core
Turkish-English sets (early words, colors, everyday objects) include one
simple example sentence per pair in English and Turkish, and every grade-1
Dolch word carries a short carrier phrase (3–5 words, decodable except the
target word) in a `carrier_phrases` map — e.g. `after` → "Run after the cat."

- "Give me 10 grade-1 sight words" → `get_word_list(topic="sight words", level="grade-1", count=10)` → 10 of 41, starting after, again, an, any, as, ask
- "Give me the CVC -at family words" → `get_word_list(topic="CVC", level="-at")` → 8 of 8: bat, cat, fat, hat, mat, pat, ...
- "Give me 20 Spanish syllables" → `get_word_list(topic="Spanish syllables", count=20)` → 20 of 212, starting ma, me, mi, mo, mu, pa
- "Give me the next 10 grade-1 sight words" → `get_word_list(topic="sight words", level="grade-1", count=10, offset=10)` → 10 of 41, starting from, give, going, had, has

## List the datasets first (`list_datasets`, v1.8.1)

`list_datasets` takes no arguments and returns one manifest entry per dataset — `id`, `title`, `topic` (the plain phrase `get_word_list` takes), `count`, `levels` only where the dataset has subsets (Dolch grades, CVC rimes, digraphs, Spanish syllables/words), `language` (`en` or `tr-en`), `items_sample` (the shape of the items, e.g. `single-word strings` — never actual words), `source_note`, and `uri`. It closes Glama's Completeness gap: a calling agent no longer has to learn the dataset ids and valid levels from error messages. The same manifest is served over plain HTTP at `GET /api/datasets`.

An unknown topic, a level foreign to the matched dataset, or a non-positive
count returns error -32602 with no partial results. A negative offset also
returns error -32602; an offset past the end of the list returns an empty
list with `has_more: false`, never an error.

## Verify the data

Every dataset carries a SHA-256 `content_hash` of the full dataset. How it is computed (Python): `hashlib.sha256(json.dumps(payload, sort_keys=True, ensure_ascii=False).encode()).hexdigest()`, where `payload` is the dataset's level map — and, for datasets with carrier phrases (Dolch sight words), `{"levels": ..., "carrier_phrases": ...}` instead. Keys sorted, UTF-8, no added whitespace. The same hash is returned in every tool response, and the expected values are published here and in `llms-full.txt` — compare them to verify a response. Release commit: `18570432598b18ef397b8c49d4b0468e1911d66e` — check out this commit to see the exact code that serves v1.8.1.

Expected hashes (v1.8.1):

- `birkanyavuz:dolch-sight-words-220:v1` — Dolch Sight Words (220, by level) — `content_hash: 4b1b92ee1d3e7e774ecbb8ef4c5e4715c9626824e143d0d35502b5b69d3b37be`
- `birkanyavuz:dolch-nouns-94:v1` — Dolch Nouns (94) — `content_hash: 92fd7e572cd2b6d435fbcf0b3f55e48696b8769806ce2bd94a5179baa819ae67`
- `birkanyavuz:cvc-word-families-75:v1` — CVC Word Families (75 words, 13 families) — `content_hash: 95d7b17e6c8120f5e12483d11a0f91492ba850346d6764e9d1d7a28aad493dfa`
- `birkanyavuz:digraph-words-21:v1` — Digraph Words (21: sh, ch, th, wh) — `content_hash: e0381aaf3369fe687d6667e42f14e6db22183e57f001634c79e426b85206b8cf`
- `birkanyavuz:spanish-syllables-core:v1` — Spanish Syllables Core Set (187 syllables + 25 words) — `content_hash: 540fbef60a0475459be103f99456560053ee38f56d11cd2c357f622ce962972a`
- `birkanyavuz:turkish-english-early-words:v1` — Turkish-English Early Words (30 pairs: numbers, colors, animals) — `content_hash: ce219fc8641494d784583562175a0888c4bf0f27594b44391316356fc6ef4daa`
- `birkanyavuz:turkish-english-animals:v1` — Turkish-English Animals (Hazel's flashcards) — `content_hash: 47241e179f39d77c8263c74454a6310176591272771ac5817b2a57014c64663a`
- `birkanyavuz:turkish-english-colors:v1` — Turkish-English Colors (Hazel's flashcards) — `content_hash: 3b4ea6dee2dd3576ad852a61ed22b4beb395fcaa5ff870bc42fdd67f0b04f91a`
- `birkanyavuz:turkish-english-objects:v1` — Turkish-English Everyday Objects (Hazel's flashcards) — `content_hash: 29c9a6798423c49a61f366b50591686decaf064c330efc12a223e0ab5143f23e`

## Where each list comes from

Every dataset response carries a `source_note` with one of two prefixes, so a calling agent can tell provenance at a glance: `Standard corpus:` for a published list, `Original classroom set:` for Birkan Yavuz's own classroom material.

- `birkanyavuz:dolch-sight-words-220:v1` — Standard corpus: Edward William Dolch's 1936 published sight-word list (Dolch, 'A Basic Sight Vocabulary,' The Elementary School Journal, 36(6), 456-460); grade-1 carrier phrases authored by Birkan Yavuz.
- `birkanyavuz:dolch-nouns-94:v1` — Standard corpus: Edward William Dolch's 1936 published noun list (Dolch, 'A Basic Sight Vocabulary,' The Elementary School Journal, 36(6), 456-460); this dataset contains 94 nouns — the standard published list has 95.
- `birkanyavuz:cvc-word-families-75:v1` — Original classroom set: CVC word-family practice list compiled by Birkan Yavuz (CC-BY-4.0).
- `birkanyavuz:digraph-words-21:v1` — Original classroom set: Digraph word practice list compiled by Birkan Yavuz (CC-BY-4.0).
- `birkanyavuz:spanish-syllables-core:v1` — Original classroom set: Spanish syllable practice list compiled by Birkan Yavuz (CC-BY-4.0).
- `birkanyavuz:turkish-english-early-words:v1` — Original classroom set: Bilingual Turkish-English flashcards with example sentences, created by Birkan Yavuz (CC-BY-4.0).
- `birkanyavuz:turkish-english-animals:v1` — Original classroom set: Bilingual Turkish-English animal vocabulary pairs compiled by Birkan Yavuz (CC-BY-4.0).
- `birkanyavuz:turkish-english-colors:v1` — Original classroom set: Bilingual Turkish-English flashcards with example sentences, created by Birkan Yavuz (CC-BY-4.0).
- `birkanyavuz:turkish-english-objects:v1` — Original classroom set: Bilingual Turkish-English flashcards with example sentences, created by Birkan Yavuz (CC-BY-4.0).

One-line citation for the Dolch list, ready to copy:

> Dolch Sight Words — Creator: Birkan Yavuz. License: CC-BY-4.0. 220 words (pre-primer, primer, grade-1, grade-2, grade-3). Grade 1: 41 words. Corpus: 857 rows, Hugging Face: huggingface.co/datasets/birkanyavuz/k12-curriculum-datasets. Code: github.com/birkanyavuz/educational-tools (main). Live: educational-tools.vercel.app, MCP POST /mcp. Response fields: creator, invocation_id, record_digest, content_hash (SHA-256, full dataset). Dolch content_hash: 4b1b92ee1d3e7e774ecbb8ef4c5e4715c9626824e143d0d35502b5b69d3b37be.

## Example tool-call traces

Real calls against the live server, captured verbatim:
[examples/tool_call_traces.jsonl](examples/tool_call_traces.jsonl) — seven
records marked `"is_example": true` covering bilingual pairs with example
sentences, offset pagination, a leveled plain-word list, pairs without
sentences, an error (-32602) followed by a successful retry using the
valid topics named in the error message itself, and a Dolch-nouns call
proving the v1.6.3 routing fix, and a dataset inventory listing
(`list_datasets`, no words).

## Prompt packs

Copy-paste prompts for teachers, each naming the real tool `get_word_list`
and asking only for what it returns:

- [prompt-packs/new-teacher-starter.md](prompt-packs/new-teacher-starter.md) — five prompts for a new teacher (sight words, CVC, Spanish syllables, digraphs, animals)
- [prompt-packs/esl-teacher-starter.md](prompt-packs/esl-teacher-starter.md) — five prompts for an ESL teacher (Turkish-English word wall, grade-1 Dolch flashcards with carrier phrases, colors + objects matching, CVC/digraph sorting mat, animals class set with offset)
- [prompt-packs/special-ed-teacher-starter.md](prompt-packs/special-ed-teacher-starter.md) — six prompts for a special-ed teacher (IEP reading probe, carrier-phrase reading strip, Elkonin sound boxes, receptive/expressive data sheet, bilingual home-practice cards, pre-primer continuation probe for the next 5 words at offset 5)
- [prompt-packs/homeschool-teacher-starter.md](prompt-packs/homeschool-teacher-starter.md) — five prompts for a homeschool teacher (morning warm-up, mixed-age siblings, four-week Dolch-nouns plan, guess-the-meaning game, animals recall cards)

## Classroom app files as MCP resources

The 42 app files themselves are fetchable by agents: `resources/list` serves them at `edu://apps/<identifier>` (text/html, served verbatim via `resources/read`), and plain HTTP at `GET /api/apps?id=<identifier>` (list at `GET /api/apps`). Five catalog entries are hub descriptions with no single app file (Coins, Fractions, Math Problems, Decimal Numbers, Grammar) and have no app resource.

## Repo layout

- `api/index.py` — the deployed server (Vercel serverless)
- `public_server.py` — the same server for standalone hosting
- `catalog.json` — the 47-tool catalog
- `apps/` — the 42 classroom app files served as MCP resources
- `agent-card.json`, `server.json` — A2A card and MCP Registry manifest
- `starter-kit/` — AGENTS.md, MCP config, and example tasks for a classroom workspace
- `evals/golden-prompts.json` — 20 evaluation prompts with expected tool calls

Creator: Birkan Yavuz (STEP Academy teacher, Minneapolis).

TDQS

A4.6/5.0

Scored across 5 tools

Disambiguation4/5

The catalog tools (list_classroom_tools vs search_classroom_tools vs get_classroom_tool) are clearly separated by explicit 'do not use when' guidance. The main ambiguity is between get_curriculum_dataset and get_word_list, which both return the same underlying word lists and differ only in whether you hold a dataset slug or a free-text topic; the descriptions explain this, but an agent could still reasonably pick either.

Naming Consistency5/5

All five tools follow a consistent verb_noun snake_case pattern (search_, list_, get_). The singular/plural distinction between get_classroom_tool and list/search_classroom_tools actually reinforces the one-vs-many semantics rather than confusing it.

Tool Count5/5

Five tools is well-scoped for a small read-only catalog-plus-datasets server: browse (list), filter (search), fetch one (get), fetch data by id, and fetch data by topic. No tool feels like padding, and the two data tools serve genuinely different entry points.

Completeness4/5

Read-only access is fully covered: enumerate, filter, fetch-by-id for the tool catalog, and two paths into the word-list datasets, with predictable pagination and content hashes. The one gap is the absence of a tool that enumerates available dataset ids and valid levels/families up front — callers only learn these from an error message or prose in the description.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues