[UNIT] Unit 3: Advanced MCP Development - Custom Workflow Servers #50

zealoushacker · 2025-05-21T21:04:09Z

Unit 3: Advanced MCP Development - Custom Workflow Servers

This PR completes Unit 3, which teaches learners to build practical MCP servers that enhance Claude Code with custom development workflows. The unit demonstrates all core MCP primitives (Tools and Prompts) through a progressive 3-module structure.

🏗️ What Learners Build

A PR Agent Workflow Server that transforms Claude Code into a team-aware development assistant:

Smart PR Management: Automatic template selection based on code changes
CI/CD Monitoring: Real-time GitHub Actions tracking with formatted summaries
Team Communication: Intelligent Slack notifications with rich formatting

📚 Module Overview

Module 1: Build MCP Server (45 min)

Focus: MCP Tools fundamentals

What: Basic MCP server with file analysis and PR template suggestion
Tools: analyze_file_changes, get_pr_templates, suggest_template
Learning: Tool registration, schema definition, letting Claude make intelligent decisions
Outcome: Claude can analyze code changes and recommend appropriate PR templates

Module 2: GitHub Actions Integration (45 min)

Focus: MCP Prompts and webhook integration

What: Webhook server + CI/CD monitoring with standardized workflows
Tools: get_recent_actions_events, get_workflow_status
Prompts: analyze_ci_results, create_deployment_summary, troubleshoot_workflow_failure
Learning: Prompt templates, workflow consistency, Cloudflare Tunnel integration
Outcome: Claude can monitor CI/CD pipelines and provide standardized team reports

Module 3: Slack Notification (45 min)

Focus: Tools + Prompts integration

What: Complete team communication system combining all MCP primitives
Tools: send_slack_notification (with proper error handling)
Prompts: format_ci_failure_alert, format_ci_success_summary
Learning: External API integration, security best practices, development patterns
Outcome: Claude can send professional team notifications with rich Slack formatting

🎯 Progressive Learning Design

Each module builds on the previous, demonstrating MCP primitive progression:

Tools → Claude can call functions and get structured data
Prompts → Claude can follow standardized workflows consistently
Integration → All primitives work together for complex automation

✨ Key Features

Real-World Applicability

Development patterns: Proper error handling, security, environment variables
Team workflows: Actual automation teams can deploy and use
Free tooling: Slack, GitHub Actions, Cloudflare Tunnel (no paid services)

Enhanced Testing Experience

No setup barriers: curl commands simulate GitHub webhooks
Quick verification: 5-10 minute end-to-end testing
Complete workflows: From webhook events → formatted Slack messages

Security & Best Practices

Environment variables: Secure webhook URL handling
Error handling: Network timeouts, invalid URLs, missing config
Input validation: Proper API integration patterns

📁 Project Structure

  projects/unit3/
  ├── build-mcp-server/           # Module 1: Tools
  │   ├── starter/                # File analysis + template suggestion
  │   └── solution/├── github-actions-integration/  # Module 2: Prompts│   ├── starter/                # Webhook + CI monitoring
  │   └── solution/
  ├── slack-notification/         # Module 3: Integration
  │   ├── starter/                # Team communication
  │   └── solution/
  ├── templates/                  # PR templates (bug, feature, docs, etc.)
  └── team-guidelines/            # Coding standards, PR guidelines

🔄 Refinements from Original Plan

Streamlined scope: 3 focused modules instead of 5 (more achievable)
Removed complexity: Hugging Face Hub integration moved to separate PR [UNIT] Unit 3.1 on building a PR bot with #69
Enhanced testing: Complete manual testing without GitHub repo setup
Improved security: Explicit guidance for webhook handling

✅ Learning Outcomes

By completing Unit 3, learners will:

Master MCP primitives: Hands-on experience with Tools and Prompts
Build functional servers: Proper structure, error handling, security
Integrate external APIs: GitHub Actions, Slack webhooks
Understand workflow automation: How MCP enables intelligent team processes
Apply best practices: Security, testing, development patterns

Total time: ~2.5 hours | Prerequisites: Units 1 & 2 | Difficulty: Intermediate

This unit provides the foundation for building sophisticated MCP servers that enhance development team workflows with intelligent automation.

🚀 Next Steps (Separate PR)

After this foundational implementation is reviewed and approved, the following enhancements will be added in a follow-up PR to prepare for launch:

Visual Learning Materials

Screencasts: Step-by-step video walkthroughs for each module showing:
- MCP server setup and connection to Claude Code
- Real-time tool and prompt execution
- End-to-end workflow demonstrations
Screenshots: Key UI moments and expected outputs at each step

Enhanced Learner Experience

Detailed walkthroughs: More granular step-by-step instructions with learner perspective focus
Troubleshooting sections: Expanded common issues and solutions
Progress checkpoints: Clear validation points throughout each module

Launch Preparation

Manual end-to-end testing: Complete learner journey validation
Instruction polishing: Clarity improvements based on testing feedback
Final review cycle: Ensuring optimal learner experience

Parallel Development

HF Hub Module: Being developed separately as "Unit 3.1" by @burtenshaw in PR #69
No dependencies: This Unit 3 implementation is complete and standalone

- Add unit 3 covering MCP workflow servers and tool composition for Claude Code - Add unit 4 covering remote MCP deployment with Cloudflare Workers - Update table of contents to include new units with proper navigation - Include OAuth 2.1 authentication and production deployment patterns - Standardize deployment examples to use Cloudflare Workers platform

@burtenshaw

- 5-module structure with jump-in-anywhere design - Local toy to production pipeline approach - Cloudflare Tunnel integration for seamless Unit 4 transition - Specific quiz contribution areas for @burtenshaw - Free-tier compatibility throughout - Complete code examples and starter templates planned quick fix

burtenshaw · 2025-05-22T07:40:54Z

@zealoushacker looks good, but I would just make these high level changes to simplify things a bit (for us and students):

drop all unit 4 pages and content from the PR just to keep reviewing easy (including cloudflare integration)
following @Vaibhavs10 's feedback on [UNIT] Add advanced MCP unit summaries & toc from Anthropic #39 , I would focus more on free tooling so that students can learn about Claude, without access to other tools.
as above, in Module 3 I would use ngrok to just to keep things simple/ free. Unit 4 could then introduce cloudflare entirely.
I will add a module after Module 3 which implements the demo for a Hugging Face hub PR
IMO, I would drop 'Module 5 on polishing' and try to make the pages runnable in themselves.

This would give a propose structure like this:

- title: "3. Advanced MCP Use Case: Build a Pull Request agent with Anthropic, Github, Slack, and Hugging Face"
  sections:
  - local: unit3/introduction
    title: Introduction to the Autonomous Pull Request Use case
  - local: unit3/server
    title: Build your use case specific MCP server 
  - local: unit3/files
    title: Smart File Analysis
  - local: unit3/github
    title: GitHub Actions Integration
  - local: unit3/hub
    title: Hugging Face Hub Integration
  - local: unit3/slack
    title: Slack Notification

zealoushacker · 2025-05-22T19:57:58Z

@burtenshaw thanks for the review.

Hear you on potential complex stuff maybe being better to punt from Unit 3.
- Are you suggesting that unit 3 can be simple for enough without more complex stuff... and unit 4 can be where that's covered?
I want to add some content on the newly-released MCP connector in Unit 4 (assuming we keep module 4 with remote MCP servers), because it feels like the natural fit for that use case.
- On this note, are you totally opposed to the idea of Unit 4 covering the idea of deploying remote MCP servers? I feel like we can at least introduce this topic.
Anthropic prefers Cloudflare tunnels for several security reasons. I believe they have a free tier for that and other things I proposed in Unit 4. All good if we keep Cloudflare tunnels?

burtenshaw · 2025-05-22T20:03:34Z

@burtenshaw thanks for the review.

Hear you on potential complex stuff maybe being better to punt from Unit 3.

Are you suggesting that unit 3 can be simple for enough without more complex stuff... and unit 4 can be where that's covered?

That's correct. We can also make decisions based on community feedback of unit 3.

I want to add some content on the newly-released MCP connector in Unit 4 (assuming we keep module 4 with remote MCP servers), because it feels like the natural fit for that use case.

On this note, are you totally opposed to the idea of Unit 4 covering the idea of deploying remote MCP servers? I feel like we can at least introduce this topic.

I'm not opposed to introducing the concept. Mainly just trying to simplify. But tbh, I trust your judgement of you think it works.

We could also use HF spaces for remote servers.

Anthropic prefers Cloudflare tunnels for several security reasons. I believe they have a free tier for that. All good if we keep that?

Cloudflare does have a free tier.

Nice compromise. I just wasn't informed.

• 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 manual testing guide 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

burtenshaw

Nice work on this @zelouscoder! This is a great start. My only concern is around the project's structure. The current structure is not compatible with our course building CI, so we'll need to make these changes:

unit3 has to be flat. i.e. it can only contain md or mdx file that will be converted into a static html site of the written material.
project directories cannot be within units. Therefore, I would suggest moving module1/solutions , module1/starter , and module1/templates to a directory in the repo root. i.e. {repo}/projetcs/unit3.
- An alternative is that you make a separate gh repo. Then the students can just clone that. Whatever is easiest.

IMO, we should also avoid introducing new hierarchies like "module's" within "units". these have a tendency to confuse students that prefer to follow single thread through the course.

As above, great content so far. Once the structure is resolved, you can ping me and I'll review the prose and test out all the code and snippets.

✅ I implemented the above changes in a PR to your fork

burtenshaw · 2025-05-27T08:23:31Z

units/en/unit3/implementation_plan.md

I would replace this file with units/en/unit3/implementation_plan_enhancements.md for simplicity of review and delete once implemented.

burtenshaw · 2025-05-27T08:26:11Z

units/en/unit3/introduction.mdx

Good structure.

burtenshaw · 2025-05-27T08:26:40Z

units/en/unit3/mcp-server-hf-course-in-action.png

Useful graphic. Feel free to add more.

burtenshaw · 2025-05-27T08:28:00Z

units/en/unit3/module1/starter/server.py

Nice starter. We will need to resolve it's actual location in the project.

Restructure anthropic unit3

- Move unit3 starter and solution code to build-mcp-server subdirectory - Update documentation paths to reflect new directory structure - No functional changes to the code

- Implement MCP Resources for project context and team guidelines - Add solution with four resource types: templates, team guidelines, git history, and review process - Create starter code building on Module 1 solution - Add comprehensive documentation and solution walkthrough - Create shared team-guidelines directory with coding standards and PR guidelines - Include manual testing guide for resource validation - Update Module 1 comment to reflect templates are shared across all modules

- Update all configuration examples to use claude mcp add command - Remove references to claude_desktop_config.json - Remove import-from-desktop instructions - Simplify setup process for learners - Focus exclusively on Claude Code usage

- Add -- separator before uv command to properly pass arguments - Remove quotes around individual arguments - Fix command parsing error with --directory flag

- Removed smart-file-analysis module and all Resources references - Renumbered modules: GitHub Actions (2), HF Hub (3), Slack (4) - Updated all cross-references and documentation - Focused on Tools and Prompts as core MCP primitives The full Module 2 implementation is preserved at tag: preserve-module2-resources-full

- Implement webhook server to receive GitHub Actions events - Add tools to query workflow status and recent events - Create 4 MCP prompts for CI/CD workflows - Use file-based event storage for simplicity - Provide comprehensive testing documentation - Include starter code with clear TODOs for learners Module 2 teaches: - How to integrate external webhooks with MCP - Creating standardized workflows with prompts - Real-time CI/CD monitoring in Claude Code

- Remove Hugging Face Hub Integration module (will be in separate PR huggingface#69) - Restructure Unit 3 to 3 modules: Build MCP Server, GitHub Actions, Slack Notification - Build complete Slack Notification module demonstrating Tools + Prompts integration - Add comprehensive manual testing with curl commands for easy verification - Include security guidance for webhook URLs and environment variables - Fix Slack markdown formatting with proper <url|text> syntax - Create complete starter/solution project structure

burtenshaw

Hey @zealoushacker . Looking good. I worked through this and some low level comments when things didn't work. Here are some more general comments:

Missing validation scripts in build-mcp-server. We typically don't supply this per unit and so feel free to skip, and just add the solution code in a markdown block.
The structure of the material is excellent, but sometime the transitions are a bit blunt for less experienced devs. You might want to do these two things (claude is pretty good at them):
- add glueing statements that walk the student through the material. For example, "We've now built x, let's test that out" or "Or in order to do y, we will need to install z"
- use mdx blocks to highlight obvious things/ gotchas
I'm always worried about integrations like Slack because so many students/ devs struggle on this. In general, the easiest thing is to thoroughly link to their docs, and reuse their material as much as possible.
I would add an installation setup section where you install everything for the project, like Claude code, and a conclusion page where you round everything up.

units/en/unit3/build-mcp-server.mdx

burtenshaw · 2025-06-02T09:59:29Z

units/en/unit3/github-actions-integration.mdx

+Add the path to read webhook events:
+
+```python
+# File where webhook server stores events


It's not clear to the reader that this should be in server.py

@zealoushacker I still think we clarify the file we're working on.

units/en/unit3/slack-notification.mdx

This commit addresses all feedback from PR huggingface#50 review ID 2887614471: ## Core Feedback Addressed ✅ ### Content & Learning Experience - Add transitional "glue" statements for less experienced developers - Implement CodeCraft Studios narrative arc connecting all modules - Use MDX blocks (<Tip>, <Tip warning>) for important concepts - Create comprehensive conclusion page summarizing unit takeaways - Add extensive external documentation linking throughout ### Technical Infrastructure - Add missing validation scripts (validate_starter.py) to all modules - Add missing test scripts (test_server.py) to all modules - Fix all scripts to work correctly with both starter and solution code - Add proper Claude Code installation instructions with troubleshooting links ### Documentation & Clarity - Simplify Slack integration with step-by-step guidance - Add context for webhook event storage and retrieval system - Link extensively to official docs (Slack API, MCP, GitHub Actions) - Update table of contents to include conclusion page ## Key Improvements ✨ ### 1. CodeCraft Studios Story Arc - Week 1: PR chaos → Module 1 (PR Agent) - Week 2: Silent failures → Module 2 (CI/CD monitoring) - Week 3: Communication gaps → Module 3 (Slack notifications) - Resolution: Complete automation transformation ### 2. Enhanced Learning Experience - Progressive complexity with clear explanations - Real-world problems that every developer faces - Before/after transformations showing concrete value - Motivational but not overstated language ### 3. Working Testing Infrastructure - Flexible tests work with both starter stubs and full implementations - Fixed validation scripts with proper import-based testing - All scripts pass validation (6/6 checks) across all modules - Instructions match actual script behavior ## Files Modified ### Unit Content - units/en/_toctree.yml (added conclusion) - units/en/unit3/introduction.mdx (CodeCraft setup + installation) - units/en/unit3/build-mcp-server.mdx (Module 1 story + transitions) - units/en/unit3/github-actions-integration.mdx (Module 2 story + context) - units/en/unit3/slack-notification.mdx (Module 3 story + Slack docs) - units/en/unit3/conclusion.mdx (NEW: comprehensive unit summary) ### Testing Infrastructure - projects/unit3/*/starter/validate_starter.py (NEW: working validation) - projects/unit3/*/starter/test_server.py (NEW: flexible async tests) - projects/unit3/*/solution/test_server.py (NEW: fixed solution tests) Result: Unit 3 now provides engaging, accessible, well-documented learning experience that guides developers of all levels through advanced MCP concepts via relatable real-world automation scenarios.

burtenshaw

This looks really good @zealoushacker . Thanks for taking the time to make it enjoyable to students.

burtenshaw · 2025-06-03T09:23:58Z

units/en/unit3/build-mcp-server.mdx

 # Module 1: Build MCP Server

-## Introduction
+## The PR Chaos at CodeCraft Studios


😍 Love it

burtenshaw · 2025-06-03T09:25:59Z

units/en/unit3/github-actions-integration.mdx

+Add the path to read webhook events:
+
+```python
+# File where webhook server stores events


@zealoushacker I still think we clarify the file we're working on.

- Module 1: Added comprehensive lesson on handling 25k token limit - Implemented max_diff_lines parameter (default 500) - Added truncation logic with clear messaging - Included test for output limiting - Framed as important real-world learning opportunity - Modules 2 & 3: Pre-included fix so learners can focus on new concepts - Updated all starter and solution code - Added notes that output limiting is already handled - Prevents repetitive debugging of same issue This ensures learners encounter and solve the token limit problem once in Module 1 as a valuable lesson, then can focus on webhooks (Module 2) and Slack integration (Module 3) without distraction. Fixes the issue where large git diffs cause "MCP tool response exceeds maximum allowed tokens (25000)" errors.

- Add roots support to access Claude Code's working directory - Update analyze_file_changes in all modules to use correct cwd - Add documentation about working directory considerations - Include helpful comments in starter code about roots usage

…ealoushacker/mcp-course into pr/50

zealoushacker added 2 commits May 20, 2025 10:51

burtenshaw changed the title ~~Unit 3 Implementation Plan: Advanced MCP Development~~ [UNIT] Unit 3 Implementation Plan: Advanced MCP Development May 22, 2025

zealoushacker force-pushed the feature/anthropic-course-units branch from 6413fee to 72703c2 Compare May 26, 2025 23:27

burtenshaw reviewed May 27, 2025

View reviewed changes

burtenshaw added 2 commits May 27, 2025 10:47

move project to projects dir

7357b9b

flatten unit3 written material structure

c700277

burtenshaw mentioned this pull request May 27, 2025

Restructure anthropic unit3 zealoushacker/mcp-course#1

Merged

zealoushacker and others added 9 commits May 27, 2025 10:54

Merge pull request #1 from huggingface/restructure-anthropic-unit3

1efae10

Restructure anthropic unit3

fix(docs): Updates dir refs in unit3 build mcp server

7c860d6

fix(docs): Updates paths to files

6b45e64

refactor: Restructure unit3 project directory to use descriptive naming

0c29dfd

- Move unit3 starter and solution code to build-mcp-server subdirectory - Update documentation paths to reflect new directory structure - No functional changes to the code

fix: Correct claude mcp add command syntax

087b1b2

- Add -- separator before uv command to properly pass arguments - Remove quotes around individual arguments - Fix command parsing error with --directory flag

burtenshaw mentioned this pull request May 30, 2025

[UNIT] Unit 3.1 on building a PR bot with #69

Merged

zealoushacker changed the title ~~[UNIT] Unit 3 Implementation Plan: Advanced MCP Development~~ Unit 3: Advanced MCP Development - Custom Workflow Servers May 30, 2025

zealoushacker marked this pull request as ready for review May 30, 2025 23:04

burtenshaw changed the title ~~Unit 3: Advanced MCP Development - Custom Workflow Servers~~ [UNIT] Unit 3: Advanced MCP Development - Custom Workflow Servers Jun 2, 2025

burtenshaw reviewed Jun 2, 2025

View reviewed changes

zealoushacker and others added 2 commits June 2, 2025 12:50

add git clone and uv tip

39e1c9c

burtenshaw approved these changes Jun 3, 2025

View reviewed changes

burtenshaw and others added 5 commits June 3, 2025 11:29

add returns to all tips

59dab07

Merge branch 'main' into pr/50

05c9a75

Merge branch 'feature/anthropic-course-units' of https://github.com/z…

751e1c3

…ealoushacker/mcp-course into pr/50

burtenshaw changed the base branch from main to release/unit3 June 5, 2025 08:57

burtenshaw merged commit 983e8f1 into huggingface:release/unit3 Jun 5, 2025

[UNIT] Unit 3: Advanced MCP Development - Custom Workflow Servers #50

[UNIT] Unit 3: Advanced MCP Development - Custom Workflow Servers #50

Uh oh!

Conversation

zealoushacker commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unit 3: Advanced MCP Development - Custom Workflow Servers

🏗️ What Learners Build

📚 Module Overview

Module 1: Build MCP Server (45 min)

Module 2: GitHub Actions Integration (45 min)

Module 3: Slack Notification (45 min)

🎯 Progressive Learning Design

✨ Key Features

Real-World Applicability

Enhanced Testing Experience

Security & Best Practices

📁 Project Structure

🔄 Refinements from Original Plan

✅ Learning Outcomes

🚀 Next Steps (Separate PR)

Visual Learning Materials

Enhanced Learner Experience

Launch Preparation

Parallel Development

Uh oh!

burtenshaw commented May 22, 2025

Uh oh!

zealoushacker commented May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

burtenshaw commented May 22, 2025

Uh oh!

burtenshaw left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

burtenshaw left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

burtenshaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zealoushacker commented May 21, 2025 •

edited

Loading

zealoushacker commented May 22, 2025 •

edited

Loading

burtenshaw left a comment •

edited

Loading

burtenshaw left a comment •

edited

Loading