educational-tools
# Birkan Educational Tools Agent
Zero-auth, read-only **MCP server + A2A agent** by Birkan Yavuz: a catalog of 24 real
classroom activities (math visualizers, reading and Sight Words modules, Spanish
syllables, art) for Kindergarten–Grade 9, 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). 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.
## Repo layout
- `api/index.py` — the deployed server (Vercel serverless)
- `public_server.py` — the same server for standalone hosting
- `catalog.json` — the 24-tool catalog
- `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
Scored across 4 tools
Each tool has a clearly distinct purpose: fetching curriculum word data, retrieving a single classroom tool by id, listing the full catalog, and searching the catalog with filters. The descriptions explicitly cross-reference when to use an alternative tool, making misselection unlikely.
All four names follow a consistent snake_case verb_noun pattern: get_curriculum_dataset, get_classroom_tool, list_classroom_tools, search_classroom_tools. The verbs accurately reflect read-only retrieval and browsing operations.
Four tools are well-scoped for a read-only educational catalog and dataset server. Each tool earns its place by covering a distinct access pattern: full list, filtered search, single-item lookup, and dataset retrieval.
The surface covers the core read-only workflows for browsing and retrieving classroom tools and curriculum datasets. A minor gap is the lack of a dedicated dataset-listing or metadata operation to discover valid dataset_id values and their level/family boundaries without trial and error.