Oak Open Curriculum Ecosystem
oaknational/oak-open-curriculum-ecosystem
SDK e MCP server para curriculum educacional aberto com busca semântica
Ver no GitHubMCP server e SDK TypeScript para integrar o currículo aberto da Oak National Academy em aplicações de IA. Oferece acesso tipo-seguro aos dados curriculares via API, busca semântica com Elasticsearch e ferramentas para construir assistentes educacionais que ajudem professores a encontrar e adaptar recursos de qualidade.
Instalação
npx convez-ai oaknational/oak-open-curriculum-ecosystem1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir assistentes de IA para educadores encontrarem recursos curriculares
- Integrar dados estruturados de currículo em plataformas educacionais
- Implementar busca semântica sobre conteúdo educacional sequenciado
- Desenvolver aplicações MCP para Claude Cowork e ChatGPT com dados curriculares
Veredito

Projeto maduro e bem arquitetado para quem precisa integrar curriculum estruturado em aplicações de IA educacional. Recomendado para desenvolvedores construindo assistentes para o setor educacional, com SDK robusta e padrões reutilizáveis além do caso de uso específico da Oak.
README
A tradução para o português deste README ainda está na fila.
Oak Open Curriculum Ecosystem
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, MCP Apps, and semantic search over the curriculum data powered by Elasticsearch Serverless.
Vision and direction: For the strategic overview of what this repository is for, see VISION.md. For the live delivery roadmap, see the high-level plan.
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 licenced, fully sequenced, and fully resourced curriculum easier for the wider education and technology sectors to use. It provides the Oak Curriculum SDK, the canonical MCP server as both an end-user-facing app surface and a developer tool, the OpenAPI-to-MCP server pipeline, hybrid semantic search, and knowledge graph surfaces as modular building blocks for education applications.
The repository also explores what can be done with MCP Apps in AI platforms such as Claude Cowork and ChatGPT. AI assistants can search Oak's curriculum, explore lessons, units, threads, sequences, and other structured educational content — helping teachers find, adapt, and use high-quality curriculum resources.
Underneath the product surfaces, the repo develops a reusable, self-improving Practice for agentic-first engineering: a plain-text framework that lets agents from major vendors collaborate, learn, and keep operational knowledge in the repository where it remains useful.
Beyond Oak-hosted products, this repository publishes a deliberate set of reusable sector components—the OpenAPI-to-MCP pipeline, SDK-generation patterns, hybrid-search tooling, MCP/MCP App scaffolds, graph projection conventions, and the openly documented Practice—so other organisations can lower the cost of building curriculum-aware applications without starting from scratch. The canonical inventory and scope for each asset live in What We Deliver in the Vision.
Product owners, school leaders, non-technical evaluators — you do not need to read the technical content below. Start with:
- VISION.md — what this project delivers, hosted vs reusable sector components, why it matters, and the investment case
- Curriculum Guide — Oak's curriculum structure explained in plain language
- Latest progress update — what has been delivered, what is next, and why it matters
Developers and AI agents
- Developers — continue to Quick Start below
- Oak teammates joining via Claude Code (or another AI coding agent) — Quick Start as above, then MCP servers for contributors for the sanctioned MCP set, and good first issues for what to pick up first
- AI agents — read the start-right-quick workflow, then AGENT.md, then scan the five foundational ADRs — the architectural source of truth
Working with agents
This repository is designed for agentic development. Start agent sessions by naming the relevant start-right workflow and the outcome you want. The start-right workflow grounds the agent in the repo's live rules, plans, claims, comms, and git state before it acts.
For Claude Code, Cursor, Gemini, or another slash-command surface, a single agent session might start with:
/oak-start-right-quick find the most frequent user-impact bug from Sentry,
create a plan for resolving it, then execute it
For a coordinated team:
/oak-start-right-team you are part of a team of agents working on the
knowledge graph enhancement plan, please continue
For existing threads, prefer a pointer to the thread continuation record rather than restating live state in the prompt:
/oak-start-right-team continue agentic-engineering-enhancements from
.agent/memory/operational/threads/agentic-engineering-enhancements.next-session.md.
Treat this opener as a hypothesis until live grounding confirms it.
In Codex, use the same skill names through /skills or $skill-name mentions:
$oak-start-right-team continue agentic-engineering-enhancements from
.agent/memory/operational/threads/agentic-engineering-enhancements.next-session.md.
Treat this opener as a hypothesis until live grounding confirms it.
Use oak-session-handoff at the end of a meaningful solo session so the next
agent inherits the real state rather than a chat transcript guess. In team
sessions, oak-start-right-team should name the closeout owner; only that owner
runs the full handoff, while other team members leave boundary-scoped closeout
notes.
Browse the documentation by section: Foundation (vision and the agentic engineering system) · Governance (development, TypeScript, testing, accessibility, security) · Architecture (ADRs, OpenAPI pipeline, provider system) · Engineering (workflow, tooling, extending) · Operations (env vars, troubleshooting) · Domain (curriculum data) · Docs index.
What This Repo Provides
Three capabilities, powered by three open education data sources:
| Capability | What it does | Packages |
|---|---|---|
| Curriculum SDK | Typed TypeScript access to Oak's curriculum API — types, Zod validators, and MCP tool metadata, all generated from the OpenAPI schema | oak-curriculum-sdk |
| MCP Servers | AI assistants and developer tools can search, browse, and fetch curriculum data through Model Context Protocol and MCP Apps | mcp-http (canonical server workspace, web, Vercel) |
| Semantic Search | Hybrid lexical + semantic retrieval across lessons, units, threads, and curriculum sequences using Elasticsearch with reciprocal rank fusion | oak-search-cli, oak-search-sdk |
Together, shipped products and reusable sector-facing components are the pillars of compositional curriculum intelligence, framed in depth in VISION.md—including hosted surfaces versus reusable components under What We Deliver.
Sector reusable components
Partners and external builders should anchor adoption claims on the enumerated inventory in What We Deliver: what counts as reusable fabric (pipeline, SDK generation patterns, hybrid-search tooling, MCP/MCP App scaffolds, graph projection conventions, Practice) versus Oak-hosted APIs and deployments. Supporting playbooks and partner obligations grow from .agent/plans/sector-engagement/current/sector-reusable-components-adoption.plan.md.
Data Sources
This repository integrates three open education data sources, each answering a different question that teachers ask:
| Source | What It Provides | Licence |
|---|---|---|
| Oak Open Curriculum API | Lessons, units, threads, sequences, quizzes, and transcripts — openly licenced, fully sequenced, fully resourced curriculum content | OGL v3.0 |
| Oak Curriculum Ontology | Oak's formal semantic representation of curriculum structure aligned to the National Curriculum for England (2014), using W3C standards (RDF/OWL/SKOS/SHACL) | OGL v3.0 (data) + MIT (code) |
| EEF Teaching and Learning Toolkit | 30 research-synthesised teaching approaches with quantified impact, cost, and evidence strength ratings | Attribution required |
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). They also equip internal Oak teams and external builders with high-quality integration primitives spanning curriculum API access, MCP, search, ontology alignment, and evidence surfaces. Organisational reuse of Oak's delivery patterns—not merely calling the upstream REST API—is grounded in Vision, What We Deliver. See ADR-157 for the integration architecture and LICENCE-DATA.md for full licence terms.
MCP Server Capabilities
The MCP servers expose curriculum data through the three MCP primitive types:
- Tools (model-controlled): 34 curriculum tools (24 generated from the OpenAPI schema, 8 aggregated, plus a user-search pair) including orientation via
get-curriculum-modelanddownload-asset. The AI decides when to use them. Seeapps/oak-curriculum-mcp-streamable-http/README.mdas the canonical count. - 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 has been retired and removed. The
canonical MCP server workspace is now
apps/oak-curriculum-mcp-streamable-http/;
any future stdio support is expected to come from a separate stdio
entry point generalised from that workspace rather than a parallel
standalone app. See the
HTTP MCP server README,
ADR-123,
and
ADR-128.
Quick Start
Prerequisites
- Node.js 24.x — install via nvm or fnm, then run
nvm useorfnm useto activate the version in.nvmrc - pnpm — run
corepack enable(ships with Node.js) to auto-install the pinned version - bun (optional, for
pnpm dev:widget-in-host) — install via bun.sh - lsof (optional, for
apps/oak-curriculum-mcp-streamable-http/scripts/restart-dev-server.sh) — pre-installed on macOS; on Debian/Ubuntu usesudo apt install lsof; source/build instructions at github.com/lsof-org/lsof - sentry (optional, for dev-time Sentry issue triage, event inspection,
and Sentry Seer) — install only when you need local Sentry operator tooling;
see Sentry CLI usage for the
sentry-clivs dev-sentrysplit and workspace invocation details.
Install and verify
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.
Get an API key (optional)
Many tasks work without environment variables. To run dev servers, integration tests, or search workflows, you need an Oak API key:
- Request a free key: https://open-api.thenational.academy/docs/about-oaks-api/api-keys
- Copy the example environment file for the workspace you are running and add your key there:
# HTTP MCP server
cp apps/oak-curriculum-mcp-streamable-http/.env.example \
apps/oak-curriculum-mcp-streamable-http/.env.local
# Search CLI
cp apps/oak-search-cli/.env.example apps/oak-search-cli/.env.local
# Edit the relevant .env.local and set OAK_API_KEY=your_key_here
See environment variables guide for Elasticsearch, Clerk, and other service credentials.
Next steps
The Architecture section below summarises the schema-first design and key directories. For the development process, commit conventions, and quality expectations, see CONTRIBUTING.md. For a curated list of starter tasks, see good first issues. Each workspace README provides area-specific setup (see links in the capability table above).
For the shape of the curriculum data and per-key-stage variance, see the Curriculum Guide and Data Variances. For how MCP tools execute against the OpenAPI schema at runtime, see openapi-pipeline.md → Schema-First Tool Invocation.
Key Commands
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)
Architecture
Everything flows from the OpenAPI schema:
- OpenAPI Schema (single source of truth)
- → TypeScript SDK (generated at
pnpm sdk-codegen) - → MCP Tools (generated from the same schema)
- → 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.
| Directory | Purpose |
|---|---|
apps/ | The canonical HTTP MCP server and the semantic search CLI |
packages/sdks/ | Curriculum SDK (code-generation, MCP metadata) and Search SDK (ES retrieval) |
packages/core/ | Foundational packages: Result<T, E> type, env schema contracts, observability primitives, type helpers, ESLint configs |
packages/libs/ | Shared libraries: env-resolution, structured logging, search contracts, and Sentry adapters |
packages/design/ | Design token pipeline and reusable design primitives: DTCG source format, CSS custom property generation, WCAG AA contrast validation, Ink UI primitives |
agent-tools/ | Agent workflow CLIs: claude-agent-ops, cursor-session-from-claude-session, and codex-reviewer-resolve |
docs/ | Developer documentation, guides, and the full ADR index |
Workspace Summaries
Apps:
| Workspace | Purpose |
|---|---|
oak-curriculum-mcp-streamable-http | Canonical MCP server — Streamable HTTP transport, Vercel deployment, 34 curriculum tools, resources, prompts, and MCP App widget |
oak-search-cli | Search CLI — admin operations, bulk ingestion, blue/green index lifecycle (ADR-130), evaluation, and ground-truth benchmarking |
SDKs:
| Workspace | Purpose |
|---|---|
oak-curriculum-sdk | Curriculum API SDK — generated types, Zod validators, MCP tool metadata, all flowing from the OpenAPI schema |
oak-search-sdk | Search SDK — hybrid lexical (BM25) + semantic (ELSER) retrieval, admin services, observability, and blue/green index lifecycle management (zero downtime index swaps) |
oak-sdk-codegen | Schema-driven code generation — OpenAPI → TypeScript types, Zod schemas, ES mappings, MCP tool definitions |
Core and Libraries:
Core packages:
| Workspace | Purpose |
|---|---|
result | Result<T, E> type for explicit error handling without exceptions |
env | Env schema contracts — Zod-based validation for environment variables |
observability | Provider-neutral redaction and active-span helpers |
type-helpers | Shared type-level utilities |
oak-eslint | Custom ESLint rules enforcing architectural boundaries |
Libraries:
| Workspace | Purpose |
|---|---|
@oaknational/logger | Structured logger with sink fan-out, redaction, and trace correlation |
@oaknational/env-resolution | Environment resolution pipeline — .env discovery, validation, and injection |
@oaknational/search-contracts | Canonical semantic-search field and stage contracts |
@oaknational/sentry-node | Shared Sentry Node config, sinks, fixture runtime, and flush helpers |
Design:
| Workspace | Purpose |
|---|---|
design-tokens-core | Pure functions for DTCG token parsing and WCAG AA contrast validation |
oak-design-tokens | Oak-specific token definitions (palette, semantic, component) and CSS build output |
oak-design-ink | Reusable Oak React primitives for Ink-based terminal interfaces |
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 (start with the "5 ADRs in 15 Minutes" block).
Engineering Practice
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:
- Capture — agents continuously log mistakes, corrections, and patterns to a session napkin
- Refine — periodic distillation extracts high-signal entries into a curated reference
- Graduate — the consolidation workflow moves settled patterns into permanent documentation (ADRs, governance docs, READMEs)
- 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
Credits and Attribution
This repository brings together work from multiple contributors and open education organisations. See ATTRIBUTION.md for full details, citations, and licence terms for each source.
- Education Endowment Foundation — Teaching and Learning Toolkit data. Citation: Higgins, S., Katsipataki, M., Kokotsaki, D., Coleman, R., Major, L.E., & Coe, R. Teaching and Learning Toolkit. Education Endowment Foundation.
- Mark Hodierne — Oak Curriculum Ontology, primary author
- John Roberts — EEF MCP server prototype
Contributing
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.
Support and Licensing
- 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
- Attribution: see ATTRIBUTION.md for credits and citations
- Branding is copyright Oak National Academy: BRANDING.md
- Security: SECURITY.md