feat: add toctree and translation unit 2 3 4

units/vi/unit2/clients.mdx

@@ -0,0 +1,79 @@
+# Xây dựng MCP Clients
+
+Trong phần này, chúng ta sẽ tạo các client có thể tương tác với MCP server bằng các ngôn ngữ lập trình khác nhau. Chúng ta sẽ triển khai cả client JavaScript sử dụng HuggingFace.js và client Python sử dụng smolagents.
+
+## Cấu hình MCP Clients
+
+Việc triển khai hiệu quả MCP servers và clients yêu cầu cấu hình phù hợp. Đặ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 best practice hiện tại về cấu hình.
+
+### Cấu hình Files của MCP
+
+Các MCP hosts sử dụng configuration files để quản lý kết nối server. Những files này xác định các servers nào có sẵn và cách kết nối đến chúng.
+
+Các configuration files rất đơn giản, dễ hiểu và thống nhất giữa các MCP hosts chính.
+
+#### Cấu trúc `mcp.json`
+
+File cấu hình chuẩn cho MCP có tên `mcp.json`. Đây là cấu trúc cơ bản:
+
+```json
+{
+  "servers": [
+    {
+      "name": "MCP Server",
+      "transport": {
+        "type": "sse",
+        "url": "http://localhost:7860/gradio_api/mcp/sse"
+      }
+    }
+  ]
+}
+```
+
+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.
+
+<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.
+
+</Tip>
+
+#### Cấu hình cho HTTP+SSE Transport
+
+Với các servers từ xa sử dụng HTTP+SSE transport, cấu hình bao gồm URL của server:
+
+```json
+{
+  "servers": [
+    {
+      "name": "Remote MCP Server",
+      "transport": {
+        "type": "sse",
+        "url": "https://example.com/gradio_api/mcp/sse"
+      }
+    }
+  ]
+}
+```
+
+Cấu hình này cho phép UI client của bạn giao tiếp với Gradio MCP server sử dụng MCP protocol, giúp tích hợp liền mạch giữa frontend và dịch vụ MCP.
+
+## Cấu hình UI MCP Client
+
+Khi làm việc với Gradio MCP servers, bạn có thể cấu hình UI client để kết nối đến server sử dụng MCP protocol. Cách thiết lập như sau:
+
+### Cấu hình cơ bản
+
+Tạo file mới tên `config.json` với cấu hình sau:
+
+```json
+{
+  "mcpServers": {
+    "mcp": {
+      "url": "http://localhost:7860/gradio_api/mcp/sse"
+    }
+  }
+}
+```
+
+Cấu hình này cho phép UI client của bạn giao tiếp với Gradio MCP server sử dụng MCP protocol, giúp tích hợp liền mạch giữa frontend và dịch vụ MCP.

units/vi/unit2/gradio-client.mdx

@@ -0,0 +1,144 @@
+# 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.
+
+</Tip>
+
+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.
+
+<iframe
+	src="https://mcp-course-unit2-gradio-client.hf.space"
+	frameborder="0"
+	width="850"
+	height="450"
+></iframe>
+
+
+## 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.

units/vi/unit2/gradio-server.mdx

@@ -0,0 +1,228 @@
+# Xây dựng Gradio MCP Server
+
+Trong phần này, chúng ta sẽ tạo một MCP server phân tích cảm xúc bằng Gradio. Server này sẽ cung cấp công cụ phân tích cảm xúc cho cả người dùng qua giao diện web và các mô hình AI thông qua giao thức MCP.
+
+## Giới thiệu tích hợp Gradio MCP
+
+Gradio cung cấp cách đơn giản để tạo MCP server bằng việc tự động chuyển đổi các hàm Python thành MCP Tools. Khi bạn đặt `mcp_server=True` trong `launch()`, Gradio sẽ:
+
+1. Tự động chuyển đổi các hàm thành MCP Tools
+2. Ánh xạ các thành phần đầu vào sang schema tham số công cụ
+3. Xác định định dạng phản hồi từ các thành phần đầu ra
+4. Thiết lập JSON-RPC qua HTTP+SSE cho giao tiếp client-server
+5. Tạo cả giao diện web và endpoint MCP server
+
+## Thiết lập dự án
+
+Đầu tiên, hãy tạo thư mục mới cho dự án và cài đặt các phụ thuộc cần thiết:
+
+```bash
+mkdir mcp-sentiment
+cd mcp-sentiment
+python -m venv venv
+source venv/bin/activate  # Trên Windows: venv\Scripts\activate
+pip install "gradio[mcp]" textblob
+```
+
+## Tạo Server
+
+Tạo một tệp mới có tên `server.py` với mã sau:
+
+<details>
+<summary>Bấm để xem bản dịch tiếng Việt</summary>
+```python
+import gradio as gr
+from textblob import TextBlob
+
+def sentiment_analysis(text: str) -> dict:
+    """
+    Phân tích cảm xúc của văn bản được cung cấp.
+
+    Args:
+        text (str): Văn bản cần phân tích
+
+    Returns:
+        dict: Từ điển chứa thông tin về độ phân cực, tính chủ quan và đánh giá
+    """
+    blob = TextBlob(text)
+    sentiment = blob.sentiment
+    
+    return {
+        "polarity": round(sentiment.polarity, 2),  # -1 (tiêu cực) đến 1 (tích cực)
+        "subjectivity": round(sentiment.subjectivity, 2),  # 0 (khách quan) đến 1 (chủ quan)
+        "assessment": "positive" if sentiment.polarity > 0 else "negative" if sentiment.polarity < 0 else "neutral"
+    }
+
+# Tạo giao diện Gradio
+demo = gr.Interface(
+    fn=sentiment_analysis,
+    inputs=gr.Textbox(placeholder="Nhập văn bản để phân tích..."),
+    outputs=gr.JSON(),
+    title="Phân Tích Cảm Xúc Văn Bản",
+    description="Phân tích cảm xúc văn bản sử dụng TextBlob"
+)
+
+# Khởi chạy giao diện và Server MCP
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)
+```
+</details>
+
+```python
+import gradio as gr
+from textblob import TextBlob
+
+def sentiment_analysis(text: str) -> dict:
+    """
+    Analyze the sentiment of the given text.
+
+    Args:
+        text (str): The text to analyze
+
+    Returns:
+        dict: A dictionary containing polarity, subjectivity, and assessment
+    """
+    blob = TextBlob(text)
+    sentiment = blob.sentiment
+    
+    return {
+        "polarity": round(sentiment.polarity, 2),  # -1 (negative) to 1 (positive)
+        "subjectivity": round(sentiment.subjectivity, 2),  # 0 (objective) to 1 (subjective)
+        "assessment": "positive" if sentiment.polarity > 0 else "negative" if sentiment.polarity < 0 else "neutral"
+    }
+
+# Create the Gradio interface
+demo = gr.Interface(
+    fn=sentiment_analysis,
+    inputs=gr.Textbox(placeholder="Enter text to analyze..."),
+    outputs=gr.JSON(),
+    title="Text Sentiment Analysis",
+    description="Analyze the sentiment of text using TextBlob"
+)
+
+# Launch the interface and MCP server
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)
+```
+
+## Hiểu về Mã
+
+Hãy cùng phân tích các thành phần chính:
+
+1. **Định nghĩa Hàm**:
+   - Hàm `sentiment_analysis` nhận đầu vào là văn bản và trả về một từ điển
+   - Sử dụng TextBlob để phân tích cảm xúc
+   - Docstring rất quan trọng vì giúp Gradio tạo lược đồ công cụ MCP
+   - Gợi ý kiểu dữ liệu (`str` và `dict`) giúp xác định lược đồ đầu vào/đầu ra
+
+2. **Giao diện Gradio**:
+   - `gr.Interface` tạo cả giao diện web và Server MCP
+   - Hàm được hiển thị như một công cụ MCP tự động
+   - Các thành phần đầu vào và đầu ra xác định lược đồ công cụ
+   - Thành phần đầu ra JSON đảm bảo tuần tự hóa đúng cách
+
+3. **Server MCP**:
+   - Thiết lập `mcp_server=True` kích hoạt Server MCP
+   - Server sẽ có sẵn tại `http://localhost:7860/gradio_api/mcp/sse`
+   - Bạn cũng có thể kích hoạt bằng biến môi trường:
+     ```bash
+     export GRADIO_MCP_SERVER=True
+     ```
+
+## Chạy Server
+
+Khởi động Server bằng cách chạy:
+
+```bash
+python server.py
+```
+
+Bạn sẽ thấy đầu ra cho biết cả giao diện web và Server MCP đang chạy. Giao diện web sẽ có sẵn tại `http://localhost:7860`, và Server MCP tại `http://localhost:7860/gradio_api/mcp/sse`.
+
+## Kiểm tra Server
+
+Bạn có thể kiểm tra Server bằng hai cách:
+
+1. **Giao diện Web**:
+   - Mở `http://localhost:7860` trong trình duyệt
+   - Nhập văn bản và nhấp "Submit"
+   - Bạn sẽ thấy kết quả phân tích cảm xúc
+
+2. **Lược đồ MCP**:
+   - Truy cập `http://localhost:7860/gradio_api/mcp/schema`
+   - Hiển thị lược đồ công cụ MCP mà các Client sẽ sử dụng
+   - Bạn cũng có thể tìm thấy liên kết này trong phần "View API" ở chân trang ứng dụng Gradio
+
+## Mẹo Xử lý Sự cố
+
+1. **Gợi ý Kiểu dữ liệu và Docstring**:
+   - Luôn cung cấp gợi ý kiểu dữ liệu cho tham số hàm và giá trị trả về
+   - Bao gồm docstring với khối "Args:" cho mỗi tham số
+   - Điều này giúp Gradio tạo lược đồ công cụ MCP chính xác
+
+2. **Đầu vào Chuỗi**:
+   - Khi không chắc chắn, hãy chấp nhận đối số đầu vào dưới dạng `str`
+   - Chuyển đổi chúng sang kiểu mong muốn bên trong hàm
+   - Cung cấp khả năng tương thích tốt hơn với các Client MCP
+
+3. **Hỗ trợ SSE**:
+   - Một số Client MCP không hỗ trợ Server MCP dựa trên SSE
+   - Trong trường hợp đó, sử dụng `mcp-remote`:
+     ```json
+     {
+       "mcpServers": {
+         "gradio": {
+           "command": "npx",
+           "args": [
+             "mcp-remote",
+             "http://localhost:7860/gradio_api/mcp/sse"
+           ]
+         }
+       }
+     }
+     ```
+
+4. **Sự cố Kết nối**:
+   - Nếu gặp vấn đề kết nối, thử khởi động lại cả Client và Server
+   - Kiểm tra xem Server đang chạy và có thể truy cập được không
+   - Xác nhận rằng lược đồ MCP có sẵn tại URL mong đợi
+
+## Triển khai lên Hugging Face Spaces
+
+Để làm cho Server của bạn có sẵn cho người khác, bạn có thể triển khai lên Hugging Face Spaces:
+
+1. Tạo một Space mới trên Hugging Face:
+   - Truy cập huggingface.co/spaces
+   - Nhấp "Create new Space"
+   - Chọn "Gradio" làm SDK
+   - Đặt tên cho Space của bạn (ví dụ: "mcp-sentiment")
+
+2. Tạo tệp `requirements.txt`:
+```txt
+gradio[mcp]
+textblob
+```
+
+3. Đẩy mã của bạn 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-sentiment
+git push -u origin main
+```
+
+Server MCP của các bạn giờ đã có thể truy cập tại:
+```
+https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse
+```
+
+## Bước tiếp theo
+
+Giờ khi đã có Server MCP đang chạy, chúng ta sẽ tạo các Client để tương tác với nó. Trong các phần tiếp theo, chúng ta sẽ:
+
+1. Tạo một Client dựa trên HuggingFace.js lấy cảm hứng từ Tiny Agents
+2. Triển khai một Client Python dựa trên SmolAgents
+3. Kiểm tra cả hai Client với Server đã triển khai
+
+Hãy cùng chuyển sang phần xây dựng Client đầu tiên nào!

units/vi/unit2/introduction.mdx

@@ -0,0 +1,66 @@
+# Xây Dựng Ứng Dụng MCP Đầu Cuối
+
+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.
+
+<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ế.
+
+</Tip>
+
+## Những Nội Dung Bạn Sẽ Học
+
+Trong chương này, các bạn sẽ:
+
+- Tạo Server MCP sử dụng tính năng hỗ trợ MCP tích hợp của Gradio
+- Xây dựng công cụ phân tích cảm xúc có thể được sử dụng bởi các Mô hình AI
+- Kết nối với Server bằng các cách triển khai Client khác nhau:
+  - Client dựa trên HuggingFace.js
+  - Client SmolAgents dành cho Python
+- Triển khai Server MCP lên Hugging Face Spaces
+- Kiểm tra và gỡ lỗi toàn bộ hệ thống
+
+Kết thúc chương này, bạn sẽ có một ứng dụng MCP hoạt động thể hiện được sức mạnh và tính linh hoạt của giao thức này.
+
+## Điều Kiện Tiên Quyết
+
+Trước khi bắt đầu chương này, hãy đảm bảo bạn:
+
+- Đã hoàn thành Chương 1 hoặc hiểu cơ bản về các khái niệm MCP
+- Thành thạo cả Python và JavaScript/TypeScript
+- Hiểu cơ bản về API và kiến trúc Client-Server
+- Có môi trường phát triển với:
+  - Python 3.10+
+  - Node.js 18+
+  - Tài khoản Hugging Face (để triển khai)
+
+## Dự Án End-to-End Của Chúng Ta
+
+Chúng ta sẽ xây dựng ứng dụng phân tích cảm xúc bao gồm 3 phần chính: Server, Client và phần triển khai.
+
+![sentiment analysis application](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit2/1.png)
+
+### Phía Server
+
+- Sử dụng Gradio để tạo giao diện web và Server MCP qua `gr.Interface`
+- Triển khai công cụ phân tích cảm xúc bằng TextBlob
+- Cung cấp công cụ qua cả giao thức HTTP và MCP
+
+### Phía Client
+
+- Triển khai Client HuggingFace.js
+- Hoặc tạo Client Python smolagents
+- Minh họa cách sử dụng cùng một Server với các cách triển khai Client khác nhau
+
+### Triển Khai
+
+- Đưa Server lên Hugging Face Spaces
+- Cấu hình các Client để làm việc với Server đã triển khai
+
+## Hãy Bắt Đầu Nào!
+
+## Hãy Bắt Đầu Nào!
+
+Bạn đã sẵn sàng xây dựng ứng dụng MCP đầu cuối đầu tiên chưa? Hãy bắt đầu bằng cách thiết lập môi trường phát triển và tạo máy chủ MCP Gradio của chúng ta.

units/vi/unit2/tiny-agents.mdx

@@ -0,0 +1,475 @@
+# Tiny Agents: Một agent chạy bằng MCP chỉ với 50 dòng mã
+
+Sau khi đã xây dựng các máy chủ MCP bằng Gradio, giờ chúng ta sẽ khám phá sâu hơn về máy khách MCP. Phần này phát triển từ dự án thử nghiệm [Tiny Agents](https://huggingface.co/blog/tiny-agents) - minh họa cách triển khai máy khách MCP siêu đơn giản có thể kết nối với các dịch vụ như máy chủ phân tích cảm xúc Gradio của chúng ta.
+
+Trong bài thực hành ngắn này, chúng mình sẽ hướng dẫn các bạn cách triển khai máy khách MCP bằng TypeScript (JS) có thể giao tiếp với bất kỳ máy chủ MCP nào, bao gồm cả máy chủ phân tích cảm xúc dựa trên Gradio đã xây dựng ở phần trước. Bạn sẽ thấy MCP chuẩn hóa cách các agent tương tác với công cụ như thế nào, giúp phát triển AI Agent trở nên đơn giản hơn đáng kể.
+
+![meme](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/thumbnail.jpg)
+<figcaption>Ảnh được cung cấp bởi https://x.com/adamdotdev</figcaption>
+
+Chúng ta sẽ chỉ cách kết nối tiny agent của bạn với các máy chủ MCP chạy trên Gradio, cho phép nó tận dụng cả công cụ phân tích cảm xúc tùy chỉnh của bạn lẫn các công cụ có sẵn khác.
+
+## Cách chạy bản demo hoàn chỉnh
+
+Nếu đã cài NodeJS (với `pnpm` hoặc `npm`), chỉ cần chạy lệnh sau trong terminal:
+
+```bash
+npx @huggingface/mcp-client
+```
+
+hoặc nếu dùng `pnpm`:
+
+```bash
+pnpx @huggingface/mcp-client
+```
+
+Lệnh này sẽ cài đặt gói vào thư mục tạm rồi thực thi lệnh của nó.
+
+Bạn sẽ thấy Agent đơn giản của mình kết nối với nhiều máy chủ MCP (chạy local), tải các công cụ của chúng (tương tự cách nó tải công cụ phân tích cảm xúc Gradio của bạn), sau đó nhắc bạn bắt đầu hội thoại.
+
+<video controls autoplay loop>
+  <source src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/use-filesystem.mp4" type="video/mp4">
+</video>
+
+Mặc định, ví dụ của chúng ta kết nối với hai máy chủ MCP:
+
+- Máy chủ ["hệ thống file" chuẩn](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) - có quyền truy cập vào Desktop của bạn
+- Máy chủ [Playwright MCP](https://github.com/microsoft/playwright-mcp) - biết cách dùng trình duyệt Chromium trong môi trường sandbox
+
+Bạn có thể dễ dàng thêm máy chủ phân tích cảm xúc Gradio của mình vào danh sách này như chúng ta sẽ minh họa sau.
+
+> [!NOTE]
+> Lưu ý: Hiện tại tất cả máy chủ MCP trong tiny agents đều là các tiến trình local (dù các máy chủ từ xa sẽ sớm được hỗ trợ). Điều này không bao gồm máy chủ Gradio của chúng ta chạy trên localhost:7860.
+
+Đầu vào cho video đầu tiên là:
+
+> write a haiku about the Hugging Face community and write it to a file named "hf.txt" on my Desktop
+
+Giờ thử prompt liên quan đến duyệt Web:
+
+> do a Web Search for HF inference providers on Brave Search and open the first 3 results
+
+<video controls autoplay loop>
+  <source src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/brave-search.mp4" type="video/mp4">
+</video>
+
+Với công cụ phân tích cảm xúc Gradio đã kết nối, chúng ta có thể hỏi tương tự:
+> analyze the sentiment of this review: "I absolutely loved the product, it exceeded all my expectations!"
+
+### Mô hình và nhà cung cấp mặc định
+
+Về cặp mô hình/nhà cung cấp, Agent mẫu của chúng ta mặc định dùng:
+- ["Qwen/Qwen2.5-72B-Instruct"](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct)
+- chạy trên [Nebius](https://huggingface.co/docs/inference-providers/providers/nebius)
+
+Tất cả cài đặt này đều có thể tùy chỉnh qua biến môi trường! Ở đây, chúng ta cũng sẽ hướng dẫn cách thêm máy chủ Gradio MCP của mình:
+
+```ts
+const agent = new Agent({
+	provider: process.env.PROVIDER ?? "nebius",
+	model: process.env.MODEL_ID ?? "Qwen/Qwen2.5-72B-Instruct",
+	apiKey: process.env.HF_TOKEN,
+	servers: [
+		// Các máy chủ mặc định
+		{
+			command: "npx",
+			args: ["@modelcontextprotocol/servers", "filesystem"]
+		},
+		{
+			command: "npx",
+			args: ["playwright-mcp"]
+		},
+		// Máy chủ phân tích cảm xúc Gradio của chúng ta
+		{
+			command: "npx",
+			args: [
+				"mcp-remote",
+				"http://localhost:7860/gradio_api/mcp/sse"
+			]
+		}
+	],
+});
+```
+
+<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).
+
+</Tip>
+
+
+## Nền tảng cho điều này: hỗ trợ gọi công cụ native trong LLMs
+
+Điều giúp kết nối các m��y chủ MCP Gradio với Tiny Agent của chúng ta là các LLM (cả closed và open) gần đây đã được huấn luyện để gọi hàm (function calling), hay còn gọi là sử dụng công cụ. Chính khả năng này hỗ trợ tích hợp của chúng ta với công cụ phân tích cảm xúc mà chúng ta đã xây dựng bằng Gradio.
+
+Một công cụ được định nghĩa bởi tên, mô tả và biểu diễn JSONSchema của các tham số - giống hệt cách chúng ta định nghĩa hàm phân tích cảm xúc trong máy chủ Gradio. Hãy xem một ví dụ đơn giản:
+
+<details>
+<summary>Bấm để xem bản dịch tiếng Việt</summary>
+```ts
+const weatherTool = {
+	type: "function",
+	function: {
+		name: "get_weather",
+		description: "Nhận nhiệt độ hiện tại cho một địa điểm cụ thể.",
+		parameters: {
+			type: "object",
+			properties: {
+				location: {
+					type: "string",
+					description: "Thành phố và quốc gia, ví dụ: Hà Nội, Việt Nam",
+				},
+			},
+		},
+	},
+};
+```
+</details>
+
+```ts
+const weatherTool = {
+	type: "function",
+	function: {
+		name: "get_weather",
+		description: "Get current temperature for a given location.",
+		parameters: {
+			type: "object",
+			properties: {
+				location: {
+					type: "string",
+					description: "City and country e.g. Bogotá, Colombia",
+				},
+			},
+		},
+	},
+};
+```
+
+Công cụ phân tích cảm xúc Gradio của chúng ta sẽ có cấu trúc tương tự, với `text` làm tham số đầu vào thay vì `location`.
+
+Tài liệu chính thức mà mình sẽ liên kết ở đây là [tài liệu function calling của OpenAI](https://platform.openai.com/docs/guides/function-calling?api-mode=chat). (Đúng vậy... OpenAI gần như định nghĩa các tiêu chuẩn LLM cho cả cộng đồng 😅).
+
+Các inference engine cho phép bạn truyền một danh sách công cụ khi gọi LLM, và LLM có thể tự do gọi không, một hoặc nhiều công cụ trong số đó.
+Là một developer, bạn chạy các công cụ và đưa kết quả của chúng trở lại LLM để tiếp tục quá trình sinh kết quả.
+
+> Lưu ý rằng ở backend (ở cấp độ inference engine), các công cụ đơn giản được truyền vào mô hình trong một `chat_template` được định dạng đặc biệt, giống như bất kỳ tin nhắn nào khác, sau đó được phân tích từ phản hồi (sử dụng các token đặc biệt của mô hình) để hiển thị dưới dạng các lệnh gọi công cụ.
+
+## Triển khai MCP client trên InferenceClient
+
+Giờ chúng ta đã biết tool là gì trong các LLM hiện đại, hãy cùng triển khai MCP client thực tế để giao tiếp với Gradio server và các MCP server khác.
+
+Tài liệu chính thức tại https://modelcontextprotocol.io/quickstart/client khá chi tiết. Bạn chỉ cần thay thế mọi đề cập đến SDK client Anthropic bằng bất kỳ SDK client tương thích OpenAI nào khác. (Có một file [llms.txt](https://modelcontextprotocol.io/llms-full.txt) bạn có thể dùng để huấn luyện LLM của mình hỗ trợ viết code).
+
+Nhắc lại, chúng ta dùng `InferenceClient` của HF cho inference client.
+
+> [!TIP]
+> File code hoàn chỉnh `McpClient.ts` có tại [đây](https://github.com/huggingface/huggingface.js/blob/main/packages/mcp-client/src/McpClient.ts) nếu bạn muốn xem code thực tế 🤓
+
+Lớp `McpClient` của chúng ta có:
+- Một Inference Client (hoạt động với mọi Nhà cung cấp Inference, và `huggingface/inference` hỗ trợ cả endpoint từ xa lẫn local)
+- Một tập hợp các phiên MCP client, mỗi phiên cho một MCP server được kết nối (cho phép kết nối đến nhiều server, bao gồm cả Gradio server của chúng ta)
+- Danh sách các tool khả dụng sẽ được điền từ các server đã kết nối và định dạng lại một chút.
+
+```ts
+export class McpClient {
+	protected client: InferenceClient;
+	protected provider: string;
+	protected model: string;
+	private clients: Map<ToolName, Client> = new Map();
+	public readonly availableTools: ChatCompletionInputTool[] = [];
+
+	constructor({ provider, model, apiKey }: { provider: InferenceProvider; model: string; apiKey: string }) {
+		this.client = new InferenceClient(apiKey);
+		this.provider = provider;
+		this.model = model;
+	}
+	
+	// [...]
+}
+```
+
+Để kết nối đến MCP server (như Gradio server phân tích cảm xúc của chúng ta), SDK TypeScript chính thức `@modelcontextprotocol/sdk/client` cung cấp lớp `Client` với phương thức `listTools()`:
+
+```ts
+async addMcpServer(server: StdioServerParameters): Promise<void> {
+	const transport = new StdioClientTransport({
+		...server,
+		env: { ...server.env, PATH: process.env.PATH ?? "" },
+	});
+	const mcp = new Client({ name: "@huggingface/mcp-client", version: packageVersion });
+	await mcp.connect(transport);
+
+	const toolsResult = await mcp.listTools();
+	debug(
+		"Connected to server with tools:",
+		toolsResult.tools.map(({ name }) => name)
+	);
+
+	for (const tool of toolsResult.tools) {
+		this.clients.set(tool.name, mcp);
+	}
+
+	this.availableTools.push(
+		...toolsResult.tools.map((tool) => {
+			return {
+				type: "function",
+				function: {
+					name: tool.name,
+					description: tool.description,
+					parameters: tool.inputSchema,
+				},
+			} satisfies ChatCompletionInputTool;
+		})
+	);
+}
+```
+
+`StdioServerParameters` là một interface từ MCP SDK giúp bạn dễ dàng tạo một process local: như đã đề cập, hiện tại tất cả MCP server đều là các process local, bao gồm cả Gradio server của chúng ta (dù chúng ta truy cập qua HTTP).
+
+Với mỗi MCP server được kết nối (bao gồm Gradio server phân tích cảm xúc), chúng ta định dạng lại danh sách tool của nó và thêm vào `this.availableTools`.
+
+### Cách sử dụng các công cụ
+
+Sử dụng công cụ phân tích cảm xúc của chúng ta (hoặc bất kỳ công cụ MCP nào khác) rất đơn giản. Bạn chỉ cần truyền `this.availableTools` vào LLM chat-completion, cùng với mảng messages thông thường:
+
+```ts
+const stream = this.client.chatCompletionStream({
+	provider: this.provider,
+	model: this.model,
+	messages,
+	tools: this.availableTools,
+	tool_choice: "auto",
+});
+```
+
+`tool_choice: "auto"` là tham số bạn truyền để LLM có thể tạo ra không, một hoặc nhiều lệnh gọi công cụ.
+
+Khi phân tích hoặc stream kết quả, LLM sẽ tạo ra các lệnh gọi công cụ (ví dụ: tên hàm và các đối số được mã hóa JSON) mà bạn (với tư cách là nhà phát triển) cần xử lý. SDK MCP Client một lần nữa giúp việc này trở nên dễ dàng; nó có phương thức `client.callTool()`:
+
+```ts
+const toolName = toolCall.function.name;
+const toolArgs = JSON.parse(toolCall.function.arguments);
+
+const toolMessage: ChatCompletionInputMessageTool = {
+	role: "tool",
+	tool_call_id: toolCall.id,
+	content: "",
+	name: toolName,
+};
+
+/// Lấy session phù hợp cho công cụ này
+const client = this.clients.get(toolName);
+if (client) {
+	const result = await client.callTool({ name: toolName, arguments: toolArgs });
+	toolMessage.content = result.content[0].text;
+} else {
+	toolMessage.content = `Error: No session found for tool: ${toolName}`;
+}
+```
+
+Nếu LLM chọn sử dụng công cụ phân tích cảm xúc của chúng ta, đoạn code này sẽ tự động định tuyến lệnh gọi đến Gradio server của chúng ta, thực thi phân tích và trả về kết quả cho LLM.
+
+Cuối cùng, bạn sẽ thêm message công cụ kết quả vào mảng `messages` và đưa ngược lại vào LLM.
+
+## Agent 50-dòng-code của chúng ta 🤯
+
+Giờ đây khi đã có MCP client có khả năng kết nối đến các MCP server tùy ý (bao gồm cả Gradio sentiment analysis server) để lấy danh sách công cụ và chèn chúng vào LLM inference, vậy... Agent là gì?
+
+> Khi bạn đã có một inference client với một bộ công cụ, thì Agent chỉ đơn giản là một vòng lặp while bao quanh nó.
+
+Cụ thể hơn, Agent là sự kết hợp của:
+- một system prompt
+- một LLM Inference client
+- một MCP client để kết nối các công cụ từ nhiều MCP server (bao gồm Gradio server của chúng ta)
+- một số luồng điều khiển cơ bản (xem vòng lặp while bên dưới)
+
+> [!TIP]
+> File code hoàn chỉnh `Agent.ts` có tại [đây](https://github.com/huggingface/huggingface.js/blob/main/packages/mcp-client/src/Agent.ts).
+
+Lớp Agent của chúng ta đơn giản kế thừa từ McpClient:
+
+```ts
+export class Agent extends McpClient {
+	private readonly servers: StdioServerParameters[];
+	protected messages: ChatCompletionInputMessage[];
+
+	constructor({
+		provider,
+		model,
+		apiKey,
+		servers,
+		prompt,
+	}: {
+		provider: InferenceProvider;
+		model: string;
+		apiKey: string;
+		servers: StdioServerParameters[];
+		prompt?: string;
+	}) {
+		super({ provider, model, apiKey });
+		this.servers = servers;
+		this.messages = [
+			{
+				role: "system",
+				content: prompt ?? DEFAULT_SYSTEM_PROMPT,
+			},
+		];
+	}
+}
+```
+
+Mặc định, chúng ta sử dụng system prompt đơn giản lấy cảm hứng từ [hướng dẫn prompt GPT-4.1](https://cookbook.openai.com/examples/gpt4-1_prompting_guide).
+
+Mặc dù điều này đến từ OpenAI 😈, nhưng câu này đặc biệt áp dụng cho ngày càng nhiều mô hình, cả đóng và mở:
+
+> Chúng tôi khuyến khích nhà phát triển chỉ sử dụng trường tools để truyền công cụ, thay vì thủ công chèn mô tả công cụ vào prompt và viết parser riêng cho lệnh gọi công cụ như một số đã làm trước đây.
+
+Nghĩa là chúng ta không cần cung cấp danh sách ví dụ về cách sử dụng công cụ được định dạng kỹ lưỡng trong prompt. Tham số `tools: this.availableTools` là đủ, và LLM sẽ biết cách sử dụng cả công cụ hệ thống file và công cụ phân tích cảm xúc Gradio của chúng ta.
+
+Việc tải công cụ lên Agent đơn giản chỉ là kết nối đến các MCP server mong muốn (song song vì rất dễ thực hiện trong JS):
+
+```ts
+async loadTools(): Promise<void> {
+	await Promise.all(this.servers.map((s) => this.addMcpServer(s)));
+}
+```
+
+Chúng ta thêm hai công cụ bổ sung (ngoài MCP) mà LLM có thể sử dụng cho luồng điều khiển của Agent:
+
+```ts
+const taskCompletionTool: ChatCompletionInputTool = {
+	type: "function",
+	function: {
+		name: "task_complete",
+		description: "Call this tool when the task given by the user is complete",
+		parameters: {
+			type: "object",
+			properties: {},
+		},
+	},
+};
+const askQuestionTool: ChatCompletionInputTool = {
+	type: "function",
+	function: {
+		name: "ask_question",
+		description: "Ask a question to the user to get more info required to solve or clarify their problem.",
+		parameters: {
+			type: "object",
+			properties: {},
+		},
+	},
+};
+const exitLoopTools = [taskCompletionTool, askQuestionTool];
+```
+
+Khi gọi bất kỳ công cụ nào trong số này, Agent sẽ ngắt vòng lặp và trả lại quyền kiểm soát cho người dùng để có dữ liệu đầu vào mới.
+
+### Vòng lặp while hoàn chỉnh
+
+Hãy xem vòng lặp while hoàn chỉnh của chúng tôi.🎉
+
+Điểm mấu chốt của vòng lặp while chính của Agent là chúng tôi chỉ lặp lại với LLM luân phiên giữa việc gọi công cụ và cung cấp cho nó kết quả công cụ, và chúng tôi làm như vậy **cho đến khi LLM bắt đầu phản hồi bằng hai thông báo không phải công cụ liên tiếp**.
+
+Đây là vòng lặp while hoàn chỉnh:
+
+```ts
+let numOfTurns = 0;
+let nextTurnShouldCallTools = true;
+while (true) {
+	try {
+		yield* this.processSingleTurnWithTools(this.messages, {
+			exitLoopTools,
+			exitIfFirstChunkNoTool: numOfTurns > 0 && nextTurnShouldCallTools,
+			abortSignal: opts.abortSignal,
+		});
+	} catch (err) {
+		if (err instanceof Error && err.message === "AbortError") {
+			return;
+		}
+		throw err;
+	}
+	numOfTurns++;
+	const currentLast = this.messages.at(-1)!;
+	if (
+		currentLast.role === "tool" &&
+		currentLast.name &&
+		exitLoopTools.map((t) => t.function.name).includes(currentLast.name)
+	) {
+		return;
+	}
+	if (currentLast.role !== "tool" && numOfTurns > MAX_NUM_TURNS) {
+		return;
+	}
+	if (currentLast.role !== "tool" && nextTurnShouldCallTools) {
+		return;
+	}
+	if (currentLast.role === "tool") {
+		nextTurnShouldCallTools = false;
+	} else {
+		nextTurnShouldCallTools = true;
+	}
+}
+```
+
+## Kết nối Tiny Agents với Gradio MCP Servers
+
+Giờ thì chúng ta đã hiểu về cả Tiny Agents và Gradio MCP servers, hãy xem cách chúng hoạt động cùng nhau nhé! Điểm tuyệt vời của MCP là nó cung cấp cách chuẩn hóa để các agent tương tác với bất kỳ server nào tương thích MCP, bao gồm cả máy chủ phân tích cảm xúc (sentiment analysis) dựa trên Gradio của chúng ta.
+
+### Sử dụng Gradio Server với Tiny Agents
+
+Để kết nối Tiny Agent của chúng ta với máy chủ phân tích cảm xúc Gradio đã xây dựng trước đó, chúng ta chỉ cần thêm nó vào danh sách servers. Dưới đây là cách chúng ta có thể điều chỉnh cấu hình agent:
+
+```ts
+const agent = new Agent({
+    provider: process.env.PROVIDER ?? "nebius",
+    model: process.env.MODEL_ID ?? "Qwen/Qwen2.5-72B-Instruct",
+    apiKey: process.env.HF_TOKEN,
+    servers: [
+        // ... existing servers ...
+        {
+            command: "npx",
+            args: [
+                "mcp-remote",
+                "http://localhost:7860/gradio_api/mcp/sse"  // Your Gradio MCP server
+            ]
+        }
+    ],
+});
+```
+
+Giờ đây agent của chúng ta đã có thể sử dụng công cụ phân tích cảm xúc cùng với các công cụ khác! Ví dụ, nó có thể:
+1. Đọc văn bản từ file bằng filesystem server
+2. Phân tích cảm xúc bằng Gradio server của chúng ta
+3. Ghi kết quả trở lại file
+
+### Ví dụ tương tác
+
+Đây là ví dụ về cuộc hội thoại với agent:
+
+```
+User: Read the file "feedback.txt" from my Desktop and analyze its sentiment
+
+Agent: I'll help you analyze the sentiment of the feedback file. Let me break this down into steps:
+
+1. First, I'll read the file using the filesystem tool
+2. Then, I'll analyze its sentiment using the sentiment analysis tool
+3. Finally, I'll write the results to a new file
+
+[Agent tiến hành sử dụng các công cụ và cung cấp phân tích]
+```
+
+### Lưu ý khi triển khai
+
+Khi triển khai Gradio MCP server của bạn lên Hugging Face Spaces, bạn cần cập nhật URL server trong cấu hình agent để trỏ tới space đã triển khai:
+
+```ts
+{
+    command: "npx",
+    args: [
+        "mcp-remote",
+        "https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse"
+    ]
+}
+```
+
+Cách này cho phép agent của bạn sử dụng công cụ phân tích cảm xúc từ bất kỳ đâu, không chỉ trên local!

units/vi/unit3/introduction.mdx

@@ -0,0 +1,3 @@
+# Sắp ra mắt
+
+Đây sẽ là một trường hợp sử dụng khác đi sâu hơn vào giao thức MCP và cách sử dụng nó theo những phương pháp phức tạp hơn.

units/vi/unit4/introduction.mdx

@@ -0,0 +1,5 @@
+# Sắp ra mắt
+
+Chương này sẽ là sự hợp tác với các đối tác từ cộng đồng AI.
+
+Nếu các bạn đang xây dựng công cụ MCP, hãy liên hệ với chúng mình để được thêm vào chương. Mở [thảo luận](https://huggingface.co/spaces/mcp-course/README/discussions) trên hub.