PAIDEIA MCP

Using Alt instead of Claude Code, Codex, or opencode? Same tool, same on-disk layout, same license — re-homed as a local MCP server. The original PAIDEIA is a Claude Code plugin; this edition is a self-contained stdio MCP server that owns the local folder contract, markdown artifact writes, Exam Radar imports, repo/skill parsing, and the deterministic heavy work, so Alt's local model can drive the same study graph. The graph it builds is byte-for-byte identical and portable across all editions.

Security notice. PAIDEIA MCP installs as a local stdio MCP server — a pip install -e . Python package you point Alt at — and never asks you to download a .zip, run an .exe, or use any installer. Any other repository using the PAIDEIA name is not affiliated with this project unless it is explicitly linked from this README.

What Paideia means

In ancient Greece, Παιδεία was never the deposit of facts into a passive student. It was the lifelong formation of a complete human being — through structured encounter with primary texts, guided practice under a master, and reflective dialogue that folds feedback into deeper revision.

This MCP server implements that cycle for the specific, bounded problem of exam preparation in math, physics, and engineering courses:

  ingest ──▶ analyze ──▶ drill ──▶ grade ──▶ weakmap ──▶ cheatsheet
     ▲                                                        │
     └────────────────── feedback loop ───────────────────────┘

Every stage produces a markdown artifact that lives in your course folder forever. Nothing is ephemeral. Nothing is hidden behind an API. Nothing stops working when the next funding winter hits.

Related MCP server: Agent Helper

Why an MCP edition

PAIDEIA was born as a Claude Code plugin. The heavy lifting — parallel vision ingest, strategy grading, pattern extraction from your solutions — never depended on Claude specifically; it depended on any host that can run instructions against a course folder. Alt captures lectures and runs a local model, but it is not an agentic CLI with skills and subagents. So instead of porting the verbs, this edition re-homes the deterministic core into a standalone local stdio MCP server.

Goal: make the same durable PAIDEIA course folder usable from Alt, not just Claude Code / Codex / opencode. The server owns the local folder contract, markdown artifact writes, Exam Radar imports, repo/skill parsing, and deterministic heavy work; Alt's local model supplies the generation step.

Alt chat / local model
        |
        v
PAIDEIA MCP (local stdio)
        |
        v
~/courses/my-course/
  .course-meta
  materials/ converted/ course-index/ errors/ weakmap/
  quizzes/ mock/ twins/ chain/ derivations/ cheatsheet/

The study graph on disk is byte-for-byte the same as every other edition. course-index/patterns.md, errors/log.md, weakmap/weakmap_<ts>.md, cheatsheet/final.md — all the artifacts the Claude edition writes, this edition also writes, in the same format. Fork a course folder between editions and the new runner picks up without friction.

Alt Setup

Install dependencies from this folder:

python3 -m pip install -e .

On Homebrew-managed Python, use a virtual environment if pip reports an externally-managed environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

In Alt's MCP server dialog, choose the local stdio transport and use:

명령어: /absolute/path/to/PAIDEIA-mcp/.venv/bin/python
전송 방식: 로컬 (stdio)
인수:
  -m
  paideia_mcp.bootstrap
글로벌 채팅에서 사용: on
이름: PAIDEIA
작업 디렉터리: /absolute/path/to/PAIDEIA-mcp
환경 변수:
  PAIDEIA_MCP_AUTO_INSTALL = 0

You can print these exact fields for your current checkout:

python3 scripts/alt_setup.py
# or, after install
paideia-alt-setup

Important: the 인수 box takes one argument per line. Do not put python3 -m paideia_mcp.bootstrap all in the 명령어 field.

If you did not create .venv, use this lighter setup instead:

명령어: python3
전송 방식: 로컬 (stdio)
인수:
  -m
  paideia_mcp.bootstrap
글로벌 채팅에서 사용: on
이름: PAIDEIA
작업 디렉터리: /absolute/path/to/PAIDEIA-mcp
환경 변수:
  PAIDEIA_MCP_AUTO_INSTALL = 1

If Alt asks for a single command string instead of command/args fields:

python3 -m paideia_mcp.bootstrap

Transport/auth in Alt:

Transport: local / stdio
Auth: none
Server URL: leave empty for stdio

The bootstrap entrypoint installs missing Python package dependencies into the current user's site-packages before importing the MCP server. Set PAIDEIA_MCP_AUTO_INSTALL=0 to disable that behavior and fail with the manual pip install command instead.

See examples/alt-local-stdio.json for a reference snippet. Treat it as a field map, not a guaranteed Alt export format.

Before adding it to Alt, you can test the exact stdio path:

python3 scripts/smoke_stdio.py

To diagnose an install or course folder:

python3 scripts/doctor.py --project-root /absolute/path/to/course
# or, after `python3 -m pip install -e .`
paideia-doctor --project-root /absolute/path/to/course

The current Alt plugin SDK exposes notes/AI/storage/files, but not a plugin-side MCP client API. The intended bridge is:

1. Alt SDK reads notes with alt.notes.list / alt.notes.getContent.

2. Alt's MCP-enabled local model or host integration calls PAIDEIA MCP with those note payloads.

3. PAIDEIA MCP writes the durable local course folder.

See examples/alt-sdk-note-handoff.ts for the SDK-side payload shape.

How Alt Uses It

There are two classes of tools.

Deterministic tools

These tools write/read PAIDEIA artifacts directly:

PAIDEIA repo parser / action composer

These tools make all PAIDEIA actions available to Alt's local model:

The parser understands the source formats used across OPTIMETA's PAIDEIA line: Codex skill folders (plugins/paideia/skills/paideia-*/SKILL.md), Claude command markdown (plugins/paideia/commands/*.md), PAIDEIA-Hermes command markdown (commands/*.md) plus mapped Hermes skills, and opencode prompt files (assets/prompts/*.md). Canonical PAIDEIA actions are normalized to the same 16-action surface; source-only helpers such as doctor are preserved as extra_actions in the manifest/catalog.

The important pattern is:

1. Alt calls bootstrap_alt_course for a new course with selected note transcripts, or import_alt_notes / import_alt_note for later lecture transcripts.

2. Alt calls prepare_paideia_action(action="quiz", args="weakmap 5").

3. Alt's local model drafts the PAIDEIA artifact using the returned instruction.

4. Alt calls save_action_artifact to save standard outputs, or write_artifact for explicit paths like course-index/summary.md. For analyze, Alt calls save_course_index; for grading reports with mistakes, Alt calls save_grade_report.

5. If a failed/revised attempt should shape future study, Alt calls append_error or includes the errors in save_grade_report.

This is how plugin-like PAIDEIA behavior becomes possible without Claude Code: MCP supplies the durable local graph, action recipes, and instructions; Alt's local model supplies the generation step.

For model-first integration, call alt_capability_manifest or read paideia://alt/manifest. It returns a JSON map from every canonical PAIDEIA action to the MCP tools and local-model steps needed to execute it.

MCP Prompts

If Alt exposes MCP prompts, the server publishes five ready-to-use operating prompts:

paideia-operating-guide
paideia-course-bootstrap
paideia-lecture-to-quiz
paideia-attempt-first-drill
paideia-exam-radar-import

If the client only exposes tools, call alt_workflow_guide with one of: operating-guide, course-bootstrap, lecture-to-quiz, attempt-first-drill, or exam-radar-import.

MCP Resources

If Alt exposes MCP resources, the server publishes:

paideia://alt/manifest       JSON action/tool manifest for local-model orchestration
paideia://alt/system-prompt  default operating prompt for Alt local models

Tool Inventory

Current tool discovery should show 54 tools: 27 canonical tool names plus 27 Alt-search namespace aliases. If Alt searches for PAIDEIA__init_course, use the alias directly; it routes to the same handler as init_course.

ingest_pdfs
grade_pdf
build_course_index
course_phase
init_course
parse_paideia_repo
list_paideia_actions
prepare_paideia_action
list_artifacts
read_artifact
write_artifact
import_alt_note
import_alt_notes
bootstrap_alt_course
save_action_artifact
save_course_index
save_grade_report
append_error
parse_exam_radar_export
import_exam_radar
pattern_lookup
hwmap
generate_weakmap
alt_workflow_guide
alt_capability_manifest
alt_setup_instructions
paideia_doctor

Every canonical tool above is also exposed with a PAIDEIA__ prefix, for example PAIDEIA__init_course, PAIDEIA__write_artifact, and PAIDEIA__alt_setup_instructions. These aliases exist because Alt's tool search may look for server-prefixed names.

In Alt chat, call PAIDEIA MCP tools directly by name. Do not use alt_tool_search_bm25 with category: "alt" to find PAIDEIA tools; that category searches Alt-native note tools, not connected MCP server tools.

Engines

Both engines OCR fully in-process — the MCP writes finished markdown to the course folder with no external agent's vision step. This matters for Alt, whose plugin sandbox cannot read page images: a host-vision engine would be inert here, so PAIDEIA MCP does the OCR itself.

qwen3-vl is the default. When Ollama is unreachable or the model isn't pulled, it falls back to tesseract automatically so a default install still produces output; the provenance header and grade tier record which engine actually ran. Pick tesseract outright for the lightest, no-download path.

Notes for Alt Integration

• This MCP server can write markdown files and append YAML logs inside a local PAIDEIA course folder.

• It does not automatically read Alt's private note database. Alt should pass active/selected note title/transcript/memo/summary payloads into bootstrap_alt_course, import_alt_notes, or import_alt_note.

• import_exam_radar already accepts the fixed markdown emitted by Exam Radar's copy button.

• alt_capability_manifest / paideia://alt/manifest gives Alt's local model the complete action-to-tool recipe table.

• prepare_paideia_action plus save_action_artifact, save_course_index, and save_grade_report is the bridge for the rest of PAIDEIA: quiz, twin, blind, chain, mock, derive, cheatsheet, weakmap, analyze, and grade workflows can all be driven by Alt's local model using the returned instructions plus canonical artifact writes.

What ships

paideia_mcp/
├── bootstrap.py        dependency preflight + server launcher
├── server.py           stdio entrypoint, tool registration
├── repo_parser.py      parses PAIDEIA skills/prompts into an action catalog
├── action.py           composes instructions/context for Alt local models
├── alt_manifest.py     machine-readable Alt action/tool manifest
├── workspace.py        safe course-folder read/write/init and typed artifact writers
├── exam_radar.py       imports Exam Radar exam-radar:v1 exports
├── study_tools.py      hwmap/pattern/weakmap helpers
├── ingest.py           ingest_pdfs tool (render + in-process OCR → converted/**)
├── grade.py            grade_pdf tool (render + in-process OCR → answers/converted/)
├── analyze.py          build_course_index tool
├── phase.py            course_phase tool
└── ocr/
    ├── __init__.py      engine dispatch + qwen3-vl→tesseract fallback
    ├── qwen3vl.py        local Ollama Qwen3-VL 8B
    └── tesseract.py      pytesseract eng and/or kor (whichever is installed)

OCR runs entirely inside the MCP process via these two engines — there's no host-vision (codex-native / openai_vision.py) path, because Alt's plugin sandbox can't read page images, so an engine that defers OCR to the host would produce nothing here. qwen3-vl (default) falls back to tesseract when Ollama is unavailable, so the two-engine set is self-sufficient.

Connect

License

MIT. Use freely. Fork and modify for your own courses — the point of PAIDEIA is that the study graph it builds is yours to shape, not a fixed product you have to live with.