diff --git a/.github/workflows/build_documentation.yml b/.github/workflows/build_documentation.yml new file mode 100644 index 0000000..4dd1359 --- /dev/null +++ b/.github/workflows/build_documentation.yml @@ -0,0 +1,18 @@ +name: Build documentation + +on: + push: + branches: + - main + workflow_dispatch: + +jobs: + build: + uses: huggingface/doc-builder/.github/workflows/build_main_documentation.yml@main + with: + commit_sha: ${{ github.sha }} + package: mcp-course + path_to_docs: units + build_command: doc-builder build mcp-course units --build_dir build/mcp-course + deploy_to_hub: true + languages: en \ No newline at end of file diff --git a/.github/workflows/build_pr_documentation.yml b/.github/workflows/build_pr_documentation.yml new file mode 100644 index 0000000..d938647 --- /dev/null +++ b/.github/workflows/build_pr_documentation.yml @@ -0,0 +1,20 @@ +name: Build PR Documentation + +on: + pull_request: + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + +jobs: + build: + uses: huggingface/doc-builder/.github/workflows/build_pr_documentation.yml@main + with: + commit_sha: ${{ github.event.pull_request.head.sha }} + pr_number: ${{ github.event.number }} + package: mcp-course + package_name: mcp-course + path_to_docs: mcp-course/units/ + additional_args: --not_python_module + languages: en \ No newline at end of file diff --git a/.github/workflows/upload_pr_documentation.yml b/.github/workflows/upload_pr_documentation.yml new file mode 100644 index 0000000..9e72e49 --- /dev/null +++ b/.github/workflows/upload_pr_documentation.yml @@ -0,0 +1,24 @@ +name: Upload PR Documentation + +on: + workflow_run: + workflows: ["Build PR Documentation"] + types: + - completed + +permissions: + actions: write + contents: write + deployments: write + pull-requests: write + + +jobs: + build: + uses: huggingface/doc-builder/.github/workflows/upload_pr_documentation.yml@main + with: + package_name: mcp-course + hub_base_path: https://moon-ci-docs.huggingface.co/learn + secrets: + hf_token: ${{ secrets.HF_DOC_BUILD_PUSH }} + comment_bot_token: ${{ secrets.COMMENT_BOT_TOKEN }} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..7381786 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# The Model Context Protocol (MCP) Course + +If you like the course, **don't hesitate to ⭐ star this repository**. This helps us to **make the course more visible 🤗**. + +## Content + +The course is divided into 4 units. These will take you from **the basics of Model Context Protocol to a final project implementing MCP in an AI application**. + +Sign up here (it's free) 👉 [Coming Soon] + +You can access the course here 👉 [Coming Soon] + +| Unit | Topic | Description | +| ------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| 0 | Welcome to the Course | Welcome, guidelines, necessary tools, and course overview. | +| 1 | Introduction to Model Context Protocol | Definition of MCP, key concepts, and its role in connecting AI models with external data and tools. | +| 2 | Understanding MCP Architecture and Core Concepts | Explore the MCP architecture, communication protocols, and core primitives. | +| 3 | Building with MCP: Practical Development | Learn to implement MCP clients and servers using available SDKs and frameworks. | +| 4 | Advanced Topics, Security, and the Future of MCP | Explore advanced features, security considerations, and the future roadmap of MCP. | + +## Prerequisites + +* Basic understanding of AI and LLM concepts +* Familiarity with software development principles and API concepts +* Experience with at least one programming language (Python or TypeScript examples will be emphasized) + +## Contribution Guidelines + +If you want to contribute to this course, you're welcome to do so. Feel free to open an issue or submit a pull request. For specific contributions, here are some guidelines: + +### Small typo and grammar fixes + +If you find a small typo or grammar mistake, please fix it yourself and submit a pull request. This is very helpful for students. + +### New unit + +If you want to add a new unit, **please create an issue in the repository, describe the unit, and why it should be added**. We will discuss it and if it's a good addition, we can collaborate on it. + +## Citing the project + +To cite this repository in publications: + +``` +@misc{mcp-course, + author = {Your Name}, + title = {The Model Context Protocol Course}, + year = {2025}, + howpublished = {\url{https://github.com/yourusername/mcp-course}}, + note = {GitHub repository}, +} +``` \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..bbf75fb --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +hf-doc-builder>=0.5.0 +mdx_truly_sane_lists +pyyaml \ No newline at end of file diff --git a/units/en/_toctree.yml b/units/en/_toctree.yml new file mode 100644 index 0000000..d91214d --- /dev/null +++ b/units/en/_toctree.yml @@ -0,0 +1,56 @@ +- title: "0. Welcome to the MCP Course" + sections: + - local: unit0/introduction + title: Welcome to the MCP Course + +- title: "1. Introduction to Model Context Protocol" + sections: + - local: unit1/introduction + title: Introduction to Model Context Protocol (MCP) + - local: unit1/key-concepts + title: Key Concepts and Terminology + - local: unit1/architectural-components + title: Architectural Components + - local: unit1/communication-protocol + title: The Communication Protocol + - local: unit1/capabilities + title: Understanding MCP Capabilities + - local: unit1/gradio-mcp + title: Gradio MCP Integration + +- title: "2. Use Case: Building with MCP" + sections: + - local: unit2/introduction + title: Introduction + - local: unit2/environment-setup + title: Setting Up Your Development Environment & SDKs + - local: unit2/building-server + title: Building Your First MCP Server + - local: unit2/server-capabilities + title: Implementing Server Capabilities + - local: unit2/developing-clients + title: Developing MCP Clients + - local: unit2/configuration + title: Configuration, Authentication, and Debugging + - local: unit2/hub-mcp-servers + title: MCP Servers on Hugging Face Hub + +- title: "3. Use Case: Deploying with MCP" + sections: + - local: unit3/introduction + title: Introduction + - local: unit3/advanced-features + title: Exploring Advanced MCP Features + - local: unit3/security + title: Security Deep Dive - Threats and Mitigation Strategies + - local: unit3/limitations + title: Limitations, Challenges, and Comparisons + - local: unit3/huggingface-ecosystem + title: Hugging Face's Tiny Agents and MCP + - local: unit3/final-project + title: Final Project - Building a Complete MCP Application + +- title: "Bonus Units" + sections: + - local: unit4/introduction + title: Introduction diff --git a/units/en/unit0/introduction.mdx b/units/en/unit0/introduction.mdx new file mode 100644 index 0000000..4601517 --- /dev/null +++ b/units/en/unit0/introduction.mdx @@ -0,0 +1,143 @@ +# Welcome to the 🤗 Model Context Protocol (MCP) Course + + + + +Welcome to the most exciting topic in AI today: **Model Context Protocol (MCP)**! + +This free course will take you on a journey, **from beginner to expert**, in understanding, using, and building applications with MCP. + +This first unit will help you onboard: + +* Discover the **course's syllabus**. +* **Choose the path** you're going to take (either self-audit or certification process). +* **Get more information about the certification process and the deadlines**. +* Get to know the team behind the course. +* Create your **account**. +* **Sign-up to our Discord server**, and meet your classmates and us. + +Let's get started! + +## What to expect from this course? + +In this course, you will: + +* 📖 Study Model Context Protocol in **theory, design, and practice.** +* 🧑‍💻 Learn to **use established MCP SDKs and frameworks**. +* 💾 **Share your projects** and explore applications created by the community. +* 🏆 Participate in challenges where you will **evaluate your MCP implementations against other students'.** +* 🎓 **Earn a certificate of completion** by completing assignments. + +And more! + +At the end of this course, you'll understand **how MCP works and how to build your own AI applications that leverage external data and tools using the latest MCP standards**. + +Don't forget to **sign up to the course!** + +(We are respectful of your privacy. We collect your email address to be able to **send you the links when each Unit is published and give you information about the challenges and updates**). + +## What does the course look like? + +The course is composed of: + +* _Foundational Units_: where you learn MCP **concepts in theory**. +* _Hands-on_: where you'll learn **to use established MCP SDKs** to build your applications. These hands-on sections will have pre-configured environments. +* _Use case assignments_: where you'll apply the concepts you've learned to solve a real-world problem that you'll choose. +* _The Challenge_: you'll get to put your implementation to compete against other implementations in a challenge. There will also be a leaderboard for you to compare performance. + +This **course is a living project, evolving with your feedback and contributions!** Feel free to open issues and PRs in GitHub, and engage in discussions in our Discord server. + +After you have gone through the course, you can also send your feedback 👉 using this form [LINK TO FEEDBACK FORM] + +## What's the syllabus? + +Here is the **general syllabus for the course**. A more detailed list of topics will be released with each unit. + +| Chapter | Topic | Description | +| ------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| 0 | Onboarding | Set you up with the tools and platforms that you will use. | +| 1 | MCP Fundamentals | Explain core concepts, architecture, and components of Model Context Protocol. Show a simple use case using MCP. | +| 2 | Architecture and Core Concepts | Understand the MCP architecture, communication protocols, and core primitives like Tools, Resources, and Prompts. | +| 3 | Practical Development | Learn to implement MCP clients and servers using available SDKs and frameworks. | +| 4 | Advanced Topics and Security | Explore advanced features, security considerations, and the future roadmap of MCP. | + +## What are the prerequisites? + +To be able to follow this course, you should have: + +* Basic understanding of AI and LLM concepts +* Familiarity with software development principles and API concepts +* Experience with at least one programming language (Python or TypeScript examples will be emphasized) + +## What tools do I need? + +You only need 2 things: + +* _A computer_ with an internet connection. +* An _Account_: to access the course resources and create projects. If you don't have an account yet, you can create one **here** (it's free). + +## The Certification Process + +### Two paths + +You can choose to follow this course _in audit mode_, or do the activities and _get one of the two certificates we'll issue_. + +If you audit the course, you can participate in all the challenges and do assignments if you want, and **you don't need to notify us**. + +The certification process is **completely free**: + +* _To get a certification for fundamentals_: you need to complete Unit 1 of the course. This is intended for students that want to get up to date with the latest trends in MCP. +* _To get a certificate of completion_: you need to complete Unit 1, one of the use case assignments we'll propose during the course, and the final challenge. + +There's a deadline for the certification process: all the assignments must be finished before **July 1st 2025**. + + + + +## What is the recommended pace? + +Each chapter in this course is designed **to be completed in 1 week, with approximately 3-4 hours of work per week**. + +Since there's a deadline, we provide you a recommended pace: + + + + +## How to get the most out of the course? + +To get the most out of the course, we have some advice: + +1. Join study groups in Discord: studying in groups is always easier. To do that, you need to join our discord server and verify your account. +2. **Do the quizzes and assignments**: the best way to learn is through hands-on practice and self-assessment. +3. **Define a schedule to stay in sync**: you can use our recommended pace schedule below or create yours. + + + + +## Who are we + +About the authors: + +### Ben Burtenshaw + + + +## Acknowledgments + +We would like to extend our gratitude to the following individuals and partners for their invaluable contributions and support: + + + +## I found a bug, or I want to improve the course + +Contributions are **welcome** 🤗 + +* If you _found a bug 🐛 in a notebook_, please open an issue and **describe the problem**. +* If you _want to improve the course_, you can open a Pull Request. +* If you _want to add a full section or a new unit_, the best is to open an issue and **describe what content you want to add before starting to write it so that we can guide you**. + +## I still have questions + +Please ask your question in our discord server #mcp-course-questions. + +Now that you have all the information, let's get on board ⛵ \ No newline at end of file diff --git a/units/en/unit1/architectural-components.mdx b/units/en/unit1/architectural-components.mdx new file mode 100644 index 0000000..0700569 --- /dev/null +++ b/units/en/unit1/architectural-components.mdx @@ -0,0 +1,3 @@ +# Architectural Components + +This is a placeholder for the Architectural Components section. \ No newline at end of file diff --git a/units/en/unit1/capabilities.mdx b/units/en/unit1/capabilities.mdx new file mode 100644 index 0000000..2ab8489 --- /dev/null +++ b/units/en/unit1/capabilities.mdx @@ -0,0 +1,3 @@ +# Understanding MCP Capabilities + +This is a placeholder for the Understanding MCP Capabilities section. \ No newline at end of file diff --git a/units/en/unit1/communication-protocol.mdx b/units/en/unit1/communication-protocol.mdx new file mode 100644 index 0000000..f34f5fa --- /dev/null +++ b/units/en/unit1/communication-protocol.mdx @@ -0,0 +1,3 @@ +# The Communication Protocol + +This is a placeholder for the Communication Protocol section. \ No newline at end of file diff --git a/units/en/unit1/gradio-mcp.mdx b/units/en/unit1/gradio-mcp.mdx new file mode 100644 index 0000000..f8ab99a --- /dev/null +++ b/units/en/unit1/gradio-mcp.mdx @@ -0,0 +1,3 @@ +# Gradio MCP Integration + +This is a placeholder for the Gradio MCP Integration section. \ No newline at end of file diff --git a/units/en/unit1/introduction.mdx b/units/en/unit1/introduction.mdx new file mode 100644 index 0000000..abe360d --- /dev/null +++ b/units/en/unit1/introduction.mdx @@ -0,0 +1,33 @@ +# Introduction to Model Context Protocol (MCP) + +Welcome to Unit 1 of the MCP Course! In this unit, we'll explore the fundamentals of Model Context Protocol. + +## What You Will Learn + +In this unit, you will: + +* Understand what Model Context Protocol is and why it's important +* Learn the key concepts and terminology associated with MCP +* Explore the integration challenges that MCP solves +* Walk through the key benefits and goals of MCP +* See a simple example of MCP integration in action + +By the end of this unit, you'll have a solid understanding of the foundational concepts of MCP and be ready to dive deeper into its architecture and implementation in the next unit. + +## Importance of MCP + +The AI ecosystem is evolving rapidly, with Large Language Models (LLMs) and other AI systems becoming increasingly capable. However, these models are often limited by their training data and lack access to real-time information or specialized tools. This limitation hinders the potential of AI systems to provide truly relevant, accurate, and helpful responses in many scenarios. + +This is where Model Context Protocol (MCP) comes in. MCP enables AI models to connect with external data sources, tools, and environments, allowing for the seamless transfer of information and capabilities between AI systems and the broader digital world. This interoperability is crucial for the growth and adoption of truly useful AI applications. + +## Overview of Unit 1 + +Here's a brief overview of what we'll cover in this unit: + +1. **What is Model Context Protocol?** - We'll start by defining what MCP is and discussing its role in the AI ecosystem. +2. **Key Concepts** - We'll explore the fundamental concepts and terminology associated with MCP. +3. **Integration Challenges** - We'll examine the problems that MCP aims to solve, particularly the "M×N Integration Problem." +4. **Benefits and Goals** - We'll discuss the key benefits and goals of MCP, including standardization, enhanced AI capabilities, and interoperability. +5. **Simple Example** - Finally, we'll walk through a simple example of MCP integration to see how it works in practice. + +Let's dive in and explore the exciting world of Model Context Protocol! \ No newline at end of file diff --git a/units/en/unit1/key-concepts.mdx b/units/en/unit1/key-concepts.mdx new file mode 100644 index 0000000..d0ee946 --- /dev/null +++ b/units/en/unit1/key-concepts.mdx @@ -0,0 +1,15 @@ +# Key Concepts and Terminology + +This is a placeholder for the Key Concepts and Terminology section. + +## Core Terminology + +Content about core terminology will go here. + +## Technical Concepts + +Content about technical concepts will go here. + +## Architecture Overview + +Content about the architecture overview will go here. \ No newline at end of file diff --git a/units/en/unit2/building-server.mdx b/units/en/unit2/building-server.mdx new file mode 100644 index 0000000..3703829 --- /dev/null +++ b/units/en/unit2/building-server.mdx @@ -0,0 +1,3 @@ +# Building Your First MCP Server + +This is a placeholder for the Building Your First MCP Server section. \ No newline at end of file diff --git a/units/en/unit2/configuration.mdx b/units/en/unit2/configuration.mdx new file mode 100644 index 0000000..fc70917 --- /dev/null +++ b/units/en/unit2/configuration.mdx @@ -0,0 +1,3 @@ +# Configuration, Authentication, and Debugging + +This is a placeholder for the Configuration, Authentication, and Debugging section. \ No newline at end of file diff --git a/units/en/unit2/developing-clients.mdx b/units/en/unit2/developing-clients.mdx new file mode 100644 index 0000000..2c30ea6 --- /dev/null +++ b/units/en/unit2/developing-clients.mdx @@ -0,0 +1,3 @@ +# Developing MCP Clients + +This is a placeholder for the Developing MCP Clients section. \ No newline at end of file diff --git a/units/en/unit2/environment-setup.mdx b/units/en/unit2/environment-setup.mdx new file mode 100644 index 0000000..37a08b9 --- /dev/null +++ b/units/en/unit2/environment-setup.mdx @@ -0,0 +1,3 @@ +# Setting Up Your Development Environment & SDKs + +This is a placeholder for the Setting Up Your Development Environment & SDKs section. \ No newline at end of file diff --git a/units/en/unit2/hub-mcp-servers.mdx b/units/en/unit2/hub-mcp-servers.mdx new file mode 100644 index 0000000..396cc62 --- /dev/null +++ b/units/en/unit2/hub-mcp-servers.mdx @@ -0,0 +1,3 @@ +# MCP Servers on Hugging Face Hub + +This is a placeholder for the MCP Servers on Hugging Face Hub section. \ No newline at end of file diff --git a/units/en/unit2/introduction.mdx b/units/en/unit2/introduction.mdx new file mode 100644 index 0000000..def8791 --- /dev/null +++ b/units/en/unit2/introduction.mdx @@ -0,0 +1 @@ +# Understanding MCP Architecture and Core Concepts \ No newline at end of file diff --git a/units/en/unit2/server-capabilities.mdx b/units/en/unit2/server-capabilities.mdx new file mode 100644 index 0000000..6830901 --- /dev/null +++ b/units/en/unit2/server-capabilities.mdx @@ -0,0 +1,3 @@ +# Implementing Server Capabilities + +This is a placeholder for the Implementing Server Capabilities section. \ No newline at end of file diff --git a/units/en/unit3/advanced-features.mdx b/units/en/unit3/advanced-features.mdx new file mode 100644 index 0000000..db3ea4b --- /dev/null +++ b/units/en/unit3/advanced-features.mdx @@ -0,0 +1,3 @@ +# Exploring Advanced MCP Features + +This is a placeholder for the Exploring Advanced MCP Features section. \ No newline at end of file diff --git a/units/en/unit3/final-project.mdx b/units/en/unit3/final-project.mdx new file mode 100644 index 0000000..cc7a9e3 --- /dev/null +++ b/units/en/unit3/final-project.mdx @@ -0,0 +1,3 @@ +# Final Project - Building a Complete MCP Application + +This is a placeholder for the Final Project - Building a Complete MCP Application section. \ No newline at end of file diff --git a/units/en/unit3/huggingface-ecosystem.mdx b/units/en/unit3/huggingface-ecosystem.mdx new file mode 100644 index 0000000..e707ac9 --- /dev/null +++ b/units/en/unit3/huggingface-ecosystem.mdx @@ -0,0 +1,3 @@ +# Hugging Face's Tiny Agents and MCP + +This is a placeholder for the Hugging Face's Tiny Agents and MCP section. \ No newline at end of file diff --git a/units/en/unit3/introduction.mdx b/units/en/unit3/introduction.mdx new file mode 100644 index 0000000..d1526ee --- /dev/null +++ b/units/en/unit3/introduction.mdx @@ -0,0 +1 @@ +# Introduction \ No newline at end of file diff --git a/units/en/unit3/limitations.mdx b/units/en/unit3/limitations.mdx new file mode 100644 index 0000000..488f3d3 --- /dev/null +++ b/units/en/unit3/limitations.mdx @@ -0,0 +1,3 @@ +# Limitations, Challenges, and Comparisons + +This is a placeholder for the Limitations, Challenges, and Comparisons section. \ No newline at end of file diff --git a/units/en/unit3/security.mdx b/units/en/unit3/security.mdx new file mode 100644 index 0000000..efbe014 --- /dev/null +++ b/units/en/unit3/security.mdx @@ -0,0 +1,3 @@ +# Security Deep Dive - Threats and Mitigation Strategies + +This is a placeholder for the Security Deep Dive - Threats and Mitigation Strategies section. \ No newline at end of file diff --git a/units/en/unit4/introduction.mdx b/units/en/unit4/introduction.mdx new file mode 100644 index 0000000..67b7e26 --- /dev/null +++ b/units/en/unit4/introduction.mdx @@ -0,0 +1 @@ +# Advanced Topics, Security, and the Future of MCP \ No newline at end of file