ed-tech-system-mcp

Domain-Driven MCP (Model Context Protocol) server for ed-tech workflows. The server exposes validated MCP tools backed by LangGraph agents, Supabase document retrieval, web search, and YouTube video discovery — all organized with Clean Architecture and DDD.

What this project does

External MCP clients call MCP tools that validate input with Pydantic, delegate to application workflows and LangGraph agents, and reach external systems through domain ports implemented in the infrastructure layer.

MCP tools

Tool	Purpose
health_check	Liveness probe
find_documents	Document retrieval enriched with related videos (pruned response payloads)
search_youtube	YouTube video search for educational content
run_workflow	Full document + video discovery LangGraph workflow

All tool handlers are wrapped with MCP tool caching (when enabled), per-tool latency logging, and domain error mapping at the protocol boundary.

Integrations

Capability	Integration
Document retrieval	Supabase (Postgres / pgvector)
Web search	DuckDuckGo (optional Tavily) — wiring deferred until HTTP adapters land
Video discovery	YouTube Data API v3
Agent orchestration	LangChain / LangGraph
Caching	Redis (CACHE_ENABLED=true required in production)
Local workflow UI	FastAPI + React (dev tooling)

Adapter status: Infrastructure adapters are scaffolded with domain guards and exception taxonomy; full HTTP implementations (BL-022) are deferred. MCP tools exercise the workflow and port contracts through the composition root.

Architecture

The codebase follows Clean Architecture with five layers under src/mcp_server/:

entrypoint  →  interface  →  application  →  domain  ←  infrastructure
(main.py)      (MCP tools)   (agents)        (ports)     (adapters)

Layer	Path	Responsibility
domain	domain/	Entities, ports, domain exceptions — no framework imports
application	application/	LangGraph workflows, agent orchestration
interface	interface/	MCP tools, Pydantic validation, protocol adapters
infrastructure	infrastructure/	Supabase, search, YouTube, Redis adapters
entrypoint	main.py, settings.py, wiring.py	Bootstrap, settings, dependency injection

Read next: ARCHITECTURE.md for layer rules, patterns, and anti-patterns. AGENTIC_ARCHITECTURE.md for LLM wiring, tool taxonomy, and agent flows. OBSERVABILITY.md for the local LangGraph workflow UI, execution replay, and trace debugging.

Quick start

Prerequisites

• Python 3.12 (see requires-python in pyproject.toml)
• uv — environment and dependency manager
• Doppler CLI (recommended for secrets) or a local gitignored .env

Install

uv python install 3.12
uv sync --all-groups

Configure secrets

Secrets never enter git. Use Doppler (team) or a local .env (solo dev).

doppler login
./scripts/doppler/setup-local.sh
./scripts/doppler/bootstrap-from-env-example.sh   # first time only — uploads placeholders
# Fill real values in the Doppler dashboard → ed-harness-system

Required variables: APP_ENV, SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, YOUTUBE_API_KEY.

Optional: GROQ_API_KEY (only when an LLM path is invoked — lazy-init at first use), TAVILY_API_KEY, LOG_LEVEL (applied at bootstrap via configure_logging()), CACHE_ENABLED + REDIS_URL (production).

See ENVIRONMENT_SETUP.md for the full secrets workflow.

Run the MCP server

# With Doppler
doppler run -- uv run mc