diff --git a/units/en/unit0/introduction.mdx b/units/en/unit0/introduction.mdx index b6c53de..358ba09 100644 --- a/units/en/unit0/introduction.mdx +++ b/units/en/unit0/introduction.mdx @@ -68,11 +68,8 @@ If you don't have any of these, don't worry! Here are some resources that can he * [LLM Course](https://huggingface.co/learn/llm-course/) will guide you through the basics of using and building with LLMs. * [Agents Course](https://huggingface.co/learn/agents-course/) will guide you through building AI agents with LLMs. - - -The above courses are not prerequisites in themselves, so if you understand the concepts of LLMs and agents, you can start the course now! - - +> [!TIP] +> The above courses are not prerequisites in themselves, so if you understand the concepts of LLMs and agents, you can start the course now! ## What tools do I need? diff --git a/units/en/unit1/architectural-components.mdx b/units/en/unit1/architectural-components.mdx index 621fc8e..603e58b 100644 --- a/units/en/unit1/architectural-components.mdx +++ b/units/en/unit1/architectural-components.mdx @@ -48,11 +48,8 @@ The **Server** is an external program or service that exposes capabilities to AI Let's examine how these components interact in a typical MCP workflow: - - -In the next section, we'll dive deeper into the communication protocol that enables these components with practical examples. - - +> [!TIP] +> In the next section, we'll dive deeper into the communication protocol that enables these components with practical examples. 1. **User Interaction**: The user interacts with the **Host** application, expressing an intent or query. @@ -70,11 +67,8 @@ In the next section, we'll dive deeper into the communication protocol that enab A key advantage of this architecture is its modularity. A single **Host** can connect to multiple **Servers** simultaneously via different **Clients**. New **Servers** can be added to the ecosystem without requiring changes to existing **Hosts**. Capabilities can be easily composed across different **Servers**. - - -As we discussed in the previous section, this modularity transforms the traditional M×N integration problem (M AI applications connecting to N tools/services) into a more manageable M+N problem, where each Host and Server needs to implement the MCP standard only once. - - +> [!TIP] +> As we discussed in the previous section, this modularity transforms the traditional M×N integration problem (M AI applications connecting to N tools/services) into a more manageable M+N problem, where each Host and Server needs to implement the MCP standard only once. The architecture might appear simple, but its power lies in the standardization of the communication protocol and the clear separation of responsibilities between components. This design allows for a cohesive ecosystem where AI models can seamlessly connect with an ever-growing array of external tools and data sources. diff --git a/units/en/unit1/capabilities.mdx b/units/en/unit1/capabilities.mdx index 487354a..cdbcfe4 100644 --- a/units/en/unit1/capabilities.mdx +++ b/units/en/unit1/capabilities.mdx @@ -2,13 +2,10 @@ MCP Servers expose a variety of capabilities to Clients through the communication protocol. These capabilities fall into four main categories, each with distinct characteristics and use cases. Let's explore these core primitives that form the foundation of MCP's functionality. - - -In this section, we'll show examples as framework agnostic functions in each language. This is to focus on the concepts and how they work together, rather than the complexities of any framework. - -In the coming units, we'll show how these concepts are implemented in MCP specific code. - - +> [!TIP] +> In this section, we'll show examples as framework agnostic functions in each language. This is to focus on the concepts and how they work together, rather than the complexities of any framework. +> +> In the coming units, we'll show how these concepts are implemented in MCP specific code. ## Tools @@ -200,11 +197,8 @@ The sampling flow follows these steps: 4. Client reviews the completion 5. Client returns the result to the server - - -This human-in-the-loop design ensures users maintain control over what the LLM sees and generates. When implementing sampling, it's important to provide clear, well-structured prompts and include relevant context. - - +> [!TIP] +> This human-in-the-loop design ensures users maintain control over what the LLM sees and generates. When implementing sampling, it's important to provide clear, well-structured prompts and include relevant context. ## How Capabilities Work Together diff --git a/units/en/unit1/certificate.mdx b/units/en/unit1/certificate.mdx index cada2a3..70e486d 100644 --- a/units/en/unit1/certificate.mdx +++ b/units/en/unit1/certificate.mdx @@ -11,9 +11,6 @@ Below is a quiz to check your understanding of the unit. height="450" > - - -If you're struggling to use the quiz above, go to the space directly [on the Hugging Face Hub](https://huggingface.co/spaces/mcp-course/unit_1_quiz). If you find errors, you can report them in the space's [Community tab](https://huggingface.co/spaces/mcp-course/unit_1_quiz/discussions). - - +> [!TIP] +> If you're struggling to use the quiz above, go to the space directly [on the Hugging Face Hub](https://huggingface.co/spaces/mcp-course/unit_1_quiz). If you find errors, you can report them in the space's [Community tab](https://huggingface.co/spaces/mcp-course/unit_1_quiz/discussions). diff --git a/units/en/unit1/communication-protocol.mdx b/units/en/unit1/communication-protocol.mdx index a01afaf..b0fc8e2 100644 --- a/units/en/unit1/communication-protocol.mdx +++ b/units/en/unit1/communication-protocol.mdx @@ -2,11 +2,8 @@ MCP defines a standardized communication protocol that enables Clients and Servers to exchange messages in a consistent, predictable way. This standardization is critical for interoperability across the community. In this section, we'll explore the protocol structure and transport mechanisms used in MCP. - - -We're getting down to the nitty-gritty details of the MCP protocol. You won't need to know all of this to build with MCP, but it's good to know that it exists and how it works. - - +> [!WARNING] +> We're getting down to the nitty-gritty details of the MCP protocol. You won't need to know all of this to build with MCP, but it's good to know that it exists and how it works. ## JSON-RPC: The Foundation @@ -99,11 +96,8 @@ The stdio transport is used for local communication, where the Client and Server The Host application launches the Server as a subprocess and communicates with it by writing to its standard input (stdin) and reading from its standard output (stdout). - - -**Use cases** for this transport are local tools like file system access or running local scripts. - - +> [!TIP] +> **Use cases** for this transport are local tools like file system access or running local scripts. The main **Advantages** of this transport are that it's simple, no network configuration required, and securely sandboxed by the operating system. @@ -113,11 +107,8 @@ The HTTP+SSE transport is used for remote communication, where the Client and Se Communication happens over HTTP, with the Server using Server-Sent Events (SSE) to push updates to the Client over a persistent connection. - - -**Use cases** for this transport are connecting to remote APIs, cloud services, or shared resources. - - +> [!TIP] +> **Use cases** for this transport are connecting to remote APIs, cloud services, or shared resources. The main **Advantages** of this transport are that it works across networks, enables integration with web services, and is compatible with serverless environments. diff --git a/units/en/unit1/gradio-mcp.mdx b/units/en/unit1/gradio-mcp.mdx index 4d8a512..9f561b0 100644 --- a/units/en/unit1/gradio-mcp.mdx +++ b/units/en/unit1/gradio-mcp.mdx @@ -2,11 +2,8 @@ We've now explored the core concepts of the MCP protocol and how to implement MCP Servers and Clients. In this section, we're going to make things slightly easier by using Gradio to create an MCP Server! - - -Gradio is a popular Python library for quickly creating customizable web interfaces for machine learning models. - - +> [!TIP] +> Gradio is a popular Python library for quickly creating customizable web interfaces for machine learning models. ## Introduction to Gradio diff --git a/units/en/unit1/hf-mcp-server.mdx b/units/en/unit1/hf-mcp-server.mdx index 729d64d..6b743a4 100644 --- a/units/en/unit1/hf-mcp-server.mdx +++ b/units/en/unit1/hf-mcp-server.mdx @@ -2,11 +2,8 @@ The Hugging Face MCP (Model Context Protocol) Server connects your MCP‑compatible AI assistant (for example VS Code, Cursor, Zed, or Claude Desktop) directly to the Hugging Face Hub. Once connected, your assistant can search and explore Hub resources and use community tools, all from within your editor, chat or CLI. - - -The main advanatage of the Hugging Face MCP Server is that it provides a built-in tools for the hub as well as community tools based on Gradio Spaces. As we start to build our own MCP servers, we'll see that we can use the Hugging Face MCP Server as a reference for our own MCP servers. - - +> [!TIP] +> The main advanatage of the Hugging Face MCP Server is that it provides a built-in tools for the hub as well as community tools based on Gradio Spaces. As we start to build our own MCP servers, we'll see that we can use the Hugging Face MCP Server as a reference for our own MCP servers. ## What you can do @@ -31,11 +28,8 @@ The server provides curated tools that work across supported clients: 3. Paste and restart: copy the snippet into your client’s MCP configuration, save, and restart/reload the client. You should see “Hugging Face” (or similar) listed as a connected MCP server in your client. - - -The settings page generates the exact configuration your client expects. Use it rather than writing config by hand. - - +> [!TIP] +> The settings page generates the exact configuration your client expects. Use it rather than writing config by hand. ![MCP Settings Example](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hf-mcp-settings.png) diff --git a/units/en/unit1/key-concepts.mdx b/units/en/unit1/key-concepts.mdx index 3e1df92..491fe11 100644 --- a/units/en/unit1/key-concepts.mdx +++ b/units/en/unit1/key-concepts.mdx @@ -35,13 +35,10 @@ MCP transforms this into an M+N problem by providing a standard interface: each Now that we understand the problem that MCP solves, let's dive into the core terminology and concepts that make up the MCP protocol. - - -MCP is a standard like HTTP or USB-C, and is a protocol for connecting AI applications to external tools and data sources. Therefore, using standard terminology is crucial to making the MCP work effectively. - -When documenting our applications and communicating with the community, we should use the following terminology. - - +> [!TIP] +> MCP is a standard like HTTP or USB-C, and is a protocol for connecting AI applications to external tools and data sources. Therefore, using standard terminology is crucial to making the MCP work effectively. +> +> When documenting our applications and communicating with the community, we should use the following terminology. ### Components @@ -55,11 +52,8 @@ Just like client server relationships in HTTP, MCP has a client and a server. - **Server**: An external program or service that exposes capabilities (Tools, Resources, Prompts) via the MCP protocol. - - -A lot of content uses 'Client' and 'Host' interchangeably. Technically speaking, the host is the user-facing application, and the client is the component within the host application that manages communication with a specific MCP Server. - - +> [!WARNING] +> A lot of content uses 'Client' and 'Host' interchangeably. Technically speaking, the host is the user-facing application, and the client is the component within the host application that manages communication with a specific MCP Server. ### Capabilities diff --git a/units/en/unit1/mcp-clients.mdx b/units/en/unit1/mcp-clients.mdx index 29bec79..71a729d 100644 --- a/units/en/unit1/mcp-clients.mdx +++ b/units/en/unit1/mcp-clients.mdx @@ -12,13 +12,10 @@ In this section, you will: * Discover how to connect to the Hugging Face MCP Server and built-in tools * See practical examples of MCP Client usage - - -In this page we're going to show examples of how to set up MCP Clients in a few different ways using the JSON notation. For now, we will use *examples* like `path/to/server.py` to represent the path to the MCP Server. In the next unit, we'll implement this with real MCP Servers. - -For now, focus on understanding the MCP Client notation. We'll implement the MCP Servers in the next unit. - - +> [!TIP] +> In this page we're going to show examples of how to set up MCP Clients in a few different ways using the JSON notation. For now, we will use *examples* like `path/to/server.py` to represent the path to the MCP Server. In the next unit, we'll implement this with real MCP Servers. +> +> For now, focus on understanding the MCP Client notation. We'll implement the MCP Servers in the next unit. ## Understanding MCP Clients @@ -57,11 +54,8 @@ Now that we've covered the core of the MCP protocol, let's look at how to config Effective deployment of MCP servers and clients requires proper configuration. - - -The MCP specification is still evolving, so the configuration methods are subject to evolution. We'll focus on the current best practices for configuration. - - +> [!TIP] +> The MCP specification is still evolving, so the configuration methods are subject to evolution. We'll focus on the current best practices for configuration. ### MCP Configuration Files @@ -274,11 +268,8 @@ huggingface-cli login After creating your Hugging Face access token and logging in, you need to ensure your token has the proper permissions to work with inference providers. - - -**Important:** If you skip this step, you may encounter authentication errors when running tiny agents with hosted models. - - +> [!WARNING] +> **Important:** If you skip this step, you may encounter authentication errors when running tiny agents with hosted models. 1. Go to your [Hugging Face Access Tokens page](https://huggingface.co/settings/tokens) 2. Find your MCP token and click the three dots (⋮) next to it diff --git a/units/en/unit2/clients.mdx b/units/en/unit2/clients.mdx index e69da54..6d92cbe 100644 --- a/units/en/unit2/clients.mdx +++ b/units/en/unit2/clients.mdx @@ -32,11 +32,8 @@ The standard configuration file for MCP is named `mcp.json`. Here's the basic st In this example, we have a single server configured to use SSE transport, connecting to a local Gradio server running on port 7860. - - -We've connected to the Gradio app via SSE transport because we assume that the gradio app is running on a remote server. However, if you want to connect to a local script, `stdio` transport instead of `sse` transport is a better option. - - +> [!TIP] +> We've connected to the Gradio app via SSE transport because we assume that the gradio app is running on a remote server. However, if you want to connect to a local script, `stdio` transport instead of `sse` transport is a better option. #### Configuration for HTTP+SSE Transport diff --git a/units/en/unit2/continue-client.mdx b/units/en/unit2/continue-client.mdx index 941a4cb..e308f79 100644 --- a/units/en/unit2/continue-client.mdx +++ b/units/en/unit2/continue-client.mdx @@ -8,11 +8,8 @@ like Ollama. You can install Continue from the VS Code marketplace. - - -*Continue also has an extension for [JetBrains](https://plugins.jetbrains.com/plugin/22707-continue).* - - +> [!TIP] +> *Continue also has an extension for [JetBrains](https://plugins.jetbrains.com/plugin/22707-continue).* ### VS Code extension @@ -63,11 +60,8 @@ This model is around 14GB in size, so you need to ensure that the machine you ar - - -Continue supports various local model providers. Besides Ollama, Llama.cpp, and LM Studio you can also use other providers. For a complete list of supported providers and detailed configuration options, please refer to the [Continue documentation](https://docs.continue.dev/customize/model-providers). - - +> [!TIP] +> Continue supports various local model providers. Besides Ollama, Llama.cpp, and LM Studio you can also use other providers. For a complete list of supported providers and detailed configuration options, please refer to the [Continue documentation](https://docs.continue.dev/customize/model-providers). It is important that we use models that have tool calling as a built-in feature, i.e. Codestral Qwen and Llama 3.1x. diff --git a/units/en/unit2/gradio-client.mdx b/units/en/unit2/gradio-client.mdx index eb70dc0..1391a90 100644 --- a/units/en/unit2/gradio-client.mdx +++ b/units/en/unit2/gradio-client.mdx @@ -2,11 +2,8 @@ In the previous section, we explored how to create an MCP Server using Gradio and connect to it using an MCP Client. In this section, we're going to explore how to use Gradio as an MCP Client to connect to an MCP Server. - - -Gradio is best suited to the creation of UI clients and MCP servers, but it is also possible to use it as an MCP Client and expose that as a UI. - - +> [!TIP] +> Gradio is best suited to the creation of UI clients and MCP servers, but it is also possible to use it as an MCP Client and expose that as a UI. We'll connect to an MCP server similar to the one we created in the previous section but with additional features, and use it to answer questions. diff --git a/units/en/unit2/introduction.mdx b/units/en/unit2/introduction.mdx index 9b42dac..f344609 100644 --- a/units/en/unit2/introduction.mdx +++ b/units/en/unit2/introduction.mdx @@ -4,11 +4,8 @@ Welcome to Unit 2 of the MCP Course! In this unit, we'll build a complete MCP application from scratch, focusing on creating a server with Gradio and connecting it with multiple clients. This hands-on approach will give you practical experience with the entire MCP ecosystem. - - -In this unit, we're going to build a simple MCP server and client using Gradio and the HuggingFace hub. In the next unit, we'll build a more complex server that tackles a real-world use case. - - +> [!TIP] +> In this unit, we're going to build a simple MCP server and client using Gradio and the HuggingFace hub. In the next unit, we'll build a more complex server that tackles a real-world use case. ## What You'll Learn diff --git a/units/en/unit2/lemonade-server.mdx b/units/en/unit2/lemonade-server.mdx index d4a657c..a476af9 100644 --- a/units/en/unit2/lemonade-server.mdx +++ b/units/en/unit2/lemonade-server.mdx @@ -23,11 +23,8 @@ Once you have installed Lemonade Server, you can launch it by clicking the `Lemo To install Lemonade on Linux, first create and activate a venv: - - -If you don't have `uv` installed, you can install it following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). - - +> [!TIP] +> If you don't have `uv` installed, you can install it following the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). ```bash uv venv --python 3.11 @@ -54,11 +51,8 @@ lemonade-server-dev serve Lemonade Server supports CPU inference across all platforms and engines on Windows x86/x64. For GPU acceleration is enabled through llamacpp engine (Vulkan), with a focus on AMD Ryzen™ AI 7000/8000/300 series and Radeon™ 7000/9000 series. - - -*NPU acceleration is only available for AMD Ryzen™ AI 300 series on Windows.* - - +> [!TIP] +> *NPU acceleration is only available for AMD Ryzen™ AI 300 series on Windows.* @@ -343,11 +337,8 @@ Tool iNtxGmOuXHqZVBWmKnfxsc61xsJbsoAM The job description for the Senior Food Technology Engineer position emphasizes the need for a candidate who can bridge the gap between food science and artificial intelligence (...). Candidates are also expected to attend conferences and publish research on algorithmic cooking optimization. ``` - - -We are using the default system prompt, which may cause the assistant to call some tools multiple times. To create a more assertive assistant, you can provide a custom `PROMPT.md` file in the same directory as your `agent.json`. - - +> [!TIP] +> We are using the default system prompt, which may cause the assistant to call some tools multiple times. To create a more assertive assistant, you can provide a custom `PROMPT.md` file in the same directory as your `agent.json`. Great! Now let's read the candidate's resume. diff --git a/units/en/unit2/tiny-agents.mdx b/units/en/unit2/tiny-agents.mdx index 970baaa..3fa24af 100644 --- a/units/en/unit2/tiny-agents.mdx +++ b/units/en/unit2/tiny-agents.mdx @@ -11,11 +11,8 @@ In this final exercise of Unit 2, we will walk you through how to implement both Let's install the necessary packages to build our Tiny Agents. - - -Some MCP Clients, notably Claude Desktop, do not yet support SSE-based MCP Servers. In those cases, you can use a tool such as [mcp-remote](https://github.com/geelen/mcp-remote). First install Node.js. Then, add the following to your own MCP Client config: - - +> [!TIP] +> Some MCP Clients, notably Claude Desktop, do not yet support SSE-based MCP Servers. In those cases, you can use a tool such as [mcp-remote](https://github.com/geelen/mcp-remote). First install Node.js. Then, add the following to your own MCP Client config: Tiny Agent can run MCP servers with a command line environment. To do this, we will need to install `npm` and run the server with `npx`. **We'll need these for both Python and JavaScript.** @@ -140,31 +137,28 @@ Here we have a basic Tiny Agent that can connect to our Gradio MCP server. It in | `provider` | The inference provider to use for the agent | | `servers` | The servers to use for the agent. We'll use the `mcp-remote` server for our Gradio MCP server. | - - -We could also use an open source model running locally with Tiny Agents. If we start a local inference server with - -```json -{ - "model": "Qwen/Qwen3-32B", - "endpointUrl": "http://localhost:1234/v1", - "servers": [ - { - "type": "stdio", - "command": "npx", - "args": [ - "mcp-remote", - "http://localhost:1234/v1/mcp/sse" - ] - } - ] -} -``` - - -Here we have a Tiny Agent that can connect to a local model. It includes a model, endpoint URL (`http://localhost:1234/v1`), and a server configuration. The endpoint should be an OpenAI-compatible endpoint. - - +> [!TIP] +> We could also use an open source model running locally with Tiny Agents. If we start a local inference server with +> +> ```json +> { +> "model": "Qwen/Qwen3-32B", +> "endpointUrl": "http://localhost:1234/v1", +> "servers": [ +> { +> "type": "stdio", +> "command": "npx", +> "args": [ +> "mcp-remote", +> "http://localhost:1234/v1/mcp/sse" +> ] +> } +> ] +> } +> ``` +> +> +> Here we have a Tiny Agent that can connect to a local model. It includes a model, endpoint URL (`http://localhost:1234/v1`), and a server configuration. The endpoint should be an OpenAI-compatible endpoint. ## Custom Tiny Agents MCP Client diff --git a/units/en/unit3/build-mcp-server.mdx b/units/en/unit3/build-mcp-server.mdx index 5ba06c5..1656a1b 100644 --- a/units/en/unit3/build-mcp-server.mdx +++ b/units/en/unit3/build-mcp-server.mdx @@ -99,15 +99,13 @@ cd mcp-course/projects/unit3/build-mcp-server/starter Install dependencies: - - -You might want to create a virtual environment for this project: - -```bash -uv venv .venv -source .venv/bin/activate # On Windows use: .venv\Scripts\activate -``` - +> [!TIP] +> You might want to create a virtual environment for this project: +> +> ```bash +> uv venv .venv +> source .venv/bin/activate # On Windows use: .venv\Scripts\activate +> ``` ```bash uv sync --all-extras @@ -136,11 +134,8 @@ Unlike traditional systems that categorize changes based on file extensions or r - Allow Claude to make intelligent template suggestions - Keep the logic simple - Claude handles the complexity - - -**MCP Philosophy**: Instead of building complex logic into your tools, provide Claude with rich data and let its intelligence make the decisions. This makes your code simpler and more flexible than traditional rule-based systems. - - +> [!TIP] +> **MCP Philosophy**: Instead of building complex logic into your tools, provide Claude with rich data and let its intelligence make the decisions. This makes your code simpler and more flexible than traditional rule-based systems. ## Testing Your Implementation @@ -177,11 +172,8 @@ Then: 2. Ask Claude: "Can you analyze my changes and suggest a PR template?" 3. Watch Claude use your tools to provide intelligent suggestions - - -**Common first error**: If you get "MCP tool response exceeds maximum allowed tokens (25000)", this is expected! Large repositories can generate massive diffs. This is a valuable learning moment - see the "Handling Large Outputs" section for the solution. - - +> [!WARNING] +> **Common first error**: If you get "MCP tool response exceeds maximum allowed tokens (25000)", this is expected! Large repositories can generate massive diffs. This is a valuable learning moment - see the "Handling Large Outputs" section for the solution. ## Common Patterns @@ -213,19 +205,13 @@ except Exception as e: return json.dumps({"error": str(e)}) ``` - - -**Error Handling**: Always return valid JSON from your tools, even for errors. Claude needs structured data to understand what went wrong and provide helpful responses to users. - - +> [!WARNING] +> **Error Handling**: Always return valid JSON from your tools, even for errors. Claude needs structured data to understand what went wrong and provide helpful responses to users. ### Handling Large Outputs (Critical Learning Moment!) - - -**Real-world constraint**: MCP tools have a token limit of 25,000 tokens per response. Large git diffs can easily exceed this limit 10x or more! This is a critical lesson for production MCP development. - - +> [!WARNING] +> **Real-world constraint**: MCP tools have a token limit of 25,000 tokens per response. Large git diffs can easily exceed this limit 10x or more! This is a critical lesson for production MCP development. When implementing `analyze_file_changes`, you'll likely encounter this error: ``` diff --git a/units/en/unit3/certificate.mdx b/units/en/unit3/certificate.mdx index b21c62b..c304ed6 100644 --- a/units/en/unit3/certificate.mdx +++ b/units/en/unit3/certificate.mdx @@ -11,9 +11,6 @@ Below is a quiz to check your understanding of the unit. height="450" > - - -If you're struggling to use the quiz above, go to the space directly [on the Hugging Face Hub](https://huggingface.co/spaces/mcp-course/unit_3_quiz). If you find errors, you can report them in the space's [Community tab](https://huggingface.co/spaces/mcp-course/unit_3_quiz/discussions). - - +> [!TIP] +> If you're struggling to use the quiz above, go to the space directly [on the Hugging Face Hub](https://huggingface.co/spaces/mcp-course/unit_3_quiz). If you find errors, you can report them in the space's [Community tab](https://huggingface.co/spaces/mcp-course/unit_3_quiz/discussions). diff --git a/units/en/unit3/conclusion.mdx b/units/en/unit3/conclusion.mdx index 16654a4..c320a43 100644 --- a/units/en/unit3/conclusion.mdx +++ b/units/en/unit3/conclusion.mdx @@ -64,11 +64,8 @@ Your three-module journey tackled real problems that every development team face The patterns you've learned can be applied to many automation scenarios: - - -**Beyond CI/CD**: The Tools + Prompts pattern works for customer support automation, content moderation, data analysis workflows, and any scenario where you need intelligent processing of external data. - - +> [!TIP] +> **Beyond CI/CD**: The Tools + Prompts pattern works for customer support automation, content moderation, data analysis workflows, and any scenario where you need intelligent processing of external data. ### Common Patterns from Unit 3 1. **Data Collection** → Tools that gather information @@ -96,11 +93,8 @@ The patterns you've learned can be applied to many automation scenarios: ## Key Takeaways - - -**MCP Philosophy**: The most effective MCP servers don't try to be smart - they provide Claude with rich, structured data and let Claude's intelligence do the heavy lifting. This makes your code simpler and more flexible. - - +> [!TIP] +> **MCP Philosophy**: The most effective MCP servers don't try to be smart - they provide Claude with rich, structured data and let Claude's intelligence do the heavy lifting. This makes your code simpler and more flexible. ### Technical Insights - **Simple is powerful**: JSON file storage can handle many use cases diff --git a/units/en/unit3/github-actions-integration.mdx b/units/en/unit3/github-actions-integration.mdx index 5747c6e..4dce3e5 100644 --- a/units/en/unit3/github-actions-integration.mdx +++ b/units/en/unit3/github-actions-integration.mdx @@ -77,11 +77,8 @@ Your MCP server will run two services: This allows Claude to react to real-time CI/CD events! - - -**Architecture Insight**: Running separate services for MCP communication and webhook handling is a clean separation of concerns. The webhook server handles HTTP complexity while your MCP server focuses on data analysis and Claude integration. - - +> [!TIP] +> **Architecture Insight**: Running separate services for MCP communication and webhook handling is a clean separation of concerns. The webhook server handles HTTP complexity while your MCP server focuses on data analysis and Claude integration. ## Project Structure @@ -136,21 +133,15 @@ EVENTS_FILE = Path(__file__).parent / "github_events.json" The webhook server handles all the HTTP details - you just need to read the JSON file! This separation of concerns keeps your MCP server focused on what it does best. - - -**Development Tip**: Working with files instead of HTTP requests makes testing much easier. You can manually add events to `github_events.json` to test your tools without setting up webhooks. - - +> [!TIP] +> **Development Tip**: Working with files instead of HTTP requests makes testing much easier. You can manually add events to `github_events.json` to test your tools without setting up webhooks. ### Step 3: Add GitHub Actions Tools Just like in Module 1 where you created tools for file analysis, you'll now create tools for CI/CD analysis. These tools will work alongside your existing PR analysis tools, giving Claude a complete view of both code changes and build status. - - -**Note**: The starter code already includes the output limiting fix from Module 1, so you won't encounter token limit errors. Focus on the new concepts in this module! - - +> [!TIP] +> **Note**: The starter code already includes the output limiting fix from Module 1, so you won't encounter token limit errors. Focus on the new concepts in this module! Implement two new tools: diff --git a/units/en/unit3/introduction.mdx b/units/en/unit3/introduction.mdx index 4c6b5d7..9c84248 100644 --- a/units/en/unit3/introduction.mdx +++ b/units/en/unit3/introduction.mdx @@ -64,11 +64,8 @@ Before starting this unit, ensure you have: This unit requires Claude Code to test your MCP server integration. - - -**Installation Required:** This unit requires Claude Code for testing MCP server integration with AI workflows. - - +> [!TIP] +> **Installation Required:** This unit requires Claude Code for testing MCP server integration with AI workflows. **Quick Setup:** @@ -76,11 +73,8 @@ Follow the [official installation guide](https://docs.anthropic.com/en/docs/clau Once installed, you'll use Claude Code throughout this unit to test your MCP server and interact with the workflow automation you build. - - -**New to Claude Code?** If you encounter any setup issues, the [troubleshooting guide](https://docs.anthropic.com/en/docs/claude-code/troubleshooting) covers common installation and authentication problems. - - +> [!WARNING] +> **New to Claude Code?** If you encounter any setup issues, the [troubleshooting guide](https://docs.anthropic.com/en/docs/claude-code/troubleshooting) covers common installation and authentication problems. By the end of this unit, you'll have built a complete MCP server that demonstrates how to transform Claude Code into a powerful team development assistant, with hands-on experience using all three MCP primitives. diff --git a/units/en/unit3/slack-notification.mdx b/units/en/unit3/slack-notification.mdx index 92fbc6b..97725db 100644 --- a/units/en/unit3/slack-notification.mdx +++ b/units/en/unit3/slack-notification.mdx @@ -130,21 +130,15 @@ slack-notification/ - Never commit webhook URLs to version control (add to .gitignore) - Treat it like a password - anyone with this URL can send messages to your channel - - -**Security Alert**: Webhook URLs are sensitive credentials! Anyone with your webhook URL can send messages to your Slack channel. Always store them as environment variables and never commit them to version control. - - +> [!WARNING] +> **Security Alert**: Webhook URLs are sensitive credentials! Anyone with your webhook URL can send messages to your Slack channel. Always store them as environment variables and never commit them to version control. ### Step 2: Add Slack Tool (15 min) Now that you have a working webhook, you'll add a new MCP tool to your existing server.py from Module 2. This tool will handle sending notifications to Slack by making HTTP requests to the webhook URL. - - -**Note**: The starter code includes all improvements from Modules 1 & 2 (output limiting, webhook handling). Focus on the new Slack integration! - - +> [!TIP] +> **Note**: The starter code includes all improvements from Modules 1 & 2 (output limiting, webhook handling). Focus on the new Slack integration! Add this tool to your server.py: @@ -338,11 +332,8 @@ You've now built a complete MCP workflow that demonstrates: This shows the power of MCP for building practical development automation tools! - - -**Key Learning**: You've now built a complete MCP workflow that combines Tools (for external API calls) with Prompts (for consistent formatting). This pattern of Tools + Prompts is fundamental to advanced MCP development and can be applied to many other automation scenarios. - - +> [!TIP] +> **Key Learning**: You've now built a complete MCP workflow that combines Tools (for external API calls) with Prompts (for consistent formatting). This pattern of Tools + Prompts is fundamental to advanced MCP development and can be applied to many other automation scenarios. ## Next Steps diff --git a/units/en/unit3_1/conclusion.mdx b/units/en/unit3_1/conclusion.mdx index 2c93124..28cc38f 100644 --- a/units/en/unit3_1/conclusion.mdx +++ b/units/en/unit3_1/conclusion.mdx @@ -35,8 +35,5 @@ Throughout this unit, you created a complete automation system with four key com - Build more sophisticated automation workflows - Explore commercial applications of AI automation - - -Consider documenting your experience and sharing it with the community! Your journey from learning MCP to building a production agent will help others explore AI automation. - - +> [!TIP] +> Consider documenting your experience and sharing it with the community! Your journey from learning MCP to building a production agent will help others explore AI automation. diff --git a/units/en/unit3_1/creating-the-mcp-server.mdx b/units/en/unit3_1/creating-the-mcp-server.mdx index 9ab67e0..66540c6 100644 --- a/units/en/unit3_1/creating-the-mcp-server.mdx +++ b/units/en/unit3_1/creating-the-mcp-server.mdx @@ -43,11 +43,8 @@ The imports above give us everything we need to build our MCP server. `FastMCP` The `load_dotenv()` call automatically loads environment variables from a `.env` file, making it easy to manage secrets like API tokens during development. - - -If you're using uv, you can create a `.env` file in the root of the project and you won't need to use `load_dotenv()` if you use `uv run` to run the server. - - +> [!TIP] +> If you're using uv, you can create a `.env` file in the root of the project and you won't need to use `load_dotenv()` if you use `uv run` to run the server. Next, we'll configure our server with the necessary credentials and create the FastMCP instance: @@ -88,11 +85,8 @@ def get_current_tags(repo_id: str) -> str: The function starts with validation - checking if we have an authenticated API client. Notice how we return JSON strings instead of Python objects. This is crucial for MCP communication. - - -All MCP tools must return strings, not Python objects. That's why we use `json.dumps()` to convert our results to JSON strings. This ensures reliable data exchange between the MCP server and client. - - +> [!TIP] +> All MCP tools must return strings, not Python objects. That's why we use `json.dumps()` to convert our results to JSON strings. This ensures reliable data exchange between the MCP server and client. Let's continue with the main logic of the `get_current_tags` function: @@ -127,11 +121,8 @@ This implementation follows a clear pattern: 3. **Structure the result** in a consistent JSON format 4. **Handle errors gracefully** with detailed error messages - - -The extensive logging might seem overkill, but it helps with debugging and monitoring when the server is running. Remember, your application will autonomously reacting to events from the Hub, so you won't be able to see the logs in real time. - - +> [!TIP] +> The extensive logging might seem overkill, but it helps with debugging and monitoring when the server is running. Remember, your application will autonomously reacting to events from the Hub, so you won't be able to see the logs in real time. ### 3. Add New Tag Tool @@ -176,11 +167,8 @@ Similar to our first tool, we start with validation. Now let's fetch the current This section demonstrates an important principle: **validate before acting**. We check if the tag already exists to avoid creating unnecessary pull requests. - - -Always check the current state before making changes. This prevents duplicate work and provides better user feedback. It's especially important when creating pull requests, as duplicate PRs can clutter the repository. - - +> [!TIP] +> Always check the current state before making changes. This prevents duplicate work and provides better user feedback. It's especially important when creating pull requests, as duplicate PRs can clutter the repository. Next, we'll prepare the updated tag list and handle the model card: @@ -237,13 +225,10 @@ This PR adds the `{new_tag}` tag to the model repository. We create a detailed pull request description that explains what's changing and why. This transparency is crucial for repository maintainers who will review the PR. - - -Clear, detailed PR descriptions are essential for automated pull requests. They help repository maintainers understand what's happening and make informed decisions about whether to merge the changes. - -Also, it's good practice to clearly state that the PR is created by an automated tool. This helps repository maintainers understand how to deal with the PR. - - +> [!TIP] +> Clear, detailed PR descriptions are essential for automated pull requests. They help repository maintainers understand what's happening and make informed decisions about whether to merge the changes. +> +> Also, it's good practice to clearly state that the PR is created by an automated tool. This helps repository maintainers understand how to deal with the PR. Finally, we create the commit and pull request: @@ -310,13 +295,10 @@ The comprehensive error handling includes the full traceback, which is invaluabl Emojis in log messages might seem silly, but they make scanning logs much faster. 🔧 for function calls, 📡 for API requests, ✅ for success, and ❌ for errors create visual patterns that help you quickly find what you're looking for. - - -Whilst building this application, it's easy to accidentally create an infinite loop of PRs. This is because the `create_commit` function with `create_pr=True` will create a PR for every commit. If the PR is not merged, the `create_commit` function will be called again, and again, and again... - -We've added checks to prevent this, but it's something to be aware of. - - +> [!TIP] +> Whilst building this application, it's easy to accidentally create an infinite loop of PRs. This is because the `create_commit` function with `create_pr=True` will create a PR for every commit. If the PR is not merged, the `create_commit` function will be called again, and again, and again... +> +> We've added checks to prevent this, but it's something to be aware of. ## Next Steps @@ -329,8 +311,5 @@ Now that we have our MCP server implemented with robust tagging tools, we need t In the next section, we'll create the MCP client that will allow our webhook handler to interact with these tools intelligently. - - -The MCP server runs as a separate process from your main application. This isolation provides better error handling and allows the server to be reused by multiple clients or applications. - - \ No newline at end of file +> [!TIP] +> The MCP server runs as a separate process from your main application. This isolation provides better error handling and allows the server to be reused by multiple clients or applications. \ No newline at end of file diff --git a/units/en/unit3_1/introduction.mdx b/units/en/unit3_1/introduction.mdx index 075129d..fb7036b 100644 --- a/units/en/unit3_1/introduction.mdx +++ b/units/en/unit3_1/introduction.mdx @@ -4,11 +4,8 @@ Welcome to Unit 3 of the MCP Course! In this unit, we'll build a pull request agent that automatically tags Hugging Face model repositories based on discussions and comments. This real-world application demonstrates how to integrate MCP with webhook listeners and automated workflows. - - -This unit showcases a real world use case where MCP servers can respond to real-time events from the Hugging Face Hub, automatically creating pull requests to improve repository metadata. - - +> [!TIP] +> This unit showcases a real world use case where MCP servers can respond to real-time events from the Hugging Face Hub, automatically creating pull requests to improve repository metadata. ## What You'll Learn diff --git a/units/en/unit3_1/mcp-client.mdx b/units/en/unit3_1/mcp-client.mdx index 8eaa4ea..2f72b67 100644 --- a/units/en/unit3_1/mcp-client.mdx +++ b/units/en/unit3_1/mcp-client.mdx @@ -4,11 +4,8 @@ Now that we have our MCP server with tagging tools, we need to create a client t For the sake of this project, we'll build both an API and a Gradio app. The API will be used to test the MCP server and the webhook listener, and the Gradio app will be used to test the MCP client with simulated webhook events. - - -For educational purposes, we will build the MCP Server and MCP Client in the same repo. In a real-world application, you would likely have a separate repo for the MCP Server and MCP Client. In fact, you might only build one of these components. - - +> [!TIP] +> For educational purposes, we will build the MCP Server and MCP Client in the same repo. In a real-world application, you would likely have a separate repo for the MCP Server and MCP Client. In fact, you might only build one of these components. ## Understanding the MCP Client Architecture @@ -95,11 +92,8 @@ This is where the important part happens! Let's break down the Agent configurati - `args: ["mcp_server.py"]`: The script file to execute - `env`: Pass the HF_TOKEN to the server process - - -The `stdio` connection type means the agent starts your MCP server as a subprocess and communicates with it through standard input/output. This is perfect for development and single-machine deployments. - - +> [!TIP] +> The `stdio` connection type means the agent starts your MCP server as a subprocess and communicates with it through standard input/output. This is perfect for development and single-machine deployments. The `load_tools()` call is crucial - it discovers what tools are available from the MCP server and makes them accessible to the agent's reasoning engine. @@ -173,11 +167,8 @@ async def process_webhook_comment(webhook_data: Dict[str, Any]): This first part extracts and combines tags from both the comment content and discussion title. We use a set to deduplicate any tags that appear in both places. - - -Processing both the comment and discussion title increases our chances of catching relevant tags. Users might mention tags in the title like "Missing pytorch tag" or in comments like "This needs #transformers". - - +> [!TIP] +> Processing both the comment and discussion title increases our chances of catching relevant tags. Users might mention tags in the title like "Missing pytorch tag" or in comments like "This needs #transformers". Next, we get our agent and process each tag: @@ -344,11 +335,8 @@ async def webhook_handler(request: Request, background_tasks: BackgroundTasks): This pattern ensures webhook responses are fast (under 1 second) while allowing complex tag processing to happen in the background. - - -Webhook endpoints should respond within 10 seconds or the platform may consider them timed out. Using background tasks ensures you can always respond quickly while handling complex processing asynchronously. - - +> [!TIP] +> Webhook endpoints should respond within 10 seconds or the platform may consider them timed out. Using background tasks ensures you can always respond quickly while handling complex processing asynchronously. ## Next Steps @@ -361,8 +349,5 @@ With our MCP client implemented, we can now: In the next section, we'll implement the webhook listener that will trigger our MCP-powered tagging agent. - - -The Agent class from `huggingface_hub` provides both MCP tool integration and language model reasoning, making it perfect for building intelligent automation workflows like our PR agent. - - \ No newline at end of file +> [!TIP] +> The Agent class from `huggingface_hub` provides both MCP tool integration and language model reasoning, making it perfect for building intelligent automation workflows like our PR agent. \ No newline at end of file diff --git a/units/en/unit3_1/setting-up-the-project.mdx b/units/en/unit3_1/setting-up-the-project.mdx index 4354672..81cb033 100644 --- a/units/en/unit3_1/setting-up-the-project.mdx +++ b/units/en/unit3_1/setting-up-the-project.mdx @@ -2,11 +2,8 @@ In this section, we'll set up the development environment for our Pull Request Agent. - - -We'll use modern Python tooling with `uv` for dependency management and create the necessary configuration files. If you're not familiar with `uv`, you can learn more about it [here](https://docs.astral.sh/uv/). - - +> [!TIP] +> We'll use modern Python tooling with `uv` for dependency management and create the necessary configuration files. If you're not familiar with `uv`, you can learn more about it [here](https://docs.astral.sh/uv/). ## Project Structure @@ -37,11 +34,8 @@ Let's walk through the dependencies and configuration for our project. We will use `uv` to create the `pyproject.toml` file to define our project: - - -If you don't have `uv` installed, you can follow the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). - - +> [!TIP] +> If you don't have `uv` installed, you can follow the instructions [here](https://docs.astral.sh/uv/getting-started/installation/). ```toml [project] @@ -126,8 +120,5 @@ With our project structure and environment set up, we're ready to: In the next section, we'll dive into creating our MCP server that will handle all the Hugging Face Hub interactions. - - -Keep your `.env` file secure and never commit it to version control. The `.env` file should be added to your `.gitignore` file to prevent accidental exposure of secrets. - - \ No newline at end of file +> [!TIP] +> Keep your `.env` file secure and never commit it to version control. The `.env` file should be added to your `.gitignore` file to prevent accidental exposure of secrets. \ No newline at end of file diff --git a/units/en/unit3_1/webhook-listener.mdx b/units/en/unit3_1/webhook-listener.mdx index 62e0fa3..d156e5a 100644 --- a/units/en/unit3_1/webhook-listener.mdx +++ b/units/en/unit3_1/webhook-listener.mdx @@ -19,11 +19,8 @@ Understanding the webhook flow is crucial for building a reliable listener: 5. **Processing**: Extract tags from the comment content 6. **Action**: Use MCP tools to create pull requests for new tags - - -Webhooks are push notifications - the Hugging Face Hub actively sends events to your application rather than you polling for changes. This enables real-time responses to discussions and comments. - - +> [!TIP] +> Webhooks are push notifications - the Hugging Face Hub actively sends events to your application rather than you polling for changes. This enables real-time responses to discussions and comments. ## FastAPI Webhook Application @@ -66,9 +63,8 @@ This configuration sets up: - **Operations store**: In-memory storage for monitoring processed operations - **CORS middleware**: Allows cross-origin requests for the web interface - -The `tag_operations_store` list keeps track of recent webhook processing operations. This is useful for debugging and monitoring, but in production you might want to use a database or limit the size of this list. - +> [!TIP] +> The `tag_operations_store` list keeps track of recent webhook processing operations. This is useful for debugging and monitoring, but in production you might want to use a database or limit the size of this list. ### 2. Webhook Data Models @@ -112,11 +108,8 @@ async def webhook_handler(request: Request, background_tasks: BackgroundTasks): The first step is security validation. We check the `X-Webhook-Secret` header against our configured secret to ensure the webhook is legitimate. - - -Always validate webhook secrets! Without this check, anyone could send fake webhook requests to your application. The secret acts as a shared password between Hugging Face and your application. - - +> [!TIP] +> Always validate webhook secrets! Without this check, anyone could send fake webhook requests to your application. The secret acts as a shared password between Hugging Face and your application. Next, let's parse and validate the webhook data: @@ -169,11 +162,8 @@ This filtering ensures we only process the events we care about - new discussion We use FastAPI's `background_tasks.add_task()` to process the webhook asynchronously. This allows us to return a response quickly (within seconds) while the actual tag processing happens in the background. - - -Webhook endpoints should respond within 10 seconds, or the sending platform may consider them failed. Using background tasks ensures fast responses while allowing complex processing to happen asynchronously. - - +> [!TIP] +> Webhook endpoints should respond within 10 seconds, or the sending platform may consider them failed. Using background tasks ensures fast responses while allowing complex processing to happen asynchronously. ### 4. Comment Processing Logic @@ -227,11 +217,8 @@ Next, we extract and process the tags: We combine tags from both sources and create an operation record for monitoring. This record tracks the progress of each webhook processing operation. - - -Storing operation records is crucial for debugging and monitoring. When something goes wrong, you can look at recent operations to understand what happened and why. - - +> [!TIP] +> Storing operation records is crucial for debugging and monitoring. When something goes wrong, you can look at recent operations to understand what happened and why. Now for the MCP agent integration: @@ -357,11 +344,8 @@ async def get_operations(): The operations endpoint lets you see recent webhook processing activity, which is invaluable for debugging and monitoring. - - -Health and monitoring endpoints are crucial for production deployments. They help you quickly identify configuration issues and monitor your application's activity without digging through logs. - - +> [!TIP] +> Health and monitoring endpoints are crucial for production deployments. They help you quickly identify configuration issues and monitor your application's activity without digging through logs. ## Webhook Configuration on Hugging Face Hub @@ -380,11 +364,8 @@ Navigate to your [Hugging Face Settings](https://huggingface.co/settings/webhook 3. **Secret**: Use the same secret from your `WEBHOOK_SECRET` environment variable 4. **Events**: Subscribe to "Community (PR & discussions)" events - - -Start with one or two test repositories before configuring webhooks for many repositories. This lets you validate your application works correctly before scaling up. - - +> [!TIP] +> Start with one or two test repositories before configuring webhooks for many repositories. This lets you validate your application works correctly before scaling up. ### 2. Space URL Configuration @@ -487,9 +468,8 @@ async def simulate_webhook( This endpoint makes it easy to test different scenarios through your application's interface. - -Simulation endpoints are incredibly useful during development. They let you test different tag combinations and edge cases without creating actual repository discussions. - +> [!TIP] +> Simulation endpoints are incredibly useful during development. They let you test different tag combinations and edge cases without creating actual repository discussions. ## Expected Webhook Result @@ -512,8 +492,5 @@ With our webhook listener implemented, we now have: In the next section, we'll integrate everything into a complete Pull Request Agent that demonstrates the full workflow from webhook to PR creation. - - -Always return webhook responses quickly (within 10 seconds) to avoid timeouts. Use background tasks for longer processing operations like MCP tool execution and pull request creation. - - \ No newline at end of file +> [!TIP] +> Always return webhook responses quickly (within 10 seconds) to avoid timeouts. Use background tasks for longer processing operations like MCP tool execution and pull request creation. \ No newline at end of file diff --git a/units/vi/unit0/introduction.mdx b/units/vi/unit0/introduction.mdx index 1694f27..a89cf14 100644 --- a/units/vi/unit0/introduction.mdx +++ b/units/vi/unit0/introduction.mdx @@ -66,11 +66,8 @@ Nếu bạn chưa có những kiến thức này, đừng lo! Dưới đây là * [LLM Course](https://huggingface.co/learn/llm-course/) sẽ hướng dẫn bạn những kiến thức cơ bản về sử dụng và xây dựng với LLMs. * [Agents Course](https://huggingface.co/learn/agents-course/) sẽ hướng dẫn bạn cách xây dựng AI Agents với LLMs. - - -Các khóa học trên không phải là điều kiện bắt buộc, vì vậy nếu bạn đã hiểu các khái niệm về LLM và Agents, các bạn có thể bắt đầu khóa học ngay bây giờ! - - +> [!TIP] +> Các khóa học trên không phải là điều kiện bắt buộc, vì vậy nếu bạn đã hiểu các khái niệm về LLM và Agents, các bạn có thể bắt đầu khóa học ngay bây giờ! ## Tôi cần những công cụ gì? diff --git a/units/vi/unit1/architectural-components.mdx b/units/vi/unit1/architectural-components.mdx index 260be55..08d4d3a 100644 --- a/units/vi/unit1/architectural-components.mdx +++ b/units/vi/unit1/architectural-components.mdx @@ -48,11 +48,8 @@ Thông thường, người dùng sẽ chọn ứng dụng Host dựa trên nhu c Cùng xem cách các thành phần tương tác trong quy trình MCP điển hình: - - -Trong phần tiếp theo, chúng ta sẽ khám phá sâu hơn về giao thức giao tiếp với các ví dụ thực tế. - - +> [!TIP] +> Trong phần tiếp theo, chúng ta sẽ khám phá sâu hơn về giao thức giao tiếp với các ví dụ thực tế. 1. **Tương tác người dùng**: Người dùng tương tác với ứng dụng **Host**, thể hiện nhu cầu hoặc truy vấn. @@ -70,11 +67,8 @@ Trong phần tiếp theo, chúng ta sẽ khám phá sâu hơn về giao thức g Ưu điểm chính của kiến trúc này là tính mô-đun. Một Host duy nhất có thể kết nối với nhiều Server cùng lúc thông qua các Client khác nhau. Có thể thêm Server mới vào hệ sinh thái mà không cần thay đổi Host hiện có. Có thể dễ dàng kết hợp các khả năng trên nhiều Server khác nhau. - - -Như đã thảo luận ở phần trước, tính mô-đun này biến bài toán tích hợp M×N truyền thống (khi M ứng dụng AI kết nối với N công cụ/dịch vụ) thành một bài toán M+N dễ quản lý hơn - nơi mỗi Host và Server chỉ cần triển khai chuẩn MCP một lần. - - +> [!TIP] +> Như đã thảo luận ở phần trước, tính mô-đun này biến bài toán tích hợp M×N truyền thống (khi M ứng dụng AI kết nối với N công cụ/dịch vụ) thành một bài toán M+N dễ quản lý hơn - nơi mỗi Host và Server chỉ cần triển khai chuẩn MCP một lần. Kiến trúc này trông có vẻ đơn giản, nhưng sức mạnh thực sự nằm ở việc chuẩn hóa giao thức truyền thông và sự phân tách rõ ràng trách nhiệm giữa các thành phần. Thiết kế này cho phép tạo ra một hệ sinh thái gắn kết nơi các mô hình AI có thể kết nối liền mạch với một mảng các công cụ và nguồn dữ liệu bên ngoài ngày càng phát triển. diff --git a/units/vi/unit1/capabilities.mdx b/units/vi/unit1/capabilities.mdx index 00c8938..a02b3f5 100644 --- a/units/vi/unit1/capabilities.mdx +++ b/units/vi/unit1/capabilities.mdx @@ -2,13 +2,10 @@ Các MCP Server cung cấp nhiều khả năng khác nhau cho Client thông qua giao thức truyền thông. Những khả năng này được chia thành bốn loại chính, mỗi loại có đặc điểm và trường hợp sử dụng riêng. Hãy cùng khám phá các nguyên thủy cốt lõi tạo nền tảng cho chức năng của MCP. - - -Trong phần này, chúng ta sẽ xem các ví dụ dưới dạng hàm độc lập với framework trong mỗi ngôn ngữ. Mục đích là tập trung vào khái niệm và cách chúng phối hợp với nhau, thay vì sự phức tạp của bất kỳ framework cụ thể nào. - -Trong các chương tiếp theo, chúng ta sẽ xem cách triển khai các khái niệm này trong mã cụ thể của MCP. - - +> [!TIP] +> Trong phần này, chúng ta sẽ xem các ví dụ dưới dạng hàm độc lập với framework trong mỗi ngôn ngữ. Mục đích là tập trung vào khái niệm và cách chúng phối hợp với nhau, thay vì sự phức tạp của bất kỳ framework cụ thể nào. +> +> Trong các chương tiếp theo, chúng ta sẽ xem cách triển khai các khái niệm này trong mã cụ thể của MCP. ## Công cụ (Tools) @@ -334,11 +331,8 @@ Quy trình lấy mẫu (sampling) diễn ra theo các bước sau: 4. Client kiểm tra kết quả hoàn thiện 5. Client trả kết quả về cho server - - -Thiết kế human-in-the-loop (có sự tham gia của con người trong vòng lặp) này đảm bảo người dùng duy trì quyền kiểm soát những gì LLM nhìn thấy và tạo ra. Khi triển khai sampling, điều quan trọng là phải cung cấp các lời nhắc rõ ràng, được cấu trúc tốt và bao gồm ngữ cảnh liên quan. - - +> [!TIP] +> Thiết kế human-in-the-loop (có sự tham gia của con người trong vòng lặp) này đảm bảo người dùng duy trì quyền kiểm soát những gì LLM nhìn thấy và tạo ra. Khi triển khai sampling, điều quan trọng là phải cung cấp các lời nhắc rõ ràng, được cấu trúc tốt và bao gồm ngữ cảnh liên quan. ## Cách Các Khả Năng Phối Hợp diff --git a/units/vi/unit1/communication-protocol.mdx b/units/vi/unit1/communication-protocol.mdx index ae2fbd0..2836ea1 100644 --- a/units/vi/unit1/communication-protocol.mdx +++ b/units/vi/unit1/communication-protocol.mdx @@ -2,11 +2,8 @@ MCP định nghĩa một giao thức truyền thông chuẩn hóa cho phép Client và Server trao đổi thông điệp một cách nhất quán, dễ dự đoán. Sự chuẩn hóa này rất quan trọng để đảm bảo khả năng tương tác trong cộng đồng. Trong phần này, chúng ta sẽ khám phá cấu trúc giao thức và cơ chế vận chuyển được sử dụng trong MCP. - - -Chúng ta đang đi sâu vào những chi tiết phức tạp của giao thức MCP (nguyên văn: "nitty-gritty" - chỉ những chi tiết quan trọng và phức tạp). Bạn không cần biết tất cả những điều này để xây dựng với MCP, nhưng nên biết về sự tồn tại và cách hoạt động của nó. - - +> [!WARNING] +> Chúng ta đang đi sâu vào những chi tiết phức tạp của giao thức MCP (nguyên văn: "nitty-gritty" - chỉ những chi tiết quan trọng và phức tạp). Bạn không cần biết tất cả những điều này để xây dựng với MCP, nhưng nên biết về sự tồn tại và cách hoạt động của nó. ## JSON-RPC: Nền Tảng @@ -99,11 +96,8 @@ Cơ chế stdio được dùng cho giao tiếp cục bộ, khi Client và Server Ứng dụng chủ khởi chạy Server như một tiến trình con và giao tiếp bằng cách ghi vào đầu vào chuẩn (stdin) và đọc từ đầu ra chuẩn (stdout). - - -**Trường hợp sử dụng** cho phương thức truyền tải này là các công cụ local như truy cập hệ thống file hoặc chạy script local. - - +> [!TIP] +> **Trường hợp sử dụng** cho phương thức truyền tải này là các công cụ local như truy cập hệ thống file hoặc chạy script local. **Ưu điểm** chính của phương thức này là đơn giản, không yêu cầu cấu hình mạng và được hệ điều hành cách ly an toàn. @@ -113,11 +107,8 @@ Phương thức HTTP + SSE được dùng cho giao tiếp từ xa khi Client và Giao tiếp diễn ra qua HTTP, với Server sử dụng Server-Sent Events (SSE) để đẩy các cập nhật tới Client qua kết nối liên tục. - - -**Trường hợp sử dụng** cho phương thức này là kết nối tới API từ xa, dịch vụ đám mây hoặc tài nguyên dùng chung. - - +> [!TIP] +> **Trường hợp sử dụng** cho phương thức này là kết nối tới API từ xa, dịch vụ đám mây hoặc tài nguyên dùng chung. **Ưu điểm** chính là hoạt động được qua mạng, tích hợp được với dịch vụ web và tương thích với môi trường serverless. diff --git a/units/vi/unit1/gradio-mcp.mdx b/units/vi/unit1/gradio-mcp.mdx index b777f1c..13f015e 100644 --- a/units/vi/unit1/gradio-mcp.mdx +++ b/units/vi/unit1/gradio-mcp.mdx @@ -2,11 +2,8 @@ Giờ chúng ta đã tìm hiểu các khái niệm cốt lõi của Giao Thức Ngữ Cảnh Mô Hình (MCP) và cách triển khai MCP Servers và Clients. Trong phần này, chúng ta sẽ làm mọi thứ dễ dàng hơn bằng cách sử dụng Gradio để tạo một MCP Server! - - -Gradio là thư viện Python nổi tiếng giúp tạo giao diện web tùy chỉnh nhanh chóng cho các mô hình học máy. - - +> [!TIP] +> Gradio là thư viện Python nổi tiếng giúp tạo giao diện web tùy chỉnh nhanh chóng cho các mô hình học máy. ## Giới thiệu về Gradio diff --git a/units/vi/unit1/key-concepts.mdx b/units/vi/unit1/key-concepts.mdx index 1cf8192..d7bad33 100644 --- a/units/vi/unit1/key-concepts.mdx +++ b/units/vi/unit1/key-concepts.mdx @@ -33,13 +33,10 @@ Mỗi ứng dụng AI triển khai phía Máy khách MCP một lần, mỗi côn Giờ chúng ta đã hiểu vấn đề mà MCP giải quyết, hãy cùng khám phá các thuật ngữ và khái niệm cốt lõi tạo nên giao thức MCP. - - -MCP là một chuẩn như HTTP hay USB-C, và là giao thức để kết nối các ứng dụng AI với công cụ và nguồn dữ liệu bên ngoài. Vì vậy, việc sử dụng thuật ngữ chuẩn là cực kỳ quan trọng để MCP hoạt động hiệu quả. - -Khi viết tài liệu ứng dụng và trao đổi với cộng đồng, chúng ta nên sử dụng các thuật ngữ sau đây. - - +> [!TIP] +> MCP là một chuẩn như HTTP hay USB-C, và là giao thức để kết nối các ứng dụng AI với công cụ và nguồn dữ liệu bên ngoài. Vì vậy, việc sử dụng thuật ngữ chuẩn là cực kỳ quan trọng để MCP hoạt động hiệu quả. +> +> Khi viết tài liệu ứng dụng và trao đổi với cộng đồng, chúng ta nên sử dụng các thuật ngữ sau đây. ### Thành phần @@ -53,11 +50,8 @@ Tương tự như mối quan hệ client-server trong HTTP, MCP có client (máy - **Server**: Chương trình hoặc dịch vụ bên ngoài cung cấp các khả năng (Tools, Resources, Prompts) thông qua giao thức MCP. - - -Nhiều tài liệu sử dụng 'Client' và 'Host' thay thế cho nhau. Về mặt kỹ thuật, Host là ứng dụng hướng đến người dùng, còn Client là thành phần bên trong ứng dụng Host quản lý giao tiếp với MCP Server. - - +> [!WARNING] +> Nhiều tài liệu sử dụng 'Client' và 'Host' thay thế cho nhau. Về mặt kỹ thuật, Host là ứng dụng hướng đến người dùng, còn Client là thành phần bên trong ứng dụng Host quản lý giao tiếp với MCP Server. ### Khả năng diff --git a/units/vi/unit1/mcp-clients.mdx b/units/vi/unit1/mcp-clients.mdx index c6f3bce..c6ee2af 100644 --- a/units/vi/unit1/mcp-clients.mdx +++ b/units/vi/unit1/mcp-clients.mdx @@ -36,11 +36,8 @@ Giờ khi đã nắm được phần cốt lõi của giao thức MCP, hãy xem Triển khai hiệu quả các Server và Client MCP yêu cầu cấu hình đúng cách. - - -Đặc tả MCP vẫn đang phát triển, vì vậy các phương pháp cấu hình có thể thay đổi. Chúng ta sẽ tập trung vào các phương pháp tốt nhất hiện tại để cấu hình. - - +> [!TIP] +> Đặc tả MCP vẫn đang phát triển, vì vậy các phương pháp cấu hình có thể thay đổi. Chúng ta sẽ tập trung vào các phương pháp tốt nhất hiện tại để cấu hình. ### Tệp cấu hình MCP diff --git a/units/vi/unit2/clients.mdx b/units/vi/unit2/clients.mdx index 84ff04e..8de5587 100644 --- a/units/vi/unit2/clients.mdx +++ b/units/vi/unit2/clients.mdx @@ -32,11 +32,8 @@ File cấu hình chuẩn cho MCP có tên `mcp.json`. Đây là cấu trúc cơ Trong ví dụ này, chúng ta có một server được cấu hình sử dụng SSE transport, kết nối đến Gradio server local chạy trên cổng 7860. - - -Chúng ta đã kết nối đến ứng dụng Gradio qua giao thức SSE vì giả định rằng ứng dụng gradio đang chạy trên một Server từ xa. Tuy nhiên nếu bạn muốn kết nối đến script local, `stdio` transport thay vì `sse` transport là lựa chọn tốt hơn. - - +> [!TIP] +> Chúng ta đã kết nối đến ứng dụng Gradio qua giao thức SSE vì giả định rằng ứng dụng gradio đang chạy trên một Server từ xa. Tuy nhiên nếu bạn muốn kết nối đến script local, `stdio` transport thay vì `sse` transport là lựa chọn tốt hơn. #### Cấu hình cho HTTP+SSE Transport diff --git a/units/vi/unit2/gradio-client.mdx b/units/vi/unit2/gradio-client.mdx index 4518920..dda36f8 100644 --- a/units/vi/unit2/gradio-client.mdx +++ b/units/vi/unit2/gradio-client.mdx @@ -1,144 +1,141 @@ -# Gradio với vai trò Máy khách MCP - -Ở chương trước, chúng ta đã tìm hiểu cách tạo MCP Server bằng Gradio và kết nối đến nó bằng một MCP Client. Trong chương này, chúng ta sẽ khám phá cách sử dụng Gradio như một MCP Client để kết nối đến MCP Server. - - - -Gradio phù hợp nhất để tạo UI client và MCP server, nhưng cũng có thể dùng nó như MCP Client và hiển thị dưới dạng UI. - - - -Chúng ta sẽ kết nối đến MCP server đã tạo ở chương trước và dùng nó để trả lời câu hỏi. - -## MCP Client trong Gradio - -Đầu tiên, cần cài đặt các thư viện `smolagents`, gradio và mcp-client nếu chưa có: - -```bash -pip install smolagents[mcp] gradio[mcp] mcp -``` - -Giờ chúng ta có thể import các thư viện cần thiết và tạo giao diện Gradio đơn giản sử dụng MCP Client để kết nối đến MCP Server. - -```python -import gradio as gr - -from mcp.client.stdio import StdioServerParameters -from smolagents import ToolCollection, CodeAgent -from smolagents import CodeAgent, InferenceClientModel -from smolagents.mcp_client import MCPClient -``` - -Tiếp theo, kết nối đến MCP Server và lấy các công cụ có thể dùng để trả lời câu hỏi. - -```python -mcp_client = MCPClient( - {"url": "http://localhost:7860/gradio_api/mcp/sse"} -) -tools = mcp_client.get_tools() -``` - -Sau khi có các công cụ, ta có thể tạo một agent đơn giản sử dụng chúng để trả lời câu hỏi. Hiện tại chúng ta sẽ dùng `InferenceClientModel` và mô hình mặc định từ `smolagents`. - -```python -model = InferenceClientModel() -agent = CodeAgent(tools=[*tools], model=model) -``` - -Giờ tạo giao diện Gradio đơn giản sử dụng agent để trả lời câu hỏi. - -```python -demo = gr.ChatInterface( - fn=lambda message, history: str(agent.run(message)), - type="messages", - examples=["Prime factorization of 68"], - title="Agent with MCP Tools", - description="Đây là agent đơn giản sử dụng các công cụ MCP để trả lời câu hỏi.", - messages=[], -) - -demo.launch() -``` - -Vậy là xong! Chúng ta đã tạo một giao diện Gradio đơn giản dùng MCP Client để kết nối đến MCP Server và trả lời câu hỏi. - - - - -## Ví dụ hoàn chỉnh - -Dưới đây là ví dụ hoàn chỉnh của MCP Client trong Gradio: - -```python -import gradio as gr - -from mcp.client.stdio import StdioServerParameters -from smolagents import ToolCollection, CodeAgent -from smolagents import CodeAgent, InferenceClientModel -from smolagents.mcp_client import MCPClient - - -try: - mcp_client = MCPClient( - # {"url": "https://abidlabs-mcp-tools.hf.space/gradio_api/mcp/sse"} - {"url": "http://localhost:7860/gradio_api/mcp/sse"} - ) - tools = mcp_client.get_tools() - - model = InferenceClientModel() - agent = CodeAgent(tools=[*tools], model=model) - - def call_agent(message, history): - return str(agent.run(message)) - - - demo = gr.ChatInterface( - fn=lambda message, history: str(agent.run(message)), - type="messages", - examples=["Prime factorization of 68"], - title="Agent with MCP Tools", - description="Đây là agent đơn giản sử dụng các công cụ MCP để trả lời câu hỏi.", - messages=[], - ) - - demo.launch() -finally: - mcp_client.close() -``` - -Bạn sẽ thấy chúng ta đóng MCP Client trong khối `finally`. Điều này quan trọng vì MCP Client là đối tượng tồn tại lâu dài cần được đóng khi chương trình kết thúc. - -## Triển khai lên Hugging Face Spaces - -Để chia sẻ server của bạn với mọi người, bạn có thể triển khai lên Hugging Face Spaces như đã làm ở chương trước. -Để triển khai Gradio MCP client lên Hugging Face Spaces: - -1. Tạo Space mới trên Hugging Face: - - Truy cập huggingface.co/spaces - - Click "Create new Space" - - Chọn "Gradio" làm SDK - - Đặt tên cho Space (ví dụ: "mcp-client") - -2. Tạo một tệp `requirements.txt`: -```txt -gradio[mcp] -smolagents[mcp] -``` - -3. Đẩy code lên Space: -```bash -git init -git add server.py requirements.txt -git commit -m "Initial commit" -git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/mcp-client -git push -u origin main -``` - -## Kết luận - +# Gradio với vai trò Máy khách MCP + +Ở chương trước, chúng ta đã tìm hiểu cách tạo MCP Server bằng Gradio và kết nối đến nó bằng một MCP Client. Trong chương này, chúng ta sẽ khám phá cách sử dụng Gradio như một MCP Client để kết nối đến MCP Server. + +> [!TIP] +> Gradio phù hợp nhất để tạo UI client và MCP server, nhưng cũng có thể dùng nó như MCP Client và hiển thị dưới dạng UI. + +Chúng ta sẽ kết nối đến MCP server đã tạo ở chương trước và dùng nó để trả lời câu hỏi. + +## MCP Client trong Gradio + +Đầu tiên, cần cài đặt các thư viện `smolagents`, gradio và mcp-client nếu chưa có: + +```bash +pip install smolagents[mcp] gradio[mcp] mcp +``` + +Giờ chúng ta có thể import các thư viện cần thiết và tạo giao diện Gradio đơn giản sử dụng MCP Client để kết nối đến MCP Server. + +```python +import gradio as gr + +from mcp.client.stdio import StdioServerParameters +from smolagents import ToolCollection, CodeAgent +from smolagents import CodeAgent, InferenceClientModel +from smolagents.mcp_client import MCPClient +``` + +Tiếp theo, kết nối đến MCP Server và lấy các công cụ có thể dùng để trả lời câu hỏi. + +```python +mcp_client = MCPClient( + {"url": "http://localhost:7860/gradio_api/mcp/sse"} +) +tools = mcp_client.get_tools() +``` + +Sau khi có các công cụ, ta có thể tạo một agent đơn giản sử dụng chúng để trả lời câu hỏi. Hiện tại chúng ta sẽ dùng `InferenceClientModel` và mô hình mặc định từ `smolagents`. + +```python +model = InferenceClientModel() +agent = CodeAgent(tools=[*tools], model=model) +``` + +Giờ tạo giao diện Gradio đơn giản sử dụng agent để trả lời câu hỏi. + +```python +demo = gr.ChatInterface( + fn=lambda message, history: str(agent.run(message)), + type="messages", + examples=["Prime factorization of 68"], + title="Agent with MCP Tools", + description="Đây là agent đơn giản sử dụng các công cụ MCP để trả lời câu hỏi.", + messages=[], +) + +demo.launch() +``` + +Vậy là xong! Chúng ta đã tạo một giao diện Gradio đơn giản dùng MCP Client để kết nối đến MCP Server và trả lời câu hỏi. + + + + +## Ví dụ hoàn chỉnh + +Dưới đây là ví dụ hoàn chỉnh của MCP Client trong Gradio: + +```python +import gradio as gr + +from mcp.client.stdio import StdioServerParameters +from smolagents import ToolCollection, CodeAgent +from smolagents import CodeAgent, InferenceClientModel +from smolagents.mcp_client import MCPClient + + +try: + mcp_client = MCPClient( + # {"url": "https://abidlabs-mcp-tools.hf.space/gradio_api/mcp/sse"} + {"url": "http://localhost:7860/gradio_api/mcp/sse"} + ) + tools = mcp_client.get_tools() + + model = InferenceClientModel() + agent = CodeAgent(tools=[*tools], model=model) + + def call_agent(message, history): + return str(agent.run(message)) + + + demo = gr.ChatInterface( + fn=lambda message, history: str(agent.run(message)), + type="messages", + examples=["Prime factorization of 68"], + title="Agent with MCP Tools", + description="Đây là agent đơn giản sử dụng các công cụ MCP để trả lời câu hỏi.", + messages=[], + ) + + demo.launch() +finally: + mcp_client.close() +``` + +Bạn sẽ thấy chúng ta đóng MCP Client trong khối `finally`. Điều này quan trọng vì MCP Client là đối tượng tồn tại lâu dài cần được đóng khi chương trình kết thúc. + +## Triển khai lên Hugging Face Spaces + +Để chia sẻ server của bạn với mọi người, bạn có thể triển khai lên Hugging Face Spaces như đã làm ở chương trước. +Để triển khai Gradio MCP client lên Hugging Face Spaces: + +1. Tạo Space mới trên Hugging Face: + - Truy cập huggingface.co/spaces + - Click "Create new Space" + - Chọn "Gradio" làm SDK + - Đặt tên cho Space (ví dụ: "mcp-client") + +2. Tạo một tệp `requirements.txt`: +```txt +gradio[mcp] +smolagents[mcp] +``` + +3. Đẩy code lên Space: +```bash +git init +git add server.py requirements.txt +git commit -m "Initial commit" +git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/mcp-client +git push -u origin main +``` + +## Kết luận + Trong phần này, chúng ta đã tìm hiểu cách sử dụng Gradio như một MCP Client để kết nối đến một MCP Server. Chúng ta cũng đã xem qua cách triển khai MCP Client trên Hugging Face Spaces. \ No newline at end of file diff --git a/units/vi/unit2/introduction.mdx b/units/vi/unit2/introduction.mdx index 667ea8f..58292a6 100644 --- a/units/vi/unit2/introduction.mdx +++ b/units/vi/unit2/introduction.mdx @@ -4,11 +4,8 @@ Chào mừng các bạn đến với Chương 2 của Khóa học MCP! Trong chương này, chúng ta sẽ xây dựng một ứng dụng MCP hoàn chỉnh từ đầu, tập trung vào việc tạo Server với Gradio và kết nối nó với nhiều Client. Cách tiếp cận thực hành này sẽ giúp bạn có được kinh nghiệm thực tế với toàn bộ hệ sinh thái MCP. - - -Trong chương này, chúng ta sẽ xây dựng một Server và Client MCP đơn giản bằng Gradio và HuggingFace Hub. Ở chương tiếp theo, chúng ta sẽ phát triển một Server phức tạp hơn để giải quyết các bài toán thực tế. - - +> [!TIP] +> Trong chương này, chúng ta sẽ xây dựng một Server và Client MCP đơn giản bằng Gradio và HuggingFace Hub. Ở chương tiếp theo, chúng ta sẽ phát triển một Server phức tạp hơn để giải quyết các bài toán thực tế. ## Những Nội Dung Bạn Sẽ Học diff --git a/units/vi/unit2/tiny-agents.mdx b/units/vi/unit2/tiny-agents.mdx index f22ed7e..bbf8c1f 100644 --- a/units/vi/unit2/tiny-agents.mdx +++ b/units/vi/unit2/tiny-agents.mdx @@ -91,11 +91,8 @@ const agent = new Agent({ }); ``` - - -Chúng ta kết nối tới máy chủ MCP dựa trên Gradio thông qua gói [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). - - +> [!TIP] +> Chúng ta kết nối tới máy chủ MCP dựa trên Gradio thông qua gói [`mcp-remote`](https://www.npmjs.com/package/mcp-remote). ## Nền tảng cho điều này: hỗ trợ gọi công cụ native trong LLMs