convez.ai
MCP ServerIntegração & APIsAvançado
oaknational

Oak Open Curriculum Ecosystem

oaknational/oak-open-curriculum-ecosystem

SDK e MCP server para curriculum educacional aberto com busca semântica

Ver no GitHub
BomPluginScore · de 0 a 100

MCP 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-ecosystem

1 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

Estrelas
9
Forks
5
Acompanhando
0
Saúde
87%
Último commit
há 1 dia
Versão
v1.187.0
Issues abertas
23
Contribuidores
5

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.

Quality Gate Status AI Code Assurance

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.


MIT Licence OGL Data Licence

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

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:

CapabilityWhat it doesPackages
Curriculum SDKTyped TypeScript access to Oak's curriculum API — types, Zod validators, and MCP tool metadata, all generated from the OpenAPI schemaoak-curriculum-sdk
MCP ServersAI assistants and developer tools can search, browse, and fetch curriculum data through Model Context Protocol and MCP Appsmcp-http (canonical server workspace, web, Vercel)
Semantic SearchHybrid lexical + semantic retrieval across lessons, units, threads, and curriculum sequences using Elasticsearch with reciprocal rank fusionoak-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:

SourceWhat It ProvidesLicence
Oak Open Curriculum APILessons, units, threads, sequences, quizzes, and transcripts — openly licenced, fully sequenced, fully resourced curriculum contentOGL v3.0
Oak Curriculum OntologyOak'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 Toolkit30 research-synthesised teaching approaches with quantified impact, cost, and evidence strength ratingsAttribution 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-model and download-asset. The AI decides when to use them. See apps/oak-curriculum-mcp-streamable-http/README.md as 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 use or fnm use to 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 use sudo 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-cli vs dev-sentry split 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:

  1. Request a free key: https://open-api.thenational.academy/docs/about-oaks-api/api-keys
  2. 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:

  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.

DirectoryPurpose
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:

WorkspacePurpose
oak-curriculum-mcp-streamable-httpCanonical MCP server — Streamable HTTP transport, Vercel deployment, 34 curriculum tools, resources, prompts, and MCP App widget
oak-search-cliSearch CLI — admin operations, bulk ingestion, blue/green index lifecycle (ADR-130), evaluation, and ground-truth benchmarking

SDKs:

WorkspacePurpose
oak-curriculum-sdkCurriculum API SDK — generated types, Zod validators, MCP tool metadata, all flowing from the OpenAPI schema
oak-search-sdkSearch SDK — hybrid lexical (BM25) + semantic (ELSER) retrieval, admin services, observability, and blue/green index lifecycle management (zero downtime index swaps)
oak-sdk-codegenSchema-driven code generation — OpenAPI → TypeScript types, Zod schemas, ES mappings, MCP tool definitions

Core and Libraries:

Core packages:

WorkspacePurpose
resultResult<T, E> type for explicit error handling without exceptions
envEnv schema contracts — Zod-based validation for environment variables
observabilityProvider-neutral redaction and active-span helpers
type-helpersShared type-level utilities
oak-eslintCustom ESLint rules enforcing architectural boundaries

Libraries:

WorkspacePurpose
@oaknational/loggerStructured logger with sink fan-out, redaction, and trace correlation
@oaknational/env-resolutionEnvironment resolution pipeline — .env discovery, validation, and injection
@oaknational/search-contractsCanonical semantic-search field and stage contracts
@oaknational/sentry-nodeShared Sentry Node config, sinks, fixture runtime, and flush helpers

Design:

WorkspacePurpose
design-tokens-corePure functions for DTCG token parsing and WCAG AA contrast validation
oak-design-tokensOak-specific token definitions (palette, semantic, component) and CSS build output
oak-design-inkReusable 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:

  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:

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

Ver o original no GitHub

Bom para

Relacionados