@epic-web/workshop-mcp 6.60.0 → 6.61.0

package/dist/server-metadata.d.ts

@@ -110,6 +110,60 @@ export declare const toolDocs: {
             openWorldHint: false;
         };
     };
+    list_saved_playgrounds: {
+        title: string;
+        summary: string;
+        inputs: {
+            name: string;
+            type: string;
+            required: true;
+            description: string;
+            examples: string[];
+        }[];
+        returns: string;
+        examples: {
+            description: string;
+            params: string;
+        }[];
+        nextSteps: string[];
+        errorNextSteps: string[];
+        annotations: {
+            readOnlyHint: true;
+            destructiveHint: false;
+            idempotentHint: true;
+            openWorldHint: false;
+        };
+    };
+    set_saved_playground: {
+        title: string;
+        summary: string;
+        inputs: ({
+            name: string;
+            type: string;
+            required: true;
+            description: string;
+            examples: string[];
+        } | {
+            name: string;
+            type: string;
+            required: false;
+            description: string;
+            examples: string[];
+        })[];
+        returns: string;
+        examples: {
+            description: string;
+            params: string;
+        }[];
+        nextSteps: string[];
+        errorNextSteps: string[];
+        annotations: {
+            readOnlyHint: false;
+            destructiveHint: false;
+            idempotentHint: false;
+            openWorldHint: false;
+        };
+    };
     update_progress: {
         title: string;
         summary: string;

package/dist/server-metadata.js

@@ -5,6 +5,7 @@ Quick start
 - Use \`set_playground\` to move to a step, then \`open_exercise_step_files\` to open relevant files.
 
 Default behavior
+- Use \`list_saved_playgrounds\` and \`set_saved_playground\` to restore saved copies when persistence is enabled.
 - \`workshopDirectory\` is required and must be an absolute path to the workshop root.
 - Passing a \`/playground\` path is normalized to the workshop root.
 - The user's work-in-progress lives in the \`playground\` directory.
@@ -141,6 +142,88 @@ export const toolDocs = {
             openWorldHint: false,
         },
     },
+    list_saved_playgrounds: {
+        title: 'List Saved Playgrounds',
+        summary: 'List saved playground copies when playground persistence is enabled.',
+        inputs: [
+            {
+                name: 'workshopDirectory',
+                type: 'string',
+                required: true,
+                description: 'Absolute path to the workshop root.',
+                examples: ['/Users/alice/workshops/react-fundamentals'],
+            },
+        ],
+        returns: '{ savedPlaygrounds: [{ id, appName, displayName, createdAt, createdAtMs, fullPath }] }',
+        examples: [
+            {
+                description: 'List saved playgrounds',
+                params: '{ "workshopDirectory": "/Users/alice/workshops/react" }',
+            },
+        ],
+        nextSteps: [
+            'Call `set_saved_playground` with a savedPlaygroundId to restore a copy.',
+        ],
+        errorNextSteps: [
+            'Enable playground persistence in Preferences and set the playground at least once.',
+        ],
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    set_saved_playground: {
+        title: 'Set Saved Playground',
+        summary: 'Restore the playground from a saved copy.',
+        inputs: [
+            {
+                name: 'workshopDirectory',
+                type: 'string',
+                required: true,
+                description: 'Absolute path to the workshop root.',
+                examples: ['/Users/alice/workshops/react-fundamentals'],
+            },
+            {
+                name: 'savedPlaygroundId',
+                type: 'string',
+                required: false,
+                description: 'Saved playground id (directory name). Omit to restore the most recent saved copy.',
+                examples: ['2026.01.18_11.12.00_01.01.problem'],
+            },
+            {
+                name: 'latest',
+                type: 'boolean',
+                required: false,
+                description: 'Use the most recent saved playground when true.',
+                examples: ['true'],
+            },
+        ],
+        returns: '{ savedPlayground: { id, appName, displayName, createdAt, fullPath } }',
+        examples: [
+            {
+                description: 'Restore the most recent saved playground',
+                params: '{ "workshopDirectory": "/Users/alice/workshops/react" }',
+            },
+            {
+                description: 'Restore a specific saved playground',
+                params: '{ "workshopDirectory": "/Users/alice/workshops/react", "savedPlaygroundId": "2026.01.18_11.12.00_01.01.problem" }',
+            },
+        ],
+        nextSteps: [
+            'Open relevant files with `open_exercise_step_files` or `open_file`.',
+        ],
+        errorNextSteps: [
+            'Call `list_saved_playgrounds` to get valid savedPlaygroundId values.',
+        ],
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    },
     update_progress: {
         title: 'Update Progress',
         summary: 'Mark an Epic lesson as complete or incomplete for the current user.',

package/dist/tools.js

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import { invariant } from '@epic-web/invariant';
-import { getAppByName, getApps, getExercise, getExerciseApp, getExercises, getPlaygroundApp, getPlaygroundAppName, isExerciseStepApp, isProblemApp, setPlayground, } from '@epic-web/workshop-utils/apps.server';
+import { getAppByName, getAppDisplayName, getApps, getExercise, getExerciseApp, getExercises, getPlaygroundApp, getPlaygroundAppName, getSavedPlaygrounds, isExerciseStepApp, isProblemApp, setPlayground, } from '@epic-web/workshop-utils/apps.server';
 import { deleteCache } from '@epic-web/workshop-utils/cache.server';
 import { getWorkshopConfig } from '@epic-web/workshop-utils/config.server';
-import { getAuthInfo, logout, setAuthInfo, } from '@epic-web/workshop-utils/db.server';
+import { getAuthInfo, getPreferences, logout, setAuthInfo, } from '@epic-web/workshop-utils/db.server';
 import { getDiffFiles } from '@epic-web/workshop-utils/diff.server';
 import { getProgress, getUserInfo, updateProgress, } from '@epic-web/workshop-utils/epic-api.server';
 import { launchEditor } from '@epic-web/workshop-utils/launch-editor.server';
@@ -62,6 +62,15 @@ function createToolErrorResult(toolName, error) {
     });
     return { ...response, isError: true };
 }
+function formatSavedPlaygroundTimestamp(createdAt) {
+    const createdAtDate = new Date(createdAt);
+    if (Number.isNaN(createdAtDate.getTime()))
+        return createdAt;
+    return new Intl.DateTimeFormat(undefined, {
+        dateStyle: 'medium',
+        timeStyle: 'short',
+    }).format(createdAtDate);
+}
 function parseResourceText(resource) {
     if (typeof resource.text === 'string') {
         try {
@@ -308,6 +317,82 @@ export function initTools(server) {
             },
         });
     });
+    registerTool(server, 'list_saved_playgrounds', {
+        workshopDirectory: workshopDirectoryInputSchema,
+    }, async ({ workshopDirectory }) => {
+        await handleWorkshopDirectory(workshopDirectory);
+        const persistEnabled = (await getPreferences())?.playground?.persist ?? false;
+        invariant(persistEnabled, 'Playground persistence is disabled. Enable it in Preferences to use saved playgrounds.');
+        const [savedPlaygrounds, apps] = await Promise.all([
+            getSavedPlaygrounds(),
+            getApps(),
+        ]);
+        const savedPlaygroundEntries = savedPlaygrounds.map((entry) => {
+            const matchingApp = apps.find((app) => app.name === entry.appName);
+            const displayName = matchingApp
+                ? getAppDisplayName(matchingApp, apps)
+                : entry.appName;
+            return { ...entry, displayName };
+        });
+        const details = savedPlaygroundEntries.slice(0, 5).map((entry) => {
+            const timestamp = formatSavedPlaygroundTimestamp(entry.createdAt);
+            return `${entry.displayName} (${entry.appName}) — ${timestamp} — ${entry.id}`;
+        });
+        const summary = savedPlaygroundEntries.length
+            ? `${savedPlaygroundEntries.length} saved playgrounds found.`
+            : 'No saved playgrounds found.';
+        return createToolResponse({
+            toolName: 'list_saved_playgrounds',
+            summary,
+            details: details.length ? details : undefined,
+            structuredContent: {
+                savedPlaygrounds: savedPlaygroundEntries,
+            },
+        });
+    });
+    registerTool(server, 'set_saved_playground', {
+        workshopDirectory: workshopDirectoryInputSchema,
+        savedPlaygroundId: z
+            .string()
+            .optional()
+            .describe('Saved playground id to restore (directory name).'),
+        latest: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Use the most recent saved playground when true.'),
+    }, async ({ workshopDirectory, savedPlaygroundId, latest }) => {
+        await handleWorkshopDirectory(workshopDirectory);
+        const persistEnabled = (await getPreferences())?.playground?.persist ?? false;
+        invariant(persistEnabled, 'Playground persistence is disabled. Enable it in Preferences to use saved playgrounds.');
+        const [savedPlaygrounds, apps] = await Promise.all([
+            getSavedPlaygrounds(),
+            getApps(),
+        ]);
+        invariant(savedPlaygrounds.length, 'No saved playgrounds found.');
+        const useLatest = latest || !savedPlaygroundId;
+        const selected = savedPlaygroundId
+            ? savedPlaygrounds.find((entry) => entry.id === savedPlaygroundId)
+            : useLatest
+                ? savedPlaygrounds[0]
+                : undefined;
+        invariant(selected, `Saved playground not found: ${savedPlaygroundId}`);
+        await setPlayground(selected.fullPath);
+        const matchingApp = apps.find((app) => app.name === selected.appName);
+        const displayName = matchingApp
+            ? getAppDisplayName(matchingApp, apps)
+            : selected.appName;
+        return createToolResponse({
+            toolName: 'set_saved_playground',
+            summary: `Playground set from saved copy: ${displayName}.`,
+            structuredContent: {
+                savedPlayground: {
+                    ...selected,
+                    displayName,
+                },
+            },
+        });
+    });
     registerTool(server, 'update_progress', {
         workshopDirectory: workshopDirectoryInputSchema,
         epicLessonSlug: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epic-web/workshop-mcp",
-  "version": "6.60.0",
+  "version": "6.61.0",
   "publishConfig": {
     "access": "public"
   },
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@epic-web/invariant": "^1.0.0",
-    "@epic-web/workshop-utils": "6.60.0",
+    "@epic-web/workshop-utils": "6.61.0",
     "@mcp-ui/server": "^5.13.1",
     "@modelcontextprotocol/sdk": "^1.21.1",
     "@sentry/node": "^10.25.0",