feat: add tutorial guided execution MCP tools (Phase 2)#12
Merged
jung-thomas merged 8 commits intomainfrom Apr 21, 2026
Merged
Conversation
Registers 4 new MCP tools (get_tutorial_step, update_tutorial_progress, get_tutorial_progress, list_active_tutorials) in tools_tutorial_exec.go. get_tutorial_step is fully implemented with loadOrFetchTutorial helper (cache-hit → GitHub fetch fallback), StepAnnotations extraction, and optional progress tracking. The other 3 handlers are stubs returning "not implemented yet" for Tasks 6-7. Extends MCP server instructions with guidance for the new tutorial execution tools.
Replaces the stub handler with a real implementation that merges completed step indices into stored progress via MergeCompletedSteps, validates slug and step ranges, and returns a progress snapshot. Adds three unit tests covering the happy path, invalid slug, and out-of-range step inputs.
Replaces the two remaining stub handlers with real implementations. get_tutorial_progress returns a single-tutorial or all-tutorials progress snapshot sorted by last access. list_active_tutorials returns only incomplete tutorials (CompletedAt == nil), respects the limit parameter, and is sorted by recency. Adds five unit tests covering single/all/missing progress lookups and active-tutorial filtering.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
get_tutorial_step,update_tutorial_progress,get_tutorial_progress,list_active_tutorialsinternal/tutorials/annotate.go) that extracts executable commands, file creates, and verification checks from tutorial step markdownMergeCompletedStepsbatch progress update function with deduplication, sorting, and completion detectionDataDirinto MCP serverDepsand update server instructions for the 4 new tools (26 → 30 total)Design
The MCP server is stateless — the AI agent drives the tutorial flow by calling tools sequentially. The annotation engine is intentionally conservative (false negatives preferred over false positives) and classifies fenced code blocks based on language tag and preceding text context. Progress is stored in
tutorial-progress.jsonin the XDG data directory, shared between MCP tools and the existing TUI.New Files
internal/tutorials/annotate.go— Annotation engine:AnnotateStep()pure function with block parsing/classificationinternal/tutorials/annotate_test.go— 15 black-box testsinternal/mcpserver/tools_tutorial_exec.go— 4 MCP tool handlers + registrationinternal/mcpserver/tools_tutorial_exec_test.go— 13 handler testsTest Plan
go build ./...passesgo vet ./...passesgo test ./internal/tutorials/...passes (CI)go test ./internal/mcpserver/...passes (CI)