name:MCP Course Authoring from Structured Payloads
overview:Build an MCP-compatible authoring surface that lets external AI clients such as Claude send normalized course structures into ClassroomIO, save them as reviewable drafts, revise them, and publish them into real ClassroomIO courses.
todos:
- id:prd-review
content:Finalize PRD scope, product policy, and success metrics with stakeholders
Enable external AI clients such as Claude to create and edit ClassroomIO courses through MCP by sending normalized course structures into ClassroomIO.
The key product outcome is:
1. Claude or another agent reads source material externally
2. Claude turns that material into structured course JSON
3. MCP sends that JSON to ClassroomIO
4. ClassroomIO stores it as a draft
5. the user reviews and explicitly publishes it
This supports prompts like:
- "Create a complete course on exponential functions in Classroom."
- "Read this PDF, extract the course structure, and publish it into Classroom."
with one important boundary:
**In v1, ClassroomIO does not parse or extract PDFs itself.**
## Problem Statement
ClassroomIO already has the core CRUD primitives needed to create courses and content, but it does not yet expose a clean automation layer for external AI agents.
Current limitations:
- external AI clients have no MCP-compatible tool surface
- there is no normalized course payload contract for external agents
- there is no first-class draft persistence model for AI-generated course structures
- there is no explicit review/publish workflow for machine-generated content
- there is no stable API contract for "here is a complete course structure, store it safely"
This means agents can only create ClassroomIO content through brittle, record-by-record automation instead of a deliberate authoring pipeline.
## Core Product Decision
**Claude or the external agent is responsible for extraction. ClassroomIO is responsible for validation, persistence, review, authorization, and publish.**
That means:
- if the source is a PDF, Claude reads it
- if the source is a website, Claude reads it
- if the source is a prompt, Claude expands it
- ClassroomIO only receives structured payloads
## Primary Use Cases
### Use Case 1: Prompt to Structured Draft
A teacher asks Claude to create a course on a topic. Claude reasons about the content and sends a normalized course payload to ClassroomIO through MCP.
### Use Case 2: PDF to Structured Draft
A teacher provides one or more PDFs to Claude. Claude extracts the material and converts it into a normalized course payload. MCP sends that payload to ClassroomIO.
### Use Case 3: Draft Revision
After initial creation, Claude updates the draft by:
1. renaming sections
2. rewriting lesson content
3. reordering lessons
4. adding or removing lessons
5. publishing when the teacher confirms
## Goals
1. Provide an MCP-compatible authoring surface for external AI clients.
2. Keep ClassroomIO as the source of truth for auth, permissions, validation, persistence, and publishing.
3. Standardize a normalized course payload that any external agent can submit.
4. Make draft review mandatory before publish in v1.
5. Ensure org-scoped, permission-safe authoring with no direct DB access from the MCP server.
6. Support both prompt-derived and PDF-derived content through one shared payload contract.
7. Preserve human control by returning warnings and requiring explicit publish.
## Non-Goals (v1)
- Student-facing AI workflows
- Direct DB writes from the MCP server
- Full autonomous publishing without a review step
- ClassroomIO-side PDF extraction, OCR, or parsing
- Async PDF extraction workers
- Cross-organization or cross-course content access
- Full LMS migration parity with Teachable/Thinkific/SCORM in this PRD
- Perfect fidelity for tables, diagrams, formulas, or source formatting
## Confirmed Product Decisions
1. MCP is an orchestration layer, not the persistence layer.
2. ClassroomIO API owns validation, authorization, draft storage, and publish.
3. Draft-first is required; AI-generated content is not published immediately in v1.
4. External agents submit structured payloads; ClassroomIO does not ingest raw PDFs in v1.
5. The MCP server should start as a thin tool adapter and not require its own model provider.
6. Lesson long-form content should be stored in lesson language content, not only `lesson.note`.
7. Publish remains an explicit second step.
## Current-State Audit
| Capability | Current State | Notes |
| --- | --- | --- |
| Course creation | Exists via `POST /course` | Creates course shell only |
| Section creation | Exists via `POST /course/:courseId/section` | One section at a time |
| Lesson creation | Exists via `POST /course/:courseId/lesson` | One lesson at a time |
| Lesson language content | Exists via lesson-language routes | Good fit for generated lesson body |
| Course content reorder | Exists via content/section/lesson reorder routes | Useful after generation |
| Document upload | Exists for lesson documents | Not needed for v1 MCP ingestion |
| AI course assistant | PRD exists | Focused on in-app chat, not MCP |
| Public API keys | PRD exists | Likely dependency for auth model |
| Draft persistence for AI-generated course structures | Does not exist yet | Must be added |
Publishing should be blocked on validation errors. Informational warnings may still allow publish.
## Security Considerations
1. Reject cross-org access for all draft and publish routes.
2. Enforce org admin or equivalent authoring permissions.
3. Log key ID, key type, organization, and output course IDs for all MCP-triggered publishes.
4. Apply rate limits per org and per key.
5. Keep the MCP server outside the database trust boundary.
## Success Metrics
### Product Metrics
1. Time from agent output to first draft available
2. Draft-to-publish conversion rate
3. Average manual edits before publish
4. Percentage of generated drafts published within 24 hours
### Quality Metrics
1. Percentage of drafts requiring no structural edits
2. Publish failure rate
3. Duplicate publish rate
4. Support tickets related to malformed structure payloads
## Rollout Plan
### Phase 1: Draft and Publish API
Ship:
- normalized payload schema
- draft create endpoint
- draft update endpoint
- publish endpoint
### Phase 2: MCP Server
Ship:
- stdio MCP server
- auth wiring
- tool contracts for create/get/update/publish
### Phase 3: Hardening
Ship:
- idempotency keys
- richer warnings
- observability
- docs and examples
## Dependencies
1. Existing course, section, lesson, and lesson-language services remain the publish target.
2. Shared organization automation key infrastructure must be implemented.
3. External agent must generate normalized course payloads that match the schema.
## Open Questions
1. Should `publish_course_draft` remain a separate tool only, or support an explicit `publish: true` flag during draft creation?
2. Should exercise payloads be part of v1 or deferred until lesson drafting stabilizes?
3. What locale set should be supported by default?
4. Should cloud-only restrictions apply, similar to the AI assistant PRD?
5. Should the shared key-management routes ship before public `/v1/*` API routes, so MCP can adopt them first?
## Recommendation Summary
The correct v1 shape is:
1. thin MCP server
2. ClassroomIO-owned draft/publish API
3. external agent owns source extraction
4. explicit draft review before publish
5. publish via existing content services, not custom DB writes
That keeps the system small, matches your clarified boundary, and gives Claude a clean automation surface without forcing ClassroomIO to solve PDF extraction in v1.
