@classroomio/mcp 0.0.3 → 0.0.5

package/README.md

@@ -41,11 +41,19 @@ ClassroomIO DB
 
 Current tools:
 
+- `list_org_courses`
 - `get_course_structure`
 - `create_course_draft`
 - `create_course_draft_from_course`
 - `get_course_draft`
+- `list_course_exercises`
+- `get_course_exercise`
+- `create_course_exercise`
+- `create_course_exercise_from_template`
+- `update_course_exercise`
 - `update_course_draft`
+- `tag_course_draft`
+- `tag_courses`
 - `publish_course_draft`
 - `publish_course_draft_to_existing_course`
 
@@ -139,6 +147,7 @@ Draft payload shape:
 ```text
 draft
   course
+  tags[]
   sections[]
   lessons[]
   lessonLanguages[]
@@ -154,6 +163,31 @@ Drafts support:
 - safer updates to existing courses
 - auditability of AI-generated structure
 
+## 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
@@ -178,6 +212,8 @@ 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: Create a draft from a PDF
 
@@ -202,7 +238,27 @@ Important:
 - the PDF does not need to be uploaded to MCP
 - the MCP package only receives structured JSON
 
-### Flow 3: Update an existing course safely
+### Flow 3: 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 4: Update an existing course safely
 
 User says:
 
@@ -212,19 +268,39 @@ Take my existing Algebra course, reorganize it, and rewrite the lesson content f
 
 Expected tool sequence:
 
-1. Agent calls `get_course_structure` with the existing `courseId`.
-2. Agent optionally calls `create_course_draft_from_course` to persist a seeded draft.
-3. Agent updates the draft with the new structure and content using `update_course_draft`.
-4. User reviews the changes.
-5. Agent calls `publish_course_draft_to_existing_course`.
+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`.
+5. User reviews the changes.
+6. Agent calls `publish_course_draft_to_existing_course`.
 
 What this publish does today:
 
 - updates the existing course title, description, type, and metadata
+- can set a generated course cover from Unsplash
+- returns the public `courseUrl`
 - updates existing sections when the draft keeps their IDs
 - updates existing lessons when the draft keeps their IDs
 - creates new sections and lessons for draft items without matching live IDs
 - upserts lesson language content
+- merges draft tags into the existing course
+
+### Flow 5: Add exercises to a live course
+
+User says:
+
+```text
+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:
 
@@ -253,6 +329,28 @@ For large updates, the agent should:
 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`
+
 ## Operational Notes
 
 - `create_course_draft_from_course` may add warnings if a live course uses legacy lesson notes instead of localized lesson content