gogcli-mcp-classroom 4.4.0 → 4.5.1

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-classroom",
   "display_name": "gogcli (Classroom)",
-  "version": "4.4.0",
+  "version": "4.5.1",
   "description": "Extended Google Classroom for Claude via gogcli — auth + full Classroom support (courses, rosters, coursework, submissions, announcements, topics, invitations)",
   "author": {
     "name": "Chris Hall",
@@ -115,7 +115,7 @@
     },
     {
       "name": "gog_classroom_courses_delete",
-      "description": "Delete a course"
+      "description": "Delete a course (asks the user to confirm)"
     },
     {
       "name": "gog_classroom_courses_archive",
@@ -135,7 +135,7 @@
     },
     {
       "name": "gog_classroom_students_add",
-      "description": "Add a student to a course"
+      "description": "Add a student to a course (asks the user to confirm unless adding yourself)"
     },
     {
       "name": "gog_classroom_students_remove",
@@ -151,7 +151,7 @@
     },
     {
       "name": "gog_classroom_teachers_add",
-      "description": "Add a teacher to a course"
+      "description": "Add a teacher to a course (asks the user to confirm)"
     },
     {
       "name": "gog_classroom_teachers_remove",
@@ -171,15 +171,15 @@
     },
     {
       "name": "gog_classroom_coursework_create",
-      "description": "Create coursework (assignment/question)"
+      "description": "Create coursework (assignment/question) (asks the user to confirm unless an unscheduled DRAFT)"
     },
     {
       "name": "gog_classroom_coursework_update",
-      "description": "Update existing coursework"
+      "description": "Update existing coursework (publishing asks the user to confirm)"
     },
     {
       "name": "gog_classroom_coursework_delete",
-      "description": "Delete coursework"
+      "description": "Delete coursework (asks the user to confirm)"
     },
     {
       "name": "gog_classroom_submissions_list",
@@ -195,7 +195,7 @@
     },
     {
       "name": "gog_classroom_submissions_return",
-      "description": "Return a graded submission"
+      "description": "Return a graded submission (asks the user to confirm)"
     },
     {
       "name": "gog_classroom_submissions_turn_in",
@@ -219,7 +219,7 @@
     },
     {
       "name": "gog_classroom_announcements_update",
-      "description": "Update an announcement"
+      "description": "Update an announcement (publishing asks the user to confirm)"
     },
     {
       "name": "gog_classroom_announcements_delete",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-classroom",
-  "version": "4.4.0",
+  "version": "4.5.1",
   "mcpName": "io.github.chrischall/gogcli-mcp-classroom",
   "description": "Extended Google Classroom MCP server via gogcli — auth + full Classroom support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.4.0",
+    "@chrischall/mcp-utils": "^2.6.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "zod": "^4.6.1"
   },

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp-classroom"
   },
-  "version": "4.4.0",
+  "version": "4.5.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-classroom",
-      "version": "4.4.0",
+      "version": "4.5.1",
       "transport": {
         "type": "stdio"
       },

package/src/tools/classroom-extra.ts

@@ -1,12 +1,44 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, pos, readCourse, requireDispatchConfirmation, CONFIRM_FALLBACK_DESCRIPTION, confirmTokenParam } from '../../../gogcli-mcp/src/lib.js';
+import {
+  accountParam,
+  runOrDiagnose,
+  pos,
+  readCourse,
+  readCoursework,
+  readClassroomWork,
+  requireDispatchConfirmation,
+  bodyPreview,
+  CONFIRM_FALLBACK_DESCRIPTION,
+  confirmTokenParam,
+} from '../../../gogcli-mcp/src/lib.js';
 import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
 const courseState = z.enum(['ACTIVE', 'ARCHIVED', 'PROVISIONED', 'DECLINED', 'SUSPENDED']);
 const workState = z.enum(['PUBLISHED', 'DRAFT']);
 const workType = z.enum(['ASSIGNMENT', 'SHORT_ANSWER_QUESTION', 'MULTIPLE_CHOICE_QUESTION']);
 
+// ============================================================================
+// PUBLISHING THROUGH UPDATE is on the dispatch rail (SEC-3, fleet-audit #932).
+// gog_classroom_announcements_create asks unless the state is DRAFT — the
+// draft path is documented as the way through on a client that cannot be
+// prompted — so create-as-DRAFT then update-to-PUBLISHED was the same two-step
+// around a gate that closed for Gmail drafts. An update that publishes (state
+// PUBLISHED, or a schedule: a scheduled item is a draft that publishes itself)
+// reads the course and the item and asks, with the text or title the class
+// will actually see; a text edit, a due date or a return to DRAFT does not.
+// ============================================================================
+
+/** When an update makes work visible to students, in the words the prompt uses; undefined when it does not. */
+function publishesWhen(state: string | undefined, scheduled: string | undefined): string | undefined {
+  if (scheduled) return `at ${scheduled}`;
+  return state === 'PUBLISHED' ? 'immediately' : undefined;
+}
+
+const PUBLISH_DESCRIPTION = ' Publishing it (state PUBLISHED, or a scheduled time) reads the course and the item and asks the MCP host to '
+  + 'show the user a confirmation prompt with the class and what students will see; nothing is published unless they '
+  + 'accept. Other edits, and a return to DRAFT, need no confirmation.' + CONFIRM_FALLBACK_DESCRIPTION;
+
 // Fields shared by courses_create and courses_update. `name` is required on
 // create, optional on update — keep it out of this fragment so each tool can
 // declare its own rule.
@@ -74,13 +106,33 @@ export function registerExtraClassroomTools(server: McpServer): void {
   });
 
   server.registerTool('gog_classroom_courses_delete', {
-    description: 'Delete a Google Classroom course.',
+    description: 'Delete a Google Classroom course — its coursework, submissions and grades go with it, for good. Reads '
+      + 'the course and asks the MCP host to show the user a confirmation prompt naming it first; nothing is deleted '
+      + 'unless they accept. gog_classroom_courses_archive is the reversible alternative.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, account }) => {
+  }, async ({ courseId, account, confirmToken }, ctx) => {
+    const read = await readCourse(courseId, account, runOrDiagnose);
+    if (read.error) return read.error;
+    const view = { course: read.course, deletes: 'the course with all of its coursework, submissions and grades, for good' };
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'classroom.course-delete',
+      message: 'Review and confirm PERMANENTLY deleting this course:',
+      confirmationLabel: 'Confirm that this course should be deleted now.',
+      details: view,
+      unsupportedNote: 'Archive it with gog_classroom_courses_archive instead, or ask the user to delete it from Classroom.',
+      fallback: {
+        tool: 'gog_classroom_courses_delete',
+        account,
+        confirmToken,
+        subject: () => ({ target: courseId, payload: view, preview: view }),
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(['classroom', 'courses', 'delete', pos(courseId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
@@ -107,17 +159,39 @@ export function registerExtraClassroomTools(server: McpServer): void {
   });
 
   server.registerTool('gog_classroom_students_add', {
-    description: 'Add a student to a Google Classroom course.',
+    description: 'Add a student to a Google Classroom course. Adding someone else gives them the class stream and '
+      + 'materials, so this reads the course and asks the MCP host to show the user a confirmation prompt with the class '
+      + 'and the student first; enrolling yourself ("me") does not ask.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
-      userId: z.string().describe('Student user ID (or "me")'),
+      userId: z.string().describe('Student user ID or email (or "me")'),
       enrollmentCode: z.string().optional().describe('Enrollment code (required if adding self via code)'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, userId, enrollmentCode, account }) => {
+  }, async ({ courseId, userId, enrollmentCode, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['classroom', 'students', 'add', pos(courseId), pos(userId)];
     if (enrollmentCode) args.push(`--enrollment-code=${enrollmentCode}`);
+    if (userId.toLowerCase() !== 'me') {
+      const read = await readCourse(courseId, account, runOrDiagnose);
+      if (read.error) return read.error;
+      const view = { course: read.course, student: userId };
+      const confirmation = await requireDispatchConfirmation(ctx, {
+        action: 'classroom.student-add',
+        message: 'Review and confirm adding this student to the class:',
+        confirmationLabel: 'Confirm that this person should be added to the class now.',
+        details: view,
+        unsupportedNote: 'Ask the user to add them from Classroom, or invite them with gog_classroom_invitations_create.',
+        fallback: {
+          tool: 'gog_classroom_students_add',
+          account,
+          confirmToken,
+          subject: () => ({ target: `${courseId}/${userId}`, payload: view, preview: view }),
+        },
+      });
+      if (confirmation) return confirmation;
+    }
     return runOrDiagnose(args, { account });
   });
 
@@ -134,14 +208,34 @@ export function registerExtraClassroomTools(server: McpServer): void {
   });
 
   server.registerTool('gog_classroom_teachers_add', {
-    description: 'Add a teacher to a Google Classroom course.',
+    description: 'Add a teacher to a Google Classroom course. A co-teacher sees every student\'s work and grades, so '
+      + 'this reads the course and asks the MCP host to show the user a confirmation prompt with the class and the '
+      + 'teacher first; nothing changes unless they accept.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
-      userId: z.string().describe('Teacher user ID'),
+      userId: z.string().describe('Teacher user ID or email'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, userId, account }) => {
+  }, async ({ courseId, userId, account, confirmToken }, ctx) => {
+    const read = await readCourse(courseId, account, runOrDiagnose);
+    if (read.error) return read.error;
+    const view = { course: read.course, teacher: userId, grants: 'teacher access: every student\'s work, grades and roster' };
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'classroom.teacher-add',
+      message: 'Review and confirm giving this person teacher access to the class:',
+      confirmationLabel: 'Confirm that this person should become a teacher of the class now.',
+      details: view,
+      unsupportedNote: 'Ask the user to add them from Classroom, or invite them with gog_classroom_invitations_create.',
+      fallback: {
+        tool: 'gog_classroom_teachers_add',
+        account,
+        confirmToken,
+        subject: () => ({ target: `${courseId}/${userId}`, payload: view, preview: view }),
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(['classroom', 'teachers', 'add', pos(courseId), pos(userId)], { account });
   });
 
@@ -158,15 +252,20 @@ export function registerExtraClassroomTools(server: McpServer): void {
   });
 
   server.registerTool('gog_classroom_coursework_create', {
-    description: 'Create a new coursework item (assignment, question, etc.) in a course.',
+    description: 'Create a new coursework item (assignment, question, etc.) in a course. Unless state is DRAFT with no '
+      + 'scheduled time (which students cannot see; a scheduled draft publishes itself), the class is notified, so this '
+      + 'reads the course and asks the MCP host to show the user a confirmation prompt with the class, the title, the '
+      + 'text, the due date and when it publishes; nothing is posted unless they accept. To stage one without asking, '
+      + 'pass state DRAFT and no scheduled time.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
       title: z.string().describe('Coursework title'),
       ...courseworkSharedFields,
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, title, description, type, state, maxPoints, due, dueDate, dueTime, scheduled, topic, account }) => {
+  }, async ({ courseId, title, description, type, state, maxPoints, due, dueDate, dueTime, scheduled, topic, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['classroom', 'coursework', 'create', pos(courseId), `--title=${title}`];
     if (description) args.push(`--description=${description}`);
     if (type) args.push(`--type=${type}`);
@@ -177,11 +276,42 @@ export function registerExtraClassroomTools(server: McpServer): void {
     if (dueTime) args.push(`--due-time=${dueTime}`);
     if (scheduled) args.push(`--scheduled=${scheduled}`);
     if (topic) args.push(`--topic=${topic}`);
+    // An unscheduled draft reaches nobody until a teacher publishes it; a
+    // scheduled one publishes itself.
+    if (state !== 'DRAFT' || scheduled) {
+      const read = await readCourse(courseId, account, runOrDiagnose);
+      if (read.error) return read.error;
+      const work = {
+        course: read.course,
+        title,
+        type: type ?? 'ASSIGNMENT',
+        publishes: scheduled ? `at ${scheduled}` : 'immediately',
+        due: due ?? ([dueDate, dueTime].filter(Boolean).join(' ') || undefined),
+        maxPoints,
+      };
+      const confirmation = await requireDispatchConfirmation(ctx, {
+        action: 'classroom.coursework-create',
+        message: 'Review and confirm posting this coursework to the class:',
+        confirmationLabel: 'Confirm that this coursework should be posted to the class.',
+        details: { ...work, descriptionPreview: bodyPreview(description) },
+        unsupportedNote: 'Create it with state DRAFT instead; the user can review and post it from Classroom.',
+        fallback: {
+          tool: 'gog_classroom_coursework_create',
+          account,
+          confirmToken,
+          subject: () => {
+            const view = { ...work, description };
+            return { target: courseId, payload: view, preview: view };
+          },
+        },
+      });
+      if (confirmation) return confirmation;
+    }
     return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_classroom_coursework_update', {
-    description: 'Update an existing coursework item.',
+    description: 'Update an existing coursework item.' + PUBLISH_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
@@ -189,8 +319,9 @@ export function registerExtraClassroomTools(server: McpServer): void {
       title: z.string().optional().describe('New title'),
       ...courseworkSharedFields,
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, courseworkId, title, description, type, state, maxPoints, due, dueDate, dueTime, scheduled, topic, account }) => {
+  }, async ({ courseId, courseworkId, title, description, type, state, maxPoints, due, dueDate, dueTime, scheduled, topic, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['classroom', 'coursework', 'update', pos(courseId), pos(courseworkId)];
     if (title) args.push(`--title=${title}`);
     if (description) args.push(`--description=${description}`);
@@ -202,37 +333,134 @@ export function registerExtraClassroomTools(server: McpServer): void {
     if (dueTime) args.push(`--due-time=${dueTime}`);
     if (scheduled) args.push(`--scheduled=${scheduled}`);
     if (topic) args.push(`--topic=${topic}`);
+    const publishes = publishesWhen(state, scheduled);
+    if (publishes) {
+      const read = await readCourse(courseId, account, runOrDiagnose);
+      if (read.error) return read.error;
+      const current = await readClassroomWork('coursework', courseId, courseworkId, account, runOrDiagnose);
+      if (current.error) return current.error;
+      // What the class will see: the new title/description when this call
+      // replaces them, else what the draft says now. `||`, not `??`: an empty
+      // string is never sent (the argv guards above are truthy checks), so gog
+      // keeps the current value and the prompt must show that one.
+      const published = description || current.work.description;
+      const publishedTitle = title || current.work.title;
+      const view = {
+        course: read.course,
+        coursework: { id: courseworkId, title: publishedTitle, state: current.work.state },
+        publishes,
+        descriptionPreview: bodyPreview(published),
+      };
+      const confirmation = await requireDispatchConfirmation(ctx, {
+        action: 'classroom.coursework-publish',
+        message: 'Review and confirm publishing this Classroom coursework to students:',
+        confirmationLabel: 'Confirm that this coursework should be published to the class.',
+        details: view,
+        unsupportedNote: 'Leave it as a DRAFT; the user can review and publish it from Classroom.',
+        fallback: {
+          tool: 'gog_classroom_coursework_update',
+          account,
+          confirmToken,
+          subject: () => ({
+            target: `${courseId}/${courseworkId}`,
+            revision: current.work.updateTime,
+            payload: { course: read.course, courseworkId, title: publishedTitle, description: published, type, state, maxPoints, due, dueDate, dueTime, scheduled, topic },
+            preview: view,
+          }),
+        },
+      });
+      if (confirmation) return confirmation;
+    }
     return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_classroom_coursework_delete', {
-    description: 'Delete a coursework item.',
+    description: 'Delete a coursework item — every student submission to it goes too, for good. Reads the course and '
+      + 'the coursework and asks the MCP host to show the user a confirmation prompt naming both first; nothing is '
+      + 'deleted unless they accept.' + CONFIRM_FALLBACK_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
       courseworkId: z.string().describe('Coursework ID'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, courseworkId, account }) => {
+  }, async ({ courseId, courseworkId, account, confirmToken }, ctx) => {
+    const course = await readCourse(courseId, account, runOrDiagnose);
+    if (course.error) return course.error;
+    const work = await readCoursework(courseId, courseworkId, account, runOrDiagnose);
+    if (work.error) return work.error;
+    const view = { course: course.course, coursework: work.coursework, deletes: 'the coursework and every student submission to it, for good' };
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'classroom.coursework-delete',
+      message: 'Review and confirm PERMANENTLY deleting this coursework and its submissions:',
+      confirmationLabel: 'Confirm that this coursework should be deleted now.',
+      details: view,
+      unsupportedNote: 'Ask the user to delete it from Classroom.',
+      fallback: {
+        tool: 'gog_classroom_coursework_delete',
+        account,
+        confirmToken,
+        subject: () => ({ target: `${courseId}/${courseworkId}`, payload: view, preview: view }),
+      },
+    });
+    if (confirmation) return confirmation;
     return runOrDiagnose(['classroom', 'coursework', 'delete', pos(courseId), pos(courseworkId), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_classroom_announcements_update', {
-    description: 'Update an existing announcement.',
+    description: 'Update an existing announcement.' + PUBLISH_DESCRIPTION,
     annotations: { destructiveHint: true },
     inputSchema: z.object({
       courseId: z.string().describe('Course ID'),
       announcementId: z.string().describe('Announcement ID'),
       text: z.string().optional().describe('New text'),
-      state: workState.optional().describe('State'),
-      scheduled: z.string().optional().describe('Scheduled publish time'),
+      state: workState.optional().describe('State (PUBLISHED asks the user to confirm; DRAFT does not)'),
+      scheduled: z.string().optional().describe('Scheduled publish time (asks the user to confirm)'),
       account: accountParam,
+      confirmToken: confirmTokenParam,
     }),
-  }, async ({ courseId, announcementId, text, state, scheduled, account }) => {
+  }, async ({ courseId, announcementId, text, state, scheduled, account, confirmToken }, ctx) => {
     const args: GogArg[] = ['classroom', 'announcements', 'update', pos(courseId), pos(announcementId)];
     if (text) args.push(`--text=${text}`);
     if (state) args.push(`--state=${state}`);
     if (scheduled) args.push(`--scheduled=${scheduled}`);
+    const publishes = publishesWhen(state, scheduled);
+    if (publishes) {
+      const read = await readCourse(courseId, account, runOrDiagnose);
+      if (read.error) return read.error;
+      const current = await readClassroomWork('announcements', courseId, announcementId, account, runOrDiagnose);
+      if (current.error) return current.error;
+      // The text the class will see: the new one when this call replaces it,
+      // else what the draft says now. `||`, not `??`: an empty --text is never
+      // sent, so gog keeps the current text.
+      const published = text || current.work.text;
+      const view = {
+        course: read.course,
+        announcement: { id: announcementId, state: current.work.state },
+        publishes,
+        textPreview: bodyPreview(published),
+      };
+      const confirmation = await requireDispatchConfirmation(ctx, {
+        action: 'classroom.announcement-publish',
+        message: 'Review and confirm publishing this Classroom announcement to the class:',
+        confirmationLabel: 'Confirm that this announcement should be published to the class.',
+        details: view,
+        unsupportedNote: 'Leave it as a DRAFT; the user can review and publish it from Classroom.',
+        fallback: {
+          tool: 'gog_classroom_announcements_update',
+          account,
+          confirmToken,
+          subject: () => ({
+            target: `${courseId}/${announcementId}`,
+            revision: current.work.updateTime,
+            payload: { course: read.course, announcementId, text: published, state, scheduled },
+            preview: view,
+          }),
+        },
+      });
+      if (confirmation) return confirmation;
+    }
     return runOrDiagnose(args, { account });
   });