Thin stdio MCP server for ClassroomIO course authoring.
The package does not parse PDFs or generate course structures. The agent does that work. `@classroomio/mcp` only exposes tools, validates tool input, and forwards requests to the ClassroomIO API.
- ClassroomIO already renders the lesson title in the course UI
## After Publish
Once a draft has been published, the live course becomes the safer source of truth.
Recommended agent rule:
- if the draft is still `DRAFT`, continue editing that draft
- if the draft is `PUBLISHED`, do not keep reusing it for major follow-up edits
- instead, read the live course and create a fresh draft from that course
Recommended post-publish sequence:
1.`get_course_structure`
2.`create_course_draft_from_course`
3.`update_course_draft`
4.`publish_course_draft_to_existing_course`
Why:
- teachers may edit the live course in the UI after publish
- another agent session may have changed the course
- reusing an old published draft can overwrite newer live changes
For exercises on an already-published course, prefer the direct exercise tools instead of creating a whole new draft when the user only wants to add or revise exercises.
## User Flows
### Flow 1: Create a new course from a prompt
User says:
```text
Create a complete course on exponential functions for high school students.
```
Expected tool sequence:
1. Agent plans the course.
2. Agent calls `create_course_draft`.
3. User asks for revisions.
4. Agent calls `update_course_draft`.
5. User approves.
6. Agent calls `publish_course_draft`.
Result:
- a new course is created
- sections and lessons are created
- localized lesson content is written
- publish returns the live `courseId` and public `courseUrl`
- publish can optionally set a random Unsplash-derived course cover
### Flow 2: Update a landing page with AI-generated copy and media
User says:
```text
Rewrite this course landing page to feel more premium, generate a new cover image, and add three believable reviews.
```
Expected tool sequence:
1. Agent calls `list_org_courses` if it needs to resolve the course ID by name first.
2. Agent calls `update_course_landing_page`.
What the landing-page tool can update:
- title
- short description
- overview
- requirements
- goals
- pricing fields
- instructor section
- reviews
- landing page image
The tool can either:
- use an explicit `imageUrl`
- or generate a random Unsplash-based image with `generateImage` and `imageQuery`
### Flow 3: Create a draft from a PDF
User says:
```text
I have my course in a PDF. Extract it and turn it into a ClassroomIO course draft.
```
Expected tool sequence:
1. Agent reads the PDF itself.
2. Agent restructures the content into normalized JSON.
3. Agent calls `create_course_draft`.
4. User reviews the draft.
5. Agent calls `update_course_draft` if needed.
6. User approves.
7. Agent calls `publish_course_draft`.
Important:
- the PDF does not need to be uploaded to MCP
- the MCP package only receives structured JSON
### Flow 4: Tag a draft before publish
User says:
```text
Add tags for algebra, beginner, and exponential growth to this draft.
```
Expected tool sequence:
1. Agent calls `tag_course_draft`.
2. User reviews the updated draft tags.
3. Agent later calls `publish_course_draft`.
Result:
- the draft stores tag names
- publish ensures the tags exist in ClassroomIO
- publish assigns those tags to the live course
### Flow 5: Update an existing course safely
User says:
```text
Take my existing Algebra course, reorganize it, and rewrite the lesson content for a beginner audience.
```
Expected tool sequence:
1. Agent calls `list_org_courses` if it needs to resolve the course ID from the course name first.
2. Agent calls `get_course_structure` with the existing `courseId`.
3. Agent optionally calls `create_course_draft_from_course` to persist a seeded draft.
4. Agent updates the draft with the new structure and content using `update_course_draft`.
Add a 5-question multiple-choice exercise to lesson 3.
```
Expected tool sequence:
1. Agent calls `list_course_exercises` if it needs current context.
2. Agent calls `create_course_exercise` for a brand new exercise.
3. Agent calls `update_course_exercise` for later revisions.
Use this direct path when the course is already live and the change is exercise-specific.
What it does not do today:
- automatically delete sections or lessons that are absent from the draft
- automatically delete lesson locales that are absent from the draft
That behavior is intentional. The current update path is non-destructive by default.
## How Existing-Course Updates Work
When a draft is seeded from a live course:
- section `externalId` values are the real section IDs
- lesson `externalId` values are the real lesson IDs
As long as the agent preserves those IDs while editing the draft, publish-to-existing-course can map draft items back to the live records and update them safely.
If the agent adds a brand new section or lesson, it should assign a new synthetic `externalId`. ClassroomIO will create that record on publish.
## Input Contract Notes
For large updates, the agent should:
1. call `get_course_structure`
2. keep existing `externalId` values for records it wants to update
3. only generate new `externalId` values for new records
4. avoid deleting records from the draft unless the user explicitly wants omitted content to remain untouched
Publish input also supports:
-`bannerImageUrl`: use this exact course cover
-`bannerImageQuery`: search Unsplash with this query
-`generateBannerImage`: fetch a random Unsplash image using the course title or query
Tagging tools use:
-`tagNames`: human-readable tag names, not tag IDs
-`mode: "merge" | "replace"`
-`groupName` optional, defaults to `Automation`
The API creates missing tags automatically when needed.
Exercise tools use the live course directly:
-`list_course_exercises`
-`get_course_exercise`
-`create_course_exercise`
-`create_course_exercise_from_template`
-`update_course_exercise`
Supported `questionTypeId` values for exercise payloads:
-`14``THUMBS` - Thumbs up/down (open-ended poll with customizable Yes/No labels; no correct answer)
`TRUE_FALSE` is auto-graded with `settings.correctValue` (boolean) and fixed True/False labels for factual statements. `THUMBS` is open-ended (not auto-graded): two customizable Yes/No-style options with thumbs icons for sentiment or poll-style questions — do not set `settings.correctValue`. `MATCHING` and `HOTSPOT` are disabled and must not be used.
