diff --git a/.gitignore b/.gitignore index c571e8b..03ae1b8 100644 --- a/.gitignore +++ b/.gitignore @@ -165,7 +165,7 @@ cython_debug/ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. -#.idea/ +.idea/ # Ruff stuff: .ruff_cache/ diff --git a/units/he/_toctree.yml b/units/he/_toctree.yml new file mode 100644 index 0000000..7ed77e7 --- /dev/null +++ b/units/he/_toctree.yml @@ -0,0 +1,52 @@ +- title: "0. Welcome to the MCP Course" + sections: + - local: unit0/introduction + title: Welcome to the MCP Course + +- title: "1. Introduction to Model Context Protocol" + sections: + - local: unit1/introduction + title: Introduction to Model Context Protocol (MCP) + - local: unit1/key-concepts + title: Key Concepts and Terminology + - local: unit1/architectural-components + title: Architectural Components + - local: unit1/quiz1 + title: Quiz 1 - MCP Fundamentals + - local: unit1/communication-protocol + title: The Communication Protocol + - local: unit1/capabilities + title: Understanding MCP Capabilities + - local: unit1/sdk + title: MCP SDK + - local: unit1/quiz2 + title: Quiz 2 - MCP SDK + - local: unit1/mcp-clients + title: MCP Clients + - local: unit1/gradio-mcp + title: Gradio MCP Integration + - local: unit1/certificate + title: Get your certificate! + +- title: "2. Use Case: End-to-End MCP Application" + sections: + - local: unit2/introduction + title: Introduction to Building an MCP Application + - local: unit2/gradio-server + title: Building the Gradio MCP Server + - local: unit2/clients + title: Using MCP Clients with your application + - local: unit2/gradio-client + title: Building an MCP Client with Gradio + - local: unit2/tiny-agents + title: Building a Tiny Agent with TypeScript + +- title: "3. Use Case: Advanced MCP Development" + sections: + - local: unit3/introduction + title: Coming Soon + +- title: "Bonus Units" + sections: + - local: unit4/introduction + title: Coming Soon diff --git a/units/he/unit0/introduction.mdx b/units/he/unit0/introduction.mdx new file mode 100644 index 0000000..1935792 --- /dev/null +++ b/units/he/unit0/introduction.mdx @@ -0,0 +1,137 @@ +# ברוכים הבאים לקורס 🤗 פרוטוקול הקשר המודל (MCP) + +![תמונת קורס MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit0/1.png) + +ברוכים הבאים לנושא המרתק ביותר בתחום הבינה המלאכותית כיום: **פרוטוקול הקשר המודל (MCP)**! + +קורס חינמי זה ייקח אותך למסע, **ממתחיל למיודע**, בהבנה, שימוש ובניית יישומים עם MCP. + +היחידה הראשונה תעזור לך להתחיל: + +* גלה את **תוכנית הלימודים של הקורס**. +* **קבל מידע נוסף על תהליך ההסמכה והלו"ז**. +* הכר את הצוות מאחורי הקורס. +* צור את **החשבון שלך**. +* **הרשם לשרת הדיסקורד שלנו**, ופגוש את חבריך לכיתה ואותנו. + +בואו נתחיל! + +## למה לצפות מהקורס הזה? + +בקורס זה, אתה: + +* 📖 תלמד את פרוטוקול הקשר המודל **בתיאוריה, תכנון ובפרקטיקה.** +* 🧑‍💻 תלמד **להשתמש ב-SDK ובמסגרות MCP מבוססות**. +* 💾 **תשתף את הפרויקטים שלך** ותחקור יישומים שנוצרו על ידי הקהילה. +* 🏆 תשתתף באתגרים בהם **תעריך את יישומי ה-MCP שלך מול יישומים של סטודנטים אחרים.** +* 🎓 **תקבל תעודת סיום** על ידי השלמת המשימות. + +ועוד! + +בסוף הקורס הזה, תבין **איך MCP עובד ואיך לבנות את היישומים שלך עם בינה מלאכותית המנצלים נתונים חיצוניים וכלים באמצעות תקני MCP העדכניים ביותר**. + +אל תשכח [**להירשם לקורס!**](https://huggingface.co/mcp-course) + +## איך נראה הקורס? + +הקורס מורכב מ: + +* _יחידות יסוד_: בהן תלמד **מושגי MCP בתיאוריה**. +* _התנסות מעשית_: בה תלמד **להשתמש ב-SDK של MCP מבוססים** כדי לבנות את היישומים שלך. לסעיפי ההתנסות המעשית יהיו סביבות מוגדרות מראש. +* _משימות מקרה שימוש_: בהן תיישם את המושגים שלמדת כדי לפתור בעיה מהעולם האמיתי שתבחר. +* _שיתופי פעולה_: אנו משתפים פעולה עם השותפים של Hugging Face כדי להעניק לך את יישומי וכלי ה-MCP העדכניים ביותר. + +**קורס זה הוא פרויקט חי, המתפתח עם המשוב והתרומות שלך!** אל תהסס לפתוח סוגיות ו-PR ב-GitHub, ולהשתתף בדיונים בשרת הדיסקורד שלנו. + +## מהי תוכנית הלימודים? + +להלן **תוכנית הלימודים הכללית לקורס**. רשימה מפורטת יותר של נושאים תשוחרר עם כל יחידה. + +| פרק | נושא | תיאור | +| ------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| 0 | התחלה | מכין אותך עם הכלים והפלטפורמות שבהם תשתמש. | +| 1 | יסודות MCP, ארכיטקטורה ומושגי ליבה | מסביר מושגי ליבה, ארכיטקטורה ורכיבים של פרוטוקול הקשר המודל. מציג מקרה שימוש פשוט באמצעות MCP. | +| 2 | מקרה שימוש מקצה לקצה: MCP בפעולה | בנה יישום MCP פשוט מקצה לקצה שתוכל לשתף עם הקהילה. | +| 3 | מקרה שימוש מופעל: MCP בפעולה | בנה יישום MCP מופעל באמצעות המערכת האקולוגית של Hugging Face ושירותי השותפים. | +| 4 | יחידות בונוס | יחידות בונוס שיעזרו לך להפיק יותר מהקורס, עבודה עם ספריות ושירותים של שותפים. | + +## מהן דרישות הקדם? + +כדי שתוכל לעקוב אחר הקורס הזה, כדאי שיהיו לך: + +* הבנה בסיסית של מושגי בינה מלאכותית ו-LLM +* היכרות עם עקרונות פיתוח תוכנה ומושגי API +* ניסיון עם לפחות שפת תכנות אחת (יוצגו דוגמאות בפייתון או TypeScript) + +אם אין לך אף אחד מאלה, אל תדאג! הנה כמה משאבים שיכולים לעזור לך: + +* [קורס LLM](https://huggingface.co/learn/llm-course/) ינחה אותך דרך היסודות של שימוש ובנייה עם LLM. +* [קורס סוכנים](https://huggingface.co/learn/agents-course/) ינחה אותך בבניית סוכני בינה מלאכותית עם LLM. + + + +הקורסים הנ"ל אינם דרישות קדם בפני עצמם, לכן אם אתה מבין את המושגים של LLM וסוכנים, אתה יכול להתחיל את הקורס עכשיו! + + + +## אילו כלים אני צריך? + +אתה צריך רק 2 דברים: + +* _מחשב_ עם חיבור לאינטרנט. +* _חשבון_: כדי לגשת למשאבי הקורס וליצור פרויקטים. אם אין לך עדיין חשבון, תוכל ליצור אחד [כאן](https://huggingface.co/join) (זה חינם). + +## תהליך ההסמכה + +אתה יכול לבחור לעקוב אחר הקורס הזה _במצב צפייה_, או לעשות את הפעילויות ו_לקבל אחת משתי התעודות שנפיק_. אם אתה צופה בקורס, אתה יכול להשתתף בכל האתגרים ולעשות משימות אם תרצה, ו**אתה לא צריך להודיע לנו**. + +תהליך ההסמכה הוא **לחלוטין חינם**: + +* _כדי לקבל תעודה על יסודות_: עליך להשלים את יחידה 1 של הקורס. זה מיועד לסטודנטים שרוצים להתעדכן במגמות האחרונות ב-MCP, מבלי הצורך לבנות יישום מלא. +* _כדי לקבל תעודת סיום_: עליך להשלים את יחידות מקרה השימוש (2 ו-3). זה מיועד לסטודנטים שרוצים לבנות יישום מלא ולשתף אותו עם הקהילה. + +## מהו הקצב המומלץ? + +כל פרק בקורס זה מתוכנן **להיות מושלם בשבוע אחד, עם כ-3-4 שעות עבודה בשבוע**. + +מכיוון שיש מועד אחרון, אנו מספקים לך קצב מומלץ: + +![קצב מומלץ](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit0/2.png) + +## איך להפיק את המרב מהקורס? + +כדי להפיק את המרב מהקורס, יש לנו כמה עצות: + +1. [הצטרף לקבוצות לימוד בדיסקורד](https://discord.gg/UrrTSsSyjb): לימוד בקבוצות תמיד קל יותר. כדי לעשות זאת, עליך להצטרף לשרת הדיסקורד שלנו ולאמת את החשבון שלך. +2. **עשה את החידונים והמשימות**: הדרך הטובה ביותר ללמוד היא באמצעות תרגול מעשי והערכה עצמית. +3. **הגדר לוח זמנים כדי להישאר מסונכרן**: אתה יכול להשתמש בלוח הזמנים המומלץ שלנו למטה או ליצור את שלך. + +![עצות לקורס](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit0/3.png) + +## מי אנחנו + +על המחברים: + +### בן בורטנשו + +בן הוא מהנדס למידת מכונה ב-Hugging Face המתמקד בבניית יישומי LLM, עם גישות לאחר אימון וסוכנים. [עקוב אחרי בן ב-Hub](https://huggingface.co/burtenshaw) כדי לראות את הפרויקטים האחרונים שלו. + + + + + + + +## מצאתי באג, או שאני רוצה לשפר את הקורס + +תרומות **מתקבלות בברכה** 🤗 + +* אם _מצאת באג 🐛 במחברת_, אנא [פתח סוגיה](https://github.com/huggingface/mcp-course/issues/new) ו**תאר את הבעיה**. +* אם _אתה רוצה לשפר את הקורס_, אתה יכול [לפתוח בקשת משיכה](https://github.com/huggingface/mcp-course/pulls). +* אם _אתה רוצה להוסיף סעיף שלם או יחידה חדשה_, הכי טוב [לפתוח סוגיה](https://github.com/huggingface/mcp-course/issues/new) ו**לתאר איזה תוכן אתה רוצה להוסיף לפני שתתחיל לכתוב כדי שנוכל להדריך אותך**. + +## עדיין יש לי שאלות + +אנא שאל את השאלה שלך בשרת הדיסקורד שלנו #mcp-course-questions. + +עכשיו שיש לך את כל המידע, בואו נעלה על הסיפון ⛵ diff --git a/units/he/unit1/architectural-components.mdx b/units/he/unit1/architectural-components.mdx new file mode 100644 index 0000000..d9f74a0 --- /dev/null +++ b/units/he/unit1/architectural-components.mdx @@ -0,0 +1,85 @@ +# רכיבים ארכיטקטוניים של MCP + +בסעיף הקודם, דנו במושגים המרכזיים ובטרמינולוגיה של MCP. כעת, בואו נעמיק יותר ברכיבים הארכיטקטוניים המרכיבים את המערכת האקולוגית של MCP. + +## מארח (Host), לקוח (Client) ושרת (Server) + +פרוטוקול הקשר המודל (MCP) בנוי על ארכיטקטורת לקוח-שרת המאפשרת תקשורת מובנית בין מודלי בינה מלאכותית ומערכות חיצוניות. + +![ארכיטקטורת MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/4.png) + +ארכיטקטורת ה-MCP מורכבת משלושה רכיבים עיקריים, כל אחד עם תפקידים ואחריות מוגדרים היטב: מארח, לקוח ושרת. נגענו באלה בסעיף הקודם, אבל בואו נעמיק בכל רכיב ובאחריות שלהם. + +### מארח (Host) + +ה**מארח** הוא יישום הבינה המלאכותית שמשתמשי הקצה מתקשרים איתו ישירות. + +דוגמאות כוללות: +- אפליקציות צ'אט בינה מלאכותית כמו OpenAI ChatGPT או Anthropic's Claude Desktop +- סביבות פיתוח משולבות (IDE) משופרות בבינה מלאכותית כמו Cursor, או אינטגרציות לכלים כמו Continue.dev +- סוכנים ויישומי בינה מלאכותית מותאמים אישית שנבנו בספריות כמו LangChain או smolagents + +האחריות של המארח כוללת: +- ניהול אינטראקציות משתמשים והרשאות +- יצירת חיבורים לשרתי MCP באמצעות לקוחות MCP +- תזמור הזרימה הכוללת בין בקשות משתמשים, עיבוד LLM וכלים חיצוניים +- הצגת תוצאות למשתמשים בפורמט קוהרנטי + +ברוב המקרים, משתמשים יבחרו את יישום המארח שלהם בהתבסס על הצרכים וההעדפות שלהם. לדוגמה, מפתח עשוי לבחור ב-Cursor בזכות יכולות עריכת הקוד החזקות שלו, בעוד שמומחי תחום עשויים להשתמש ביישומים מותאמים אישית שנבנו ב-smolagents. + +### לקוח (Client) + +ה**לקוח** הוא רכיב בתוך יישום המארח שמנהל תקשורת עם שרת MCP ספציפי. מאפיינים מרכזיים כוללים: + +- כל לקוח מתחזק חיבור 1:1 עם שרת יחיד +- מטפל בפרטים ברמת הפרוטוקול של תקשורת MCP +- פועל כמתווך בין הלוגיקה של המארח לבין השרת החיצוני + +### שרת (Server) + +ה**שרת** הוא תוכנית או שירות חיצוני שחושף יכולות למודלי בינה מלאכותית באמצעות פרוטוקול MCP. שרתים: + +- מספקים גישה לכלים חיצוניים ספציפיים, מקורות מידע או שירותים +- פועלים כעטיפות קלות משקל סביב פונקציונליות קיימת +- יכולים לרוץ מקומית (על אותה מכונה כמו המארח) או מרחוק (דרך רשת) +- חושפים את היכולות שלהם בפורמט סטנדרטי שלקוחות יכולים לגלות ולהשתמש בו + +## זרימת תקשורת + +בואו נבחן כיצד רכיבים אלה מתקשרים בזרימת עבודה טיפוסית של MCP: + + + +בסעיף הבא, נעמיק יותר בפרוטוקול התקשורת המאפשר רכיבים אלה עם דוגמאות מעשיות. + + + +1. **אינטראקציית משתמש**: המשתמש מתקשר עם יישום ה**מארח**, מביע כוונה או שאילתה. + +2. **עיבוד מארח**: ה**מארח** מעבד את קלט המשתמש, ופוטנציאלית משתמש ב-LLM להבנת הבקשה וקביעת אילו יכולות חיצוניות עשויות להיות נדרשות. + +3. **חיבור לקוח**: ה**מארח** מנחה את רכיב ה**לקוח** שלו להתחבר לשרת(ים) המתאים(ים). + +4. **גילוי יכולות**: ה**לקוח** שואל את ה**שרת** לגלות אילו יכולות (כלים, משאבים, הנחיות) הוא מציע. + +5. **הפעלת יכולות**: בהתבסס על צרכי המשתמש או קביעת ה-LLM, המארח מורה ל**לקוח** להפעיל יכולות ספציפיות מה**שרת**. + +6. **ביצוע שרת**: ה**שרת** מבצע את הפונקציונליות המבוקשת ומחזיר תוצאות ל**לקוח**. + +7. **שילוב תוצאות**: ה**לקוח** מעביר תוצאות אלו בחזרה ל**מארח**, אשר משלב אותן בהקשר עבור ה-LLM או מציג אותן ישירות למשתמש. + +יתרון מרכזי של ארכיטקטורה זו הוא המודולריות שלה. **מארח** יחיד יכול להתחבר למספר **שרתים** בו-זמנית באמצעות **לקוחות** שונים. **שרתים** חדשים יכולים להתווסף למערכת האקולוגית ללא דרישה לשינויים ב**מארחים** קיימים. ניתן לחבר יכולות בקלות בין **שרתים** שונים. + + + +כפי שדנו בסעיף הקודם, מודולריות זו הופכת את בעיית האינטגרציה המסורתית של M×N (M יישומי בינה מלאכותית המתחברים ל-N כלים/שירותים) לבעיה יותר ניתנת לניהול של M+N, שבה כל מארח ושרת צריכים ליישם את תקן ה-MCP רק פעם אחת. + + + +הארכיטקטורה עשויה להיראות פשוטה, אך כוחה טמון בסטנדרטיזציה של פרוטוקול התקשורת ובהפרדה הברורה של האחריות בין רכיבים. עיצוב זה מאפשר מערכת אקולוגית מלוכדת שבה מודלי בינה מלאכותית יכולים להתחבר באופן חלק למערך גדל והולך של כלים חיצוניים ומקורות מידע. + +## סיכום + +דפוסי אינטראקציה אלה מונחים על ידי מספר עקרונות מפתח המעצבים את התכנון והאבולוציה של MCP. הפרוטוקול מדגיש **סטנדרטיזציה** על ידי אספקת פרוטוקול אוניברסלי לקישוריות בינה מלאכותית, תוך שמירה על **פשטות** על ידי שמירת הפרוטוקול הבסיסי פשוט אך מאפשר תכונות מתקדמות. **בטיחות** מקבלת עדיפות על ידי דרישת אישור משתמש מפורש לפעולות רגישות, וגילוי מאפשר גילוי דינמי של יכולות. הפרוטוקול נבנה עם **הרחבה** בראש, תומך באבולוציה דרך גרסאות ומשא ומתן על יכולות, ומבטיח **יכולת פעולה הדדית** בין יישומים שונים וסביבות. + +בסעיף הבא, נחקור את פרוטוקול התקשורת המאפשר לרכיבים אלה לעבוד יחד ביעילות. diff --git a/units/he/unit1/capabilities.mdx b/units/he/unit1/capabilities.mdx new file mode 100644 index 0000000..7d2eee7 --- /dev/null +++ b/units/he/unit1/capabilities.mdx @@ -0,0 +1,245 @@ +# הבנת יכולות MCP + +שרתי MCP חושפים מגוון יכולות ללקוחות דרך פרוטוקול התקשורת. יכולות אלה נופלות לארבע קטגוריות עיקריות, כל אחת עם מאפיינים ייחודיים ומקרי שימוש. בואו נחקור את המרכיבים הבסיסיים האלה שמהווים את היסוד לפונקציונליות של MCP. + + + +בסעיף זה, נציג דוגמאות כפונקציות אגנוסטיות למסגרת בכל שפה. זאת כדי להתמקד במושגים ובאופן שבו הם עובדים יחד, ולא במורכבויות של מסגרת כלשהי. + +ביחידות הבאות, נראה כיצד מושגים אלה מיושמים בקוד ספציפי ל-MCP. + + + +## כלים (Tools) + +כלים הם פונקציות או פעולות הניתנות להפעלה שמודל הבינה המלאכותית יכול להפעיל דרך פרוטוקול MCP. + +- **שליטה**: כלים הם בדרך כלל **נשלטים על ידי המודל**, כלומר שמודל הבינה המלאכותית (LLM) מחליט מתי לקרוא להם בהתבסס על בקשת המשתמש וההקשר. +- **בטיחות**: בגלל היכולת שלהם לבצע פעולות עם תופעות לוואי, הפעלת כלי יכולה להיות מסוכנת. לכן, הם בדרך כלל דורשים אישור משתמש מפורש. +- **מקרי שימוש**: שליחת הודעות, יצירת כרטיסים, שאילתות API, ביצוע חישובים. + +**דוגמה**: כלי מזג אוויר שמביא נתוני מזג אוויר עדכניים למיקום נתון: + + + + +```python +def get_weather(location: str) -> dict: + """קבל את מזג האוויר הנוכחי למיקום מסוים.""" + # התחבר ל-API של מזג אוויר והבא נתונים + return { + "temperature": 72, + "conditions": "Sunny", + "humidity": 45 + } +``` + + + + +```javascript +function getWeather(location) { + // התחבר ל-API של מזג אוויר והבא נתונים + return { + temperature: 72, + conditions: 'Sunny', + humidity: 45 + }; +} +``` + + + + +## משאבים (Resources) + +משאבים מספקים גישה לקריאה בלבד למקורות מידע, מאפשרים למודל הבינה המלאכותית לאחזר הקשר ללא ביצוע לוגיקה מורכבת. + +- **שליטה**: משאבים **נשלטים על ידי היישום**, כלומר יישום המארח בדרך כלל מחליט מתי לגשת אליהם. +- **אופי**: הם מתוכננים לאחזור מידע עם חישוב מינימלי, בדומה לנקודות קצה של GET ב-REST API. +- **בטיחות**: מכיוון שהם לקריאה בלבד, הם בדרך כלל מציגים סיכוני אבטחה נמוכים יותר מאשר כלים. +- **מקרי שימוש**: גישה לתוכן קבצים, אחזור רשומות מסד נתונים, קריאת מידע תצורה. + +**דוגמה**: משאב המספק גישה לתוכן קובץ: + + + + +```python +def read_file(file_path: str) -> str: + """קרא את תוכן הקובץ בנתיב המצוין.""" + with open(file_path, 'r') as f: + return f.read() +``` + + + + +```javascript +function readFile(filePath) { + // שימוש ב-fs.readFile לקריאת תוכן קובץ + const fs = require('fs'); + return new Promise((resolve, reject) => { + fs.readFile(filePath, 'utf8', (err, data) => { + if (err) { + reject(err); + return; + } + resolve(data); + }); + }); +} +``` + + + + +## הנחיות (Prompts) + +הנחיות הן תבניות או זרימות עבודה מוגדרות מראש המנחות את האינטראקציה בין המשתמש, מודל הבינה המלאכותית והיכולות של השרת. + +- **שליטה**: הנחיות **נשלטות על ידי המשתמש**, לעתים קרובות מוצגות כאפשרויות בממשק המשתמש של יישום המארח. +- **מטרה**: הן מבנות אינטראקציות לשימוש אופטימלי בכלים ומשאבים זמינים. +- **בחירה**: משתמשים בדרך כלל בוחרים הנחיה לפני שמודל הבינה המלאכותית מתחיל לעבד, וקובעים הקשר לאינטראקציה. +- **מקרי שימוש**: זרימות עבודה נפוצות, תבניות משימה מיוחדות, אינטראקציות מודרכות. + +**דוגמה**: תבנית הנחיה ליצירת ביקורת קוד: + + + + +```python +def code_review(code: str, language: str) -> list: + """ + יצירת ביקורת קוד עבור קטע הקוד שסופק. + """ + return [ + { + "role": "system", + "content": f"אתה מבקר קוד שבוחן קוד {language}. ספק ביקורת מפורטת המדגישה שיטות עבודה מומלצות, בעיות פוטנציאליות, והצעות לשיפור." + }, + { + "role": "user", + "content": f"אנא בדוק את קוד ה-{language} הזה:\n\n```{language}\n{code}\n```" + } + ] +``` + + + + +```javascript +function codeReview(code, language) { + return [ + { + role: 'system', + content: `אתה מבקר קוד שבוחן קוד ${language}. ספק ביקורת מפורטת המדגישה שיטות עבודה מומלצות, בעיות פוטנציאליות, והצעות לשיפור.` + }, + { + role: 'user', + content: `אנא בדוק את קוד ה-${language} הזה:\n\n\`\`\`${language}\n${code}\n\`\`\`` + } + ]; +} +``` + + + + +## דגימה (Sampling) + +דגימה מאפשרת לשרתים לבקש מהלקוח (ספציפית, יישום המארח) לבצע אינטראקציות LLM. + +- **שליטה**: דגימה **מופעלת על ידי השרת** אך דורשת סיוע מהלקוח/מארח. +- **מטרה**: היא מאפשרת התנהגויות סוכניות מונעות-שרת ופוטנציאלית אינטראקציות רקורסיביות או רב-שלביות. +- **בטיחות**: בדומה לכלים, פעולות דגימה בדרך כלל דורשות אישור משתמש. +- **מקרי שימוש**: משימות מורכבות רב-שלביות, זרימות עבודה של סוכנים אוטונומיים, תהליכים אינטראקטיביים. + +**דוגמה**: שרת עשוי לבקש מהלקוח לנתח נתונים שהוא עיבד: + + + + +```python +def request_sampling(messages, system_prompt=None, include_context="none"): + """בקש דגימת LLM מהלקוח.""" + # ביישום אמיתי, זה היה שולח בקשה ללקוח + return { + "role": "assistant", + "content": "ניתוח הנתונים שסופקו..." + } +``` + + + + +```javascript +function requestSampling(messages, systemPrompt = null, includeContext = 'none') { + // ביישום אמיתי, זה היה שולח בקשה ללקוח + return { + role: 'assistant', + content: 'ניתוח הנתונים שסופקו...' + }; +} + +function handleSamplingRequest(request) { + const { messages, systemPrompt, includeContext } = request; + // ביישום אמיתי, זה היה מעבד את הבקשה ומחזיר תגובה + return { + role: 'assistant', + content: 'תגובה לבקשת הדגימה...' + }; +} +``` + + + + +זרימת הדגימה עוקבת אחר השלבים הבאים: +1. השרת שולח בקשת `sampling/createMessage` ללקוח +2. הלקוח בוחן את הבקשה ויכול לשנות אותה +3. הלקוח דוגם מ-LLM +4. הלקוח בוחן את התוצאה +5. הלקוח מחזיר את התוצאה לשרת + + + +עיצוב זה של אדם-בלולאה מבטיח שמשתמשים שומרים על שליטה במה שה-LLM רואה ומייצר. בעת יישום דגימה, חשוב לספק הנחיות ברורות, מובנות היטב ולכלול הקשר רלוונטי. + + + +## איך יכולות עובדות יחד + +בואו נראה איך יכולות אלה עובדות יחד כדי לאפשר אינטראקציות מורכבות. בטבלה למטה, פירטנו את היכולות, מי שולט בהן, כיוון השליטה, ופרטים נוספים. + +| יכולת | נשלט על ידי | כיוון | תופעות לוואי | נדרש אישור | מקרי שימוש אופייניים | +|------------|---------------|-----------|--------------|-----------------|-------------------| +| כלים | מודל (LLM) | לקוח → שרת | כן (פוטנציאלית) | כן | פעולות, קריאות API, מניפולציית נתונים | +| משאבים | יישום | לקוח → שרת | לא (קריאה בלבד) | בדרך כלל לא | אחזור נתונים, איסוף הקשר | +| הנחיות | משתמש | שרת → לקוח | לא | לא (נבחר על ידי המשתמש) | זרימות עבודה מודרכות, תבניות מיוחדות | +| דגימה | שרת | שרת → לקוח → שרת | בעקיפין | כן | משימות רב-שלביות, התנהגויות סוכניות | + +יכולות אלה מתוכננות לעבוד יחד בדרכים משלימות: + +1. משתמש עשוי לבחור **הנחיה** כדי להתחיל זרימת עבודה מיוחדת +2. ההנחיה עשויה לכלול הקשר מ**משאבים** +3. במהלך העיבוד, מודל הבינה המלאכותית עשוי לקרוא ל**כלים** כדי לבצע פעולות ספציפיות +4. עבור פעולות מורכבות, השרת עשוי להשתמש ב**דגימה** כדי לבקש עיבוד LLM נוסף + +ההבחנה בין מרכיבים בסיסיים אלה מספקת מבנה ברור לאינטראקציות MCP, מאפשרת למודלי בינה מלאכותית לגשת למידע, לבצע פעולות ולעסוק בזרימות עבודה מורכבות תוך שמירה על גבולות שליטה מתאימים. + +## תהליך גילוי + +אחת התכונות המרכזיות של MCP היא גילוי יכולות דינמי. כאשר לקוח מתחבר לשרת, הוא יכול לשאול על הכלים, המשאבים וההנחיות הזמינים דרך שיטות רשימה ספציפיות: + +- `tools/list`: גלה כלים זמינים +- `resources/list`: גלה משאבים זמינים +- `prompts/list`: גלה הנחיות זמינות + +מנגנון גילוי דינמי זה מאפשר ללקוחות להסתגל ליכולות הספציפיות שכל שרת מציע ללא צורך בידע מקודד מראש של פונקציונליות השרת. + +## סיכום + +הבנת המרכיבים הבסיסיים האלה היא חיונית לעבודה עם MCP ביעילות. על ידי אספקת סוגי יכולות מובחנים עם גבולות שליטה ברורים, MCP מאפשר אינטראקציות חזקות בין מודלי בינה מלאכותית ומערכות חיצוניות תוך שמירה על מנגנוני בטיחות ושליטה מתאימים. + +בסעיף הבא, נחקור כיצד Gradio משתלב עם MCP כדי לספק ממשקים קלים לשימוש עבור יכולות אלה. diff --git a/units/he/unit1/certificate.mdx b/units/he/unit1/certificate.mdx new file mode 100644 index 0000000..b0d2245 --- /dev/null +++ b/units/he/unit1/certificate.mdx @@ -0,0 +1,18 @@ +# קבל את התעודה שלך! + +כל הכבוד! השלמת את היחידה הראשונה של קורס MCP. כעת הגיע הזמן לעשות את המבחן כדי לקבל את התעודה שלך. + +להלן חידון לבדיקת ההבנה שלך של היחידה. + + + + + +אם אתה מתקשה להשתמש בחידון למעלה, גש למרחב ישירות [ב-Hugging Face Hub](https://huggingface.co/spaces/mcp-course/unit_1_quiz). אם אתה מוצא שגיאות, אתה יכול לדווח עליהן בלשונית [הקהילה](https://huggingface.co/spaces/mcp-course/unit_1_quiz/discussions) של המרחב. + + diff --git a/units/he/unit1/communication-protocol.mdx b/units/he/unit1/communication-protocol.mdx new file mode 100644 index 0000000..ddb498d --- /dev/null +++ b/units/he/unit1/communication-protocol.mdx @@ -0,0 +1,223 @@ +# פרוטוקול התקשורת + +MCP מגדיר פרוטוקול תקשורת סטנדרטי המאפשר ללקוחות ושרתים להחליף הודעות באופן עקבי וצפוי. סטנדרטיזציה זו קריטית ליכולת פעולה הדדית בין הקהילה. בסעיף זה, נחקור את מבנה הפרוטוקול ומנגנוני התעבורה המשמשים ב-MCP. + + + +אנחנו נכנסים לפרטים הקטנים של פרוטוקול MCP. לא תצטרך לדעת את כל זה כדי לבנות עם MCP, אבל טוב לדעת שזה קיים ואיך זה עובד. + + + +## JSON-RPC: היסוד + +בבסיסו, MCP משתמש ב-**JSON-RPC 2.0** כפורמט ההודעות עבור כל התקשורת בין לקוחות ושרתים. JSON-RPC הוא פרוטוקול קריאת פרוצדורה מרחוק קל משקל המקודד ב-JSON, מה שהופך אותו ל: + +- קריא לאדם וקל לניפוי שגיאות +- אגנוסטי לשפה, תומך ביישום בכל סביבת תכנות +- מבוסס היטב, עם מפרטים ברורים ואימוץ נרחב + +![סוגי הודעות](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/5.png) + +הפרוטוקול מגדיר שלושה סוגי הודעות: + +### 1. בקשות + +נשלחות מלקוח לשרת כדי ליזום פעולה. הודעת בקשה כוללת: +- מזהה ייחודי (`id`) +- שם השיטה להפעלה (למשל, `tools/call`) +- פרמטרים לשיטה (אם יש) + +דוגמת בקשה: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "weather", + "arguments": { + "location": "San Francisco" + } + } +} +``` + +### 2. תגובות + +נשלחות משרת ללקוח בתשובה לבקשה. הודעת תגובה כוללת: +- אותו `id` כמו הבקשה המתאימה +- או `result` (להצלחה) או `error` (לכישלון) + +דוגמת תגובת הצלחה: +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "temperature": 62, + "conditions": "Partly cloudy" + } +} +``` + +דוגמת תגובת שגיאה: +```json +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": -32602, + "message": "Invalid location parameter" + } +} +``` + +### 3. התראות + +הודעות חד-כיווניות שאינן דורשות תגובה. בדרך כלל נשלחות משרת ללקוח כדי לספק עדכונים או התראות על אירועים. + +דוגמת התראה: +```json +{ + "jsonrpc": "2.0", + "method": "progress", + "params": { + "message": "Processing data...", + "percent": 50 + } +} +``` + +## מנגנוני תעבורה + +JSON-RPC מגדיר את פורמט ההודעה, אבל MCP גם מפרט כיצד הודעות אלה מועברות בין לקוחות ושרתים. שני מנגנוני תעבורה עיקריים נתמכים: + +### stdio (קלט/פלט סטנדרטי) + +תעבורת stdio משמשת לתקשורת מקומית, כאשר הלקוח והשרת רצים על אותה מכונה: + +יישום המארח מפעיל את השרת כתהליך משנה ומתקשר איתו על ידי כתיבה לקלט הסטנדרטי שלו (stdin) וקריאה מהפלט הסטנדרטי שלו (stdout). + + + +**מקרי שימוש** לתעבורה זו הם כלים מקומיים כמו גישה למערכת קבצים או הפעלת סקריפטים מקומיים. + + + +ה**יתרונות** העיקריים של תעבורה זו הם שהיא פשוטה, לא נדרשת תצורת רשת, ומאובטחת על ידי מערכת ההפעלה. + +### HTTP + SSE (אירועים הנשלחים מהשרת) / HTTP זרימתי + +תעבורת HTTP+SSE משמשת לתקשורת מרוחקת, כאשר הלקוח והשרת עשויים להיות על מכונות שונות: + +התקשורת מתרחשת דרך HTTP, כאשר השרת משתמש באירועים הנשלחים מהשרת (SSE) כדי לדחוף עדכונים ללקוח דרך חיבור מתמשך. + + + +**מקרי שימוש** לתעבורה זו הם התחברות ל-API מרוחקים, שירותי ענן, או משאבים משותפים. + + + +ה**יתרונות** העיקריים של תעבורה זו הם שהיא עובדת דרך רשתות, מאפשרת אינטגרציה עם שירותי אינטרנט, ותואמת לסביבות serverless. + +עדכונים אחרונים לתקן MCP הציגו או שיפרו "HTTP זרימתי", המציע יותר גמישות על ידי מתן אפשרות לשרתים לשדרג דינמית ל-SSE עבור הזרמה כאשר צריך, תוך שמירה על תאימות עם סביבות serverless. + +## מחזור החיים של האינטראקציה + +בסעיף הקודם, דנו במחזור החיים של אינטראקציה בודדת בין לקוח (💻) לשרת (🌐). בואו נסתכל עכשיו על מחזור החיים של אינטראקציה שלמה בין לקוח לשרת בהקשר של פרוטוקול MCP. + +פרוטוקול MCP מגדיר מחזור חיים מובנה של אינטראקציה בין לקוחות ושרתים: + +### אתחול + +הלקוח מתחבר לשרת והם מחליפים גרסאות פרוטוקול ויכולות, והשרת מגיב עם גרסת הפרוטוקול הנתמכת והיכולות שלו. + + + + + + + + + + + + + + + + + +
💻→
initialize		🌐
💻←
response		🌐
💻→
initialized		🌐
+ +הלקוח מאשר שהאתחול הושלם באמצעות הודעת התראה. + +### גילוי + +הלקוח מבקש מידע על יכולות זמינות והשרת מגיב עם רשימה של כלים זמינים. + + + + + + + + + + + + +
💻→
tools/list		🌐
💻←
response		🌐
+ +תהליך זה יכול להיות מחזורי עבור כל סוג כלי, משאב או הנחיה. + +### ביצוע + +הלקוח מפעיל יכולות בהתבסס על צרכי המארח. + + + + + + + + + + + + + + + + + +
💻→
tools/call		🌐
💻←
notification (התקדמות אופציונלית)		🌐
💻←
response		🌐
+ +### סיום + +החיבור נסגר בצורה מסודרת כאשר אינו נדרש יותר והשרת מאשר את בקשת הכיבוי. + + + + + + + + + + + + + + + + + +
💻→
shutdown		🌐
💻←
response		🌐
💻→
exit		🌐
+ +הלקוח שולח את הודעת היציאה הסופית להשלמת הסיום. + +## אבולוציית הפרוטוקול + +פרוטוקול MCP מתוכנן להיות הרחיב ומסתגל. שלב האתחול כולל משא ומתן על גרסאות, המאפשר תאימות לאחור ככל שהפרוטוקול מתפתח. בנוסף, גילוי יכולות מאפשר ללקוחות להסתגל לתכונות הספציפיות שכל שרת מציע, מאפשר תערובת של שרתים בסיסיים ומתקדמים באותה מערכת אקולוגית. diff --git a/units/he/unit1/gradio-mcp.mdx b/units/he/unit1/gradio-mcp.mdx new file mode 100644 index 0000000..64be4b1 --- /dev/null +++ b/units/he/unit1/gradio-mcp.mdx @@ -0,0 +1,154 @@ +# אינטגרציית Gradio ל-MCP + +חקרנו כעת את המושגים הבסיסיים של פרוטוקול MCP ואיך ליישם שרתי וקליינטי MCP. בסעיף זה, נקל מעט את הדברים על ידי שימוש ב-Gradio ליצירת שרת MCP! + + + +Gradio היא ספריית פייתון פופולרית ליצירה מהירה של ממשקי משתמש מותאמים אישית למודלים של למידת מכונה. + + + +## מבוא ל-Gradio + +Gradio מאפשרת למפתחים ליצור ממשקי משתמש למודלים שלהם עם כמה שורות קוד פייתון בלבד. זה שימושי במיוחד עבור: + +- יצירת הדגמות ואבות טיפוס +- שיתוף מודלים עם משתמשים שאינם טכניים +- בדיקה וניפוי שגיאות בהתנהגות המודל + +עם תוספת תמיכת MCP, Gradio מציעה כעת דרך פשוטה לחשוף יכולות מודל בינה מלאכותית דרך פרוטוקול MCP סטנדרטי. + +שילוב Gradio עם MCP מאפשר לך ליצור גם ממשקים ידידותיים למשתמש וגם כלים נגישים לבינה מלאכותית עם קוד מינימלי. אבל הכי טוב מכל, Gradio כבר בשימוש נרחב על ידי קהילת הבינה המלאכותית, כך שתוכל להשתמש בו לשיתוף שרתי MCP שלך עם אחרים. + +## דרישות מקדימות + +כדי להשתמש ב-Gradio עם תמיכת MCP, תצטרך להתקין את Gradio עם התוספת MCP: + +```bash +pip install "gradio[mcp]" +``` + +תצטרך גם יישום LLM שתומך בקריאת כלים באמצעות פרוטוקול MCP, כמו Cursor (הידועים כ-"מארחי MCP"). + +## יצירת שרת MCP עם Gradio + +בואו נעבור על דוגמה בסיסית ליצירת שרת MCP באמצעות Gradio: + +```python +import gradio as gr + +def letter_counter(word: str, letter: str) -> int: + """ + ספור את מספר ההופעות של אות במילה או טקסט. + + Args: + word (str): טקסט הקלט לחיפוש + letter (str): האות לחיפוש + + Returns: + int: מספר הפעמים שהאות מופיעה בטקסט + """ + word = word.lower() + letter = letter.lower() + count = word.count(letter) + return count + +# יצירת ממשק Gradio סטנדרטי +demo = gr.Interface( + fn=letter_counter, + inputs=["textbox", "textbox"], + outputs="number", + title="סופר אותיות", + description="הזן טקסט ואות כדי לספור כמה פעמים האות מופיעה בטקסט." +) + +# הפעלת גם ממשק האינטרנט של Gradio וגם שרת ה-MCP +if __name__ == "__main__": + demo.launch(mcp_server=True) +``` + +עם הגדרה זו, פונקציית סופר האותיות שלך כעת נגישה דרך: + +1. ממשק אינטרנט מסורתי של Gradio לאינטראקציה אנושית ישירה +2. שרת MCP שיכול להתחבר ללקוחות תואמים + +שרת ה-MCP יהיה נגיש ב: +``` +http://your-server:port/gradio_api/mcp/sse +``` + +היישום עצמו עדיין יהיה נגיש והוא נראה כך: + +![שרת Gradio MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/7.png) + +## איך זה עובד מאחורי הקלעים + +כאשר אתה מגדיר `mcp_server=True` ב-`launch()`, מתרחשים מספר דברים: + +1. פונקציות Gradio מומרות אוטומטית לכלי MCP +2. רכיבי קלט ממופים לסכמות ארגומנטים של הכלי +3. רכיבי פלט קובעים את פורמט התגובה +4. שרת ה-Gradio כעת גם מקשיב להודעות פרוטוקול MCP +5. JSON-RPC מעל HTTP+SSE מוגדר לתקשורת לקוח-שרת + +## תכונות מפתח של אינטגרציית Gradio <> MCP + +1. **המרת כלים**: כל נקודת קצה API ביישום Gradio שלך מומרת אוטומטית לכלי MCP עם שם, תיאור וסכמת קלט מתאימים. כדי לצפות בכלים ובסכמות, בקר ב-`http://your-server:port/gradio_api/mcp/schema` או עבור לקישור "View API" בתחתית יישום ה-Gradio שלך, ואז לחץ על "MCP". + +2. **תמיכה במשתני סביבה**: יש שתי דרכים להפעיל את פונקציונליות שרת ה-MCP: +- שימוש בפרמטר `mcp_server` ב-`launch()`: + ```python + demo.launch(mcp_server=True) + ``` +- שימוש במשתני סביבה: + ```bash + export GRADIO_MCP_SERVER=True + ``` + +3. **טיפול בקבצים**: השרת מטפל אוטומטית בהמרות נתוני קבצים, כולל: + - המרת מחרוזות מקודדות base64 לנתוני קובץ + - עיבוד קבצי תמונה והחזרתם בפורמט הנכון + - ניהול אחסון קבצים זמני + + **מומלץ מאוד** שתמונות קלט וקבצים יועברו כ-URL מלאים ("http://..." או "https://...") מכיוון שלקוחות MCP לא תמיד מטפלים בקבצים מקומיים בצורה נכונה. + +4. **שרתי MCP מאוחסנים ב-🤗 Spaces**: אתה יכול לפרסם את יישום ה-Gradio שלך בחינם ב-Hugging Face Spaces, מה שיאפשר לך לקבל שרת MCP מאוחסן בחינם. הנה דוגמה לSpace כזה: https://huggingface.co/spaces/abidlabs/mcp-tools + +## טיפים לפתרון בעיות + +1. **רמזי טיפוס ו-Docstrings**: ודא שאתה מספק רמזי טיפוס ו-docstrings תקפים לפונקציות שלך. ה-docstring צריך לכלול בלוק "Args:" עם שמות פרמטרים מוזחים. + +2. **קלטי מחרוזת**: כאשר יש ספק, קבל ארגומנטי קלט כ-`str` והמר אותם לסוג הרצוי בתוך הפונקציה. + +3. **תמיכת SSE**: חלק ממארחי MCP אינם תומכים בשרתי MCP מבוססי SSE. במקרים אלה, אתה יכול להשתמש ב-`mcp-remote`: + ```json + { + "mcpServers": { + "gradio": { + "command": "npx", + "args": [ + "mcp-remote", + "http://your-server:port/gradio_api/mcp/sse" + ] + } + } + } + ``` + +4. **הפעלה מחדש**: אם אתה נתקל בבעיות חיבור, נסה להפעיל מחדש את שני לקוח MCP ושרת MCP שלך. + +## שתף את שרת ה-MCP שלך + +אתה יכול לשתף את שרת ה-MCP שלך על ידי פרסום יישום ה-Gradio שלך ל-Hugging Face Spaces. הסרטון למטה מראה כיצד ליצור Hugging Face Space. + + + +כעת, אתה יכול לשתף את שרת ה-MCP שלך עם אחרים על ידי שיתוף ה-Hugging Face Space שלך. + +## סיכום + +האינטגרציה של Gradio עם MCP מספקת נקודת כניסה נגישה למערכת האקולוגית של MCP. על ידי ניצול הפשטות של Gradio והוספת הסטנדרטיזציה של MCP, מפתחים יכולים ליצור במהירות גם ממשקים ידידותיים למשתמש וגם כלים נגישים לבינה מלאכותית עם קוד מינימלי. + +ככל שנתקדם בקורס זה, נחקור יישומי MCP מתוחכמים יותר, אבל Gradio מציע נקודת התחלה מצוינת להבנה וניסוי עם הפרוטוקול. + +ביחידה הבאה, נעמיק בבניית יישומי MCP, ונתמקד בהגדרת סביבות פיתוח, חקירת SDK, ויישום שרתי ולקוחות MCP מתקדמים יותר. diff --git a/units/he/unit1/introduction.mdx b/units/he/unit1/introduction.mdx new file mode 100644 index 0000000..bd03413 --- /dev/null +++ b/units/he/unit1/introduction.mdx @@ -0,0 +1,33 @@ +# מבוא לפרוטוקול הקשר המודל (MCP) + +ברוכים הבאים ליחידה 1 של קורס ה-MCP! ביחידה זו, נחקור את היסודות של פרוטוקול הקשר המודל. + +## מה תלמדו + +ביחידה זו, אתם: + +* תבינו מהו פרוטוקול הקשר המודל ומדוע הוא חשוב +* תלמדו את המושגים והטרמינולוגיה המרכזיים הקשורים ל-MCP +* תחקרו את אתגרי האינטגרציה ש-MCP פותר +* תעברו על היתרונות והמטרות המרכזיות של MCP +* תראו דוגמה פשוטה של אינטגרציית MCP בפעולה + +בסוף יחידה זו, תהיה לכם הבנה מוצקה של המושגים היסודיים של MCP ותהיו מוכנים להעמיק בארכיטקטורה וביישום שלו ביחידה הבאה. + +## חשיבות ה-MCP + +המערכת האקולוגית של בינה מלאכותית מתפתחת במהירות, כאשר מודלי שפה גדולים (LLMs) ומערכות בינה מלאכותית אחרות הופכים ליותר ויותר מתקדמים. עם זאת, מודלים אלה לעתים קרובות מוגבלים על ידי נתוני האימון שלהם וחסרים גישה למידע בזמן אמת או כלים מיוחדים. מגבלה זו מעכבת את הפוטנציאל של מערכות בינה מלאכותית לספק תגובות רלוונטיות, מדויקות ומועילות באמת בתרחישים רבים. + +כאן נכנס פרוטוקול הקשר המודל (MCP). MCP מאפשר למודלי בינה מלאכותית להתחבר למקורות נתונים חיצוניים, כלים וסביבות, ומאפשר העברה חלקה של מידע ויכולות בין מערכות בינה מלאכותית והעולם הדיגיטלי הרחב יותר. יכולת פעולה הדדית זו היא קריטית לצמיחה ואימוץ של יישומי בינה מלאכותית מועילים באמת. + +## סקירה של יחידה 1 + +הנה סקירה קצרה של מה שנכסה ביחידה זו: + +1. **מהו פרוטוקול הקשר המודל?** - נתחיל בהגדרת מהו MCP ונדון בתפקידו במערכת האקולוגית של בינה מלאכותית. +2. **מושגי מפתח** - נחקור את המושגים היסודיים והטרמינולוגיה הקשורים ל-MCP. +3. **אתגרי אינטגרציה** - נבחן את הבעיות ש-MCP מטרתו לפתור, במיוחד את "בעיית האינטגרציה M×N". +4. **יתרונות ומטרות** - נדון ביתרונות ובמטרות המרכזיות של MCP, כולל סטנדרטיזציה, יכולות בינה מלאכותית משופרות ויכולת פעולה הדדית. +5. **דוגמה פשוטה** - לבסוף, נעבור על דוגמה פשוטה של אינטגרציית MCP כדי לראות איך זה עובד בפועל. + +בואו נצלול ונחקור את העולם המרתק של פרוטוקול הקשר המודל! diff --git a/units/he/unit1/key-concepts.mdx b/units/he/unit1/key-concepts.mdx new file mode 100644 index 0000000..e8a29cf --- /dev/null +++ b/units/he/unit1/key-concepts.mdx @@ -0,0 +1,92 @@ +# מושגי מפתח וטרמינולוגיה + +לפני שנעמיק יותר בפרוטוקול הקשר המודל, חשוב להבין את מושגי המפתח והטרמינולוגיה שמהווים את הבסיס ל-MCP. סעיף זה יציג את הרעיונות היסודיים שתומכים בפרוטוקול ויספק אוצר מילים משותף לדיון ביישומי MCP לאורך הקורס. + +MCP מתואר לעתים קרובות כ"USB-C ליישומי בינה מלאכותית". בדיוק כפי ש-USB-C מספק ממשק פיזי ולוגי סטנדרטי לחיבור מגוון ציוד היקפי למכשירי מחשוב, MCP מציע פרוטוקול עקבי לקישור מודלי בינה מלאכותית ליכולות חיצוניות. סטנדרטיזציה זו מועילה לכל המערכת האקולוגית: + +- **משתמשים** נהנים מחוויות פשוטות ועקביות יותר בכל יישומי הבינה המלאכותית +- **מפתחי יישומי בינה מלאכותית** מקבלים אינטגרציה קלה עם מערכת אקולוגית צומחת של כלים ומקורות נתונים +- **ספקי כלים ונתונים** צריכים ליצור רק יישום אחד שעובד עם יישומי בינה מלאכותית מרובים +- המערכת האקולוגית הרחבה יותר נהנית מיכולת פעולה הדדית מוגברת, חדשנות ופיצול מופחת + +## בעיית האינטגרציה + +**בעיית האינטגרציה M×N** מתייחסת לאתגר של חיבור M יישומי בינה מלאכותית שונים ל-N כלים חיצוניים או מקורות נתונים שונים ללא גישה סטנדרטית. + +### ללא MCP (בעיית M×N) + +ללא פרוטוקול כמו MCP, מפתחים היו צריכים ליצור M×N אינטגרציות מותאמות אישית—אחת לכל צימוד אפשרי של יישום בינה מלאכותית עם יכולת חיצונית. + +![ללא MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/1.png) + +כל יישום בינה מלאכותית היה צריך להתממשק עם כל כלי/מקור נתונים בנפרד. זהו תהליך מורכב ויקר מאוד המכניס הרבה חיכוך למפתחים ועלויות תחזוקה גבוהות. + +ברגע שיש לנו מודלים וכלים מרובים, מספר האינטגרציות הופך גדול מדי לניהול, כל אחת עם ממשק ייחודי משלה. + +![מודלים וכלים מרובים](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/1a.png) + +### עם MCP (פתרון M+N) + +MCP הופך את זה לבעיית M+N על ידי אספקת ממשק סטנדרטי: כל יישום בינה מלאכותית מיישם את צד הלקוח של MCP פעם אחת, וכל כלי/מקור נתונים מיישם את צד השרת פעם אחת. זה מפחית משמעותית את מורכבות האינטגרציה ואת נטל התחזוקה. + +![עם MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/2.png) + +כל יישום בינה מלאכותית מיישם את צד הלקוח של MCP פעם אחת, וכל כלי/מקור נתונים מיישם את צד השרת פעם אחת. + +## טרמינולוגיית ליבה של MCP + +עכשיו שאנחנו מבינים את הבעיה ש-MCP פותר, בואו נצלול למונחים ומושגי הליבה המרכיבים את פרוטוקול ה-MCP. + + + +MCP הוא סטנדרט כמו HTTP או USB-C, והוא פרוטוקול לחיבור יישומי בינה מלאכותית לכלים ומקורות נתונים חיצוניים. לכן, שימוש בטרמינולוגיה סטנדרטית הוא קריטי לגרום ל-MCP לעבוד ביעילות. + +כאשר אנו מתעדים את היישומים שלנו ומתקשרים עם הקהילה, עלינו להשתמש בטרמינולוגיה הבאה. + + + +### רכיבים + +בדיוק כמו יחסי לקוח-שרת ב-HTTP, ל-MCP יש לקוח ושרת. + +![רכיבי MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/3.png) + +- **מארח**: יישום הבינה המלאכותית הפונה למשתמש שמשתמשי קצה מתקשרים איתו ישירות. דוגמאות כוללות את Claude Desktop של Anthropic, סביבות פיתוח משופרות בבינה מלאכותית כמו Cursor, ספריות הסקה כמו Hugging Face Python SDK, או יישומים מותאמים אישית שנבנו בספריות כמו LangChain או smolagents. מארחים יוזמים חיבורים לשרתי MCP ומתזמרים את הזרימה הכוללת בין בקשות משתמשים, עיבוד LLM, וכלים חיצוניים. + +- **לקוח**: רכיב בתוך יישום המארח שמנהל תקשורת עם שרת MCP ספציפי. כל לקוח מתחזק חיבור 1:1 עם שרת יחיד, מטפל בפרטים ברמת הפרוטוקול של תקשורת MCP ופועל כמתווך בין הלוגיקה של המארח לבין השרת החיצוני. + +- **שרת**: תוכנית או שירות חיצוני שחושף יכולות (כלים, משאבים, הנחיות) דרך פרוטוקול ה-MCP. + + + +הרבה תוכן משתמש ב'לקוח' ו'מארח' לחלופין. טכנית, המארח הוא היישום הפונה למשתמש, והלקוח הוא הרכיב בתוך יישום המארח שמנהל תקשורת עם שרת MCP ספציפי. + + + +### יכולות + +כמובן, הערך של היישום שלך הוא סכום היכולות שהוא מציע. לכן היכולות הן החלק החשוב ביותר ביישום שלך. MCP יכול להתחבר לכל שירות תוכנה, אך יש כמה יכולות נפוצות שמשמשות עבור יישומי בינה מלאכותית רבים. + +| יכולת | תיאור | דוגמה | +| ---------- | ----------- | ------- | +| **כלים** | פונקציות ניתנות להפעלה שמודל הבינה המלאכותית יכול להפעיל כדי לבצע פעולות או לאחזר נתונים מחושבים. בדרך כלל קשורים למקרה השימוש של היישום. | כלי ליישום מזג אוויר עשוי להיות פונקציה המחזירה את מזג האוויר במיקום ספציפי. | +| **משאבים** | מקורות נתונים לקריאה בלבד המספקים הקשר ללא חישוב משמעותי. | עוזר חוקר עשוי לכלול משאב למאמרים מדעיים. | +| **הנחיות** | תבניות או זרימות עבודה מוגדרות מראש המנחות אינטראקציות בין משתמשים, מודלי בינה מלאכותית, והיכולות הזמינות. | הנחיית סיכום. | +| **דגימה** | בקשות מופעלות על ידי השרת ללקוח/מארח לבצע אינטראקציות LLM, המאפשרות פעולות רקורסיביות בהן ה-LLM יכול לסקור תוכן שנוצר ולקבל החלטות נוספות. | יישום כתיבה הסוקר את הפלט שלו עצמו ומחליט לשפר אותו יותר. | + +בתרשים הבא, אנו יכולים לראות את היכולות הקולקטיביות המיושמות על מקרה שימוש עבור סוכן קוד. + +![תרשים קולקטיבי](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/8.png) + +יישום זה עשוי להשתמש בישויות ה-MCP שלו בדרך הבאה: + +| ישות | שם | תיאור | +| --- | --- | --- | +| כלי | מפרש קוד | כלי שיכול להריץ קוד שה-LLM כותב. | +| משאב | תיעוד | משאב שמכיל את התיעוד של היישום. | +| הנחיה | סגנון קוד | הנחיה שמדריכה את ה-LLM ליצור קוד. | +| דגימה | סקירת קוד | דגימה שמאפשרת ל-LLM לסקור את הקוד ולקבל החלטות נוספות. | + +### סיכום + +הבנת מושגי המפתח והטרמינולוגיה הללו מספקת את היסוד לעבודה יעילה עם MCP. בסעיפים הבאים, נבנה על יסוד זה כדי לחקור את הרכיבים הארכיטקטוניים, פרוטוקול התקשורת, והיכולות המרכיבים את פרוטוקול הקשר המודל. diff --git a/units/he/unit1/mcp-clients.mdx b/units/he/unit1/mcp-clients.mdx new file mode 100644 index 0000000..b9c5441 --- /dev/null +++ b/units/he/unit1/mcp-clients.mdx @@ -0,0 +1,342 @@ +# לקוחות MCP + +כעת שיש לנו הבנה בסיסית של פרוטוקול הקשר המודל, אנחנו יכולים לחקור את התפקיד החיוני של לקוחות MCP במערכת האקולוגית של פרוטוקול הקשר המודל. + +בחלק זה של יחידה 1, נחקור את התפקיד החיוני של לקוחות MCP במערכת האקולוגית של פרוטוקול הקשר המודל. + +בסעיף זה, אתם: + +* תבינו מהם לקוחות MCP ומהו תפקידם בארכיטקטורת ה-MCP +* תלמדו על האחריות המרכזית של לקוחות MCP +* תחקרו את יישומי לקוח ה-MCP העיקריים +* תגלו איך להשתמש ביישום לקוח ה-MCP של Hugging Face +* תראו דוגמאות מעשיות לשימוש בלקוח MCP + +## הבנת לקוחות MCP + +לקוחות MCP הם רכיבים קריטיים הפועלים כגשר בין יישומי בינה מלאכותית (מארחים) ליכולות חיצוניות המסופקות על ידי שרתי MCP. חשבו על המארח כיישום הראשי שלכם (כמו עוזר בינה מלאכותית או IDE) ועל הלקוח כמודול ייעודי בתוך המארח האחראי על טיפול בתקשורת MCP. + +## לקוח ממשק משתמש + +בואו נתחיל בחקירת לקוחות ממשק המשתמש הזמינים עבור ה-MCP. + +### לקוחות ממשק צ'אט + +Claude Desktop של Anthropic עומד כאחד מלקוחות ה-MCP הבולטים ביותר, המספק אינטגרציה עם שרתי MCP שונים. + +### לקוחות פיתוח אינטראקטיביים + +יישום לקוח ה-MCP של Cursor מאפשר סיוע בקידוד מופעל בינה מלאכותית באמצעות אינטגרציה ישירה עם יכולות עריכת קוד. הוא תומך בחיבורי שרת MCP מרובים ומספק הפעלת כלים בזמן אמת במהלך הקידוד, מה שהופך אותו לכלי עוצמתי למפתחים. + +Continue.dev הוא דוגמה נוספת ללקוח פיתוח אינטראקטיבי התומך ב-MCP ומתחבר לשרת MCP מ-VS Code. + +## הגדרת לקוחות MCP + +כעת שכיסינו את הליבה של פרוטוקול ה-MCP, בואו נראה איך להגדיר את שרתי ולקוחות ה-MCP שלכם. + +פריסה יעילה של שרתים ולקוחות MCP דורשת הגדרה נכונה. + + + +מפרט ה-MCP עדיין מתפתח, כך ששיטות ההגדרה כפופות לאבולוציה. נתמקד בשיטות העבודה המומלצות הנוכחיות להגדרה. + + + +### קבצי הגדרה של MCP + +מארחי MCP משתמשים בקבצי הגדרה לניהול חיבורי שרת. קבצים אלה מגדירים אילו שרתים זמינים וכיצד להתחבר אליהם. + +למרבה המזל, קבצי ההגדרה הם מאוד פשוטים, קלים להבנה, ועקביים בין מארחי MCP עיקריים. + +#### מבנה `mcp.json` + +קובץ ההגדרה הסטנדרטי ל-MCP נקרא `mcp.json`. הנה המבנה הבסיסי: + +```json +{ + "servers": [ + { + "name": "שם השרת", + "transport": { + "type": "stdio|sse", + // הגדרות ספציפיות לתעבורה + } + } + ] +} +``` + +בדוגמה זו, יש לנו שרת יחיד עם שם וסוג תעבורה. סוג התעבורה הוא או `stdio` או `sse`. + +#### הגדרה עבור תעבורת stdio + +עבור שרתים מקומיים המשתמשים בתעבורת stdio, ההגדרה כוללת את הפקודה והארגומנטים להפעלת תהליך השרת: + +```json +{ + "servers": [ + { + "name": "סייר קבצים", + "transport": { + "type": "stdio", + "command": "python", + "args": ["/path/to/file_explorer_server.py"] + } + } + ] +} +``` + +כאן, יש לנו שרת הנקרא "סייר קבצים" שהוא סקריפט מקומי. + +#### הגדרה עבור תעבורת HTTP+SSE + +עבור שרתים מרוחקים המשתמשים בתעבורת HTTP+SSE, ההגדרה כוללת את כתובת ה-URL של השרת: + +```json +{ + "servers": [ + { + "name": "שרת API מרוחק", + "transport": { + "type": "sse", + "url": "https://example.com/mcp-server" + } + } + ] +} +``` + +#### משתני סביבה בהגדרה + +ניתן להעביר משתני סביבה לתהליכי שרת באמצעות השדה `env`. הנה כיצד לגשת אליהם בקוד השרת שלכם: + + + + +בפייתון, אנו משתמשים במודול `os` כדי לגשת למשתני סביבה: + +```python +import os + +# גישה למשתני סביבה +github_token = os.environ.get("GITHUB_TOKEN") +if not github_token: + raise ValueError("משתנה הסביבה GITHUB_TOKEN נדרש") + +# שימוש בטוקן בקוד השרת שלך +def make_github_request(): + headers = {"Authorization": f"Bearer {github_token}"} + # ... שאר הקוד שלך +``` + + + + +בג'אווהסקריפט, אנו משתמשים באובייקט `process.env` כדי לגשת למשתני סביבה: + +```javascript +// גישה למשתני סביבה +const githubToken = process.env.GITHUB_TOKEN; +if (!githubToken) { + throw new Error("משתנה הסביבה GITHUB_TOKEN נדרש"); +} + +// שימוש בטוקן בקוד השרת שלך +function makeGithubRequest() { + const headers = { "Authorization": `Bearer ${githubToken}` }; + // ... שאר הקוד שלך +} +``` + + + + +ההגדרה המתאימה ב-`mcp.json` תיראה כך: + +```json +{ + "servers": [ + { + "name": "GitHub API", + "transport": { + "type": "stdio", + "command": "python", + "args": ["/path/to/github_server.py"], + "env": { + "GITHUB_TOKEN": "הטוקן_שלך_בגיטהאב" + } + } + } + ] +} +``` + +### דוגמאות הגדרה + +בואו נסתכל על כמה תרחישי הגדרה מהעולם האמיתי: + +#### תרחיש 1: הגדרת שרת מקומי + +בתרחיש זה, יש לנו שרת מקומי שהוא סקריפט פייתון שיכול להיות סייר קבצים או עורך קוד. + +```json +{ + "servers": [ + { + "name": "סייר קבצים", + "transport": { + "type": "stdio", + "command": "python", + "args": ["/path/to/file_explorer_server.py"] + } + } + ] +} +``` + +#### תרחיש 2: הגדרת שרת מרוחק + +בתרחיש זה, יש לנו שרת מרוחק שהוא API מזג אוויר. + +```json +{ + "servers": [ + { + "name": "API מזג אוויר", + "transport": { + "type": "sse", + "url": "https://example.com/mcp-server" + } + } + ] +} +``` + +הגדרה נכונה היא חיונית לפריסה מוצלחת של אינטגרציות MCP. על ידי הבנת היבטים אלה, אתם יכולים ליצור חיבורים חזקים ואמינים בין יישומי בינה מלאכותית ויכולות חיצוניות. + +בסעיף הבא, נחקור את המערכת האקולוגית של שרתי MCP הזמינים ב-Hugging Face Hub וכיצד לפרסם את השרתים שלכם שם. + +## לקוחות קוד + +אתם יכולים גם להשתמש בלקוח ה-MCP בתוך קוד כך שהכלים יהיו זמינים ל-LLM. בואו נחקור כמה דוגמאות ב-`smolagents`. + +ראשית, בואו נחקור את שרת מזג האוויר שלנו מהעמוד הקודם. ב-`smolagents`, אנחנו יכולים להשתמש במחלקה `ToolCollection` כדי לגלות ולרשום באופן אוטומטי כלים משרת MCP. זה נעשה על ידי העברת `StdioServerParameters` או `SSEServerParameters` לשיטה `ToolCollection.from_mcp`. אז אנחנו יכולים להדפיס את הכלים למסוף. + +```python +from smolagents import ToolCollection +from mcp.client.stdio import StdioServerParameters + +server_parameters = StdioServerParameters(command="uv", args=["run", "server.py"]) + +with ToolCollection.from_mcp( + server_parameters, trust_remote_code=True +) as tools: + print("\n".join(f"{tool.name}: {tool.description}" for tool in tools.tools)) + +``` + +
+ +פלט + + +```sh +get_weather: קבל את מזג האוויר הנוכחי למיקום מצוין. + +``` + +
+ +אנחנו יכולים גם להתחבר לשרת MCP שמאוחסן במחשב מרוחק. במקרה זה, אנחנו צריכים להעביר את `SSEServerParameters` למחלקה `MCPClient`. + +```python +from smolagents.mcp_client import MCPClient + +with MCPClient( + {"url": "https://abidlabs-mcp-tools.hf.space/gradio_api/mcp/sse"} +) as tools: + # כלים מהשרת המרוחק זמינים + print("\n".join(f"{t.name}: {t.description}" for t in tools)) +``` + +
+ +פלט + + +```sh +prime_factors: חשב את הפירוק לגורמים ראשוניים של מספר שלם חיובי. +generate_cheetah_image: צור תמונת צ'יטה. +image_orientation: מחזיר אם התמונה היא לאורך או לרוחב. +sepia: החל פילטר ספיה לתמונת הקלט. +``` + +
+ +עכשיו, בואו נראה איך אנחנו יכולים להשתמש בלקוח ה-MCP בסוכן קוד. + +```python +from smolagents import InferenceClientModel, CodeAgent, ToolCollection +from mcp.client.stdio import StdioServerParameters + +model = InferenceClientModel() + +server_parameters = StdioServerParameters(command="uv", args=["run", "server.py"]) + +with ToolCollection.from_mcp( + server_parameters, trust_remote_code=True +) as tool_collection: + agent = CodeAgent(tools=[*tool_collection.tools], model=model) + agent.run("מה מזג האוויר בטוקיו?") + +``` + +
+ +פלט + + +```sh +מזג האוויר בטוקיו הוא שמשי עם טמפרטורה של 20 מעלות צלזיוס. +``` + +
+ +אנחנו יכולים גם להתחבר לחבילת MCP. הנה דוגמה להתחברות לחבילה `pubmedmcp`. + +```python +import os +from smolagents import ToolCollection, CodeAgent +from mcp import StdioServerParameters + +server_parameters = StdioServerParameters( + command="uv", + args=["--quiet", "pubmedmcp@0.1.3"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tool_collection: + agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True) + agent.run("אנא מצא תרופה להנגאובר.") +``` + +
+ +פלט + + +```sh +התרופה להנגאובר היא לשתות מים. +``` + +
+ +## צעדים הבאים + +עכשיו שאתם מבינים את לקוחות ה-MCP, אתם מוכנים ל: +* לחקור יישומי שרת MCP ספציפיים +* ללמוד על יצירת לקוחות MCP מותאמים אישית +* לצלול לתוך דפוסי אינטגרציה מתקדמים של MCP + +בואו נמשיך את המסע שלנו לעולם של פרוטוקול הקשר המודל! diff --git a/units/he/unit1/quiz1.mdx b/units/he/unit1/quiz1.mdx new file mode 100644 index 0000000..23842f2 --- /dev/null +++ b/units/he/unit1/quiz1.mdx @@ -0,0 +1,125 @@ +# חידון 1: יסודות MCP + +בחן את הידע שלך במושגי הליבה של פרוטוקול הקשר המודל. + +### ש1: מהי המטרה העיקרית של פרוטוקול הקשר המודל (MCP)? + + + +### ש2: איזו בעיה MCP מטרתו לפתור בעיקר? + + + +### ש3: איזה מהבאים הוא יתרון מרכזי של MCP? + + + +### ש4: בטרמינולוגיה של MCP, מהו "מארח"? + + + +### ש5: למה מתייחס "בעיית האינטגרציה M×N" בהקשר של יישומי בינה מלאכותית? + + + +כל הכבוד על סיום החידון הזה 🥳! אם אתה צריך לסקור רכיבים כלשהם, קח את הזמן לבקר מחדש בפרק כדי לחזק את הידע שלך. diff --git a/units/he/unit1/quiz2.mdx b/units/he/unit1/quiz2.mdx new file mode 100644 index 0000000..087db7c --- /dev/null +++ b/units/he/unit1/quiz2.mdx @@ -0,0 +1,125 @@ +# חידון 2: SDK של MCP + +בחן את הידע שלך ב-SDK של MCP ובפונקציונליות שלהם. + +### ש1: מהי המטרה העיקרית של ה-SDK של MCP? + + + +### ש2: איזו מהפונקציונליות הבאות ה-SDK של MCP בדרך כלל מטפלים בה? + + + +### ש3: לפי הטקסט שסופק, איזו חברה מתחזקת את ה-SDK הרשמי של פייתון ל-MCP? + + + +### ש4: באיזו פקודה משתמשים כדי להתחיל שרת פיתוח MCP באמצעות קובץ פייתון בשם `server.py`? + + + +### ש5: מהו תפקידו של JSON-RPC 2.0 ב-MCP? + + + +כל הכבוד על סיום החידון הזה 🥳! אם אתה צריך לסקור רכיבים כלשהם, קח את הזמן לבקר מחדש בפרק כדי לחזק את הידע שלך. diff --git a/units/he/unit1/sdk.mdx b/units/he/unit1/sdk.mdx new file mode 100644 index 0000000..8fb6b95 --- /dev/null +++ b/units/he/unit1/sdk.mdx @@ -0,0 +1,169 @@ +# SDK של MCP + +פרוטוקול הקשר המודל מספק SDK רשמיים הן לג'אווהסקריפט, פייתון ושפות אחרות. זה מקל על יישום לקוחות ושרתי MCP ביישומים שלך. SDK אלה מטפלים בפרטי פרוטוקול ברמה נמוכה, מאפשרים לך להתמקד בבניית היכולות של היישום שלך. + +## סקירת SDK + +שני ה-SDK מספקים פונקציונליות ליבה דומה, בהתאם למפרט פרוטוקול ה-MCP שדנו בו קודם. הם מטפלים ב: + +- תקשורת ברמת הפרוטוקול +- רישום וגילוי יכולות +- סריאליזציה/דה-סריאליזציה של הודעות +- ניהול חיבורים +- טיפול בשגיאות + +## יישום הפרימיטיבים הבסיסיים + +בואו נחקור כיצד ליישם כל אחד מהפרימיטיבים הבסיסיים (כלים, משאבים והנחיות) באמצעות שני ה-SDK. + + + + + + +```python +from mcp.server.fastmcp import FastMCP + +# יצירת שרת MCP +mcp = FastMCP("שירות מזג אוויר") + + +@mcp.tool() +def get_weather(location: str) -> str: + """קבל את מזג האוויר הנוכחי למיקום מסוים.""" + return f"מזג האוויר ב-{location}: שמשי, 22°C" + + +@mcp.resource("weather://{location}") +def weather_resource(location: str) -> str: + """ספק נתוני מזג אוויר כמשאב.""" + return f"נתוני מזג אוויר עבור {location}: שמשי, 22°C" + + +@mcp.prompt() +def weather_report(location: str) -> str: + """צור הנחיית דיווח מזג אוויר.""" + return f"""אתה מדווח מזג אוויר. דוח מזג אוויר עבור {location}?""" + + +# הרץ את השרת +if __name__ == "__main__": + mcp.run() + +``` + + + + +```javascript +import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { z } from "zod"; + +// יצירת שרת MCP +const server = new McpServer({ + name: "שירות מזג אוויר", + version: "1.0.0" +}); + +// יישום כלי +server.tool("get_weather", + { location: z.string() }, + async ({ location }) => ({ + content: [{ + type: "text", + text: `מזג האוויר ב-${location}: שמשי, 22°C` + }] + }) +); + +// יישום משאב +server.resource( + "weather", + new ResourceTemplate("weather://{location}", { list: undefined }), + async (uri, { location }) => ({ + contents: [{ + uri: uri.href, + text: `נתוני מזג אוויר עבור ${location}: שמשי, 22°C` + }] + }) +); + +// יישום הנחיה +server.prompt( + "weather_report", + { location: z.string() }, + async ({ location }) => ({ + messages: [ + { + role: "assistant", + content: { + type: "text", + text: "אתה מדווח מזג אוויר." + } + }, + { + role: "user", + content: { + type: "text", + text: `דוח מזג אוויר עבור ${location}?` + } + } + ] + }) +); + +// הרץ את השרת +const transport = new StdioServerTransport(); +await server.connect(transport); +``` + + + + +לאחר שיש לך את השרת מיושם, אתה יכול להתחיל אותו על ידי הרצת סקריפט השרת. + +```bash +mcp dev server.py +``` + +זה יאתחל שרת פיתוח המריץ את הקובץ `server.py`. ויתעד את הפלט הבא: + +```bash +מתחיל את MCP inspector... +⚙️ שרת proxy מאזין בפורט 6277 +הפעיל תעבורת stdio +חיבר לקוח MCP לתעבורת שרת גיבוי +יצר תעבורת אפליקציית web +הגדיר proxy MCP +🔍 MCP Inspector פועל וזמין בכתובת http://127.0.0.1:6274 🚀 +``` + +אתה יכול אז לפתוח את MCP Inspector בכתובת [http://127.0.0.1:6274](http://127.0.0.1:6274) כדי לראות את היכולות של השרת ולתקשר איתן. + +תראה את היכולות של השרת ואת היכולת לקרוא להן דרך הממשק. + +![MCP Inspector](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/6.png) + +## SDK של MCP + +MCP מתוכנן להיות אגנוסטי לשפה, וישנם SDK רשמיים זמינים למספר שפות תכנות פופולריות: + +| שפה | מאגר | מתחזק(ים) | סטטוס | +|----------|------------|---------------|--------| +| TypeScript | [github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) | Anthropic | פעיל | +| Python | [github.com/modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) | Anthropic | פעיל | +| Java | [github.com/modelcontextprotocol/java-sdk](https://github.com/modelcontextprotocol/java-sdk) | Spring AI (VMware) | פעיל | +| Kotlin | [github.com/modelcontextprotocol/kotlin-sdk](https://github.com/modelcontextprotocol/kotlin-sdk) | JetBrains | פעיל | +| C# | [github.com/modelcontextprotocol/csharp-sdk](https://github.com/modelcontextprotocol/csharp-sdk) | Microsoft | פעיל (תצוגה מקדימה) | +| Swift | [github.com/modelcontextprotocol/swift-sdk](https://github.com/modelcontextprotocol/swift-sdk) | loopwork-ai | פעיל | +| Rust | [github.com/modelcontextprotocol/rust-sdk](https://github.com/modelcontextprotocol/rust-sdk) | Anthropic/קהילה | פעיל | +| Dart | [https://github.com/leehack/mcp_dart](https://github.com/leehack/mcp_dart) | קהילת Flutter | פעיל | + +SDK אלה מספקים הפשטות ספציפיות לשפה המפשטות את העבודה עם פרוטוקול ה-MCP, מאפשרים לך להתמקד ביישום הלוגיקה המרכזית של השרתים או הלקוחות שלך במקום להתמודד עם פרטי פרוטוקול ברמה נמוכה. + +## הצעדים הבאים + +רק שרטנו את פני השטח של מה שאתה יכול לעשות עם ה-MCP אבל כבר יש לך שרת בסיסי פועל. למעשה, התחברת אליו גם באמצעות לקוח ה-MCP בדפדפן. + +בסעיף הבא, נראה כיצד להתחבר לשרת שלך מ-LLM. diff --git a/units/he/unit2/clients.mdx b/units/he/unit2/clients.mdx new file mode 100644 index 0000000..4558b26 --- /dev/null +++ b/units/he/unit2/clients.mdx @@ -0,0 +1,79 @@ +# בניית לקוחות MCP + +בסעיף זה, ניצור לקוחות שיכולים לתקשר עם שרת ה-MCP שלנו באמצעות שפות תכנות שונות. נממש גם לקוח JavaScript באמצעות HuggingFace.js וגם לקוח Python באמצעות smolagents. + +## הגדרת לקוחות MCP + +פריסה יעילה של שרתי ולקוחות MCP דורשת הגדרה נכונה. מפרט ה-MCP עדיין מתפתח, כך ששיטות ההגדרה כפופות לאבולוציה. נתמקד בשיטות העבודה המומלצות הנוכחיות להגדרה. + +### קבצי הגדרה של MCP + +מארחי MCP משתמשים בקבצי הגדרה לניהול חיבורי שרת. קבצים אלה מגדירים אילו שרתים זמינים וכיצד להתחבר אליהם. + +קבצי ההגדרה הם מאוד פשוטים, קלים להבנה, ועקביים בין מארחי MCP עיקריים. + +#### מבנה `mcp.json` + +קובץ ההגדרה הסטנדרטי ל-MCP נקרא `mcp.json`. הנה המבנה הבסיסי: + +```json +{ + "servers": [ + { + "name": "שרת MCP", + "transport": { + "type": "sse", + "url": "http://localhost:7860/gradio_api/mcp/sse" + } + } + ] +} +``` + +בדוגמה זו, יש לנו שרת יחיד מוגדר להשתמש בתעבורת SSE, המתחבר לשרת Gradio מקומי הפועל בפורט 7860. + + + +התחברנו לאפליקציית Gradio דרך תעבורת SSE כי אנחנו מניחים שהאפליקציה פועלת בשרת מרוחק. עם זאת, אם אתה רוצה להתחבר לסקריפט מקומי, תעבורת `stdio` במקום תעבורת `sse` היא אפשרות טובה יותר. + + + +#### הגדרה עבור תעבורת HTTP+SSE + +עבור שרתים מרוחקים המשתמשים בתעבורת HTTP+SSE, ההגדרה כוללת את כתובת ה-URL של השרת: + +```json +{ + "servers": [ + { + "name": "שרת MCP מרוחק", + "transport": { + "type": "sse", + "url": "https://example.com/gradio_api/mcp/sse" + } + } + ] +} +``` + +הגדרה זו מאפשרת ללקוח ממשק המשתמש שלך לתקשר עם שרת ה-MCP של Gradio באמצעות פרוטוקול MCP, ומאפשרת אינטגרציה חלקה בין ה-frontend שלך לבין שירות ה-MCP. + +## הגדרת לקוח MCP לממשק משתמש + +כאשר עובדים עם שרתי MCP של Gradio, אתה יכול להגדיר את לקוח ממשק המשתמש שלך להתחבר לשרת באמצעות פרוטוקול ה-MCP. הנה איך להגדיר זאת: + +### הגדרה בסיסית + +צור קובץ חדש בשם `config.json` עם ההגדרה הבאה: + +```json +{ + "mcpServers": { + "mcp": { + "url": "http://localhost:7860/gradio_api/mcp/sse" + } + } +} +``` + +הגדרה זו מאפשרת ללקוח ממשק המשתמש שלך לתקשר עם שרת ה-MCP של Gradio באמצעות פרוטוקול ה-MCP, ומאפשרת אינטגרציה חלקה בין ה-frontend שלך לבין שירות ה-MCP. diff --git a/units/he/unit2/gradio-client.mdx b/units/he/unit2/gradio-client.mdx new file mode 100644 index 0000000..33feb4c --- /dev/null +++ b/units/he/unit2/gradio-client.mdx @@ -0,0 +1,139 @@ +# Gradio כלקוח MCP + +בסעיף הקודם, חקרנו כיצד ליצור שרת MCP באמצעות Gradio ולהתחבר אליו באמצעות לקוח MCP. בסעיף זה, נחקור כיצד להשתמש ב-Gradio כלקוח MCP כדי להתחבר לשרת MCP. + + + +Gradio מתאים בצורה הטובה ביותר ליצירת לקוחות UI ושרתי MCP, אך ניתן גם להשתמש בו כלקוח MCP ולחשוף זאת כממשק משתמש. + + + +נתחבר לשרת ה-MCP שיצרנו בסעיף הקודם ונשתמש בו כדי לענות על שאלות. + +## לקוח MCP ב-Gradio + +ראשית, עלינו להתקין את הספריות `smolagents`, gradio ו-mcp-client, אם עדיין לא עשינו זאת: + +```bash +pip install "smolagents[mcp]" "gradio[mcp]" mcp +``` + +כעת, נוכל לייבא את הספריות הנדרשות וליצור ממשק Gradio פשוט המשתמש בלקוח MCP כדי להתחבר לשרת ה-MCP. + + +```python +import gradio as gr + +from mcp.client.stdio import StdioServerParameters +from smolagents import InferenceClientModel, CodeAgent, ToolCollection +from smolagents.mcp_client import MCPClient +``` + +לאחר מכן, נתחבר לשרת ה-MCP ונקבל את הכלים שנוכל להשתמש בהם כדי לענות על שאלות. + +```python +mcp_client = MCPClient( + {"url": "http://localhost:7860/gradio_api/mcp/sse"} +) +tools = mcp_client.get_tools() +``` + +עכשיו שיש לנו את הכלים, נוכל ליצור סוכן פשוט המשתמש בהם כדי לענות על שאלות. לעת עתה, נשתמש ב-`InferenceClientModel` פשוט ובמודל ברירת המחדל מ-`smolagents`. + +```python +model = InferenceClientModel() +agent = CodeAgent(tools=[*tools], model=model) +``` + +כעת, נוכל ליצור ממשק Gradio פשוט המשתמש בסוכן כדי לענות על שאלות. + +```python +demo = gr.ChatInterface( + fn=lambda message, history: str(agent.run(message)), + type="messages", + examples=["פירוק לגורמים ראשוניים של 68"], + title="סוכן עם כלי MCP", + description="זהו סוכן פשוט המשתמש בכלי MCP כדי לענות על שאלות.", + messages=[], +) + +demo.launch() +``` + +וזהו! יצרנו ממשק Gradio פשוט המשתמש בלקוח MCP כדי להתחבר לשרת ה-MCP ולענות על שאלות. + + + + +## דוגמה מלאה + +הנה הדוגמה המלאה של לקוח ה-MCP ב-Gradio: + +```python +import gradio as gr + +from mcp.client.stdio import StdioServerParameters +from smolagents import InferenceClientModel, CodeAgent, ToolCollection +from smolagents.mcp_client import MCPClient + + +try: + mcp_client = MCPClient( + ## נסה דוגמה פעילה זו ב-hub: + # {"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) + + demo = gr.ChatInterface( + fn=lambda message, history: str(agent.run(message)), + type="messages", + examples=["פירוק לגורמים ראשוניים של 68"], + title="סוכן עם כלי MCP", + description="זהו סוכן פשוט המשתמש בכלי MCP כדי לענות על שאלות.", + ) + + demo.launch() +finally: + mcp_client.disconnect() +``` + +תשים לב שאנחנו סוגרים את לקוח ה-MCP בבלוק `finally`. זה חשוב כי לקוח ה-MCP הוא אובייקט ארוך חיים שצריך להיסגר כאשר התוכנית יוצאת. + +## פריסה ל-Hugging Face Spaces + +כדי להפוך את השרת שלך זמין לאחרים, אתה יכול לפרוס אותו ל-Hugging Face Spaces, בדיוק כפי שעשינו בסעיף הקודם. +כדי לפרוס את לקוח ה-MCP של Gradio ל-Hugging Face Spaces: + +1. צור Space חדש ב-Hugging Face: + - לך ל-huggingface.co/spaces + - לחץ על "Create new Space" + - בחר "Gradio" כ-SDK + - תן שם ל-space שלך (לדוגמה, "mcp-client") + +2. צור קובץ `requirements.txt`: +```txt +gradio[mcp] +smolagents[mcp] +``` + +3. דחוף את הקוד שלך ל-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 +``` + +## סיכום + +בסעיף זה, חקרנו כיצד להשתמש ב-Gradio כלקוח MCP כדי להתחבר לשרת MCP. ראינו גם כיצד לפרוס את לקוח ה-MCP ב-Hugging Face Spaces. diff --git a/units/he/unit2/gradio-server.mdx b/units/he/unit2/gradio-server.mdx new file mode 100644 index 0000000..5794806 --- /dev/null +++ b/units/he/unit2/gradio-server.mdx @@ -0,0 +1,190 @@ +# בניית שרת MCP של Gradio + +בסעיף זה, ניצור את שרת ה-MCP לניתוח רגשות שלנו באמצעות Gradio. שרת זה יחשוף כלי לניתוח רגשות שיכול לשמש הן משתמשים אנושיים דרך ממשק אינטרנט והן מודלי בינה מלאכותית דרך פרוטוקול ה-MCP. + +## מבוא לאינטגרציית MCP של Gradio + +Gradio מספק דרך פשוטה ליצירת שרתי MCP על ידי המרה אוטומטית של פונקציות Python שלך לכלי MCP. כאשר אתה מגדיר `mcp_server=True` ב-`launch()`, Gradio: + +1. ממיר אוטומטית את הפונקציות שלך לכלי MCP +2. ממפה רכיבי קלט לסכימות ארגומנטים של הכלי +3. קובע פורמטים של תגובות מרכיבי פלט +4. מגדיר JSON-RPC מעל HTTP+SSE לתקשורת לקוח-שרת +5. יוצר גם ממשק אינטרנט וגם נקודת קצה של שרת MCP + +## הגדרת הפרויקט + +ראשית, בואו ניצור ספרייה חדשה לפרויקט שלנו ונגדיר את התלויות הנדרשות: + +```bash +mkdir mcp-sentiment +cd mcp-sentiment +python -m venv venv +source venv/bin/activate # בווינדוס: venv\Scripts\activate +pip install "gradio[mcp]" textblob +``` + +## יצירת השרת + +> Hugging face spaces צריך קובץ app.py כדי לבנות את המרחב. אז שם קובץ ה-python חייב להיות app.py + +צור קובץ חדש בשם `app.py` עם הקוד הבא: + +```python +import gradio as gr +from textblob import TextBlob + +def sentiment_analysis(text: str) -> dict: + """ + נתח את הרגש של הטקסט הנתון. + + Args: + text (str): הטקסט לניתוח + + Returns: + dict: מילון המכיל קוטביות, סובייקטיביות והערכה + """ + blob = TextBlob(text) + sentiment = blob.sentiment + + return { + "polarity": round(sentiment.polarity, 2), # -1 (שלילי) עד 1 (חיובי) + "subjectivity": round(sentiment.subjectivity, 2), # 0 (אובייקטיבי) עד 1 (סובייקטיבי) + "assessment": "positive" if sentiment.polarity > 0 else "negative" if sentiment.polarity < 0 else "neutral" + } + +# יצירת ממשק Gradio +demo = gr.Interface( + fn=sentiment_analysis, + inputs=gr.Textbox(placeholder="הזן טקסט לניתוח..."), + outputs=gr.JSON(), + title="ניתוח רגשות טקסט", + description="ניתוח הרגש של טקסט באמצעות TextBlob" +) + +# הפעלת הממשק ושרת ה-MCP +if __name__ == "__main__": + demo.launch(mcp_server=True) +``` + +## הבנת הקוד + +בואו נפרק את הרכיבים העיקריים: + +1. **הגדרת פונקציה**: + - הפונקציה `sentiment_analysis` מקבלת קלט טקסט ומחזירה מילון + - היא משתמשת ב-TextBlob לניתוח הרגש + - ה-docstring הוא קריטי כי הוא עוזר ל-Gradio לייצר את סכימת כלי ה-MCP + - רמזי טיפוס (`str` ו-`dict`) עוזרים להגדיר את סכימת הקלט/פלט + +2. **ממשק Gradio**: + - `gr.Interface` יוצר גם את ממשק המשתמש וגם את שרת ה-MCP + - הפונקציה חשופה כלי MCP באופן אוטומטי + - רכיבי קלט ופלט מגדירים את הסכימה של הכלי + - רכיב הפלט JSON מבטיח סריאליזציה נכונה + +3. **שרת MCP**: + - הגדרת `mcp_server=True` מפעילה את שרת ה-MCP + - השרת יהיה זמין בכתובת `http://localhost:7860/gradio_api/mcp/sse` + - אתה יכול גם להפעיל אותו באמצעות משתנה סביבה: + ```bash + export GRADIO_MCP_SERVER=True + ``` + +## הפעלת השרת + +התחל את השרת על ידי הרצת: + +```bash +python app.py +``` + +אתה אמור לראות פלט המציין שגם ממשק האינטרנט וגם שרת ה-MCP פועלים. ממשק האינטרנט יהיה זמין בכתובת `http://localhost:7860`, ושרת ה-MCP בכתובת `http://localhost:7860/gradio_api/mcp/sse`. + +## בדיקת השרת + +אתה יכול לבדוק את השרת בשתי דרכים: + +1. **ממשק אינטרנט**: + - פתח את `http://localhost:7860` בדפדפן שלך + - הזן טקסט כלשהו ולחץ על "Submit" + - אתה אמור לראות את תוצאות ניתוח הרגש + +2. **סכימת MCP**: + - בקר בכתובת `http://localhost:7860/gradio_api/mcp/schema` + - זה מציג את סכימת כלי ה-MCP שבה ישתמשו לקוחות + - אתה יכול גם למצוא זאת בקישור "View API" בתחתית יישום ה-Gradio שלך + +## טיפים לפתרון בעיות + +1. **רמזי טיפוס ו-Docstrings**: + - תמיד ספק רמזי טיפוס לפרמטרים וערכי החזרה של הפונקציה שלך + - כלול docstring עם בלוק "Args:" עבור כל פרמטר + - זה עוזר ל-Gradio לייצר סכימות כלי MCP מדויקות + +2. **קלטי מחרוזת**: + - כאשר יש ספק, קבל ארגומנטי קלט כ-`str` + - המר אותם לסוג הרצוי בתוך הפונקציה + - זה מספק תאימות טובה יותר עם לקוחות MCP + +3. **תמיכת SSE**: + - חלק מלקוחות MCP אינם תומכים בשרתי MCP מבוססי SSE + - במקרים אלה, השתמש ב-`mcp-remote`: + ```json + { + "mcpServers": { + "gradio": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:7860/gradio_api/mcp/sse" + ] + } + } + } + ``` + +4. **בעיות חיבור**: + - אם אתה נתקל בבעיות חיבור, נסה להפעיל מחדש גם את הלקוח וגם את השרת + - בדוק שהשרת פועל ונגיש + - ודא שסכימת ה-MCP זמינה בכתובת ה-URL הצפויה + +## פריסה ל-Hugging Face Spaces + +כדי להפוך את השרת שלך זמין לאחרים, אתה יכול לפרוס אותו ל-Hugging Face Spaces: + +1. צור Space חדש ב-Hugging Face: + - לך ל-huggingface.co/spaces + - לחץ על "Create new Space" + - בחר "Gradio" כ-SDK + - תן שם ל-space שלך (לדוגמה, "mcp-sentiment") + +2. צור קובץ `requirements.txt`: +```txt +gradio[mcp] +textblob +``` + +3. דחוף את הקוד שלך ל-Space: +```bash +git init +git add app.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 +``` + +שרת ה-MCP שלך יהיה כעת זמין בכתובת: +``` +https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse +``` + +## הצעדים הבאים + +עכשיו שיש לנו את שרת ה-MCP פועל, ניצור לקוחות כדי לתקשר איתו. בסעיפים הבאים, אנחנו: + +1. ניצור לקוח מבוסס HuggingFace.js בהשראת Tiny Agents +2. נממש לקוח Python מבוסס SmolAgents +3. נבדוק את שני הלקוחות עם השרת שפרסנו + +בואו נמשיך לבניית הלקוח הראשון שלנו! diff --git a/units/he/unit2/introduction.mdx b/units/he/unit2/introduction.mdx new file mode 100644 index 0000000..47efef5 --- /dev/null +++ b/units/he/unit2/introduction.mdx @@ -0,0 +1,64 @@ +# בניית יישום MCP מקצה לקצה + +ברוכים הבאים ליחידה 2 של קורס ה-MCP! + +ביחידה זו, נבנה יישום MCP שלם מאפס, תוך התמקדות ביצירת שרת עם Gradio וחיבורו עם לקוחות מרובים. גישה מעשית זו תעניק לך ניסיון מעשי עם כל המערכת האקולוגית של MCP. + + + +ביחידה זו, נבנה שרת וקליינט MCP פשוטים באמצעות Gradio ו-HuggingFace hub. ביחידה הבאה, נבנה שרת מורכב יותר שמתמודד עם מקרה שימוש מהעולם האמיתי. + + + +## מה תלמד + +ביחידה זו, אתה: + +- תיצור שרת MCP באמצעות תמיכת ה-MCP המובנית של Gradio +- תבנה כלי לניתוח רגשות שיכול לשמש מודלי בינה מלאכותית +- תתחבר לשרת באמצעות יישומי לקוח שונים: + - לקוח מבוסס HuggingFace.js + - לקוח מבוסס SmolAgents עבור Python +- תפרוס את שרת ה-MCP שלך ל-Hugging Face Spaces +- תבדוק ותנפה שגיאות במערכת השלמה + +בסוף יחידה זו, יהיה לך יישום MCP עובד המדגים את העוצמה והגמישות של הפרוטוקול. + +## דרישות מוקדמות + +לפני שתמשיך עם יחידה זו, ודא כי: + +- השלמת את יחידה 1 או שיש לך הבנה בסיסית של מושגי MCP +- אתה נוח עם Python וגם עם JavaScript/TypeScript +- יש לך הבנה בסיסית של API וארכיטקטורת לקוח-שרת +- יש לך סביבת פיתוח עם: + - Python 3.10+ + - Node.js 18+ + - חשבון Hugging Face (לצורך פריסה) + +## הפרויקט מקצה לקצה שלנו + +נבנה יישום ניתוח רגשות המורכב משלושה חלקים עיקריים: השרת, הלקוח והפריסה. + +![יישום ניתוח רגשות](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit2/1.png) + +### צד השרת + +- משתמש ב-Gradio ליצירת ממשק אינטרנט ושרת MCP באמצעות `gr.Interface` +- מיישם כלי ניתוח רגשות באמצעות TextBlob +- חושף את הכלי דרך פרוטוקולי HTTP ו-MCP + +### צד הלקוח + +- מיישם לקוח HuggingFace.js +- או, יוצר לקוח Python של smolagents +- מדגים כיצד להשתמש באותו שרת עם יישומי לקוח שונים + +### פריסה + +- פורס את השרת ל-Hugging Face Spaces +- מגדיר את הלקוחות לעבוד עם השרת הפרוס + +## בואו נתחיל! + +האם אתה מוכן לבנות את יישום ה-MCP הראשון שלך מקצה לקצה? בואו נתחיל בהגדרת סביבת הפיתוח ויצירת שרת ה-MCP של Gradio. diff --git a/units/he/unit2/tiny-agents.mdx b/units/he/unit2/tiny-agents.mdx new file mode 100644 index 0000000..62a8202 --- /dev/null +++ b/units/he/unit2/tiny-agents.mdx @@ -0,0 +1,556 @@ +# סוכנים זעירים: סוכן מופעל-MCP ב-50 שורות קוד + +עכשיו שבנינו שרתי MCP ב-Gradio ולמדנו על יצירת לקוחות MCP, בואו נשלים את היישום שלנו מקצה לקצה על ידי בניית סוכן TypeScript שיכול לתקשר בקלות עם כלי ניתוח הרגשות שלנו. סעיף זה מבוסס על הפרויקט [Tiny Agents](https://huggingface.co/blog/tiny-agents), המדגים דרך פשוטה במיוחד לפריסת לקוחות MCP שיכולים להתחבר לשירותים כמו שרת ניתוח הרגשות של Gradio שבנינו. + +בתרגיל האחרון הזה של יחידה 2, נדריך אותך כיצד ליישם לקוח MCP של TypeScript (JS) שיכול לתקשר עם כל שרת MCP, כולל שרת ניתוח הרגשות מבוסס-Gradio שבנינו בסעיפים הקודמים. זה משלים את זרימת היישום MCP מקצה לקצה שלנו: מבניית שרת MCP של Gradio החושף כלי ניתוח רגשות, ועד ליצירת סוכן גמיש שיכול להשתמש בכלי זה לצד יכולות אחרות. + +![מים](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/thumbnail.jpg) +
קרדיט לתמונה https://x.com/adamdotdev
+ +## התקנה + +ראשית, עלינו להתקין את החבילה `tiny-agents`. + +```bash +npm install @huggingface/tiny-agents +# או +pnpm add @huggingface/tiny-agents +``` + +לאחר מכן, עלינו להתקין את החבילה `mcp-remote`. + +```bash +npm install @mcpjs/mcp-remote +# או +pnpm add @mcpjs/mcp-remote +``` + +## לקוח MCP של Tiny Agents בשורת הפקודה + +Tiny Agents יכול ליצור לקוחות MCP משורת הפקודה על בסיס קבצי תצורה JSON. + +בואו נגדיר פרויקט עם סוכן זעיר בסיסי. + +```bash +mkdir my-agent +touch my-agent/agent.json +``` + +קובץ ה-JSON ייראה כך: + +```json +{ + "model": "Qwen/Qwen2.5-72B-Instruct", + "provider": "nebius", + "servers": [ + { + "type": "stdio", + "config": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:7860/gradio_api/mcp/sse" + ] + } + } + ] +} +``` + +כאן יש לנו סוכן זעיר בסיסי שיכול להתחבר לשרת ה-MCP של Gradio שלנו. הוא כולל מודל, ספק, ותצורת שרת. + +| שדה | תיאור | +|-------|-------------| +| `model` | המודל בקוד פתוח לשימוש עבור הסוכן | +| `provider` | ספק ההיסק לשימוש עבור הסוכן | +| `servers` | השרתים לשימוש עבור הסוכן. נשתמש בשרת `mcp-remote` עבור שרת ה-MCP של Gradio שלנו. | + +אנחנו יכולים גם להשתמש במודל קוד פתוח שרץ מקומית עם Tiny Agents. + +```json +{ + "model": "Qwen/Qwen3-32B", + "endpointUrl": "http://localhost:1234/v1", + "servers": [ + { + "type": "stdio", + "config": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:1234/v1/mcp/sse" + ] + } + } + ] +} +``` + +כאן יש לנו סוכן זעיר שיכול להתחבר למודל מקומי. הוא כולל מודל, כתובת נקודת קצה (`http://localhost:1234/v1`), ותצורת שרת. נקודת הקצה צריכה להיות נקודת קצה תואמת OpenAI. + +אנחנו יכולים אז להפעיל את הסוכן עם הפקודה הבאה: + +```bash +npx @huggingface/tiny-agents run ./my-agent +``` + +## לקוח MCP של Tiny Agents מותאם אישית + +עכשיו שאנחנו מבינים גם את Tiny Agents וגם את שרתי MCP של Gradio, בואו נראה איך הם עובדים יחד! היופי של MCP הוא שהוא מספק דרך סטנדרטית לסוכנים לתקשר עם כל שרת תואם-MCP, כולל שרת ניתוח הרגשות מבוסס-Gradio שלנו מהסעיפים הקודמים. + +### שימוש בשרת Gradio עם Tiny Agents + +כדי לחבר את הסוכן הזעיר שלנו לשרת ניתוח הרגשות של Gradio שבנינו קודם ביחידה זו, אנחנו רק צריכים להוסיף אותו לרשימת השרתים שלנו. הנה איך אנחנו יכולים לשנות את תצורת הסוכן שלנו: + +```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: [ + // ... שרתים קיימים ... + { + command: "npx", + args: [ + "mcp-remote", + "http://localhost:7860/gradio_api/mcp/sse" // שרת ה-MCP של Gradio שלך + ] + } + ], +}); +``` + +עכשיו הסוכן שלנו יכול להשתמש בכלי ניתוח הרגשות לצד כלים אחרים! לדוגמה, הוא יכול: +1. לקרוא טקסט מקובץ באמצעות שרת מערכת הקבצים +2. לנתח את הרגש שלו באמצעות שרת ה-Gradio שלנו +3. לכתוב את התוצאות בחזרה לקובץ + +### דוגמת אינטראקציה + +הנה איך שיחה עם הסוכן שלנו עשויה להיראות: + +``` +משתמש: קרא את הקובץ "feedback.txt" משולחן העבודה שלי ונתח את הרגש שלו + +סוכן: אעזור לך לנתח את הרגש של קובץ המשוב. בואו נפרק זאת לשלבים: + +1. ראשית, אקרא את הקובץ באמצעות כלי מערכת הקבצים +2. לאחר מכן, אנתח את הרגש שלו באמצעות כלי ניתוח הרגשות +3. לבסוף, אכתוב את התוצאות לקובץ חדש + +[הסוכן ממשיך להשתמש בכלים ולספק את הניתוח] +``` + +### שיקולי פריסה + +כאשר אתה פורס את שרת ה-MCP של Gradio ל-Hugging Face Spaces, תצטרך לעדכן את כתובת ה-URL של השרת בתצורת הסוכן שלך כדי שתצביע לחלל המפורס שלך: + +```ts +{ + command: "npx", + args: [ + "mcp-remote", + "https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse" + ] +} +``` + +זה מאפשר לסוכן שלך להשתמש בכלי ניתוח הרגשות מכל מקום, לא רק מקומית! + +## סיכום: היישום השלם מקצה לקצה של MCP שלנו + +ביחידה זו, עברנו מהבנת יסודות ה-MCP לבניית יישום שלם מקצה לקצה: + +1. יצרנו שרת MCP של Gradio שחושף כלי ניתוח רגשות +2. למדנו כיצד להתחבר לשרת זה באמצעות לקוחות MCP +3. בנינו סוכן זעיר ב-TypeScript שיכול לתקשר עם הכלי שלנו + +זה מדגים את הכוח של פרוטוקול הקשר המודל - אנחנו יכולים ליצור כלים מתמחים באמצעות מסגרות שאנחנו מכירים (כמו Gradio), לחשוף אותם דרך ממשק סטנדרטי (MCP), ואז לגרום לסוכנים להשתמש בכלים אלה בצורה חלקה לצד יכולות אחרות. + +הזרימה השלמה שבנינו מאפשרת לסוכן: +- להתחבר למספר ספקי כלים +- לגלות באופן דינמי כלים זמינים +- להשתמש בכלי ניתוח הרגשות המותאם אישית שלנו +- לשלב אותו עם יכולות אחרות כמו גישה למערכת קבצים וגלישה באינטרנט + +גישה מודולרית זו היא מה שהופך את MCP לכל כך עוצמתי לבניית יישומי בינה מלאכותית גמישים. + +## בונוס: בניית שרת MCP לאוטומציית דפדפן עם Playwright + +כבונוס, בואו נחקור כיצד להשתמש בשרת MCP של Playwright לאוטומציית דפדפן עם Tiny Agents. זה מדגים את יכולת ההרחבה של המערכת האקולוגית של MCP מעבר לדוגמת ניתוח הרגשות שלנו. + + + +סעיף זה מבוסס על [פוסט הבלוג של Tiny Agents](https://huggingface.co/blog/tiny-agents) ומותאם לקורס MCP. + + + +בסעיף זה, נראה לך כיצד לבנות סוכן שיכול לבצע משימות אוטומציית אינטרנט כמו חיפוש, לחיצה, ומיצוי מידע מאתרי אינטרנט. + +```ts +// playwright-agent.ts +import { Agent } from "@huggingface/tiny-agents"; + +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: [ + { + command: "npx", + args: ["playwright-mcp"] + } + ], +}); + +await agent.run(); +``` + +שרת ה-MCP של Playwright חושף כלים המאפשרים לסוכן שלך: + +1. לפתוח כרטיסיות דפדפן +2. לנווט ל-URL +3. ללחוץ על אלמנטים +4. להקליד בטפסים +5. למצות תוכן מדפי אינטרנט +6. לצלם צילומי מסך + +הנה דוגמת אינטראקציה עם סוכן אוטומציית הדפדפן שלנו: + +``` +משתמש: חפש "tiny agents" ב-GitHub ואסוף את השמות של 3 המאגרים המובילים + +סוכן: אחפש ב-GitHub מאגרים של "tiny agents". +[הסוכן פותח דפדפן, מנווט ל-GitHub, מבצע את החיפוש, ומחלץ שמות מאגרים] + +הנה 3 המאגרים המובילים (לא אמיתיים) עבור "tiny agents": +1. huggingface/tiny-agents +2. modelcontextprotocol/tiny-agents-examples +3. langchain/tiny-agents-js +``` + +יכולת אוטומציית דפדפן זו יכולה להשתלב עם שרתי MCP אחרים ליצירת זרימות עבודה עוצמתיות—לדוגמה, חילוץ טקסט מדף אינטרנט ואז ניתוחו עם כלים מותאמים אישית. + +## איך להריץ את ההדגמה המלאה + +אם יש לך NodeJS (עם `pnpm` או `npm`), פשוט הפעל זאת בטרמינל: + +```bash +npx @huggingface/mcp-client +``` + +או אם משתמשים ב-`pnpm`: + +```bash +pnpx @huggingface/mcp-client +``` + +זה מתקין את החבילה לתיקייה זמנית ואז מפעיל את הפקודה שלה. + +תראה את הסוכן הפשוט שלך מתחבר למספר שרתי MCP (הרצים מקומית), טוען את הכלים שלהם (בדומה לאיך שהוא יטען את כלי ניתוח הרגשות של Gradio שלך), ואז מבקש ממך שיחה. + + + +כברירת מחדל הסוכן שלנו בדוגמה מתחבר לשני שרתי MCP הבאים: + +- [שרת מערכת הקבצים](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) ה"קנוני", שמקבל גישה לשולחן העבודה שלך, +- ושרת [Playwright MCP](https://github.com/microsoft/playwright-mcp), שיודע להשתמש בדפדפן Chromium מבודד עבורך. + +> [!NOTE] +> הערה: זה קצת נגד האינטואיציה אבל כרגע, כל שרתי ה-MCP ב-tiny agents הם למעשה תהליכים מקומיים (אם כי שרתים מרוחקים יגיעו בקרוב). + +הקלט שלנו לסרטון הראשון הזה היה: + +> כתוב האיקו על קהילת Hugging Face וכתוב אותו לקובץ בשם "hf.txt" על שולחן העבודה שלי + +עכשיו בואו ננסה את הרמז הזה שכולל גלישה באינטרנט: + +> בצע חיפוש באינטרנט על ספקי היסק של HF ב-Brave Search ופתח את 3 התוצאות הראשונות + + + +### מודל וספק ברירת מחדל + +מבחינת צמד מודל/ספק, סוכן הדוגמה שלנו משתמש כברירת מחדל ב: +- ["Qwen/Qwen2.5-72B-Instruct"](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct) +- רץ על [Nebius](https://huggingface.co/docs/inference-providers/providers/nebius) + +כל זה ניתן להגדרה דרך משתני סביבה: + +```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: [ + // שרתי ברירת מחדל + { + command: "npx", + args: ["@modelcontextprotocol/servers", "filesystem"] + }, + { + command: "npx", + args: ["playwright-mcp"] + }, + ], +}); +``` + +## יישום לקוח MCP מעל InferenceClient + +עכשיו שאנחנו יודעים מהו כלי ב-LLM עדכניים, בואו ניישם את לקוח ה-MCP עצמו שיתקשר עם שרתי MCP ושרתי MCP אחרים. + +התיעוד הרשמי ב-https://modelcontextprotocol.io/quickstart/client כתוב די טוב. אתה רק צריך להחליף כל אזכור של ה-SDK של לקוח Anthropic בכל SDK לקוח אחר תואם-OpenAI. (יש גם [llms.txt](https://modelcontextprotocol.io/llms-full.txt) שאתה יכול להזין ל-LLM שלך כדי לעזור לך לכתוב קוד). + +כתזכורת, אנחנו משתמשים ב-`InferenceClient` של HF עבור לקוח ההיסק שלנו. + +> [!TIP] +> קובץ הקוד השלם של `McpClient.ts` נמצא [כאן](https://github.com/huggingface/huggingface.js/blob/main/packages/mcp-client/src/McpClient.ts) אם אתה רוצה לעקוב באמצעות הקוד האמיתי 🤓 + +למחלקת `McpClient` שלנו יש: +- לקוח היסק (עובד עם כל ספק היסק, ו-`huggingface/inference` תומך הן בנקודות קצה מרוחקות והן מקומיות) +- סט של סשנים של לקוחות MCP, אחד לכל שרת MCP מחובר (זה מאפשר לנו להתחבר למספר שרתים) +- ורשימה של כלים זמינים שתתמלא מהשרתים המחוברים ותעוצב מחדש מעט. + +```ts +export class McpClient { + protected client: InferenceClient; + protected provider: string; + protected model: string; + private clients: Map = 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; + } + + // [...] +} +``` + +כדי להתחבר לשרת MCP, ה-SDK הרשמי של TypeScript `@modelcontextprotocol/sdk/client` מספק מחלקת `Client` עם שיטת `listTools()`: + +```ts +async addMcpServer(server: StdioServerParameters): Promise { + 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` הוא ממשק מה-SDK של MCP שיאפשר לך בקלות להפעיל תהליך מקומי: כפי שציינו קודם, כרגע, כל שרתי ה-MCP הם למעשה תהליכים מקומיים. + +### איך להשתמש בכלים + +השימוש בכלי ניתוח הרגשות שלנו (או כל כלי MCP אחר) הוא פשוט. אתה פשוט מעביר את `this.availableTools` להשלמת צ'אט ה-LLM שלך, בנוסף למערך ההודעות הרגיל שלך: + +```ts +const stream = this.client.chatCompletionStream({ + provider: this.provider, + model: this.model, + messages, + tools: this.availableTools, + tool_choice: "auto", +}); +``` + +`tool_choice: "auto"` הוא הפרמטר שאתה מעביר כדי שה-LLM יצור אפס, אחת, או מספר קריאות לכלים. + +בעת ניתוח או הזרמת הפלט, ה-LLM יצור כמה קריאות לכלים (כלומר, שם פונקציה וכמה ארגומנטים מקודדי JSON), שאתה (כמפתח) צריך לחשב. לקוח ה-SDK של MCP שוב הופך את זה לקל מאוד; יש לו שיטת `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, +}; + +/// קבל את הסשן המתאים לכלי זה +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}`; +} +``` + +אם ה-LLM בוחר להשתמש בכלי, קוד זה ינתב אוטומטית את הקריאה לשרת ה-MCP, יבצע את הניתוח, ויחזיר את התוצאה בחזרה ל-LLM. + +לבסוף אתה תוסיף את הודעת הכלי שנוצרה למערך `messages` שלך ובחזרה ל-LLM. + +## הסוכן שלנו ב-50 שורות קוד 🤯 + +עכשיו שיש לנו לקוח MCP המסוגל להתחבר לשרתי MCP שרירותיים כדי לקבל רשימות של כלים ומסוגל להזריק אותם ולנתח אותם מההיסק של ה-LLM, טוב... מהו סוכן? + +> ברגע שיש לך לקוח היסק עם סט של כלים, אז סוכן הוא רק לולאת while מעליו. + +ביתר פירוט, סוכן הוא פשוט שילוב של: +- רמז מערכת +- לקוח היסק LLM +- לקוח MCP לחיבור סט של כלים אליו ממספר שרתי MCP +- זרימת בקרה בסיסית (ראה למטה את לולאת ה-while) + +> [!TIP] +> קובץ הקוד השלם של `Agent.ts` נמצא [כאן](https://github.com/huggingface/huggingface.js/blob/main/packages/mcp-client/src/Agent.ts). + +מחלקת Agent שלנו פשוט מרחיבה את 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, + }, + ]; + } +} +``` + +כברירת מחדל, אנחנו משתמשים ברמז מערכת פשוט מאוד בהשראת זה שהשותף במדריך רמזים של [GPT-4.1](https://cookbook.openai.com/examples/gpt4-1_prompting_guide). + +למרות שזה מגיע מ-OpenAI 😈, המשפט הזה בפרט חל על יותר ויותר מודלים, הן סגורים והן פתוחים: + +> אנו מעודדים מפתחים להשתמש בלעדית בשדה tools להעברת כלים, במקום להזריק תיאורי כלים באופן ידני לרמז שלך ולכתוב מנתח נפרד לקריאות לכלים, כפי שחלק דיווחו שעשו בעבר. + +כלומר, אנחנו לא צריכים לספק רשימות מפורמטות בקפידה של דוגמאות לשימוש בכלים ברמז. הפרמטר `tools: this.availableTools` מספיק, וה-LLM ידע כיצד להשתמש בכלי מערכת הקבצים. + +טעינת הכלים על הסוכן היא פשוט חיבור לשרתי ה-MCP שאנחנו רוצים (במקביל כי זה כל כך קל לעשות ב-JS): + +```ts +async loadTools(): Promise { + await Promise.all(this.servers.map((s) => this.addMcpServer(s))); +} +``` + +אנחנו מוסיפים שני כלים נוספים (מחוץ ל-MCP) שיכולים לשמש את ה-LLM לזרימת הבקרה של הסוכן שלנו: + +```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]; +``` + +כאשר קוראים לכל אחד מהכלים האלה, הסוכן ישבור את הלולאה שלו ויחזיר שליטה למשתמש לקלט חדש. + +### לולאת ה-while השלמה + +ראו את לולאת ה-while השלמה שלנו.🎉 + +העיקרון של לולאת ה-while העיקרית של הסוכן שלנו הוא שאנחנו פשוט מבצעים איטרציה עם ה-LLM מתחלפים בין קריאת כלים והזנת תוצאות הכלים אליו, ואנחנו עושים זאת **עד שה-LLM מתחיל להגיב עם שתי הודעות שאינן כלים ברצף**. + +זוהי לולאת ה-while השלמה: + +```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; + } +} +``` diff --git a/units/he/unit3/introduction.mdx b/units/he/unit3/introduction.mdx new file mode 100644 index 0000000..8cbb85d --- /dev/null +++ b/units/he/unit3/introduction.mdx @@ -0,0 +1,3 @@ +# בקרוב + +זה יהיה מקרה שימוש נוסף שמעמיק יותר בפרוטוקול MCP וכיצד להשתמש בו בדרכים מורכבות יותר. diff --git a/units/he/unit4/introduction.mdx b/units/he/unit4/introduction.mdx new file mode 100644 index 0000000..9eef6e5 --- /dev/null +++ b/units/he/unit4/introduction.mdx @@ -0,0 +1,5 @@ +# בקרוב + +יחידה זו תהיה שיתוף פעולה עם שותפים מקהילת הבינה המלאכותית. + +אם אתה בונה כלים עבור MCP, אנא צור איתנו קשר ונוסיף אותך ליחידה. פתח [דיון](https://huggingface.co/spaces/mcp-course/README/discussions) בארגון ההאב. diff --git a/units/pt/_toctree.yml b/units/pt/_toctree.yml new file mode 100644 index 0000000..1bd451d --- /dev/null +++ b/units/pt/_toctree.yml @@ -0,0 +1,53 @@ +- title: "0. Bem-vindo ao Curso MCP" + sections: + - local: unit0/introduction + title: Bem-vindo ao Curso MCP + +- title: "1. Introdução ao Protocolo de Contexto de Modelo" + sections: + - local: unit1/introduction + title: Introdução ao Protocolo de Contexto de Modelo (MCP) + - local: unit1/key-concepts + title: Conceitos-Chave e Terminologia + - local: unit1/architectural-components + title: Componentes Arquitetônicos + - local: unit1/quiz1 + title: Quiz 1 - Fundamentos do MCP + - local: unit1/communication-protocol + title: O Protocolo de Comunicação + - local: unit1/capabilities + title: Entendendo as Capacidades do MCP + - local: unit1/sdk + title: SDK do MCP + - local: unit1/quiz2 + title: Quiz 2 - SDK do MCP + - local: unit1/mcp-clients + title: Clientes MCP + - local: unit1/gradio-mcp + title: Integração do Gradio com MCP + - local: unit1/certificate + title: Obtenha seu certificado! + +- title: "2. Caso de Uso: Aplicação MCP Completa" + sections: + - local: unit2/introduction + title: Introdução à Construção de uma Aplicação MCP + - local: unit2/gradio-server + title: Construindo o Servidor MCP com Gradio + - local: unit2/clients + title: Usando Clientes MCP com sua aplicação + - local: unit2/gradio-client + title: Construindo um Cliente MCP com Gradio + - local: unit2/tiny-agents + title: Construindo um Tiny Agent com TypeScript + +- title: "3. Caso de Uso: Desenvolvimento Avançado de MCP" + sections: + - local: unit3/introduction + title: Em Breve + +- title: "Unidades Bônus" + sections: + - local: unit4/introduction + title: Em Breve + diff --git a/units/pt/unit0/introduction.mdx b/units/pt/unit0/introduction.mdx new file mode 100644 index 0000000..c33c6fa --- /dev/null +++ b/units/pt/unit0/introduction.mdx @@ -0,0 +1,137 @@ +# Bem-vindo ao Curso 🤗 Model Context Protocol (MCP) + +![Miniatura do Curso MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit0/1.png) + +Bem-vindo ao tópico mais empolgante em IA hoje: **Model Context Protocol (MCP)**! + +Este curso gratuito te levará em uma jornada, **de iniciante a informado**, em compreender, usar e construir aplicações com MCP. + +Esta primeira unidade te ajudará a começar: + +- Descobrir o **programa do curso**. +- **Obter mais informações sobre o processo de certificação e o cronograma**. +- Conhecer a equipe por trás do curso. +- Criar sua **conta**. +- **Inscrever-se em nosso servidor Discord**, e conhecer seus colegas de classe e nós. + +Vamos começar! + +## O que esperar deste curso? + +Neste curso, você irá: + +- 📖 Estudar Model Context Protocol em **teoria, design e prática**. +- 🧑‍💻 Aprender a **usar SDKs e frameworks MCP estabelecidos**. +- 💾 **Compartilhar seus projetos** e explorar aplicações criadas pela comunidade. +- 🏆 Participar de desafios onde você irá **avaliar suas implementações MCP contra as de outros estudantes**. +- 🎓 **Ganhar um certificado de conclusão** completando as tarefas. + +E mais! + +Ao final deste curso, você entenderá **como o MCP funciona e como construir suas próprias aplicações de IA que aproveitam dados externos e ferramentas usando os mais recentes padrões MCP**. + +Não se esqueça de [**se inscrever no curso!**](https://huggingface.co/mcp-course) + +## Como é o curso? + +O curso é composto por: + +- _Unidades Fundamentais_: onde você aprende conceitos MCP **em teoria**. +- _Prática_: onde você aprenderá **a usar SDKs MCP estabelecidos** para construir suas aplicações. Essas seções práticas terão ambientes pré-configurados. +- _Tarefas de casos de uso_: onde você aplicará os conceitos que aprendeu para resolver um problema do mundo real que você escolherá. +- _Colaborações_: Estamos colaborando com parceiros da Hugging Face para te dar as mais recentes implementações e ferramentas MCP. + +Este **curso é um projeto vivo, evoluindo com seu feedback e contribuições!** Sinta-se livre para abrir issues e PRs no GitHub, e participar de discussões em nosso servidor Discord. + +## Qual é o programa? + +Aqui está o **programa geral do curso**. Uma lista mais detalhada de tópicos será divulgada com cada unidade. + +| Capítulo | Tópico | Descrição | +| -------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | +| 0 | Integração | Te configurar com as ferramentas e plataformas que você usará. | +| 1 | Fundamentos MCP, Arquitetura e Conceitos Centrais | Explicar conceitos centrais, arquitetura e componentes do Model Context Protocol. Mostrar um caso de uso simples usando MCP. | +| 2 | Caso de uso ponta a ponta: MCP em Ação | Construir uma aplicação MCP simples ponta a ponta que você pode compartilhar com a comunidade. | +| 3 | Caso de uso implantado: MCP em Ação | Construir uma aplicação MCP implantada usando o ecossistema Hugging Face e serviços de parceiros. | +| 4 | Unidades Bônus | Unidades bônus para te ajudar a aproveitar mais o curso, trabalhando com bibliotecas e serviços de parceiros. | + +## Quais são os pré-requisitos? + +Para conseguir acompanhar este curso, você deve ter: + +- Compreensão básica de IA e conceitos de LLM +- Familiaridade com princípios de desenvolvimento de software e conceitos de API +- Experiência com pelo menos uma linguagem de programação (exemplos em Python ou TypeScript serão mostrados) + +Se você não tem nenhum destes, não se preocupe! Aqui estão alguns recursos que podem te ajudar: + +- [Curso LLM](https://huggingface.co/learn/llm-course/) te guiará através do básico de usar e construir com LLMs. +- [Curso de Agentes](https://huggingface.co/learn/agents-course/) te guiará através da construção de agentes de IA com LLMs. + + + +Os cursos acima não são pré-requisitos em si, então se você entende os conceitos de LLMs e agentes, pode começar o curso agora! + + + +## Que ferramentas eu preciso? + +Você só precisa de 2 coisas: + +- _Um computador_ com conexão à internet. +- Uma _conta_: para acessar os recursos do curso e criar projetos. Se você ainda não tem uma conta, pode criar uma [aqui](https://huggingface.co/join) (é gratuito). + +## O Processo de Certificação + +Você pode escolher seguir este curso _em modo auditoria_, ou fazer as atividades e _obter um dos dois certificados que emitiremos_. Se você auditar o curso, pode participar de todos os desafios e fazer tarefas se quiser, e **não precisa nos notificar**. + +O processo de certificação é **completamente gratuito**: + +- _Para obter uma certificação para fundamentos_: você precisa completar a Unidade 1 do curso. Isso é destinado a estudantes que querem se atualizar com as últimas tendências em MCP, sem a necessidade de construir uma aplicação completa. +- _Para obter um certificado de conclusão_: você precisa completar as unidades de casos de uso (2 e 3). Isso é destinado a estudantes que querem construir uma aplicação completa e compartilhá-la com a comunidade. + +## Qual é o ritmo recomendado? + +Cada capítulo neste curso é projetado **para ser completado em 1 semana, com aproximadamente 3-4 horas de trabalho por semana**. + +Como há um prazo, fornecemos um ritmo recomendado: + +![Ritmo Recomendado](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit0/2.png) + +## Como aproveitar ao máximo o curso? + +Para aproveitar ao máximo o curso, temos alguns conselhos: + +1. [Junte-se a grupos de estudo no Discord](https://discord.gg/UrrTSsSyjb): Estudar em grupos é sempre mais fácil. Para fazer isso, você precisa se juntar ao nosso servidor discord e verificar sua conta. +2. **Faça os quizzes e tarefas**: A melhor maneira de aprender é através da prática e auto-avaliação. +3. **Defina um cronograma para se manter sincronizado**: Você pode usar nosso cronograma de ritmo recomendado abaixo ou criar o seu. + +![Conselhos do Curso](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit0/3.png) + +## Quem somos + +Sobre os autores: + +### Ben Burtenshaw + +Ben é um Engenheiro de Machine Learning na Hugging Face que foca na construção de aplicações LLM, com abordagens de pós-treinamento e agênticas. [Siga Ben no Hub](https://huggingface.co/burtenshaw) para ver seus projetos mais recentes. + + + + + + + +## Encontrei um bug, ou quero melhorar o curso + +Contribuições são **bem-vindas** 🤗 + +- Se você _encontrou um bug 🐛 em um notebook_, por favor [abra uma issue](https://github.com/huggingface/mcp-course/issues/new) e **descreva o problema**. +- Se você _quer melhorar o curso_, pode [abrir um Pull Request](https://github.com/huggingface/mcp-course/pulls). +- Se você _quer adicionar uma seção completa ou uma nova unidade_, o melhor é [abrir uma issue](https://github.com/huggingface/mcp-course/issues/new) e **descrever que conteúdo você quer adicionar antes de começar a escrever para que possamos te orientar**. + +## Ainda tenho dúvidas + +Por favor, faça sua pergunta em nosso servidor discord #mcp-course-questions. + +Agora que você tem todas as informações, vamos embarcar ⛵ diff --git a/units/pt/unit1/architectural-components.mdx b/units/pt/unit1/architectural-components.mdx new file mode 100644 index 0000000..4444b2a --- /dev/null +++ b/units/pt/unit1/architectural-components.mdx @@ -0,0 +1,85 @@ +# Componentes Arquiteturais do MCP + +Na seção anterior, discutimos os conceitos-chave e terminologia do MCP. Agora, vamos nos aprofundar nos componentes arquiteturais que compõem o ecossistema MCP. + +## Host, Cliente e Servidor + +O Model Context Protocol (MCP) é construído sobre uma arquitetura cliente-servidor que permite comunicação estruturada entre modelos de IA e sistemas externos. + +![Arquitetura MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/4.png) + +A arquitetura MCP consiste em três componentes principais, cada um com papéis e responsabilidades bem definidos: Host, Cliente e Servidor. Tocamos nestes na seção anterior, mas vamos nos aprofundar em cada componente e suas responsabilidades. + +### Host + +O **Host** é a aplicação de IA voltada para o usuário com a qual os usuários finais interagem diretamente. + +Exemplos incluem: +- Aplicações de Chat de IA como OpenAI ChatGPT ou Anthropic's Claude Desktop +- IDEs aprimoradas por IA como Cursor, ou integrações a ferramentas como Continue.dev +- Agentes de IA personalizados e aplicações construídas em bibliotecas como LangChain ou smolagents + +As responsabilidades do Host incluem: +- Gerenciar interações e permissões do usuário +- Iniciar conexões aos Servidores MCP via Clientes MCP +- Orquestrar o fluxo geral entre solicitações do usuário, processamento LLM e ferramentas externas +- Renderizar resultados de volta aos usuários em um formato coerente + +Na maioria dos casos, os usuários selecionarão sua aplicação host baseado em suas necessidades e preferências. Por exemplo, um desenvolvedor pode escolher Cursor por suas poderosas capacidades de edição de código, enquanto especialistas de domínio podem usar aplicações personalizadas construídas em smolagents. + +### Cliente + +O **Cliente** é um componente dentro da aplicação Host que gerencia comunicação com um Servidor MCP específico. Características principais incluem: + +- Cada Cliente mantém uma conexão 1:1 com um único Servidor +- Lida com os detalhes de nível de protocolo da comunicação MCP +- Atua como intermediário entre a lógica do Host e o Servidor externo + +### Servidor + +O **Servidor** é um programa ou serviço externo que expõe capacidades aos modelos de IA via protocolo MCP. Servidores: + +- Fornecem acesso a ferramentas específicas externas, fontes de dados ou serviços +- Atuam como wrappers leves em torno de funcionalidade existente +- Podem executar localmente (na mesma máquina que o Host) ou remotamente (através de uma rede) +- Expõem suas capacidades em um formato padronizado que Clientes podem descobrir e usar + +## Fluxo de Comunicação + +Vamos examinar como esses componentes interagem em um fluxo de trabalho MCP típico: + + + +Na próxima seção, nos aprofundaremos no protocolo de comunicação que permite esses componentes com exemplos práticos. + + + +1. **Interação do Usuário**: O usuário interage com a aplicação **Host**, expressando uma intenção ou consulta. + +2. **Processamento do Host**: O **Host** processa a entrada do usuário, potencialmente usando um LLM para entender a solicitação e determinar quais capacidades externas podem ser necessárias. + +3. **Conexão do Cliente**: O **Host** direciona seu componente **Cliente** para se conectar ao(s) Servidor(es) apropriado(s). + +4. **Descoberta de Capacidades**: O **Cliente** consulta o **Servidor** para descobrir quais capacidades (Ferramentas, Recursos, Prompts) ele oferece. + +5. **Invocação de Capacidades**: Baseado nas necessidades do usuário ou determinação do LLM, o Host instrui o **Cliente** a invocar capacidades específicas do **Servidor**. + +6. **Execução do Servidor**: O **Servidor** executa a funcionalidade solicitada e retorna resultados ao **Cliente**. + +7. **Integração de Resultados**: O **Cliente** retransmite esses resultados de volta ao **Host**, que os incorpora no contexto para o LLM ou os apresenta diretamente ao usuário. + +Uma vantagem chave desta arquitetura é sua modularidade. Um único **Host** pode se conectar a múltiplos **Servidores** simultaneamente via diferentes **Clientes**. Novos **Servidores** podem ser adicionados ao ecossistema sem exigir mudanças nos **Hosts** existentes. Capacidades podem ser facilmente compostas através de diferentes **Servidores**. + + + +Como discutimos na seção anterior, esta modularidade transforma o problema tradicional de integração M×N (M aplicações de IA se conectando a N ferramentas/serviços) em um problema mais gerenciável M+N, onde cada Host e Servidor precisa implementar o padrão MCP apenas uma vez. + + + +A arquitetura pode parecer simples, mas seu poder reside na padronização do protocolo de comunicação e na clara separação de responsabilidades entre componentes. Este design permite um ecossistema coeso onde modelos de IA podem se conectar perfeitamente com uma gama sempre crescente de ferramentas externas e fontes de dados. + +## Conclusão + +Esses padrões de interação são guiados por vários princípios-chave que moldam o design e evolução do MCP. O protocolo enfatiza **padronização** fornecendo um protocolo universal para conectividade de IA, mantendo **simplicidade** mantendo o protocolo central direto, mas permitindo recursos avançados. **Segurança** é priorizada exigindo aprovação explícita do usuário para operações sensíveis, e discoverabilidade permite descoberta dinâmica de capacidades. O protocolo é construído com **extensibilidade** em mente, suportando evolução através de versionamento e negociação de capacidades, e garante **interoperabilidade** através de diferentes implementações e ambientes. + +Na próxima seção, exploraremos o protocolo de comunicação que permite esses componentes trabalharem juntos efetivamente. \ No newline at end of file diff --git a/units/pt/unit1/capabilities.mdx b/units/pt/unit1/capabilities.mdx new file mode 100644 index 0000000..ecdaa21 --- /dev/null +++ b/units/pt/unit1/capabilities.mdx @@ -0,0 +1,243 @@ +# Entendendo as Capacidades do MCP + +Servidores MCP expõem uma variedade de capacidades aos Clientes através do protocolo de comunicação. Essas capacidades se dividem em quatro categorias principais, cada uma com características distintas e casos de uso. Vamos explorar essas primitivas centrais que formam a base da funcionalidade do MCP. + + + +Nesta seção, mostraremos exemplos como funções agnósticas de framework em cada linguagem. Isso é para focar nos conceitos e como eles trabalham juntos, ao invés das complexidades de qualquer framework. + +Nas próximas unidades, mostraremos como esses conceitos são implementados em código específico do MCP. + + + +## Ferramentas + +Ferramentas são funções ou ações executáveis que o modelo de IA pode invocar através do protocolo MCP. + +- **Controle**: Ferramentas são tipicamente **controladas pelo modelo**, significando que o modelo de IA (LLM) decide quando chamá-las baseado na solicitação do usuário e contexto. +- **Segurança**: Devido à sua capacidade de realizar ações com efeitos colaterais, execução de ferramentas pode ser perigosa. Portanto, elas tipicamente requerem aprovação explícita do usuário. +- **Casos de Uso**: Enviar mensagens, criar tickets, consultar APIs, realizar cálculos. + +**Exemplo**: Uma ferramenta de clima que busca dados meteorológicos atuais para uma localização dada: + + + + +```python +def get_weather(location: str) -> dict: + """Obter o clima atual para uma localização especificada.""" + # Conectar à API de clima e buscar dados + return { + "temperature": 72, + "conditions": "Ensolarado", + "humidity": 45 + } +``` + + + + +```javascript +function getWeather(location) { + // Conectar à API de clima e buscar dados + return { + temperature: 72, + conditions: 'Ensolarado', + humidity: 45 + }; +} +``` + + + + +## Recursos + +Recursos fornecem acesso somente leitura a fontes de dados, permitindo que o modelo de IA recupere contexto sem executar lógica complexa. + +- **Controle**: Recursos são **controlados pela aplicação**, significando que a aplicação Host tipicamente decide quando acessá-los. +- **Natureza**: Eles são projetados para recuperação de dados com computação mínima, similar a endpoints GET em APIs REST. +- **Segurança**: Como são somente leitura, eles tipicamente apresentam riscos de segurança menores que Ferramentas. +- **Casos de Uso**: Acessar conteúdos de arquivo, recuperar registros de banco de dados, ler informações de configuração. + +**Exemplo**: Um recurso que fornece acesso a conteúdos de arquivo: + + + + +```python +def read_file(file_path: str) -> str: + """Ler o conteúdo de um arquivo no caminho especificado.""" + with open(file_path, 'r') as f: + return f.read() +``` + + + + +```javascript +function readFile(filePath) { + // Usando fs.readFile para ler conteúdos do arquivo + const fs = require('fs'); + return new Promise((resolve, reject) => { + fs.readFile(filePath, 'utf8', (err, data) => { + if (err) { + reject(err); + return; + } + resolve(data); + }); + }); +} +``` + + + + +## Prompts + +Prompts são templates ou fluxos de trabalho predefinidos que guiam a interação entre o usuário, o modelo de IA e as capacidades do Servidor. + +- **Controle**: Prompts são **controlados pelo usuário**, frequentemente apresentados como opções na UI da aplicação Host. +- **Propósito**: Eles estruturam interações para uso ótimo de Ferramentas e Recursos disponíveis. +- **Seleção**: Usuários tipicamente selecionam um prompt antes do modelo de IA começar o processamento, definindo contexto para a interação. +- **Casos de Uso**: Fluxos de trabalho comuns, templates de tarefas especializadas, interações guiadas. + +**Exemplo**: Um template de prompt para gerar uma revisão de código: + + + + +```python +def code_review(code: str, language: str) -> list: + """Gerar uma revisão de código para o snippet de código fornecido.""" + return [ + { + "role": "system", + "content": f"Você é um revisor de código examinando código {language}. Forneça uma revisão detalhada destacando melhores práticas, problemas potenciais e sugestões de melhoria." + }, + { + "role": "user", + "content": f"Por favor, revise este código {language}:\n\n```{language}\n{code}\n```" + } + ] +``` + + + + +```javascript +function codeReview(code, language) { + return [ + { + role: 'system', + content: `Você é um revisor de código examinando código ${language}. Forneça uma revisão detalhada destacando melhores práticas, problemas potenciais e sugestões de melhoria.` + }, + { + role: 'user', + content: `Por favor, revise este código ${language}:\n\n\`\`\`${language}\n${code}\n\`\`\`` + } + ]; +} +``` + + + + +## Amostragem + +Amostragem permite que Servidores solicitem ao Cliente (especificamente, a aplicação Host) para realizar interações LLM. + +- **Controle**: Amostragem é **iniciada pelo servidor** mas requer facilitação do Cliente/Host. +- **Propósito**: Permite comportamentos agênticos dirigidos pelo servidor e potencialmente interações recursivas ou multi-etapas. +- **Segurança**: Como Ferramentas, operações de amostragem tipicamente requerem aprovação do usuário. +- **Casos de Uso**: Tarefas complexas multi-etapas, fluxos de trabalho de agentes autônomos, processos interativos. + +**Exemplo**: Um Servidor pode solicitar ao Cliente para analisar dados que processou: + + + + +```python +def request_sampling(messages, system_prompt=None, include_context="none"): + """Solicitar amostragem LLM do cliente.""" + # Em uma implementação real, isso enviaria uma solicitação ao cliente + return { + "role": "assistant", + "content": "Análise dos dados fornecidos..." + } +``` + + + + +```javascript +function requestSampling(messages, systemPrompt = null, includeContext = 'none') { + // Em uma implementação real, isso enviaria uma solicitação ao cliente + return { + role: 'assistant', + content: 'Análise dos dados fornecidos...' + }; +} + +function handleSamplingRequest(request) { + const { messages, systemPrompt, includeContext } = request; + // Em uma implementação real, isso processaria a solicitação e retornaria uma resposta + return { + role: 'assistant', + content: 'Resposta à solicitação de amostragem...' + }; +} +``` + + + + +O fluxo de amostragem segue estes passos: +1. Servidor envia uma solicitação `sampling/createMessage` ao cliente +2. Cliente revisa a solicitação e pode modificá-la +3. Cliente faz amostragem de um LLM +4. Cliente revisa a conclusão +5. Cliente retorna o resultado ao servidor + + + +Este design humano-no-loop garante que usuários mantenham controle sobre o que o LLM vê e gera. Ao implementar amostragem, é importante fornecer prompts claros e bem estruturados e incluir contexto relevante. + + + +## Como as Capacidades Trabalham Juntas + +Vamos ver como essas capacidades trabalham juntas para permitir interações complexas. Na tabela abaixo, delineamos as capacidades, quem as controla, a direção do controle e alguns outros detalhes. + +| Capacidade | Controlada Por | Direção | Efeitos Colaterais | Aprovação Necessária | Casos de Uso Típicos | +|------------|---------------|-----------|--------------|-----------------|-------------------| +| Ferramentas | Modelo (LLM) | Cliente → Servidor | Sim (potencialmente) | Sim | Ações, chamadas API, manipulação de dados | +| Recursos | Aplicação | Cliente → Servidor | Não (somente leitura) | Tipicamente não | Recuperação de dados, coleta de contexto | +| Prompts | Usuário | Servidor → Cliente | Não | Não (selecionado pelo usuário) | Fluxos de trabalho guiados, templates especializados | +| Amostragem | Servidor | Servidor → Cliente → Servidor | Indiretamente | Sim | Tarefas multi-etapas, comportamentos agênticos | + +Essas capacidades são projetadas para trabalhar juntas de maneiras complementares: + +1. Um usuário pode selecionar um **Prompt** para iniciar um fluxo de trabalho especializado +2. O Prompt pode incluir contexto de **Recursos** +3. Durante o processamento, o modelo de IA pode chamar **Ferramentas** para realizar ações específicas +4. Para operações complexas, o Servidor pode usar **Amostragem** para solicitar processamento LLM adicional + +A distinção entre essas primitivas fornece uma estrutura clara para interações MCP, permitindo que modelos de IA acessem informações, realizem ações e se envolvam em fluxos de trabalho complexos mantendo limites de controle apropriados. + +## Processo de Descoberta + +Uma das características-chave do MCP é a descoberta dinâmica de capacidades. Quando um Cliente se conecta a um Servidor, ele pode consultar as Ferramentas, Recursos e Prompts disponíveis através de métodos de lista específicos: + +- `tools/list`: Descobrir Ferramentas disponíveis +- `resources/list`: Descobrir Recursos disponíveis +- `prompts/list`: Descobrir Prompts disponíveis + +Este mecanismo de descoberta dinâmica permite que Clientes se adaptem às capacidades específicas que cada Servidor oferece sem exigir conhecimento hardcoded da funcionalidade do Servidor. + +## Conclusão + +Entender essas primitivas centrais é essencial para trabalhar com MCP efetivamente. Fornecendo tipos distintos de capacidades com limites de controle claros, o MCP permite interações poderosas entre modelos de IA e sistemas externos mantendo mecanismos apropriados de segurança e controle. + +Na próxima seção, nós vamos explorar como o Gradio integra com MCP para prover interfaces de fácil utilização para estas capacidades. \ No newline at end of file diff --git a/units/pt/unit1/certificate.mdx b/units/pt/unit1/certificate.mdx new file mode 100644 index 0000000..210adc4 --- /dev/null +++ b/units/pt/unit1/certificate.mdx @@ -0,0 +1,18 @@ +# Obtenha seu certificado! + +Muito bem! Você concluiu a primeira unidade do curso MCP. Agora é hora de fazer o exame para obter seu certificado. + +Abaixo está um quiz para verificar sua compreensão da unidade. + + + + + +Se você está tendo dificuldades para usar o quiz acima, acesse o espaço diretamente [no Hugging Face Hub](https://huggingface.co/spaces/mcp-course/unit_1_quiz). Se encontrar erros, você pode reportá-los na [aba Comunidade](https://huggingface.co/spaces/mcp-course/unit_1_quiz/discussions) do espaço. + + diff --git a/units/pt/unit1/communication-protocol.mdx b/units/pt/unit1/communication-protocol.mdx new file mode 100644 index 0000000..5115ee5 --- /dev/null +++ b/units/pt/unit1/communication-protocol.mdx @@ -0,0 +1,223 @@ +# O Protocolo de Comunicação + +O MCP define um protocolo de comunicação padronizado que permite que Clientes e Servidores troquem mensagens de forma consistente e previsível. Essa padronização é fundamental para a interoperabilidade em toda a comunidade. Nesta seção, exploraremos a estrutura do protocolo e os mecanismos de transporte utilizados no MCP. + + + +Estamos entrando nos detalhes minuciosos do protocolo MCP. Você não precisará conhecer todos esses detalhes para construir com o MCP, mas é bom saber que eles existem e como funcionam. + + + +## JSON-RPC: A Base + +Em sua essência, o MCP utiliza o **JSON-RPC 2.0** como formato de mensagem para toda a comunicação entre Clientes e Servidores. JSON-RPC é um protocolo leve de chamada de procedimento remoto codificado em JSON, o que o torna: + +- Legível por humanos e fácil de depurar +- Agnóstico em relação à linguagem, permitindo implementação em qualquer ambiente de programação +- Bem estabelecido, com especificações claras e ampla adoção + +![tipos de mensagens](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/5.png) + +O protocolo define três tipos de mensagens: + +### 1. Requisições + +Enviadas do Cliente para o Servidor para iniciar uma operação. Uma mensagem de Requisição inclui: +- Um identificador único (`id`) +- O nome do método a ser invocado (ex: `tools/call`) +- Parâmetros para o método (se houver) + +Exemplo de Requisição: + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "tools/call", + "params": { + "name": "weather", + "arguments": { + "location": "San Francisco" + } + } +} +``` + +### 2. Respostas + +Enviadas do Servidor para o Cliente em resposta a uma Requisição. Uma mensagem de Resposta inclui: +- O mesmo `id` da Requisição correspondente +- Um `result` (para sucesso) ou um `error` (para falha) + +Exemplo de Resposta com Sucesso: +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "temperature": 62, + "conditions": "Partly cloudy" + } +} +``` + +Exemplo de Resposta com Erro: +```json +{ + "jsonrpc": "2.0", + "id": 1, + "error": { + "code": -32602, + "message": "Invalid location parameter" + } +} +``` + +### 3. Notificações + +Mensagens unidirecionais que não requerem resposta. Normalmente enviadas do Servidor para o Cliente para fornecer atualizações ou notificações sobre eventos. + +Exemplo de Notificação: +```json +{ + "jsonrpc": "2.0", + "method": "progress", + "params": { + "message": "Processing data...", + "percent": 50 + } +} +``` + +## Mecanismos de Transporte + +O JSON-RPC define o formato da mensagem, mas o MCP também especifica como essas mensagens são transportadas entre Clientes e Servidores. Dois mecanismos principais de transporte são suportados: + +### stdio (Entrada/Saída Padrão) + +O transporte stdio é usado para comunicação local, onde o Cliente e o Servidor executam na mesma máquina: + +A aplicação Host inicia o Servidor como um subprocesso e se comunica com ele escrevendo em sua entrada padrão (stdin) e lendo de sua saída padrão (stdout). + + + +**Casos de uso** para este transporte são ferramentas locais como acesso ao sistema de arquivos ou execução de scripts locais. + + + +As principais **Vantagens** deste transporte são: é simples, não requer configuração de rede e é seguramente isolado pelo sistema operacional. + +### HTTP + SSE (Server-Sent Events) / HTTP Streamable + +O transporte HTTP+SSE é usado para comunicação remota, onde o Cliente e o Servidor podem estar em máquinas diferentes: + +A comunicação ocorre via HTTP, com o Servidor usando Server-Sent Events (SSE) para enviar atualizações ao Cliente através de uma conexão persistente. + + + +**Casos de uso** para este transporte são conexões com APIs remotas, serviços em nuvem ou recursos compartilhados. + + + +As principais **Vantagens** deste transporte são: funciona através de redes, permite integração com serviços web e é compatível com ambientes serverless. + +Atualizações recentes no padrão MCP introduziram ou refinaram o "HTTP Streamable", que oferece mais flexibilidade ao permitir que servidores façam upgrade dinâmico para SSE para streaming quando necessário, mantendo a compatibilidade com ambientes serverless. + +## O Ciclo de Vida da Interação + +Na seção anterior, discutimos o ciclo de vida de uma única interação entre um Cliente (💻) e um Servidor (🌐). Vamos agora examinar o ciclo de vida de uma interação completa entre um Cliente e um Servidor no contexto do protocolo MCP. + +O protocolo MCP define um ciclo de vida de interação estruturado entre Clientes e Servidores: + +### Inicialização + +O Cliente se conecta ao Servidor e eles trocam versões de protocolo e capacidades, e o Servidor responde com sua versão de protocolo suportada e capacidades. + + + + + + + + + + + + + + + + + +
💻→
initialize		🌐
💻←
response		🌐
💻→
initialized		🌐
+ +O Cliente confirma que a inicialização está completa através de uma mensagem de notificação. + +### Descoberta + +O Cliente solicita informações sobre capacidades disponíveis e o Servidor responde com uma lista de ferramentas disponíveis. + + + + + + + + + + + + +
💻→
tools/list		🌐
💻←
response		🌐
+ +Este processo pode ser repetido para cada ferramenta, recurso ou tipo de prompt. + +### Execução + +O Cliente invoca capacidades com base nas necessidades do Host. + + + + + + + + + + + + + + + + + +
💻→
tools/call		🌐
💻←
notification (progresso opcional)		🌐
💻←
response		🌐
+ +### Encerramento + +A conexão é fechada de forma elegante quando não é mais necessária e o Servidor reconhece a solicitação de desligamento. + + + + + + + + + + + + + + + + + +
💻→
shutdown		🌐
💻←
response		🌐
💻→
exit		🌐
+ +O Cliente envia a mensagem final de saída para completar o encerramento. + +## Evolução do Protocolo + +O protocolo MCP é projetado para ser extensível e adaptável. A fase de inicialização inclui negociação de versão, permitindo compatibilidade retroativa à medida que o protocolo evolui. Além disso, a descoberta de capacidades permite que os Clientes se adaptem às características específicas oferecidas por cada Servidor, possibilitando uma mistura de Servidores básicos e avançados no mesmo ecossistema. diff --git a/units/pt/unit1/gradio-mcp.mdx b/units/pt/unit1/gradio-mcp.mdx new file mode 100644 index 0000000..3e67fde --- /dev/null +++ b/units/pt/unit1/gradio-mcp.mdx @@ -0,0 +1,154 @@ +# Integração do Gradio com MCP + +Agora que exploramos os conceitos fundamentais do protocolo MCP e como implementar Servidores e Clientes MCP, vamos facilitar um pouco as coisas usando o Gradio para criar um Servidor MCP! + + + +Gradio é uma biblioteca Python popular para criar rapidamente interfaces web personalizáveis para modelos de aprendizado de máquina. + + + +## Introdução ao Gradio + +O Gradio permite que desenvolvedores criem interfaces de usuário para seus modelos com apenas algumas linhas de código Python. É particularmente útil para: + +- Criar demonstrações e protótipos +- Compartilhar modelos com usuários não técnicos +- Testar e depurar o comportamento do modelo + +Com a adição do suporte ao MCP, o Gradio agora oferece uma maneira direta de expor as capacidades do modelo de IA através do protocolo MCP padronizado. + +Combinar o Gradio com o MCP permite criar interfaces amigáveis para humanos e ferramentas acessíveis por IA com código mínimo. Mas o melhor de tudo é que o Gradio já é amplamente utilizado pela comunidade de IA, então você pode usá-lo para compartilhar seus Servidores MCP com outras pessoas. + +## Pré-requisitos + +Para usar o Gradio com suporte ao MCP, você precisará instalar o Gradio com o extra MCP: + +```bash +pip install "gradio[mcp]" +``` + +Você também precisará de uma aplicação LLM que suporte chamada de ferramentas usando o protocolo MCP, como o Cursor (conhecido como "MCP Hosts"). + +## Criando um Servidor MCP com Gradio + +Vamos ver um exemplo básico de como criar um Servidor MCP usando Gradio: + +```python +import gradio as gr + +def letter_counter(word: str, letter: str) -> int: + """ + Count the number of occurrences of a letter in a word or text. + + Args: + word (str): The input text to search through + letter (str): The letter to search for + + Returns: + int: The number of times the letter appears in the text + """ + word = word.lower() + letter = letter.lower() + count = word.count(letter) + return count + +# Create a standard Gradio interface +demo = gr.Interface( + fn=letter_counter, + inputs=["textbox", "textbox"], + outputs="number", + title="Letter Counter", + description="Enter text and a letter to count how many times the letter appears in the text." +) + +# Launch both the Gradio web interface and the MCP server +if __name__ == "__main__": + demo.launch(mcp_server=True) +``` + +Com esta configuração, sua função de contador de letras agora está acessível através de: + +1. Uma interface web tradicional do Gradio para interação humana direta +2. Um Servidor MCP que pode ser conectado a clientes compatíveis + +O servidor MCP estará acessível em: +``` +http://your-server:port/gradio_api/mcp/sse +``` + +A aplicação em si ainda estará acessível e se parece com isto: + +![Servidor Gradio MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/7.png) + +## Como Funciona nos Bastidores + +Quando você define `mcp_server=True` em `launch()`, várias coisas acontecem: + +1. As funções do Gradio são automaticamente convertidas em Ferramentas MCP +2. Os componentes de entrada são mapeados para esquemas de argumentos de ferramentas +3. Os componentes de saída determinam o formato da resposta +4. O servidor Gradio passa a ouvir mensagens do protocolo MCP +5. JSON-RPC sobre HTTP+SSE é configurado para comunicação cliente-servidor + +## Principais Características da Integração Gradio <> MCP + +1. **Conversão de Ferramentas**: Cada endpoint da API em seu aplicativo Gradio é automaticamente convertido em uma ferramenta MCP com nome, descrição e esquema de entrada correspondentes. Para visualizar as ferramentas e esquemas, visite `http://your-server:port/gradio_api/mcp/schema` ou acesse o link "View API" no rodapé do seu aplicativo Gradio, e depois clique em "MCP". + +2. **Suporte a Variáveis de Ambiente**: Existem duas maneiras de habilitar a funcionalidade do servidor MCP: +- Usando o parâmetro `mcp_server` em `launch()`: + ```python + demo.launch(mcp_server=True) + ``` +- Usando variáveis de ambiente: + ```bash + export GRADIO_MCP_SERVER=True + ``` + +3. **Manipulação de Arquivos**: O servidor lida automaticamente com conversões de dados de arquivos, incluindo: + - Conversão de strings codificadas em base64 para dados de arquivo + - Processamento de arquivos de imagem e retorno no formato correto + - Gerenciamento de armazenamento temporário de arquivos + + É **fortemente** recomendado que imagens e arquivos de entrada sejam passados como URLs completas ("http://..." ou "https://..."), pois os Clientes MCP nem sempre lidam corretamente com arquivos locais. + +4. **Servidores MCP Hospedados no 🤗 Spaces**: Você pode publicar seu aplicativo Gradio gratuitamente no Hugging Face Spaces, o que permitirá ter um servidor MCP hospedado gratuitamente. Aqui está um exemplo de Space: https://huggingface.co/spaces/abidlabs/mcp-tools + +## Dicas de Solução de Problemas + +1. **Dicas de Tipo e Docstrings**: Certifique-se de fornecer dicas de tipo e docstrings válidas para suas funções. A docstring deve incluir um bloco "Args:" com nomes de parâmetros indentados. + +2. **Entradas de String**: Em caso de dúvida, aceite argumentos de entrada como `str` e converta-os para o tipo desejado dentro da função. + +3. **Suporte a SSE**: Alguns Hosts MCP não suportam Servidores MCP baseados em SSE. Nesses casos, você pode usar `mcp-remote`: + ```json + { + "mcpServers": { + "gradio": { + "command": "npx", + "args": [ + "mcp-remote", + "http://your-server:port/gradio_api/mcp/sse" + ] + } + } + } + ``` + +4. **Reiniciar**: Se encontrar problemas de conexão, tente reiniciar tanto seu Cliente MCP quanto seu Servidor MCP. + +## Compartilhe seu Servidor MCP + +Você pode compartilhar seu Servidor MCP publicando seu aplicativo Gradio no Hugging Face Spaces. O vídeo abaixo mostra como criar um Hugging Face Space. + + + +Agora, você pode compartilhar seu Servidor MCP com outras pessoas compartilhando seu Hugging Face Space. + +## Conclusão + +A integração do Gradio com o MCP fornece um ponto de entrada acessível para o ecossistema MCP. Ao aproveitar a simplicidade do Gradio e adicionar a padronização do MCP, os desenvolvedores podem criar rapidamente interfaces amigáveis para humanos e ferramentas acessíveis por IA com código mínimo. + +À medida que avançamos neste curso, exploraremos implementações mais sofisticadas do MCP, mas o Gradio oferece um excelente ponto de partida para entender e experimentar o protocolo. + +Na próxima unidade, mergulharemos mais profundamente na construção de aplicações MCP, focando na configuração de ambientes de desenvolvimento, explorando SDKs e implementando Servidores e Clientes MCP mais avançados. diff --git a/units/pt/unit1/introduction.mdx b/units/pt/unit1/introduction.mdx new file mode 100644 index 0000000..2542d8d --- /dev/null +++ b/units/pt/unit1/introduction.mdx @@ -0,0 +1,33 @@ +# Introdução ao Model Context Protocol (MCP) + +Bem-vindo à Unidade 1 do Curso MCP! Nesta unidade, exploraremos os fundamentos do Model Context Protocol. + +## O que Você Vai Aprender + +Nesta unidade, você irá: + +* Entender o que é Model Context Protocol e por que é importante +* Aprender os conceitos-chave e terminologia associada ao MCP +* Explorar os desafios de integração que o MCP resolve +* Percorrer os principais benefícios e objetivos do MCP +* Ver um exemplo simples de integração MCP em ação + +Ao final desta unidade, você terá uma compreensão sólida dos conceitos fundamentais do MCP e estará pronto para se aprofundar em sua arquitetura e implementação na próxima unidade. + +## Importância do MCP + +O ecossistema de IA está evoluindo rapidamente, com Large Language Models (LLMs) e outros sistemas de IA se tornando cada vez mais capazes. No entanto, esses modelos são frequentemente limitados por seus dados de treinamento e carecem de acesso a informações em tempo real ou ferramentas especializadas. Esta limitação impede o potencial dos sistemas de IA de fornecer respostas verdadeiramente relevantes, precisas e úteis em muitos cenários. + +É aqui que o Model Context Protocol (MCP) entra. O MCP permite que modelos de IA se conectem com fontes de dados externas, ferramentas e ambientes, permitindo a transferência perfeita de informações e capacidades entre sistemas de IA e o mundo digital mais amplo. Esta interoperabilidade é crucial para o crescimento e adoção de aplicações de IA verdadeiramente úteis. + +## Visão Geral da Unidade 1 + +Aqui está uma breve visão geral do que cobriremos nesta unidade: + +1. **O que é Model Context Protocol?** - Começaremos definindo o que é MCP e discutindo seu papel no ecossistema de IA. +2. **Conceitos-Chave** - Exploraremos os conceitos fundamentais e terminologia associada ao MCP. +3. **Desafios de Integração** - Examinaremos os problemas que o MCP visa resolver, particularmente o "Problema de Integração M×N." +4. **Benefícios e Objetivos** - Discutiremos os principais benefícios e objetivos do MCP, incluindo padronização, capacidades aprimoradas de IA e interoperabilidade. +5. **Exemplo Simples** - Finalmente, percorreremos um exemplo simples de integração MCP para ver como funciona na prática. + +Vamos mergulhar de cabeça e explorar o empolgante mundo do protocolo de contexto de modelo! \ No newline at end of file diff --git a/units/pt/unit1/key-concepts.mdx b/units/pt/unit1/key-concepts.mdx new file mode 100644 index 0000000..a92dce2 --- /dev/null +++ b/units/pt/unit1/key-concepts.mdx @@ -0,0 +1,92 @@ +# Conceitos-Chave e Terminologia + +Antes de mergulhar mais profundamente no Protocolo de Contexto de Modelo (MCP), é importante entender os conceitos-chave e a terminologia que formam a base do MCP. Esta seção apresentará as ideias fundamentais que sustentam o protocolo e fornecerá um vocabulário comum para discutir implementações de MCP ao longo do curso. + +O MCP é frequentemente descrito como o "USB-C para aplicações de IA". Assim como o USB-C fornece uma interface física e lógica padronizada para conectar vários periféricos a dispositivos de computação, o MCP oferece um protocolo consistente para conectar modelos de IA a capacidades externas. Esta padronização beneficia todo o ecossistema: + +- **usuários** desfrutam de experiências mais simples e consistentes em aplicações de IA +- **desenvolvedores de aplicações de IA** ganham fácil integração com um ecossistema crescente de ferramentas e fontes de dados +- **provedores de ferramentas e dados** precisam criar apenas uma única implementação que funcione com múltiplas aplicações de IA +- o ecossistema mais amplo se beneficia de maior interoperabilidade, inovação e redução da fragmentação + +## O Problema de Integração + +O **Problema de Integração M×N** refere-se ao desafio de conectar M diferentes aplicações de IA a N diferentes ferramentas externas ou fontes de dados sem uma abordagem padronizada. + +### Sem o MCP (Problema M×N) + +Sem um protocolo como o MCP, os desenvolvedores precisariam criar M×N integrações personalizadas—uma para cada possível emparelhamento de uma aplicação de IA com uma capacidade externa. + +![Sem o MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/1.png) + +Cada aplicação de IA precisaria integrar-se individualmente com cada ferramenta/fonte de dados. Este é um processo muito complexo e caro que introduz muita fricção para os desenvolvedores e altos custos de manutenção. + +Quando temos múltiplos modelos e múltiplas ferramentas, o número de integrações torna-se grande demais para gerenciar, cada uma com sua própria interface única. + +![Múltiplos Modelos e Ferramentas](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/1a.png) + +### Com o MCP (Solução M+N) + +O MCP transforma isso em um problema M+N ao fornecer uma interface padrão: cada aplicação de IA implementa o lado cliente do MCP uma vez, e cada ferramenta/fonte de dados implementa o lado servidor uma vez. Isso reduz drasticamente a complexidade de integração e a carga de manutenção. + +![Com o MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/2.png) + +Cada aplicação de IA implementa o lado cliente do MCP uma vez, e cada ferramenta/fonte de dados implementa o lado servidor uma vez. + +## Terminologia Básica do MCP + +Agora que entendemos o problema que o MCP resolve, vamos mergulhar na terminologia e conceitos básicos que compõem o protocolo MCP. + + + +O MCP é um padrão como HTTP ou USB-C, e é um protocolo para conectar aplicações de IA a ferramentas e fontes de dados externas. Portanto, usar terminologia padrão é crucial para fazer o MCP funcionar efetivamente. + +Ao documentar nossas aplicações e comunicar com a comunidade, devemos usar a seguinte terminologia. + + + +### Componentes + +Assim como as relações cliente-servidor no HTTP, o MCP tem um cliente e um servidor. + +![Componentes MCP](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/3.png) + +- **Host**: A aplicação de IA voltada para o usuário com a qual os usuários finais interagem diretamente. Exemplos incluem o Claude Desktop da Anthropic, IDEs aprimorados com IA como o Cursor, bibliotecas de inferência como o Hugging Face Python SDK, ou aplicações personalizadas construídas em bibliotecas como LangChain ou smolagents. Os Hosts iniciam conexões com Servidores MCP e orquestram o fluxo geral entre solicitações do usuário, processamento LLM e ferramentas externas. + +- **Cliente**: Um componente dentro da aplicação host que gerencia a comunicação com um Servidor MCP específico. Cada Cliente mantém uma conexão 1:1 com um único Servidor, lidando com os detalhes de nível de protocolo da comunicação MCP e atuando como intermediário entre a lógica do Host e o Servidor externo. + +- **Servidor**: Um programa ou serviço externo que expõe capacidades (Ferramentas, Recursos, Prompts) via protocolo MCP. + + + +Muitos conteúdos usam 'Cliente' e 'Host' de forma intercambiável. Tecnicamente falando, o host é a aplicação voltada para o usuário, e o cliente é o componente dentro da aplicação host que gerencia a comunicação com um Servidor MCP específico. + + + +### Capacidades + +Claro, o valor da sua aplicação é a soma das capacidades que ela oferece. Portanto, as capacidades são a parte mais importante da sua aplicação. Os MCPs podem se conectar com qualquer serviço de software, mas existem algumas capacidades comuns que são usadas para muitas aplicações de IA. + +| Capacidade | Descrição | Exemplo | +| ---------- | ----------- | ------- | +| **Ferramentas** | Funções executáveis que o modelo de IA pode invocar para realizar ações ou recuperar dados computados. Geralmente relacionadas ao caso de uso da aplicação. | Uma ferramenta para uma aplicação de clima pode ser uma função que retorna o clima em um local específico. | +| **Recursos** | Fontes de dados somente leitura que fornecem contexto sem computação significativa. | Um assistente de pesquisa pode ter um recurso para artigos científicos. | +| **Prompts** | Modelos ou fluxos de trabalho predefinidos que orientam interações entre usuários, modelos de IA e as capacidades disponíveis. | Um prompt de resumo. | +| **Amostragem** | Solicitações iniciadas pelo servidor para que o Cliente/Host realize interações LLM, permitindo ações recursivas onde o LLM pode revisar conteúdo gerado e tomar decisões adicionais. | Uma aplicação de escrita revisando sua própria saída e decidindo refiná-la ainda mais. | + +No diagrama a seguir, podemos ver as capacidades coletivas aplicadas a um caso de uso para um agente de código. + +![diagrama coletivo](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/8.png) + +Esta aplicação pode usar suas entidades MCP da seguinte maneira: + +| Entidade | Nome | Descrição | +| --- | --- | --- | +| Ferramenta | Interpretador de Código | Uma ferramenta que pode executar código que o LLM escreve. | +| Recurso | Documentação | Um recurso que contém a documentação da aplicação. | +| Prompt | Estilo de Código | Um prompt que orienta o LLM a gerar código. | +| Amostragem | Revisão de Código | Uma amostragem que permite ao LLM revisar o código e tomar decisões adicionais. | + +### Conclusão + +Entender esses conceitos-chave e terminologia fornece a base para trabalhar com o MCP de forma eficaz. Nas seções seguintes, construiremos sobre essa base para explorar os componentes arquitetônicos, o protocolo de comunicação e as capacidades que compõem o Protocolo de Contexto de Modelo. diff --git a/units/pt/unit1/mcp-clients.mdx b/units/pt/unit1/mcp-clients.mdx new file mode 100644 index 0000000..79616db --- /dev/null +++ b/units/pt/unit1/mcp-clients.mdx @@ -0,0 +1,342 @@ +# Clientes MCP + +Agora que temos um entendimento básico do Protocolo de Contexto de Modelo, podemos explorar o papel essencial dos Clientes MCP no ecossistema do Protocolo de Contexto de Modelo. + +Nesta parte da Unidade 1, exploraremos o papel essencial dos Clientes MCP no ecossistema do Protocolo de Contexto de Modelo. + +Nesta seção, você irá: + +* Entender o que são os Clientes MCP e seu papel na arquitetura MCP +* Aprender sobre as principais responsabilidades dos Clientes MCP +* Explorar as principais implementações de Clientes MCP +* Descobrir como usar a implementação do Cliente MCP do Hugging Face +* Ver exemplos práticos de uso do Cliente MCP + +## Entendendo os Clientes MCP + +Os Clientes MCP são componentes cruciais que atuam como ponte entre aplicações de IA (Hosts) e capacidades externas fornecidas por Servidores MCP. Pense no Host como sua aplicação principal (como um assistente de IA ou IDE) e no Cliente como um módulo especializado dentro desse Host responsável por lidar com as comunicações MCP. + +## Cliente de Interface do Usuário + +Vamos começar explorando os clientes de interface do usuário que estão disponíveis para o MCP. + +### Clientes de Interface de Chat + +O Claude Desktop da Anthropic se destaca como um dos Clientes MCP mais proeminentes, fornecendo integração com vários Servidores MCP. + +### Clientes de Desenvolvimento Interativo + +A implementação do Cliente MCP do Cursor permite assistência de codificação com IA através da integração direta com recursos de edição de código. Ele suporta múltiplas conexões com Servidores MCP e fornece invocação de ferramentas em tempo real durante a codificação, tornando-o uma ferramenta poderosa para desenvolvedores. + +Continue.dev é outro exemplo de cliente de desenvolvimento interativo que suporta MCP e se conecta a um servidor MCP a partir do VS Code. + +## Configurando Clientes MCP + +Agora que abordamos o núcleo do protocolo MCP, vamos ver como configurar seus servidores e clientes MCP. + +A implantação eficaz de servidores e clientes MCP requer configuração adequada. + + + +A especificação MCP ainda está evoluindo, então os métodos de configuração estão sujeitos a evolução. Vamos nos concentrar nas melhores práticas atuais para configuração. + + + +### Arquivos de Configuração MCP + +Os hosts MCP usam arquivos de configuração para gerenciar conexões de servidor. Esses arquivos definem quais servidores estão disponíveis e como se conectar a eles. + +Felizmente, os arquivos de configuração são muito simples, fáceis de entender e consistentes entre os principais hosts MCP. + +#### Estrutura do `mcp.json` + +O arquivo de configuração padrão para MCP é chamado `mcp.json`. Aqui está a estrutura básica: + +```json +{ + "servers": [ + { + "name": "Server Name", + "transport": { + "type": "stdio|sse", + // Transport-specific configuration + } + } + ] +} +``` + +Neste exemplo, temos um único servidor com um nome e um tipo de transporte. O tipo de transporte é `stdio` ou `sse`. + +#### Configuração para Transporte stdio + +Para servidores locais usando transporte stdio, a configuração inclui o comando e argumentos para iniciar o processo do servidor: + +```json +{ + "servers": [ + { + "name": "File Explorer", + "transport": { + "type": "stdio", + "command": "python", + "args": ["/path/to/file_explorer_server.py"] + } + } + ] +} +``` + +Aqui, temos um servidor chamado "File Explorer" que é um script local. + +#### Configuração para Transporte HTTP+SSE + +Para servidores remotos usando transporte HTTP+SSE, a configuração inclui a URL do servidor: + +```json +{ + "servers": [ + { + "name": "Remote API Server", + "transport": { + "type": "sse", + "url": "https://example.com/mcp-server" + } + } + ] +} +``` + +#### Variáveis de Ambiente na Configuração + +Variáveis de ambiente podem ser passadas para processos do servidor usando o campo `env`. Veja como acessá-las no código do seu servidor: + + + + +Em Python, usamos o módulo `os` para acessar variáveis de ambiente: + +```python +import os + +# Access environment variables +github_token = os.environ.get("GITHUB_TOKEN") +if not github_token: + raise ValueError("GITHUB_TOKEN environment variable is required") + +# Use the token in your server code +def make_github_request(): + headers = {"Authorization": f"Bearer {github_token}"} + # ... rest of your code +``` + + + + +Em JavaScript, usamos o objeto `process.env` para acessar variáveis de ambiente: + +```javascript +// Access environment variables +const githubToken = process.env.GITHUB_TOKEN; +if (!githubToken) { + throw new Error("GITHUB_TOKEN environment variable is required"); +} + +// Use the token in your server code +function makeGithubRequest() { + const headers = { "Authorization": `Bearer ${githubToken}` }; + // ... rest of your code +} +``` + + + + +A configuração correspondente em `mcp.json` seria assim: + +```json +{ + "servers": [ + { + "name": "GitHub API", + "transport": { + "type": "stdio", + "command": "python", + "args": ["/path/to/github_server.py"], + "env": { + "GITHUB_TOKEN": "your_github_token" + } + } + } + ] +} +``` + +### Exemplos de Configuração + +Vamos ver alguns cenários de configuração do mundo real: + +#### Cenário 1: Configuração de Servidor Local + +Neste cenário, temos um servidor local que é um script Python que poderia ser um explorador de arquivos ou um editor de código. + +```json +{ + "servers": [ + { + "name": "File Explorer", + "transport": { + "type": "stdio", + "command": "python", + "args": ["/path/to/file_explorer_server.py"] + } + } + ] +} +``` + +#### Cenário 2: Configuração de Servidor Remoto + +Neste cenário, temos um servidor remoto que é uma API de clima. + +```json +{ + "servers": [ + { + "name": "Weather API", + "transport": { + "type": "sse", + "url": "https://example.com/mcp-server" + } + } + ] +} +``` + +A configuração adequada é essencial para implantar integrações MCP com sucesso. Ao entender esses aspectos, você pode criar conexões robustas e confiáveis entre aplicações de IA e capacidades externas. + +Na próxima seção, exploraremos o ecossistema de servidores MCP disponíveis no Hugging Face Hub e como publicar seus próprios servidores lá. + +## Clientes de Código + +Você também pode usar o Cliente MCP dentro do código para que as ferramentas estejam disponíveis para o LLM. Vamos explorar alguns exemplos em `smolagents`. + +Primeiro, vamos explorar nosso servidor de clima da página anterior. Em `smolagents`, podemos usar a classe `ToolCollection` para descobrir e registrar automaticamente ferramentas de um servidor MCP. Isso é feito passando o `StdioServerParameters` ou `SSEServerParameters` para o método `ToolCollection.from_mcp`. Em seguida, podemos imprimir as ferramentas no console. + +```python +from smolagents import ToolCollection +from mcp.client.stdio import StdioServerParameters + +server_parameters = StdioServerParameters(command="uv", args=["run", "server.py"]) + +with ToolCollection.from_mcp( + server_parameters, trust_remote_code=True +) as tools: + print("\n".join(f"{tool.name}: {tool.description}" for tool in tools.tools)) + +``` + +
+ +Saída + + +```sh +get_weather: Get the current weather for a specified location. + +``` + +
+ +Também podemos nos conectar a um servidor MCP que está hospedado em uma máquina remota. Nesse caso, precisamos passar o `SSEServerParameters` para a classe `MCPClient`. + +```python +from smolagents.mcp_client import MCPClient + +with MCPClient( + {"url": "https://abidlabs-mcp-tools.hf.space/gradio_api/mcp/sse"} +) as tools: + # Tools from the remote server are available + print("\n".join(f"{t.name}: {t.description}" for t in tools)) +``` + +
+ +Saída + + +```sh +prime_factors: Compute the prime factorization of a positive integer. +generate_cheetah_image: Generate a cheetah image. +image_orientation: Returns whether image is portrait or landscape. +sepia: Apply a sepia filter to the input image. +``` + +
+ +Agora, vamos ver como podemos usar o Cliente MCP em um agente de código. + +```python +from smolagents import InferenceClientModel, CodeAgent, ToolCollection +from mcp.client.stdio import StdioServerParameters + +model = InferenceClientModel() + +server_parameters = StdioServerParameters(command="uv", args=["run", "server.py"]) + +with ToolCollection.from_mcp( + server_parameters, trust_remote_code=True +) as tool_collection: + agent = CodeAgent(tools=[*tool_collection.tools], model=model) + agent.run("What's the weather in Tokyo?") + +``` + +
+ +Saída + + +```sh +The weather in Tokyo is sunny with a temperature of 20 degrees Celsius. +``` + +
+ +Também podemos nos conectar a um pacote MCP. Aqui está um exemplo de conexão com o pacote `pubmedmcp`. + +```python +import os +from smolagents import ToolCollection, CodeAgent +from mcp import StdioServerParameters + +server_parameters = StdioServerParameters( + command="uv", + args=["--quiet", "pubmedmcp@0.1.3"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tool_collection: + agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True) + agent.run("Please find a remedy for hangover.") +``` + +
+ +Saída + + +```sh +The remedy for hangover is to drink water. +``` + +
+ +## Próximos Passos + +Agora que você entende os Clientes MCP, está pronto para: +* Explorar implementações específicas de Servidores MCP +* Aprender sobre a criação de Clientes MCP personalizados +* Mergulhar em padrões avançados de integração MCP + +Vamos continuar nossa jornada pelo mundo do Protocolo de Contexto de Modelo! diff --git a/units/pt/unit1/quiz1.mdx b/units/pt/unit1/quiz1.mdx new file mode 100644 index 0000000..c5e05b3 --- /dev/null +++ b/units/pt/unit1/quiz1.mdx @@ -0,0 +1,125 @@ +# Quiz 1: Fundamentos do MCP + +Teste seu conhecimento sobre os conceitos fundamentais do Protocolo de Contexto de Modelo. + +### Q1: Qual é o propósito principal do Protocolo de Contexto de Modelo (MCP)? + + + +### Q2: Qual problema o MCP visa resolver principalmente? + + + +### Q3: Qual dos seguintes é um benefício chave do MCP? + + + +### Q4: Na terminologia do MCP, o que é um "Host"? + + + +### Q5: A que se refere o "Problema de Integração M×N" no contexto de aplicações de IA? + + + +Parabéns por concluir este Quiz 🥳! Se precisar revisar algum elemento, aproveite para revisitar o capítulo e reforçar seu conhecimento. diff --git a/units/pt/unit1/quiz2.mdx b/units/pt/unit1/quiz2.mdx new file mode 100644 index 0000000..5a2218f --- /dev/null +++ b/units/pt/unit1/quiz2.mdx @@ -0,0 +1,125 @@ +# Quiz 2: SDK do MCP + +Teste seu conhecimento sobre os SDKs do MCP e suas funcionalidades. + +### Q1: Qual é o principal objetivo dos SDKs do MCP? + + + +### Q2: Qual das seguintes funcionalidades os SDKs do MCP normalmente tratam? + + + +### Q3: De acordo com o texto fornecido, qual empresa mantém o SDK oficial de Python para MCP? + + + +### Q4: Qual comando é usado para iniciar um servidor MCP de desenvolvimento usando um arquivo Python chamado `server.py`? + + + +### Q5: Qual é o papel do JSON-RPC 2.0 no MCP? + + + +Parabéns por concluir este Quiz 🥳! Se precisar revisar algum elemento, aproveite para revisitar o capítulo e reforçar seu conhecimento. diff --git a/units/pt/unit1/sdk.mdx b/units/pt/unit1/sdk.mdx new file mode 100644 index 0000000..4b5fc8b --- /dev/null +++ b/units/pt/unit1/sdk.mdx @@ -0,0 +1,169 @@ +# SDK do MCP + +O Protocolo de Contexto de Modelo fornece SDKs oficiais para JavaScript, Python e outras linguagens. Isso facilita a implementação de clientes e servidores MCP em suas aplicações. Esses SDKs lidam com os detalhes de baixo nível do protocolo, permitindo que você se concentre na construção das capacidades da sua aplicação. + +## Visão Geral do SDK + +Ambos os SDKs fornecem funcionalidades essenciais semelhantes, seguindo a especificação do protocolo MCP que discutimos anteriormente. Eles lidam com: + +- Comunicação em nível de protocolo +- Registro e descoberta de capacidades +- Serialização/desserialização de mensagens +- Gerenciamento de conexões +- Tratamento de erros + +## Implementação de Primitivas Essenciais + +Vamos explorar como implementar cada uma das primitivas essenciais (Ferramentas, Recursos e Prompts) usando ambos os SDKs. + + + + + + +```python +from mcp.server.fastmcp import FastMCP + +# Create an MCP server +mcp = FastMCP("Weather Service") + + +@mcp.tool() +def get_weather(location: str) -> str: + """Get the current weather for a specified location.""" + return f"Weather in {location}: Sunny, 72°F" + + +@mcp.resource("weather://{location}") +def weather_resource(location: str) -> str: + """Provide weather data as a resource.""" + return f"Weather data for {location}: Sunny, 72°F" + + +@mcp.prompt() +def weather_report(location: str) -> str: + """Create a weather report prompt.""" + return f"""You are a weather reporter. Weather report for {location}?""" + + +# Run the server +if __name__ == "__main__": + mcp.run() + +``` + + + + +```javascript +import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { z } from "zod"; + +// Create an MCP server +const server = new McpServer({ + name: "Weather Service", + version: "1.0.0" +}); + +// Tool implementation +server.tool("get_weather", + { location: z.string() }, + async ({ location }) => ({ + content: [{ + type: "text", + text: `Weather in ${location}: Sunny, 72°F` + }] + }) +); + +// Resource implementation +server.resource( + "weather", + new ResourceTemplate("weather://{location}", { list: undefined }), + async (uri, { location }) => ({ + contents: [{ + uri: uri.href, + text: `Weather data for ${location}: Sunny, 72°F` + }] + }) +); + +// Prompt implementation +server.prompt( + "weather_report", + { location: z.string() }, + async ({ location }) => ({ + messages: [ + { + role: "assistant", + content: { + type: "text", + text: "You are a weather reporter." + } + }, + { + role: "user", + content: { + type: "text", + text: `Weather report for ${location}?` + } + } + ] + }) +); + +// Run the server +const transport = new StdioServerTransport(); +await server.connect(transport); +``` + + + + +Uma vez que você tenha implementado seu servidor, você pode iniciá-lo executando o script do servidor. + +```bash +mcp dev server.py +``` + +Isso inicializará um servidor de desenvolvimento executando o arquivo `server.py`. E registrará a seguinte saída: + +```bash +Starting MCP inspector... +⚙️ Proxy server listening on port 6277 +Spawned stdio transport +Connected MCP client to backing server transport +Created web app transport +Set up MCP proxy +🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀 +``` + +Você pode então abrir o MCP Inspector em [http://127.0.0.1:6274](http://127.0.0.1:6274) para ver as capacidades do servidor e interagir com elas. + +Você verá as capacidades do servidor e a possibilidade de chamá-las através da UI. + +![MCP Inspector](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit1/6.png) + +## SDKs do MCP + +O MCP foi projetado para ser agnóstico em relação à linguagem, e existem SDKs oficiais disponíveis para várias linguagens de programação populares: + +| Linguagem | Repositório | Mantenedor(es) | Status | +|----------|------------|---------------|--------| +| TypeScript | [github.com/modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) | Anthropic | Ativo | +| Python | [github.com/modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) | Anthropic | Ativo | +| Java | [github.com/modelcontextprotocol/java-sdk](https://github.com/modelcontextprotocol/java-sdk) | Spring AI (VMware) | Ativo | +| Kotlin | [github.com/modelcontextprotocol/kotlin-sdk](https://github.com/modelcontextprotocol/kotlin-sdk) | JetBrains | Ativo | +| C# | [github.com/modelcontextprotocol/csharp-sdk](https://github.com/modelcontextprotocol/csharp-sdk) | Microsoft | Ativo (Preview) | +| Swift | [github.com/modelcontextprotocol/swift-sdk](https://github.com/modelcontextprotocol/swift-sdk) | loopwork-ai | Ativo | +| Rust | [github.com/modelcontextprotocol/rust-sdk](https://github.com/modelcontextprotocol/rust-sdk) | Anthropic/Comunidade | Ativo | +| Dart | [https://github.com/leehack/mcp_dart](https://github.com/leehack/mcp_dart) | Comunidade Flutter | Ativo | + +Esses SDKs fornecem abstrações específicas de linguagem que simplificam o trabalho com o protocolo MCP, permitindo que você se concentre na implementação da lógica central de seus servidores ou clientes, em vez de lidar com detalhes de protocolo de baixo nível. + +## Próximos Passos + +Apenas arranhamos a superfície do que você pode fazer com o MCP, mas você já tem um servidor básico em execução. Na verdade, você também se conectou a ele usando o Cliente MCP no navegador. + +Na próxima seção, veremos como conectar seu servidor a um LLM. diff --git a/units/pt/unit2/clients.mdx b/units/pt/unit2/clients.mdx new file mode 100644 index 0000000..1f72377 --- /dev/null +++ b/units/pt/unit2/clients.mdx @@ -0,0 +1,79 @@ +# Construindo Clientes MCP + +Nesta seção, criaremos clientes que podem interagir com nosso servidor MCP usando diferentes linguagens de programação. Implementaremos tanto um cliente JavaScript usando HuggingFace.js quanto um cliente Python usando smolagents. + +## Configurando Clientes MCP + +A implantação eficaz de servidores e clientes MCP requer uma configuração adequada. A especificação MCP ainda está evoluindo, então os métodos de configuração estão sujeitos a mudanças. Vamos nos concentrar nas melhores práticas atuais para configuração. + +### Arquivos de Configuração MCP + +Hosts MCP usam arquivos de configuração para gerenciar conexões com servidores. Esses arquivos definem quais servidores estão disponíveis e como se conectar a eles. + +Os arquivos de configuração são muito simples, fáceis de entender e consistentes entre os principais hosts MCP. + +#### Estrutura do `mcp.json` + +O arquivo de configuração padrão para MCP é chamado `mcp.json`. Aqui está a estrutura básica: + +```json +{ + "servers": [ + { + "name": "MCP Server", + "transport": { + "type": "sse", + "url": "http://localhost:7860/gradio_api/mcp/sse" + } + } + ] +} +``` + +Neste exemplo, temos um único servidor configurado para usar o transporte SSE, conectando-se a um servidor Gradio local rodando na porta 7860. + + + +Nos conectamos ao aplicativo Gradio via transporte SSE porque assumimos que o aplicativo gradio está sendo executado em um servidor remoto. No entanto, se você quiser se conectar a um script local, o transporte `stdio` em vez do transporte `sse` é uma opção melhor. + + + +#### Configuração para Transporte HTTP+SSE + +Para servidores remotos usando o transporte HTTP+SSE, a configuração inclui a URL do servidor: + +```json +{ + "servers": [ + { + "name": "Remote MCP Server", + "transport": { + "type": "sse", + "url": "https://example.com/gradio_api/mcp/sse" + } + } + ] +} +``` + +Essa configuração permite que seu cliente de interface do usuário se comunique com o servidor MCP do Gradio usando o protocolo MCP, permitindo uma integração perfeita entre seu frontend e o serviço MCP. + +## Configurando um Cliente MCP de Interface do Usuário + +Ao trabalhar com servidores Gradio MCP, você pode configurar seu cliente de interface do usuário para se conectar ao servidor usando o protocolo MCP. Veja como configurá-lo: + +### Configuração Básica + +Crie um novo arquivo chamado `config.json` com a seguinte configuração: + +```json +{ + "mcpServers": { + "mcp": { + "url": "http://localhost:7860/gradio_api/mcp/sse" + } + } +} +``` + +Esta configuração permite que seu cliente de interface do usuário se comunique com o servidor MCP do Gradio usando o protocolo MCP, permitindo uma integração perfeita entre seu frontend e o serviço MCP. diff --git a/units/pt/unit2/gradio-client.mdx b/units/pt/unit2/gradio-client.mdx new file mode 100644 index 0000000..8e49f67 --- /dev/null +++ b/units/pt/unit2/gradio-client.mdx @@ -0,0 +1,139 @@ +# Gradio como Cliente MCP + +Na seção anterior, exploramos como criar um Servidor MCP usando Gradio e como se conectar a ele usando um Cliente MCP. Nesta seção, vamos explorar como usar o Gradio como um Cliente MCP para se conectar a um Servidor MCP. + + + +O Gradio é mais adequado para a criação de clientes de interface do usuário e servidores MCP, mas também é possível usá-lo como Cliente MCP e expor isso como uma interface de usuário. + + + +Vamos nos conectar ao servidor MCP que criamos na seção anterior e usá-lo para responder perguntas. + +## Cliente MCP no Gradio + +Primeiro, precisamos instalar as bibliotecas `smolagents`, gradio e mcp-client, se ainda não as tivermos: + +```bash +pip install "smolagents[mcp]" "gradio[mcp]" mcp +``` + +Agora, podemos importar as bibliotecas necessárias e criar uma interface Gradio simples que usa o Cliente MCP para se conectar ao Servidor MCP. + + +```python +import gradio as gr + +from mcp.client.stdio import StdioServerParameters +from smolagents import InferenceClientModel, CodeAgent, ToolCollection +from smolagents.mcp_client import MCPClient +``` + +Em seguida, vamos nos conectar ao Servidor MCP e obter as ferramentas que podemos usar para responder perguntas. + +```python +mcp_client = MCPClient( + {"url": "http://localhost:7860/gradio_api/mcp/sse"} +) +tools = mcp_client.get_tools() +``` + +Agora que temos as ferramentas, podemos criar um agente simples que as usa para responder perguntas. Vamos usar um simples `InferenceClientModel` e o modelo padrão do `smolagents` por enquanto. + +```python +model = InferenceClientModel() +agent = CodeAgent(tools=[*tools], model=model) +``` + +Agora, podemos criar uma interface Gradio simples que usa o agente para responder perguntas. + +```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="This is a simple agent that uses MCP tools to answer questions.", + messages=[], +) + +demo.launch() +``` + +E é isso! Criamos uma interface Gradio simples que usa o Cliente MCP para se conectar ao Servidor MCP e responder perguntas. + + + + +## Exemplo Completo + +Aqui está o exemplo completo do Cliente MCP no Gradio: + +```python +import gradio as gr + +from mcp.client.stdio import StdioServerParameters +from smolagents import InferenceClientModel, CodeAgent, ToolCollection +from smolagents.mcp_client import MCPClient + + +try: + mcp_client = MCPClient( + ## Experimente este exemplo funcional no hub: + # {"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) + + demo = gr.ChatInterface( + fn=lambda message, history: str(agent.run(message)), + type="messages", + examples=["Prime factorization of 68"], + title="Agent with MCP Tools", + description="This is a simple agent that uses MCP tools to answer questions.", + ) + + demo.launch() +finally: + mcp_client.disconnect() +``` + +Observe que estamos fechando o Cliente MCP no bloco `finally`. Isso é importante porque o Cliente MCP é um objeto de vida longa que precisa ser fechado quando o programa é encerrado. + +## Implantando no Hugging Face Spaces + +Para disponibilizar seu servidor para outras pessoas, você pode implantá-lo no Hugging Face Spaces, assim como fizemos na seção anterior. +Para implantar seu cliente MCP Gradio no Hugging Face Spaces: + +1. Crie um novo Space no Hugging Face: + - Acesse huggingface.co/spaces + - Clique em "Create new Space" + - Escolha "Gradio" como SDK + - Nomeie seu space (ex: "mcp-client") + +2. Crie um arquivo `requirements.txt`: +```txt +gradio[mcp] +smolagents[mcp] +``` + +3. Envie seu código para o 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 +``` + +## Conclusão + +Nesta seção, exploramos como usar o Gradio como um Cliente MCP para se conectar a um Servidor MCP. Também vimos como implantar o Cliente MCP no Hugging Face Spaces. diff --git a/units/pt/unit2/gradio-server.mdx b/units/pt/unit2/gradio-server.mdx new file mode 100644 index 0000000..cd8c861 --- /dev/null +++ b/units/pt/unit2/gradio-server.mdx @@ -0,0 +1,190 @@ +# Construindo o Servidor MCP com Gradio + +Nesta seção, criaremos nosso servidor MCP de análise de sentimentos usando Gradio. Este servidor irá expor uma ferramenta de análise de sentimentos que pode ser usada tanto por usuários humanos através de uma interface web quanto por modelos de IA através do protocolo MCP. + +## Introdução à Integração Gradio MCP + +Gradio fornece uma maneira direta de criar servidores MCP, convertendo automaticamente suas funções Python em ferramentas MCP. Quando você configura `mcp_server=True` em `launch()`, o Gradio: + +1. Converte automaticamente suas funções em Ferramentas MCP +2. Mapeia os componentes de entrada para esquemas de argumentos de ferramentas +3. Determina os formatos de resposta a partir dos componentes de saída +4. Configura JSON-RPC sobre HTTP+SSE para comunicação cliente-servidor +5. Cria tanto uma interface web quanto um endpoint de servidor MCP + +## Configurando o Projeto + +Primeiro, vamos criar um novo diretório para nosso projeto e configurar as dependências necessárias: + +```bash +mkdir mcp-sentiment +cd mcp-sentiment +python -m venv venv +source venv/bin/activate # No Windows: venv\Scripts\activate +pip install "gradio[mcp]" textblob +``` + +## Criando o Servidor + +> Os espaços do Hugging Face precisam de um arquivo app.py para construir o espaço. Portanto, o nome do arquivo Python deve ser app.py + +Crie um novo arquivo chamado `app.py` com o seguinte código: + +```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 (negativo) a 1 (positivo) + "subjectivity": round(sentiment.subjectivity, 2), # 0 (objetivo) a 1 (subjetivo) + "assessment": "positive" if sentiment.polarity > 0 else "negative" if sentiment.polarity < 0 else "neutral" + } + +# Criar a interface Gradio +demo = gr.Interface( + fn=sentiment_analysis, + inputs=gr.Textbox(placeholder="Digite um texto para analisar..."), + outputs=gr.JSON(), + title="Análise de Sentimento de Texto", + description="Analise o sentimento de um texto usando TextBlob" +) + +# Iniciar a interface e o servidor MCP +if __name__ == "__main__": + demo.launch(mcp_server=True) +``` + +## Entendendo o Código + +Vamos decompor os componentes principais: + +1. **Definição da Função**: + - A função `sentiment_analysis` recebe uma entrada de texto e retorna um dicionário + - Ela usa TextBlob para analisar o sentimento + - A docstring é crucial, pois ajuda o Gradio a gerar o esquema da ferramenta MCP + - As dicas de tipo (`str` e `dict`) ajudam a definir o esquema de entrada/saída + +2. **Interface Gradio**: + - `gr.Interface` cria tanto a UI web quanto o servidor MCP + - A função é exposta automaticamente como uma ferramenta MCP + - Os componentes de entrada e saída definem o esquema da ferramenta + - O componente de saída JSON garante a serialização adequada + +3. **Servidor MCP**: + - Definir `mcp_server=True` habilita o servidor MCP + - O servidor estará disponível em `http://localhost:7860/gradio_api/mcp/sse` + - Você também pode habilitá-lo usando a variável de ambiente: + ```bash + export GRADIO_MCP_SERVER=True + ``` + +## Executando o Servidor + +Inicie o servidor executando: + +```bash +python app.py +``` + +Você deverá ver uma saída indicando que tanto a interface web quanto o servidor MCP estão em execução. A interface web estará disponível em `http://localhost:7860` e o servidor MCP em `http://localhost:7860/gradio_api/mcp/sse`. + +## Testando o Servidor + +Você pode testar o servidor de duas maneiras: + +1. **Interface Web**: + - Abra `http://localhost:7860` em seu navegador + - Digite algum texto e clique em "Enviar" + - Você deverá ver os resultados da análise de sentimento + +2. **Esquema MCP**: + - Visite `http://localhost:7860/gradio_api/mcp/schema` + - Isso mostra o esquema da ferramenta MCP que os clientes usarão + - Você também pode encontrar isso no link "View API" no rodapé do seu aplicativo Gradio + +## Dicas de Solução de Problemas + +1. **Dicas de Tipo e Docstrings**: + - Sempre forneça dicas de tipo para os parâmetros e valores de retorno da sua função + - Inclua uma docstring com um bloco "Args:" para cada parâmetro + - Isso ajuda o Gradio a gerar esquemas de ferramentas MCP precisos + +2. **Entradas de String**: + - Em caso de dúvida, aceite argumentos de entrada como `str` + - Converta-os para o tipo desejado dentro da função + - Isso proporciona melhor compatibilidade com clientes MCP + +3. **Suporte a SSE**: + - Alguns clientes MCP não suportam Servidores MCP baseados em SSE + - Nesses casos, use `mcp-remote`: + ```json + { + "mcpServers": { + "gradio": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:7860/gradio_api/mcp/sse" + ] + } + } + } + ``` + +4. **Problemas de Conexão**: + - Se encontrar problemas de conexão, tente reiniciar tanto o cliente quanto o servidor + - Verifique se o servidor está em execução e acessível + - Verifique se o esquema MCP está disponível na URL esperada + +## Implantando no Hugging Face Spaces + +Para disponibilizar seu servidor para outras pessoas, você pode implantá-lo no Hugging Face Spaces: + +1. Crie um novo Space no Hugging Face: + - Acesse huggingface.co/spaces + - Clique em "Create new Space" + - Escolha "Gradio" como SDK + - Nomeie seu space (ex: "mcp-sentiment") + +2. Crie um arquivo `requirements.txt`: +```txt +gradio[mcp] +textblob +``` + +3. Envie seu código para o Space: +```bash +git init +git add app.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 +``` + +Seu servidor MCP agora estará disponível em: +``` +https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse +``` + +## Próximos Passos + +Agora que temos nosso servidor MCP em execução, criaremos clientes para interagir com ele. Nas próximas seções, vamos: + +1. Criar um cliente baseado em HuggingFace.js inspirado no Tiny Agents +2. Implementar um cliente Python baseado em SmolAgents +3. Testar ambos os clientes com nosso servidor implantado + +Vamos avançar para construir nosso primeiro cliente! diff --git a/units/pt/unit2/introduction.mdx b/units/pt/unit2/introduction.mdx new file mode 100644 index 0000000..dc4e023 --- /dev/null +++ b/units/pt/unit2/introduction.mdx @@ -0,0 +1,64 @@ +# Construindo uma Aplicação MCP Completa + +Bem-vindo à Unidade 2 do Curso MCP! + +Nesta unidade, construiremos uma aplicação MCP completa do zero, focando na criação de um servidor com Gradio e conectando-o a múltiplos clientes. Esta abordagem prática lhe dará experiência com todo o ecossistema MCP. + + + +Nesta unidade, vamos construir um servidor e cliente MCP simples usando Gradio e o Hugging Face Hub. Na próxima unidade, construiremos um servidor mais complexo que aborda um caso de uso do mundo real. + + + +## O Que Você Aprenderá + +Nesta unidade, você irá: + +- Criar um Servidor MCP usando o suporte integrado do Gradio ao MCP +- Construir uma ferramenta de análise de sentimentos que pode ser usada por modelos de IA +- Conectar-se ao servidor usando diferentes implementações de cliente: + - Um cliente baseado em HuggingFace.js + - Um cliente baseado em SmolAgents para Python +- Implantar seu Servidor MCP no Hugging Face Spaces +- Testar e depurar o sistema completo + +Ao final desta unidade, você terá uma aplicação MCP funcional que demonstra o poder e a flexibilidade do protocolo. + +## Pré-requisitos + +Antes de prosseguir com esta unidade, certifique-se de que você: + +- Concluiu a Unidade 1 ou tem um entendimento básico dos conceitos MCP +- Está confortável com Python e JavaScript/TypeScript +- Tem um entendimento básico de APIs e arquitetura cliente-servidor +- Tem um ambiente de desenvolvimento com: + - Python 3.10+ + - Node.js 18+ + - Uma conta Hugging Face (para implantação) + +## Nosso Projeto Completo + +Construiremos uma aplicação de análise de sentimentos que consiste em três partes principais: o servidor, o cliente e a implantação. + +![aplicação de análise de sentimentos](https://huggingface.co/datasets/mcp-course/images/resolve/main/unit2/1.png) + +### Lado do Servidor + +- Usa Gradio para criar uma interface web e um servidor MCP via `gr.Interface` +- Implementa uma ferramenta de análise de sentimentos usando TextBlob +- Expõe a ferramenta através dos protocolos HTTP e MCP + +### Lado do Cliente + +- Implementa um cliente HuggingFace.js +- Ou, cria um cliente Python smolagents +- Demonstra como usar o mesmo servidor com diferentes implementações de cliente + +### Implantação + +- Implanta o servidor no Hugging Face Spaces +- Configura os clientes para trabalhar com o servidor implantado + +## Vamos Começar! + +Você está pronto para construir sua primeira aplicação MCP completa? Vamos começar configurando o ambiente de desenvolvimento e criando nosso servidor MCP Gradio. diff --git a/units/pt/unit2/tiny-agents.mdx b/units/pt/unit2/tiny-agents.mdx new file mode 100644 index 0000000..f4105b5 --- /dev/null +++ b/units/pt/unit2/tiny-agents.mdx @@ -0,0 +1,556 @@ +# Tiny Agents: um agente MCP em 50 linhas de código + +Agora que construímos servidores MCP no Gradio e aprendemos sobre a criação de clientes MCP, vamos completar nossa aplicação completa construindo um agente TypeScript que pode interagir perfeitamente com nossa ferramenta de análise de sentimentos. Esta seção é baseada no projeto [Tiny Agents](https://huggingface.co/blog/tiny-agents), que demonstra uma maneira super simples de implantar clientes MCP que podem se conectar a serviços como nosso servidor de análise de sentimentos Gradio. + +Neste exercício final da Unidade 2, vamos orientá-lo na implementação de um cliente MCP TypeScript (JS) que pode se comunicar com qualquer servidor MCP, incluindo o servidor de análise de sentimentos baseado em Gradio que construímos nas seções anteriores. Isso completa nosso fluxo de aplicação MCP completo: desde a construção de um servidor MCP Gradio expondo uma ferramenta de análise de sentimentos, até a criação de um agente flexível que pode usar esta ferramenta junto com outras capacidades. + +![meme](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/thumbnail.jpg) +
Crédito da imagem https://x.com/adamdotdev
+ +## Instalação + +Primeiro, precisamos instalar o pacote `tiny-agents`. + +```bash +npm install @huggingface/tiny-agents +# ou +pnpm add @huggingface/tiny-agents +``` + +Em seguida, precisamos instalar o pacote `mcp-remote`. + +```bash +npm install @mcpjs/mcp-remote +# ou +pnpm add @mcpjs/mcp-remote +``` + +## Cliente MCP Tiny Agents na Linha de Comando + +Tiny Agents pode criar clientes MCP a partir da linha de comando com base em arquivos de configuração JSON. + +Vamos configurar um projeto com um Tiny Agent básico. + +```bash +mkdir my-agent +touch my-agent/agent.json +``` + +O arquivo JSON ficará assim: + +```json +{ + "model": "Qwen/Qwen2.5-72B-Instruct", + "provider": "nebius", + "servers": [ + { + "type": "stdio", + "config": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:7860/gradio_api/mcp/sse" + ] + } + } + ] +} +``` + +Aqui temos um Tiny Agent básico que pode se conectar ao nosso servidor MCP Gradio. Ele inclui um modelo, provedor e uma configuração de servidor. + +| Campo | Descrição | +|-------|-------------| +| `model` | O modelo de código aberto a ser usado pelo agente | +| `provider` | O provedor de inferência a ser usado pelo agente | +| `servers` | Os servidores a serem usados pelo agente. Usaremos o servidor `mcp-remote` para nosso servidor MCP Gradio. | + +Também poderíamos usar um modelo de código aberto executando localmente com Tiny Agents. + +```json +{ + "model": "Qwen/Qwen3-32B", + "endpointUrl": "http://localhost:1234/v1", + "servers": [ + { + "type": "stdio", + "config": { + "command": "npx", + "args": [ + "mcp-remote", + "http://localhost:1234/v1/mcp/sse" + ] + } + } + ] +} +``` + +Aqui temos um Tiny Agent que pode se conectar a um modelo local. Ele inclui um modelo, URL de endpoint (`http://localhost:1234/v1`) e uma configuração de servidor. O endpoint deve ser um endpoint compatível com OpenAI. + +Podemos então executar o agente com o seguinte comando: + +```bash +npx @huggingface/tiny-agents run ./my-agent +``` + +## Cliente MCP Tiny Agents Personalizado + +Agora que entendemos tanto os Tiny Agents quanto os servidores MCP Gradio, vamos ver como eles funcionam juntos! A beleza do MCP é que ele fornece uma maneira padronizada para os agentes interagirem com qualquer servidor compatível com MCP, incluindo nosso servidor de análise de sentimentos baseado em Gradio das seções anteriores. + +### Usando o Servidor Gradio com Tiny Agents + +Para conectar nosso Tiny Agent ao servidor de análise de sentimentos Gradio que construímos anteriormente nesta unidade, só precisamos adicioná-lo à nossa lista de servidores. Veja como podemos modificar nossa configuração de agente: + +```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: [ + // ... servidores existentes ... + { + command: "npx", + args: [ + "mcp-remote", + "http://localhost:7860/gradio_api/mcp/sse" // Seu servidor MCP Gradio + ] + } + ], +}); +``` + +Agora nosso agente pode usar a ferramenta de análise de sentimentos junto com outras ferramentas! Por exemplo, ele poderia: +1. Ler texto de um arquivo usando o servidor de sistema de arquivos +2. Analisar seu sentimento usando nosso servidor Gradio +3. Escrever os resultados de volta em um arquivo + +### Exemplo de Interação + +Veja como seria uma conversa com nosso agente: + +``` +Usuário: Leia o arquivo "feedback.txt" do meu Desktop e analise seu sentimento + +Agente: Vou ajudá-lo a analisar o sentimento do arquivo de feedback. Vou dividir isso em etapas: + +1. Primeiro, vou ler o arquivo usando a ferramenta do sistema de arquivos +2. Em seguida, vou analisar seu sentimento usando a ferramenta de análise de sentimentos +3. Por fim, vou escrever os resultados em um novo arquivo + +[O Agente prossegue usando as ferramentas e fornecendo a análise] +``` + +### Considerações de Implantação + +Ao implantar seu servidor MCP Gradio no Hugging Face Spaces, você precisará atualizar a URL do servidor em sua configuração de agente para apontar para seu espaço implantado: + +```ts +{ + command: "npx", + args: [ + "mcp-remote", + "https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse" + ] +} +``` + +Isso permite que seu agente use a ferramenta de análise de sentimentos de qualquer lugar, não apenas localmente! + +## Conclusão: Nossa Aplicação MCP Completa + +Nesta unidade, passamos do entendimento dos conceitos básicos do MCP para a construção de uma aplicação completa: + +1. Criamos um servidor MCP Gradio que expõe uma ferramenta de análise de sentimentos +2. Aprendemos como se conectar a este servidor usando clientes MCP +3. Construímos um tiny agent em TypeScript que pode interagir com nossa ferramenta + +Isso demonstra o poder do Protocolo de Contexto de Modelo - podemos criar ferramentas especializadas usando frameworks com os quais estamos familiarizados (como Gradio), expô-las através de uma interface padronizada (MCP) e, em seguida, ter agentes usando essas ferramentas perfeitamente junto com outras capacidades. + +O fluxo completo que construímos permite que um agente: +- Se conecte a múltiplos provedores de ferramentas +- Descubra dinamicamente as ferramentas disponíveis +- Use nossa ferramenta personalizada de análise de sentimentos +- Combine-a com outras capacidades como acesso ao sistema de arquivos e navegação na web + +Esta abordagem modular é o que torna o MCP tão poderoso para construir aplicações de IA flexíveis. + +## Bônus: Construir um Servidor MCP de Automação de Navegador com Playwright + +Como bônus, vamos explorar como usar o servidor MCP Playwright para automação de navegador com Tiny Agents. Isso demonstra a extensibilidade do ecossistema MCP além do nosso exemplo de análise de sentimentos. + + + +Esta seção é baseada no [post do blog Tiny Agents](https://huggingface.co/blog/tiny-agents) e adaptada para o curso MCP. + + + +Nesta seção, mostraremos como construir um agente que pode realizar tarefas de automação web como pesquisar, clicar e extrair informações de sites. + +```ts +// playwright-agent.ts +import { Agent } from "@huggingface/tiny-agents"; + +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: [ + { + command: "npx", + args: ["playwright-mcp"] + } + ], +}); + +await agent.run(); +``` + +O servidor MCP Playwright expõe ferramentas que permitem que seu agente: + +1. Abra abas do navegador +2. Navegue para URLs +3. Clique em elementos +4. Digite em formulários +5. Extraia conteúdo de páginas web +6. Tire capturas de tela + +Veja um exemplo de interação com nosso agente de automação de navegador: + +``` +Usuário: Pesquise por "tiny agents" no GitHub e colete os nomes dos 3 principais repositórios + +Agente: Vou pesquisar repositórios de "tiny agents" no GitHub. +[O Agente abre o navegador, navega até o GitHub, realiza a pesquisa e extrai os nomes dos repositórios] + +Aqui estão os 3 principais repositórios (não reais) para "tiny agents": +1. huggingface/tiny-agents +2. modelcontextprotocol/tiny-agents-examples +3. langchain/tiny-agents-js +``` + +Esta capacidade de automação de navegador pode ser combinada com outros servidores MCP para criar fluxos de trabalho poderosos—por exemplo, extraindo texto de uma página web e depois analisando-o com ferramentas personalizadas. + +## Como executar a demonstração completa + +Se você tem NodeJS (com `pnpm` ou `npm`), basta executar isto em um terminal: + +```bash +npx @huggingface/mcp-client +``` + +ou se estiver usando `pnpm`: + +```bash +pnpx @huggingface/mcp-client +``` + +Isso instala o pacote em uma pasta temporária e depois executa seu comando. + +Você verá seu Agente simples se conectar a múltiplos servidores MCP (executando localmente), carregando suas ferramentas (semelhante a como carregaria sua ferramenta de análise de sentimentos Gradio), e depois solicitando uma conversa. + + + +Por padrão, nosso Agente de exemplo se conecta aos seguintes dois servidores MCP: + +- o servidor de sistema de arquivos [canônico](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), que obtém acesso ao seu Desktop, +- e o servidor [Playwright MCP](https://github.com/microsoft/playwright-mcp), que sabe como usar um navegador Chromium sandbox para você. + +> [!NOTE] +> Nota: isso é um pouco contraintuitivo, mas atualmente, todos os servidores MCP no tiny agents são processos locais (embora servidores remotos estejam chegando em breve). + +Nossa entrada para este primeiro vídeo foi: + +> escreva um haiku sobre a comunidade Hugging Face e escreva-o em um arquivo chamado "hf.txt" no meu Desktop + +Agora vamos tentar este prompt que envolve navegação na Web: + +> faça uma Pesquisa Web por provedores de inferência HF no Brave Search e abra os 3 primeiros resultados + + + +### Modelo e provedor padrão + +Em termos de par modelo/provedor, nosso Agente de exemplo usa por padrão: +- ["Qwen/Qwen2.5-72B-Instruct"](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct) +- executando no [Nebius](https://huggingface.co/docs/inference-providers/providers/nebius) + +Tudo isso é configurável através de variáveis de ambiente: + +```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: [ + // Servidores padrão + { + command: "npx", + args: ["@modelcontextprotocol/servers", "filesystem"] + }, + { + command: "npx", + args: ["playwright-mcp"] + }, + ], +}); +``` + +## Implementando um cliente MCP em cima do InferenceClient + +Agora que sabemos o que é uma ferramenta em LLMs recentes, vamos implementar o cliente MCP real que se comunicará com servidores MCP e outros servidores MCP. + +A documentação oficial em https://modelcontextprotocol.io/quickstart/client é bastante bem escrita. Você só precisa substituir qualquer menção ao SDK do cliente Anthropic por qualquer outro SDK de cliente compatível com OpenAI. (Há também um [llms.txt](https://modelcontextprotocol.io/llms-full.txt) que você pode alimentar no seu LLM de escolha para ajudá-lo a codificar). + +Como lembrete, usamos o `InferenceClient` do HF para nosso cliente de inferência. + +> [!TIP] +> O arquivo de código completo `McpClient.ts` está [aqui](https://github.com/huggingface/huggingface.js/blob/main/packages/mcp-client/src/McpClient.ts) se você quiser acompanhar usando o código real 🤓 + +Nossa classe `McpClient` tem: +- um Cliente de Inferência (funciona com qualquer Provedor de Inferência, e `huggingface/inference` suporta endpoints remotos e locais) +- um conjunto de sessões de cliente MCP, uma para cada servidor MCP conectado (isso nos permite conectar a múltiplos servidores) +- e uma lista de ferramentas disponíveis que será preenchida a partir dos servidores conectados e apenas ligeiramente reformatada. + +```ts +export class McpClient { + protected client: InferenceClient; + protected provider: string; + protected model: string; + private clients: Map = 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; + } + + // [...] +} +``` + +Para se conectar a um servidor MCP, o SDK TypeScript oficial `@modelcontextprotocol/sdk/client` fornece uma classe `Client` com um método `listTools()`: + +```ts +async addMcpServer(server: StdioServerParameters): Promise { + 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` é uma interface do SDK MCP que permitirá que você facilmente inicie um processo local: como mencionamos anteriormente, atualmente, todos os servidores MCP são processos locais. + +### Como usar as ferramentas + +Usar nossa ferramenta de análise de sentimentos (ou qualquer outra ferramenta MCP) é simples. Você apenas passa `this.availableTools` para a conclusão de chat do seu LLM, além do seu array habitual de mensagens: + +```ts +const stream = this.client.chatCompletionStream({ + provider: this.provider, + model: this.model, + messages, + tools: this.availableTools, + tool_choice: "auto", +}); +``` + +`tool_choice: "auto"` é o parâmetro que você passa para o LLM gerar zero, uma ou múltiplas chamadas de ferramentas. + +Ao analisar ou transmitir a saída, o LLM gerará algumas chamadas de ferramentas (ou seja, um nome de função e alguns argumentos codificados em JSON), que você (como desenvolvedor) precisa computar. O SDK cliente MCP novamente facilita isso; ele tem um método `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, +}; + +/// Obter a sessão apropriada para esta ferramenta +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}`; +} +``` + +Se o LLM escolher usar uma ferramenta, este código automaticamente encaminhará a chamada para o servidor MCP, executará a análise e retornará o resultado ao LLM. + +Finalmente, você adicionará a mensagem de ferramenta resultante ao seu array `messages` e de volta ao LLM. + +## Nosso Agente de 50 linhas de código 🤯 + +Agora que temos um cliente MCP capaz de se conectar a servidores MCP arbitrários para obter listas de ferramentas e capaz de injetá-las e analisá-las da inferência do LLM, bem... o que é um Agente? + +> Uma vez que você tem um cliente de inferência com um conjunto de ferramentas, então um Agente é apenas um loop while em cima dele. + +Em mais detalhes, um Agente é simplesmente uma combinação de: +- um prompt de sistema +- um cliente de inferência LLM +- um cliente MCP para conectar um conjunto de Ferramentas a partir de vários servidores MCP +- algum fluxo de controle básico (veja abaixo para o loop while) + +> [!TIP] +> O arquivo de código completo `Agent.ts` está [aqui](https://github.com/huggingface/huggingface.js/blob/main/packages/mcp-client/src/Agent.ts). + +Nossa classe Agent simplesmente estende 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, + }, + ]; + } +} +``` + +Por padrão, usamos um prompt de sistema muito simples inspirado no compartilhado no [guia de prompting do GPT-4.1](https://cookbook.openai.com/examples/gpt4-1_prompting_guide). + +Mesmo que isso venha da OpenAI 😈, esta frase em particular se aplica a cada vez mais modelos, tanto fechados quanto abertos: + +> Incentivamos os desenvolvedores a usar exclusivamente o campo tools para passar ferramentas, em vez de injetar manualmente descrições de ferramentas em seu prompt e escrever um analisador separado para chamadas de ferramentas, como alguns relataram fazer no passado. + +O que quer dizer, não precisamos fornecer listas meticulosamente formatadas de exemplos de uso de ferramentas no prompt. O parâmetro `tools: this.availableTools` é suficiente, e o LLM saberá como usar as ferramentas do sistema de arquivos. + +Carregar as ferramentas no Agente é literalmente apenas conectar-se aos servidores MCP que queremos (em paralelo porque é tão fácil de fazer em JS): + +```ts +async loadTools(): Promise { + await Promise.all(this.servers.map((s) => this.addMcpServer(s))); +} +``` + +Adicionamos duas ferramentas extras (fora do MCP) que podem ser usadas pelo LLM para o fluxo de controle do nosso Agente: + +```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]; +``` + +Ao chamar qualquer uma dessas ferramentas, o Agente quebrará seu loop e devolverá o controle ao usuário para nova entrada. + +### O loop while completo + +Contemplem nosso loop while completo.🎉 + +A essência do loop principal do nosso Agente é que simplesmente iteramos com o LLM alternando entre chamadas de ferramentas e alimentando-o com os resultados das ferramentas, e fazemos isso **até que o LLM comece a responder com duas mensagens não-ferramentas consecutivas**. + +Este é o loop while completo: + +```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; + } +} +``` diff --git a/units/pt/unit3/introduction.mdx b/units/pt/unit3/introduction.mdx new file mode 100644 index 0000000..6947e1a --- /dev/null +++ b/units/pt/unit3/introduction.mdx @@ -0,0 +1,3 @@ +# Em Breve + +Esta será outra caso de uso que aprofunda o protocolo MCP e como usá-lo de maneiras mais complexas. diff --git a/units/pt/unit4/introduction.mdx b/units/pt/unit4/introduction.mdx new file mode 100644 index 0000000..51b580e --- /dev/null +++ b/units/pt/unit4/introduction.mdx @@ -0,0 +1,5 @@ +# Em Breve + +Esta unidade será uma colaboração com parceiros da comunidade de IA. + +Se você está construindo ferramentas para MCP, entre em contato conosco e nós o adicionaremos à unidade. Abra uma [discussão](https://huggingface.co/spaces/mcp-course/README/discussions) na organização do hub.