Tools for building AI applications on the Oak National Academy Open Curriculum, using a generated, type-safe TypeScript SDK and Model Context Protocol (MCP) servers, and semantic search over the curriculum data powered by Elasticsearch Serverless.

Strategic Overview: For the vision, delivery roadmap, and engineering approach, see the Strategic Overview.

Current status: Invite-Only Alpha (M1 complete) — The server is live at curriculum-mcp-alpha.oaknational.dev. Open public alpha (M2) is next. See the high-level plan for milestone detail.

This repository is how Oak makes its openly-licensed, fully sequenced, and fully resourced curriculum available to AI systems and the wider education technology community, via SDKs, MCP servers, and semantic search. AI assistants like Claude, ChatGPT, and Gemini can search Oak's curriculum, explore lessons, units, threads, and sequences, and other structured educational content — helping teachers find, adapt, and use high-quality curriculum resources.

Product owners, school leaders, non-technical evaluators — you do not need to read the technical content below. Start with:

• Strategic Overview — reading guide connecting vision, roadmap, and engineering approach
• VISION.md — what this project delivers, why it matters, and the investment case
• Curriculum Guide — Oak's curriculum structure explained in plain language

• Developers — continue to Quick Start below
• AI agents — read the start-right-quick workflow, then AGENT.md

Three capabilities, powered by three open education data sources:

This repository integrates three open education data sources, each answering a different question that teachers ask:

Together these sources enable evidence-grounded curriculum discovery: AI agents can search for content (Oak API), understand where it fits in the curriculum structure (ontology), and recommend evidence-backed teaching approaches (EEF). See ADR-157 for the integration architecture and LICENCE-DATA.md for full licence terms.

The MCP servers expose curriculum data through the three MCP primitive types:

• Tools (model-controlled): 31 curriculum tools (23 generated from the OpenAPI schema, 8 aggregated) including orientation via get-curriculum-model and download-asset. The AI decides when to use them.
• Resources (application-controlled): Curriculum model, prior knowledge graph, and learning progressions as pre-loadable context for MCP clients that support resource injection.
• Prompts (user-controlled): Four workflow templates (find-lessons, lesson-planning, explore-curriculum, learning-progression) that guide users through common curriculum tasks.

The standalone stdio workspace is now a legacy transitional surface. Future stdio support should come from a separate stdio entry point generalised from the HTTP MCP server workspace rather than from continued parallel maintenance of the standalone stdio app. See the HTTP MCP server README, ADR-123, and ADR-128.

• Node.js 24.x — install via nvm or fnm, then run nvm use or fnm use to activate the version in .nvmrc
• pnpm — run corepack enable (ships with Node.js) to auto-install the pinned version

git clone https://github.com/oaknational/oak-open-curriculum-ecosystem.git
cd oak-open-curriculum-ecosystem
pnpm install
pnpm test && pnpm type-check && pnpm lint

If these pass, your toolchain is working. No API keys are required for unit tests, type-checking, linting, or building.

Before your first push: install gitleaks (brew install gitleaks on macOS). The pre-push hook runs a secrets scan and will block pushes if gitleaks is not installed.

Many tasks work without environment variables. To run dev servers, integration tests, or search workflows, you need an Oak API key:

1. Request a free key: https://open-api.thenational.academy/docs/about-oaks-api/api-keys
2. Copy the example environment file and add your key:

cp .env.example .env
# Edit .env: set OAK_API_KEY=your_key_here

See environment variables guide for Elasticsearch, Clerk, and other service credentials.

The full Quick Start Guide covers architecture, key concepts, and development workflows. Each workspace README provides area-specific setup (see links in the capability table above).

Daily development:

pnpm test           # Unit + integration tests
pnpm type-check     # Type-check all workspaces
pnpm lint           # Read-only lint verification
pnpm build          # Build all workspaces
pnpm sdk-codegen    # Regenerate SDK + MCP artefacts from OpenAPI

Widget development (from apps/oak-curriculum-mcp-streamable-http/):

pnpm dev:widget          # Standalone widget dev server with token live-reload
pnpm dev:widget-in-host  # Widget rendered inside MCP Apps basic-host (requires bun)
pnpm test:widget         # Widget unit + integration tests
pnpm test:widget:ui      # Playwright visual tests (light + dark themes)
pnpm test:widget:a11y    # Playwright axe-core WCAG 2.2 AA gate

Full verification:

pnpm make           # Full convenience pipeline with auto-fix steps; review file changes afterwards
pnpm check          # Canonical full verification gate: clean rebuild + tests + docs + formatting/linting fixes
pnpm fix            # Auto-fix: format + markdownlint + lint
pnpm clean          # Remove build artefacts (dist/, .turbo)

Everything flows from the OpenAPI schema:

1. OpenAPI Schema (single source of truth)
2. → TypeScript SDK (generated at pnpm sdk-codegen)
3. → MCP Tools (generated from the same schema)
4. → Type-safe everything (no manual type definitions, no runtime assertions)

The Cardinal Rule: If the OpenAPI schema changes, running pnpm sdk-codegen updates the SDK, types, validators, and MCP tools automatically. Zero manual intervention.

Search uses Elasticsearch with 4-way reciprocal rank fusion (ELSER sparse vectors, BM25, synonym expansion, and phrase boosting) to achieve high-accuracy retrieval across curriculum structures. See the search architecture for details and the OpenAPI pipeline for the generation architecture.

Apps:

SDKs:

Core and Libraries:

Core packages:

Libraries:

Design:

Architectural Decision Records (ADRs) are the architectural source of truth. These three foundational ADRs define the schema-first approach that underpins the codebase:

• ADR-029 — No manual API data structures
• ADR-030 — SDK as single source of truth
• ADR-031 — Generation-time extraction

See the full ADR index for all decisions.

This repository began as an exploration of what co-pilot style AI support could provide, but evolved rapidly into an agent-first engineering system. As of February 2026, for at least the previous six months, every line of code, configuration, and documentation has been written entirely by agents. Humans focus on system design: defining guardrails, architectural constraints, quality gates, and reviewer workflows; then providing direction and corrective feedback.

The result of this approach is the Practice — a transferable, self-improving system of principles, structures, specialist agents, and tooling that governs how work happens. The Practice is not a static rulebook; it contains a self-reinforcing improvement loop that learns from every session and evolves its own governance. The core cycle:

1. Capture — agents continuously log mistakes, corrections, and patterns to a session napkin
2. Refine — periodic distillation extracts high-signal entries into a curated reference
3. Graduate — the consolidation workflow moves settled patterns into permanent documentation (ADRs, governance docs, READMEs)
4. Enforce — permanent docs become rules and directives that govern the next session's work

The loop is self-referential: it improves not just the product code but the Practice itself. Rules about rule creation, patterns about distillation quality, and insights about consolidation all flow through the same cycle.

The Practice also travels between repositories via a plasmid exchange mechanism — a package of seven portable files that carry the improvement loop to new contexts. Different repos stress-test the Practice against different work, surfacing learnings that travel back to the origin. If a repo already has a Practice, then the income Practice is analysed and the best parts are integrated into the incumbent Practice. This allows the benefits of the learning loop to be compounded through multiple repos, while allowing the Practice to adapt itself to suit the context of each project.

The impact of these systems is to enable agentic engineering speed and optionality without sacrificing quality, while minimising the loss of visibility that comes from delegating work to agents. Quality gates, specialist reviewers, and the learning loop provide assurance comparable to manual code review, while the Practice's self-improving nature means governance strengthens over time rather than eroding.

Further reading:

• How the Agentic Engineering System Works — the Practice explained as an integrated engineering system
• The Practice — the same system, as an operational blueprint for AI agents
• ADR-119 — naming, boundary, and three-layer model
• ADR-131 — the improvement loop, interaction map, and self-referential property
• ADR-124 — how the Practice travels between repos
• .agent/HUMANS.md — contributor context

This repository brings together work from multiple contributors and open education organisations:

• Education Endowment Foundation — Teaching and Learning Toolkit data (citation required when using EEF-derived outputs; see LICENCE-DATA.md)
• Mark Hodierne — Oak Curriculum Ontology, primary author
• John Roberts — EEF MCP server prototype

This repository is open-source under the MIT licence. You are free to read, fork, and learn from the code.

At this time, we are not accepting external contributions (pull requests). This may change in the future; watch the repository for updates.

If you find a security issue, please follow our security policy.

Oak team members: see CONTRIBUTING.md for workflow, commit conventions, and quality expectations.

• Documentation: docs/README.md
• Issues: https://github.com/oaknational/oak-open-curriculum-ecosystem/issues
• Licence (code): MIT — see LICENCE
• Licence (curriculum data): see LICENCE-DATA.md for upstream terms
• Branding is copyright Oak National Academy: BRANDING.md
• Security: SECURITY.md