feat(learning): guided tours that teach by driving the UI#3334
feat(learning): guided tours that teach by driving the UI#3334chelojimenez wants to merge 1 commit into
Conversation
Add a "Guided tours" group to the Learning tab. Selecting a tour launches the MCPJam agent in the side panel seeded with a lesson prompt (as the user's first message); the agent teaches by driving the inspector through the existing ui_* tool catalog — navigate, narrate each screen, prefill forms, and hand the final consequential click back to the user. Client-only, no webmcp-framework/inspector-command/backend changes: - learning-concepts: LearningConcept | GuidedTourConcept discriminated union; 5 tours + shared ground rules in guided-tour-lessons.ts - extract the mcpjam:agent-pending: convention into a shared pending-prompt helper (was inline in 3 files) and reuse it - launch-lesson.ts replicates the panel's session-start ordering (pending write before setActiveSession), guards null projectId and same-tour double-click; telemetry mcpjam_agent_tour_launched/_skipped - projectId reaches LearningTab via useAppRouteContext().activeProjectId; guests have a non-null synthetic id, so no guest special-casing Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
dosubot
Bot
added
size:L
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_53d497d6-aad8-4543-80cf-0083c6f24da6) |
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
Internal previewPreview URL: https://mcp-inspector-pr-3334.up.railway.app |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (15)
WalkthroughThe learning model now supports guided tours alongside reading modules. Guided tours are displayed with badges and play affordances, and selecting one launches an agent session using the active project context. Shared helpers handle pending prompt storage and cleanup across session-start and thread components. New analytics events record skipped and successful launches. Tests cover guided-tour rendering, dispatch, prompt invariants, session lifecycle, telemetry, refocusing, and storage failures. Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
mcpjam-inspector/client/src/App.tsxOops! Something went wrong! :( ESLint: 8.57.1 Error: ESLint configuration in --config is invalid:
mcpjam-inspector/client/src/components/HomeTab.tsxOops! Something went wrong! :( ESLint: 8.57.1 Error: ESLint configuration in --config is invalid:
mcpjam-inspector/client/src/components/LearningLandingPage.tsxOops! Something went wrong! :( ESLint: 8.57.1 Error: ESLint configuration in --config is invalid:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
6 issues found across 15 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="mcpjam-inspector/client/src/components/__tests__/LearningLandingPage.tours.test.tsx">
<violation number="1" location="mcpjam-inspector/client/src/components/__tests__/LearningLandingPage.tours.test.tsx:37">
P3: Test name mentions 'play affordance' but the body doesn't assert it — either add an assertion for the Play icon or remove it from the description so the test name stays truthful.</violation>
</file>
<file name="mcpjam-inspector/client/src/components/LearningTab.tsx">
<violation number="1" location="mcpjam-inspector/client/src/components/LearningTab.tsx:358">
P2: Launching a tour with no active project starts an autosubmitted agent session scoped to the `"none"` sentinel instead of taking the intended no-project skip path. Normalize this sentinel to `null` before launching so the panel does not treat it as a resolved workspace.</violation>
</file>
<file name="mcpjam-inspector/client/src/components/lifecycle/guided-tour-lessons.ts">
<violation number="1" location="mcpjam-inspector/client/src/components/lifecycle/guided-tour-lessons.ts:107">
P2: The eval tour promises fields the agent cannot prefill, so this step leaves the test prompt and expected-call configuration for the user despite saying the agent filled them. Limit the prompt to the name prefill and have it describe the remaining values for the user to enter.</violation>
<violation number="2" location="mcpjam-inspector/client/src/components/lifecycle/guided-tour-lessons.ts:129">
P2: The agent has no persona-prefill operation: following this step with the available tool creates and selects a persistent persona rather than leaving a form for review. Ask the user to enter and create the suggested persona instead.</violation>
<violation number="3" location="mcpjam-inspector/client/src/components/lifecycle/guided-tour-lessons.ts:150">
P2: The available host operations commit both creation and server attachment, so the agent cannot perform this prefill while leaving the final Create/Save click to the user. Have the tour explain and suggest the values for the user to enter instead.</violation>
</file>
<file name="mcpjam-inspector/client/src/lib/mcpjam-agent/launch-lesson.ts">
<violation number="1" location="mcpjam-inspector/client/src/lib/mcpjam-agent/launch-lesson.ts:65">
P2: Re-clicking a tour after a project switch can refocus its previous project's session, so the panel's project-match gate shows the empty hero. Include `activeSessionProjectId` in the refocus condition so this path creates a session scoped to the current project.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| (id: string) => { | ||
| const tour = getGuidedTour(id); | ||
| if (tour) { | ||
| launchLessonSession({ tour, projectId }); |
There was a problem hiding this comment.
P2: Launching a tour with no active project starts an autosubmitted agent session scoped to the "none" sentinel instead of taking the intended no-project skip path. Normalize this sentinel to null before launching so the panel does not treat it as a resolved workspace.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At mcpjam-inspector/client/src/components/LearningTab.tsx, line 358:
<comment>Launching a tour with no active project starts an autosubmitted agent session scoped to the `"none"` sentinel instead of taking the intended no-project skip path. Normalize this sentinel to `null` before launching so the panel does not treat it as a resolved workspace.</comment>
<file context>
@@ -335,13 +337,32 @@ function AppsSdkWalkthrough({
+ (id: string) => {
+ const tour = getGuidedTour(id);
+ if (tour) {
+ launchLessonSession({ tour, projectId });
+ return;
+ }
</file context>
| launchLessonSession({ tour, projectId }); | |
| launchLessonSession({ | |
| tour, | |
| projectId: projectId === "none" ? null : projectId, | |
| }); |
| 1. In a couple of sentences, what a Host is — a named bundle of MCP servers exposed together to a client — and when I'd want one. | ||
| 2. Snapshot my state so we can use my actual connected server(s). If I have none, detour and help me connect one first. | ||
| 3. Take me to Hosts and open the host editor. | ||
| 4. Prefill a new host: give it a clear name and attach my connected server(s). Explain each part as you fill it in. |
There was a problem hiding this comment.
P2: The available host operations commit both creation and server attachment, so the agent cannot perform this prefill while leaving the final Create/Save click to the user. Have the tour explain and suggest the values for the user to enter instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At mcpjam-inspector/client/src/components/lifecycle/guided-tour-lessons.ts, line 150:
<comment>The available host operations commit both creation and server attachment, so the agent cannot perform this prefill while leaving the final Create/Save click to the user. Have the tour explain and suggest the values for the user to enter instead.</comment>
<file context>
@@ -0,0 +1,161 @@
+1. In a couple of sentences, what a Host is — a named bundle of MCP servers exposed together to a client — and when I'd want one.
+2. Snapshot my state so we can use my actual connected server(s). If I have none, detour and help me connect one first.
+3. Take me to Hosts and open the host editor.
+4. Prefill a new host: give it a clear name and attach my connected server(s). Explain each part as you fill it in.
+5. Explain what I'll be able to do with the Host once it exists.
+6. Stop and hand me the create/save button — tell me exactly what to click to finish.
</file context>
| 1. In a couple of sentences, what Swarms are — synthetic user personas that run through journeys against my server — and why that's useful. | ||
| 2. Snapshot my state. Swarms need a connected server; if I don't have one, detour and help me connect one first. | ||
| 3. Take me to Swarms and explain the pieces: personas and journeys. | ||
| 4. Explain what a persona is, then prefill one that fits my server. |
There was a problem hiding this comment.
P2: The agent has no persona-prefill operation: following this step with the available tool creates and selects a persistent persona rather than leaving a form for review. Ask the user to enter and create the suggested persona instead.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At mcpjam-inspector/client/src/components/lifecycle/guided-tour-lessons.ts, line 129:
<comment>The agent has no persona-prefill operation: following this step with the available tool creates and selects a persistent persona rather than leaving a form for review. Ask the user to enter and create the suggested persona instead.</comment>
<file context>
@@ -0,0 +1,161 @@
+1. In a couple of sentences, what Swarms are — synthetic user personas that run through journeys against my server — and why that's useful.
+2. Snapshot my state. Swarms need a connected server; if I don't have one, detour and help me connect one first.
+3. Take me to Swarms and explain the pieces: personas and journeys.
+4. Explain what a persona is, then prefill one that fits my server.
+5. Explain what a journey is, then prefill one that this persona would plausibly attempt with my server's tools.
+6. Explain that launching a swarm run consumes run quota and model calls. Stop before launching — hand me the launch button and let me decide.
</file context>
| 1. In a couple of sentences, what evals are for in MCPJam — testing that a model uses my MCP server's tools correctly. | ||
| 2. Check my current state. I need a connected MCP server to eval against; if I don't have one, help me connect one first. | ||
| 3. Take me to the evals area and explain what I'm looking at. | ||
| 4. Open the form to create a new eval suite and prefill it with a sensible example based on the tools my connected server actually exposes: a suite name, a test prompt a real user might ask, and the tool(s) you expect the model to call. Explain what each field means, especially how expected tool calls are judged. |
There was a problem hiding this comment.
P2: The eval tour promises fields the agent cannot prefill, so this step leaves the test prompt and expected-call configuration for the user despite saying the agent filled them. Limit the prompt to the name prefill and have it describe the remaining values for the user to enter.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At mcpjam-inspector/client/src/components/lifecycle/guided-tour-lessons.ts, line 107:
<comment>The eval tour promises fields the agent cannot prefill, so this step leaves the test prompt and expected-call configuration for the user despite saying the agent filled them. Limit the prompt to the name prefill and have it describe the remaining values for the user to enter.</comment>
<file context>
@@ -0,0 +1,161 @@
+1. In a couple of sentences, what evals are for in MCPJam — testing that a model uses my MCP server's tools correctly.
+2. Check my current state. I need a connected MCP server to eval against; if I don't have one, help me connect one first.
+3. Take me to the evals area and explain what I'm looking at.
+4. Open the form to create a new eval suite and prefill it with a sensible example based on the tools my connected server actually exposes: a suite name, a test prompt a real user might ask, and the tool(s) you expect the model to call. Explain what each field means, especially how expected tool calls are judged.
+5. If there's a way to generate test cases automatically, mention it and what it costs before suggesting it.
+6. Stop before running anything. Tell me exactly which button to press to save and run the suite, warn me that running it calls a real model, and let me decide.
</file context>
|
|
||
| if ( | ||
| lastLaunch?.tourId === tour.id && | ||
| panel.activeSessionId === lastLaunch.sessionId |
There was a problem hiding this comment.
P2: Re-clicking a tour after a project switch can refocus its previous project's session, so the panel's project-match gate shows the empty hero. Include activeSessionProjectId in the refocus condition so this path creates a session scoped to the current project.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At mcpjam-inspector/client/src/lib/mcpjam-agent/launch-lesson.ts, line 65:
<comment>Re-clicking a tour after a project switch can refocus its previous project's session, so the panel's project-match gate shows the empty hero. Include `activeSessionProjectId` in the refocus condition so this path creates a session scoped to the current project.</comment>
<file context>
@@ -0,0 +1,107 @@
+
+ if (
+ lastLaunch?.tourId === tour.id &&
+ panel.activeSessionId === lastLaunch.sessionId
+ ) {
+ // Same tour, session still active — just bring the panel back into view.
</file context>
| expect(totals.textContent).toContain("16 lessons"); | ||
| }); | ||
|
|
||
| it("renders a guided row with a Guided badge, play affordance, and duration", () => { |
There was a problem hiding this comment.
P3: Test name mentions 'play affordance' but the body doesn't assert it — either add an assertion for the Play icon or remove it from the description so the test name stays truthful.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At mcpjam-inspector/client/src/components/__tests__/LearningLandingPage.tours.test.tsx, line 37:
<comment>Test name mentions 'play affordance' but the body doesn't assert it — either add an assertion for the Play icon or remove it from the description so the test name stays truthful.</comment>
<file context>
@@ -0,0 +1,75 @@
+ expect(totals.textContent).toContain("16 lessons");
+ });
+
+ it("renders a guided row with a Guided badge, play affordance, and duration", () => {
+ renderPage();
+ expandGuidedTours();
</file context>
1 participant
What
Adds a Guided tours group to the Learning tab. Instead of routing to a static article, selecting a tour launches the MCPJam agent in the side panel seeded with a lesson prompt (rendered as the user's first message). The agent then teaches by driving the real inspector UI through the existing
ui_*tool catalog — navigate, narrate each screen, prefill forms, and hand the final consequential click back to the user.Five tours over the core funnel: connect a server, run a tool in the Playground, create & run an eval suite, simulate users with Swarms, package servers into a Host.
Plan + UX mockups: https://claude.ai/code/artifact/8702f480-c7f3-4c86-b0d4-5815923464c3
Why this is safe/small
The
ui_*agent-tools framework already gives show-don't-tell for free: every agent action is a visible UI action, prefill tools stop at the form, and destructive/billable tools gate behind the confirmation pill and the buttons' billing gates. The only missing piece was a launcher — and the side panel already had a pending-prompt seeding mechanism to reuse.Client-only. No
client/src/lib/webmcp/framework changes, no new inspector commands, no backend, no system-prompt changes (the lesson rides as the user's first message).How
learning-concepts.tsbecomes aLearningConcept | GuidedTourConceptdiscriminated union (kind: "guided"carries a requiredagentPrompt, nototalSteps). Tours + shared ground rules (narrate-before-act, snapshot-first, prefill-never-submit, ask-before-spend, end-with-mark-complete) live in newguided-tour-lessons.ts.mcpjam:agent-pending:convention (previously inline inAgentSidePanel/HomeTab/McpjamAgentThread) into a sharedpending-prompt.tshelper and reused it.launch-lesson.tsreplicates the panel's own session-start ordering (pending write beforesetActiveSession, which mounts the thread whose optimistic-bubble peek reads the key), with a null-projectIdskip and a same-tour double-click refocus guard. Telemetry:mcpjam_agent_tour_launched/mcpjam_agent_tour_launch_skipped.LearningTabviauseAppRouteContext().activeProjectId(the established route pattern). Guests get a non-null synthetic id, so no guest special-casing.Not in v1 (deliberate)
Auto-complete on tour finish (manual checkbox stays), a
ui_highlightcoach-mark tool, a lesson-script engine, and anyapp-surfaces.tschange (the agent never operates the Learning surface itself).Testing
npm run typecheck:client— clean.launch-lesson.test.ts,pending-prompt.test.ts,LearningLandingPage.tours.test.tsx,LearningTab.tours.test.tsx(20 tests).client/src/lib/mcpjam-agent,client/src/lib/webmcp(coverage suites — no framework drift), analytics ratchet (306 tests total).Manual: Learning → "Create and run an eval suite" → side panel opens with the lesson as the visible first message → agent navigates to Evals, narrates, prefills the suite form, hands back the Create click; destructive pill appears if asked to run; double-click doesn't spawn two sessions; works as a guest.
🤖 Generated with Claude Code
Note
Low Risk
Client-only Learning and agent UI wiring with no auth or backend changes; reuses established pending-prompt and side-panel session patterns with tests.
Overview
Adds a Guided tours track to Learning: five hands-on lessons whose prompts teach by driving the real inspector via existing UI tools (prefill, narrate, user submits final actions).
Selecting a guided row opens the MCPJam agent side panel with the tour prompt as the first message and keeps the Learning landing visible; reading modules still open in-tab articles/walkthroughs. The landing UI shows a Guided badge and play affordance on tour rows.
Content model splits
LearningModuleinto reading vskind: "guided"tours withagentPromptinguided-tour-lessons.ts.LearningRoutepassesactiveProjectIdintoLearningTabfor panel scoping.Refactor: agent pending-first-message handoff moves to shared
pending-prompt.ts;launch-lesson.tsmirrors home/panel session start (write pending beforesetActiveSession, refocus same tour, skip without project). Telemetry:mcpjam_agent_tour_launched/_skipped. New unit tests cover launch, pending prompt, and landing/tab behavior.Reviewed by Cursor Bugbot for commit 59893c1. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by cubic
Adds “Guided tours” to the Learning tab. Picking a tour opens the side panel and seeds the MCPJam agent with a lesson prompt so it teaches by driving the real UI (narrate, navigate, prefill; you click the final action).
Five tours: connect a server, run a tool in Playground, create/run an eval suite, simulate users with Swarms, and package servers into a Host. Client-only and uses existing
ui_*tools; destructive/billable actions remain gated.Guided rows stay on the landing page and show a “Guided” badge with a play affordance; counts include tours.
Learning model now supports a
LearningConcept | GuidedTourConceptunion; tours and shared ground rules live inguided-tour-lessons.ts.LearningTabacceptsprojectIdand launches tours vialaunch-lesson.ts(seeds pending prompt, sets active session, opens panel; guards double-click refocus and nullprojectId). Telemetry:mcpjam_agent_tour_launchedandmcpjam_agent_tour_launch_skipped.Extracted pending-prompt helpers to
pending-prompt.tsand reused in Home, Agent panel, and thread.Tests added:
launch-lesson.test.ts,pending-prompt.test.ts,LearningLandingPage.tours.test.tsx,LearningTab.tours.test.tsx.Written for commit 59893c1. Summary will update on new commits.