Skip to content

Commit 6413fee

Browse files
zealoushackerzealoushacker
committed
feat: implement Unit 3 - Building Custom MCP Servers
• Add comprehensive 5-module structure for Unit 3 focusing on MCP server development • Implement Module 1 with PR template suggestion tool using Anthropic's Claude API • Include starter code, solution code, and validation tests for Module 1 • Add PR templates (bug, feature, docs, performance, refactor, security, test) • Create detailed implementation plans and module introductions • Add screenshot demonstrating MCP server in action • Structure modules with progressive complexity from basic tools to advanced deployments • Update table of contents to reflect new unit structure • Remove placeholder Unit 4 content
1 parent 07b32f0 commit 6413fee

31 files changed

+3159
-128
lines changed

‎units/en/_toctree.yml‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,14 @@
3939
sections:
4040
- local: unit3/introduction
4141
title: Building Custom Workflow Servers for Claude Code
42+
- local: unit3/module1/introduction
43+
title: "Module 1: Build MCP Server"
44+
- local: unit3/module2/introduction
45+
title: "Module 2: Smart File Analysis"
46+
- local: unit3/module3/introduction
47+
title: "Module 3: GitHub Actions Integration"
48+
- local: unit3/module4/introduction
49+
title: "Module 4: Hugging Face Hub Integration"
50+
- local: unit3/module5/introduction
51+
title: "Module 5: Slack Notification"
4252

43-
- title: "4. Production Deployment: Remote Servers and Authentication"
44-
sections:
45-
- local: unit4/introduction
46-
title: Remote Servers, Authentication, and Deployment

‎units/en/unit3/NEXT_STEPS.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Unit 3 Next Steps - Status Summary
2+
3+
## Current Status (Module 1: Complete ✅)
4+
5+
### What's Done
6+
1. **Module 1: Build MCP Server** - FULLY COMPLETE
7+
- ✅ FastMCP implementation with all three tools
8+
- ✅ uv package management with pyproject.toml
9+
- ✅ Complete starter code with TODOs
10+
- ✅ Comprehensive test suite (unit tests + validation scripts)
11+
- ✅ Documentation (README, manual testing guide)
12+
- ✅ MDX file in module directory
13+
- ✅ _toctree.yml updated with module reference
14+
- ✅ All 7 PR templates created
15+
16+
2. **Unit 3 Foundation**
17+
- ✅ Updated introduction.mdx (removed production language, added MCP primitives)
18+
- ✅ Solution walkthrough document created
19+
- ✅ Implementation plans documented
20+
- ✅ Directory structure for all 5 modules
21+
22+
### Key Technology Decisions Made
23+
- **Package Manager**: uv (with pyproject.toml)
24+
- **MCP SDK**: FastMCP (not legacy Server API)
25+
- **Python Version**: >=3.10
26+
- **Testing**: pytest with pytest-asyncio
27+
- **Webhooks**: Cloudflare Tunnel (not ngrok)
28+
29+
## Immediate Next Steps (Before Committing)
30+
31+
1. **Git housekeeping**:
32+
```bash
33+
git add units/en/unit3/implementation_plan_enhancements.md
34+
git add units/en/unit3/solution_walkthrough.md
35+
```
36+
37+
2. **Verify Module 1 works**:
38+
```bash
39+
cd units/en/unit3/module1/solution
40+
uv sync --all-extras
41+
uv run python validate_solution.py
42+
```
43+
44+
3. **Consider adding to _toctree.yml**:
45+
- The solution_walkthrough.md (as a reference doc)
46+
- Future module entries as they're completed
47+
48+
## Module Implementation Roadmap
49+
50+
### Module 2: Smart File Analysis (Resources)
51+
**Goal**: Add Resources for project context
52+
- **Starter**: Copy Module 1 solution as base
53+
- **Add**: Resource registration for templates/, project-context/, git history
54+
- **MDX**: Create module2/introduction.mdx
55+
- **_toctree**: Add reference when complete
56+
57+
### Module 3: GitHub Actions Integration (Prompts)
58+
**Goal**: Add webhook handling and Prompts
59+
- **Starter**: Copy Module 2 solution
60+
- **Add**: Cloudflare Tunnel setup, webhook endpoint, prompt templates
61+
- **MDX**: Create module3/introduction.mdx
62+
- **_toctree**: Add reference when complete
63+
64+
### Module 4: Hugging Face Hub Integration
65+
**Goal**: LLM-specific workflows
66+
- **Starter**: Copy Module 3 solution
67+
- **Add**: Hub API integration, model card generation, dataset validation
68+
- **MDX**: Create module4/introduction.mdx
69+
- **_toctree**: Add reference when complete
70+
71+
### Module 5: Slack Notification (All Primitives)
72+
**Goal**: Complete integration
73+
- **Starter**: Copy Module 4 solution
74+
- **Add**: Slack webhooks, message formatting, full workflow
75+
- **MDX**: Create module5/introduction.mdx
76+
- **_toctree**: Add reference when complete
77+
78+
## Testing Checklist for Each Module
79+
80+
When implementing each module:
81+
1. [ ] Create solution with full implementation
82+
2. [ ] Create starter by removing implementation
83+
3. [ ] Write unit tests
84+
4. [ ] Create validation scripts
85+
5. [ ] Test with Claude Desktop
86+
6. [ ] Write module MDX file
87+
7. [ ] Update _toctree.yml
88+
8. [ ] Ensure progressive enhancement from previous module
89+
90+
## Documentation Updates Needed
91+
92+
1. **After all modules complete**:
93+
- Update solution_walkthrough.md if needed
94+
- Consider adding troubleshooting guide
95+
- Create unit3/conclusion.mdx
96+
97+
2. **For PR**:
98+
- Ensure commit message follows format
99+
- Update PR description with what's complete
100+
- Note that only Module 1 is implemented
101+
102+
## Commit Message Suggestion
103+
104+
```
105+
feat(unit3): implement Module 1 with FastMCP and uv
106+
107+
- Complete Module 1: Basic MCP server with PR template tools
108+
- Migrate from legacy Server API to FastMCP
109+
- Replace pip/requirements.txt with uv/pyproject.toml
110+
- Add comprehensive test suite and validation scripts
111+
- Update unit introduction to focus on learning (not production)
112+
- Create module structure for remaining 4 modules
113+
114+
Module 1 provides hands-on experience with MCP Tools, letting learners
115+
build a PR agent that analyzes git changes and suggests templates.
116+
```
117+
118+
## Quality Checklist ✅
119+
120+
- [x] All imports use current APIs (FastMCP, not legacy Server)
121+
- [x] No hardcoded paths (all use relative imports)
122+
- [x] Consistent error handling patterns
123+
- [x] Tests are meaningful and pass
124+
- [x] Documentation is clear and accurate
125+
- [x] No "production-ready" claims in Unit 3
126+
- [x] Free tooling only (no paid services required)
127+
- [x] Works with Claude Desktop
128+
129+
## Notes for Reviewers
130+
131+
1. **Only Module 1 is implemented** - Other modules are scaffolded but empty
132+
2. **FastMCP is used throughout** - This is the modern API
133+
3. **uv replaces pip** - Following MCP documentation recommendations
134+
4. **Focus is on learning** - Production concerns deferred to Unit 4
135+
5. **All MCP primitives covered** - Tools (M1), Resources (M2), Prompts (M3), Integration (M4-5)

‎units/en/unit3/implementation_plan_enhancements.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Unit 3 Implementation Plan Enhancements: Complete MCP Primitives Coverage
2+
3+
## Overview
4+
5+
This document enhances the existing [implementation_plan.md](./implementation_plan.md) to ensure comprehensive coverage of all 3 MCP primitives while maintaining the solid foundation and timeline already established.
6+
7+
## MCP Primitives Integration Strategy
8+
9+
Rather than redesigning the entire unit, we'll enhance each existing module to naturally incorporate MCP primitives without changing the core learning goals or structure.
10+
11+
## Enhanced Module Structure
12+
13+
### Module 1: Basic Workflow Server (30 min)
14+
**Existing Goal**: "I want Claude Code to help me create better PRs"
15+
**+ MCP Primitive**: **Tools**
16+
17+
**Current Plan**:
18+
- Minimal MCP server with PR template suggestion
19+
- Simple rule-based template selection (file extension → template type)
20+
21+
**Enhancements**:
22+
- **Tool**: `analyze_file_changes` - Returns structured data about changed files for Claude to analyze
23+
- **Tool**: `get_pr_templates` - Lists available PR templates with metadata
24+
- **Tool**: `suggest_template` - Provides template recommendation based on file analysis
25+
26+
**What Claude Does**: Uses tools to gather file data, then intelligently decides which template to recommend and explains why.
27+
28+
**Learning Focus**: Tool registration, schema definition, and letting Claude make smart decisions with structured data.
29+
30+
---
31+
32+
### Module 2: Smart File Analysis (45 min)
33+
**Existing Goal**: "Make template selection actually intelligent"
34+
**+ MCP Primitive**: **Resources**
35+
36+
**Current Plan**:
37+
- Context-aware file analysis (not just extensions)
38+
- Pattern matching logic and multi-file change analysis
39+
40+
**Enhancements**:
41+
- **Resource**: `file://templates/` - PR template files Claude can read and understand
42+
- **Resource**: `file://project-context/` - Project-specific guidelines, coding standards, team conventions
43+
- **Resource**: `git://recent-changes/` - Recent commit patterns and project history
44+
- **Resource**: `team://guidelines/` - Team-specific review processes and standards
45+
46+
**What Claude Does**: Reads project resources to understand context, then makes more informed template and workflow suggestions.
47+
48+
**Learning Focus**: Resource schemas, URI patterns, and making project knowledge accessible to Claude.
49+
50+
---
51+
52+
### Module 3: GitHub Actions Integration (45 min)
53+
**Existing Goal**: "Tell me when my tests pass/fail"
54+
**+ MCP Primitive**: **Prompts**
55+
56+
**Current Plan**:
57+
- Local webhook receiver using Cloudflare Tunnel
58+
- GitHub Actions event parsing and real-time CI/CD status
59+
60+
**Enhancements**:
61+
- **Prompt**: "Analyze CI Results" - Standardized prompt for processing GitHub Actions outcomes
62+
- **Prompt**: "Generate Status Summary" - Consistent format for CI/CD status updates
63+
- **Prompt**: "Create Follow-up Tasks" - Generate next steps based on CI results
64+
- **Prompt**: "Draft Team Notification" - Standardized team communication about CI events
65+
66+
**What Claude Does**: Uses prompts to consistently analyze CI results and generate standardized team communications.
67+
68+
**Learning Focus**: Prompt templates, workflow consistency, and reusable team processes.
69+
70+
---
71+
72+
### Module 4: Team Communication (30 min)
73+
**Existing Goal**: "Update my team automatically"
74+
**+ Integration**: **All Three Primitives Working Together**
75+
76+
**Current Plan**:
77+
- Slack webhook integration for notifications
78+
- Smart message formatting based on CI results
79+
80+
**Enhancements**:
81+
- **Tools**: `send_slack_message`, `get_team_members`, `track_notification_status`
82+
- **Resources**: `team://members/`, `slack://channels/`, `notification://templates/`
83+
- **Prompts**: "Format Team Update", "Choose Communication Channel", "Escalate if Critical"
84+
85+
**What Claude Does**: Combines tools (Slack API), resources (team data), and prompts (message formatting) for complete workflow automation.
86+
87+
**Learning Focus**: Primitive integration, workflow orchestration, and production patterns.
88+
89+
---
90+
91+
### Module 5: Polish & Integration (30 min)
92+
**Existing Goal**: "Make it production-ready (locally)"
93+
**+ Orchestration**: **Complete Workflow Demonstration**
94+
95+
**Current Plan**:
96+
- Error handling and logging
97+
- Configuration management
98+
- Complete Claude Code workflow demonstration
99+
100+
**Enhancements**:
101+
- **Showcase**: End-to-end workflow using all primitives
102+
- **Demo**: "Create PR → Analyze Changes → Monitor CI → Notify Team"
103+
- **Testing**: Validate all primitives work together seamlessly
104+
- **Documentation**: How each primitive contributes to the workflow
105+
106+
**What Claude Does**: Demonstrates the complete team workflow automation with intelligent decision-making at each step.
107+
108+
**Learning Focus**: System integration, error handling, and preparing for Unit 4 deployment.
109+
110+
## Primitive Distribution
111+
112+
| Module | Primary Primitive | Secondary | Learning Outcome |
113+
|--------|------------------|-----------|------------------|
114+
| 1 | **Tools** | - | Claude can call functions to get structured data |
115+
| 2 | **Resources** | Tools | Claude can read project context and make informed decisions |
116+
| 3 | **Prompts** | Resources | Claude can follow standardized workflows consistently |
117+
| 4 | **Integration** | All Three | All primitives work together for complex automation |
118+
| 5 | **Orchestration** | All Three | Production-ready workflow with proper error handling |
119+
120+
## Implementation Benefits
121+
122+
### Maintains Existing Strengths
123+
- ✅ **Same timeline** - 3 hours total, module breakdown unchanged
124+
- ✅ **Same learning goals** - Each module still has clear, practical objectives
125+
- ✅ **Same progression** - Local toy → production pipeline approach
126+
- ✅ **Same technology choices** - Cloudflare Tunnel, GitHub Actions, etc.
127+
128+
### Adds MCP Depth
129+
- ✅ **Complete coverage** - All 3 MCP primitives with real examples
130+
- ✅ **Natural integration** - Primitives enhance existing modules rather than replace them
131+
- ✅ **Progressive complexity** - Tools → Resources → Prompts → Integration
132+
- ✅ **Real-world patterns** - How to combine primitives effectively
133+
134+
### Educational Enhancements
135+
- **Advanced MCP concepts** - Beyond basic server building from Unit 2
136+
- **Primitive synergy** - How tools, resources, and prompts work together
137+
- **Workflow standardization** - Using prompts for team consistency
138+
- **Context awareness** - Resources make Claude team and project aware
139+
140+
## Quiz Enhancement Areas for @burtenshaw
141+
142+
### Additional Quiz Topics
143+
- **Tools vs Resources vs Prompts** - When to use each primitive
144+
- **Resource URI patterns** - Designing discoverable resource schemas
145+
- **Prompt engineering** - Creating effective workflow templates
146+
- **Primitive integration** - Combining all three for complex workflows
147+
148+
### Sample Questions
149+
- "How would you expose team coding standards to Claude?" (Resources)
150+
- "What's the difference between a tool and a prompt?" (Concepts)
151+
- "How do you make workflow processes consistent across team members?" (Prompts)
152+
153+
## Implementation Notes
154+
155+
### Code Structure
156+
- Each module's starter code includes framework for the new primitive
157+
- Solutions demonstrate both the existing functionality AND the primitive integration
158+
- No breaking changes to existing module goals or timelines
159+
160+
### Testing Strategy
161+
- Test each primitive individually within modules
162+
- Test primitive integration in Module 4
163+
- Validate end-to-end workflow in Module 5
164+
165+
### Documentation
166+
- Each module explains the primitive it introduces
167+
- Show how the primitive enhances the existing functionality
168+
- Provide examples of other use cases for each primitive
169+
170+
## Next Steps
171+
172+
1. **Enhance Module 1** - Add proper Tools implementation to existing file analysis
173+
2. **Design Resources** - Create resource schemas for Module 2 project context
174+
3. **Create Prompts** - Develop workflow prompt templates for Module 3
175+
4. **Integration Testing** - Ensure all primitives work together in Module 4
176+
5. **Documentation** - Update module READMEs with primitive explanations
177+
178+
---
179+
180+
*This enhancement maintains the existing solid plan while ensuring learners get comprehensive MCP primitives education through practical workflow automation.*

0 commit comments

Comments
 (0)