docs: lesson 7 - mcp #108
docs: lesson 7 - mcp #108
Conversation
| @@ -0,0 +1,482 @@ | |||
| # MCP, Model Context Protocol | |||
There was a problem hiding this comment.
To be consistent with all of the other chapters this should be:
Lesson 7: Model Context Protocol (MCP)
|
|
||
| In this chapter you will learn: | ||
|
|
||
| - How to use the Model Context Protocol, MCP to split up your server capabilities in a server and a client |
There was a problem hiding this comment.
"in" --> "into"
How to use the Model Context Protocol, MCP to split up your server capabilities into a server and a client
|
|
||
| *🎥 Click on the image above to watch a short video about MCP* | ||
|
|
||
| ## Narrative: Scipio Africanus |
There was a problem hiding this comment.
Change to the following to be consistent with the other chapters:
## Narrative - Scipio Africanus
|
|
||
| [](https://www.youtube.com/watch?v=YRfOiB0Im64) | ||
|
|
||
| _This video explains Model Context Protocol._ |
There was a problem hiding this comment.
Looks like the other chapters also have a slide deck link in addition to the video. Do we have a deck that can be added here (guessing so 🙂)?
| > Scipio Africanus's life and career exemplify the qualities of leadership, strategic brilliance, and resilience. His contributions to Rome's military and political spheres left a lasting impact on the Roman Empire. | ||
| > | ||
|
|
||
| ## Interact with scipio |
There was a problem hiding this comment.
Capitalize Scipio here:
Interact with Scipio
|
|
||
| C. Tools, Resources and Prompts | ||
|
|
||
| [Solution Quiz](/lessons/07-mcp/solution/solution-quiz.md) |
There was a problem hiding this comment.
We'd want this at the bottom after the questions right?
| In this chapter, we've learned the following: | ||
|
|
||
| - Model Context Protocol, MCP, is a great way to offload capabilties into servers instead of putting all your features in one place. This allows for your apps to stay small and focused. The added bonus is that different teams can manage different servers also. Thanks to MCP being a protocol this additionally means that anyone out there looking to share capabilities and can do so in a common format. | ||
| - Additionally we looked into how to consume an MCP Server using the Inspector tool or a written client. |
There was a problem hiding this comment.
The other chapters have something like this at the end. Let's add that for this one too especially given MCP will be very new to most people.
## Self-Study resources
- [Retrieval-Augmented Generation and Indexes](https://learn.microsoft.com/azure/ai-studio/concepts/retrieval-augmented-generation)
- **Sample apps**:
* [Serverless AI Chat with RAG](https://github.com/Azure-Samples/serverless-chat-langchainjs/)
* [Ask Youtube: A RAG-based Youtube Q&A API](https://github.com/Azure-Samples/langchainjs-quickstart-demo)
- [Full-length workshop: Create your own ChatGPT with RAG](https://moaw.dev/workshop/gh:azure-samples/azure-openai-rag-workshop/docs/workshop-qdrant.md)
|
|
||
| E. All of the above | ||
|
|
||
| ## Summary |
There was a problem hiding this comment.
I like having this, but in looking at a few of the other chapters they don't have a summary section. Once these new chapters are published it'd be good to back and add that. Nice way to wrap up the chapters.
| > [!NOTE] | ||
| > While we recommend going through the story (it's fun!), [click here](#interact-with-scipio) if you'd prefer to jump straight to the technical content. | ||
|
|
||
| _Our heroes had just learned tools and using tools via tool calling inspired by their meeting with Amelia Earhart and is now returning back to Ada Lovelace's mansion to discuss their new found knowledge. A flash of light envelops our heroes as the time beetle transports them back to Aaa's present. They find themselves in the basement of Ada Lovelace's mansion, Charles Babbage is not present, but Ada is there waiting for them. She is excited to hear about their journey and the knowledge they've gained._ |
There was a problem hiding this comment.
Let's change the first sentence to something like the following. The current sentence is a bit confusing with all of the tools, tools, tools in there. 🙂
Having just learned about tools—and how to use them via tool calling—during their meeting with Amelia Earhart, our heroes now return to Ada Lovelace’s mansion to discuss their newfound knowledge
Also, "Aaa's" should be "Ada's".
|
|
||
| **Ada**: "Welcome back! I trust your journey was enlightening." | ||
|
|
||
| **You**: "It was! meeting with mrs Earhart was quite the experience. She taught us about the importance of tools and how to use them effectively." |
|
|
||
| **You**: "It was! meeting with mrs Earhart was quite the experience. She taught us about the importance of tools and how to use them effectively." | ||
|
|
||
| **Ada**: "There are few people who understand the importance of tools better than Amelia. I trust you've also upgraded her time beetle?" |
There was a problem hiding this comment.
We seem to be using "Time Beetle" in the other chapters so I'd uppercase it. Kind of like a mechanical version of a human. :-)
|
|
||
| **You**: "Scipio Africanus? I think I remember him from history class. | ||
|
|
||
| **Ada**: "Good then, why are you still here? Time is off the essence. Ta ta" |
There was a problem hiding this comment.
"Time is of the essence".
off --> of
|
|
||
| > Scipio Africanus, also known as Publius Cornelius Scipio Africanus, was a prominent Roman general and statesman who lived from 236 BC to 183 BC. He is best known for his decisive role in the Second Punic War against Carthage and his victory over Hannibal at the Battle of Zama in 202 BC. | ||
| > | ||
| > **Key Highlights of His Life and Career:** |
There was a problem hiding this comment.
While I like the Key Highlights, I think the above paragraph provides enough information about him to move on. I'd remove the other information to shorten this up and let people get to the heart of the content sooner.
|
|
||
| ## The need for Model Context Protocol (MCP) | ||
|
|
||
| **Time beetle**: The protocol Ada spoke of is called the Model Context Protocol (MCP). It's a protocol that allows you to decentralize your application architecture, making it more scalable and resilient by adding resources on a server, or multiple servers even, and offload these from the client. I'll let Scipio explain the idea to you. |
There was a problem hiding this comment.
Time beetle --> Time Beetle
Do this throughout the doc so we're consistent with the other chapters.
|
|
||
| **Time beetle**: "To add to Scipio's point, the Model Context Protocol (MCP) is a way to decentralize your application architecture. It allows you to break down your application into smaller, more manageable components that can operate independently. Here are some important concepts to keep in mind: | ||
|
|
||
| - **MCP Hosts**: Programs like IDEs or AI tools that want to access data through MCP. |
There was a problem hiding this comment.
I'd add something like this so people more quickly understand the host concept.
For example, GitHub Copilot in VS Code or Claude Desktop.
| **Time beetle**: "To add to Scipio's point, the Model Context Protocol (MCP) is a way to decentralize your application architecture. It allows you to break down your application into smaller, more manageable components that can operate independently. Here are some important concepts to keep in mind: | ||
|
|
||
| - **MCP Hosts**: Programs like IDEs or AI tools that want to access data through MCP. | ||
| - **MCP Clients**: Protocol clients that maintain 1:1 connections with servers. |
There was a problem hiding this comment.
I'd clarify this so they know it's not regular servers we're talking about:
- **MCP Clients**: Protocol clients that maintain 1:1 connections with MCP servers.
|
|
||
| To sum things up, I should: | ||
|
|
||
| - **Use flanking maneuvers**, or in my case break down by app functionality into several MCP servers so that I can distribute them after area of usage and thereby make it easier to scale and manage the app. Such servers can even be updated independently of each other. |
There was a problem hiding this comment.
The first sentence doesn't flow right starting with the "so that I can distribute them". Something needs fixed there.
| - **Use flanking maneuvers**, or in my case break down by app functionality into several MCP servers so that I can distribute them after area of usage and thereby make it easier to scale and manage the app. Such servers can even be updated independently of each other. | ||
| - **Use infiltration**, or in my case, figure out what these servers are doing, in terms of tools and resources. This way I can make sure I'm interacting with the right server and using the right tools for the job. | ||
|
|
||
| **You**: "Time beetle, am I understanding things correctly?" |
There was a problem hiding this comment.
Mentioned this above, but do a search and replace on "Time beetle" and change to "Time Beetle" to be consistent with the other chapters.
| npm install @modelcontextprotocol/sdk zod | ||
| ``` | ||
|
|
||
| Here's a simple example on how to create an MCP server using these libraries: |
There was a problem hiding this comment.
on --> of
Here's a simple example of how to create an MCP server using these libraries:
``
|
|
||
| In the preceding code, we: | ||
|
|
||
| - Defined a tool called "add" that takes two numbers as input and returns their sum as output. |
There was a problem hiding this comment.
Minor nitpick, but I'd change "called" to "named".
|
|
||
| In this code, we: | ||
|
|
||
| - Defined a resource called "greeting" that takes a name as input and returns a greeting message. |
| In this code, we: | ||
|
|
||
| - Defined a resource called "greeting" that takes a name as input and returns a greeting message. | ||
| - Used a resource template to define how to call the resource `greeting//{name}`. This schema is used to define the resource's URI format, which includes a placeholder for the name. |
There was a problem hiding this comment.
Missing the : after greeting based on what was defined above for the template.
| - Used a resource template to define how to call the resource `greeting//{name}`. This schema is used to define the resource's URI format, which includes a placeholder for the name. | ||
| - The `async` function is used to generate the greeting message based on the provided name. | ||
|
|
||
| **You**: "So the resource is like a data source, this could be a database, file or even an API? If this was a for a file I would use a file:// URI?" like so: |
There was a problem hiding this comment.
Do we want a comma before "like so"? Otherwise the quote ends and then like so follows without any punctuation.
|
|
||
| In this code, we: | ||
|
|
||
| - Created a transport layer using the `StdioServerTransport` class, which allows the server to communicate with clients through standard input and output. |
There was a problem hiding this comment.
This may be covered later, but if not you might differentiate between how stdio runs locally whereas other options such as SSE or streaming HTTP run remotely on a server.
|
|
||
| ### -1- Connect to the server | ||
|
|
||
| **Time beetle**: Select to "Connect" and you should see the window below: |
There was a problem hiding this comment.
Update to:
**Time Beetle**: Select "Connect" and you should see the following:
|
|
||
| **Scipio**: "Interesting, I wish I could test my strategies like this. Seems very useful." | ||
|
|
||
| **You**: "Right, it really does**! I can see how this would be useful for testing and debugging." |
There was a problem hiding this comment.
Remove the extra ** after "does".
|
|
||
| ### Listing and calling tools and resources | ||
|
|
||
| **Time Beetle**: "There's generally two scenarios you want to cover, listing tools and resources, and calling them. Here's how to do that: |
There was a problem hiding this comment.
"There are" instead of "There's".
|
|
||
| ```typescript | ||
| // List prompts | ||
| const prompts = await client.listPrompts(); |
There was a problem hiding this comment.
I don't remember prompts being discussed so you might add a quick introduction above whwere you go into resources and tools (sorry if prompts was covered and I'm not remembering - doing the review in sections based on my available time).
|
|
||
| **You**: This is great, then I know what capabilities the server has. But how do I call them? | ||
|
|
||
| **Time Beetle**: "Right, let me dive into a specific example, tools first. So you start by asking for what tools you have, then you can store that response and then call the tool you want. Here's an example: |
There was a problem hiding this comment.
"So you start by asking for what tools you have" --> "So you start by asking what tools you have"
|
|
||
| **Time Beetle**: "Right, let me dive into a specific example, tools first. So you start by asking for what tools you have, then you can store that response and then call the tool you want. Here's an example: | ||
|
|
||
| So when you list tools, you get a response on this format: |
There was a problem hiding this comment.
So when you list tools, you get a response formatted like the following:
| } | ||
| ``` | ||
|
|
||
| which means, if you have the tools `add` and `subtract`, your response looks like so: |
There was a problem hiding this comment.
The code block below probably needs to be moved up so it's right below this. Otherwise it's confusing since "looks like so:" is followed by another narrative rather than the code.
|
|
||
| **You**: "Ok, good, I guess I can store that in a variable and then call the tool I want?" | ||
|
|
||
| **Time Beetle**: "Exactly! Let's show calling a tool next:" |
There was a problem hiding this comment.
Let's look at how a tool can be called next:
|
|
||
| **You**: "I get it nice, although, you're thinking to yourself, I bet we can improve this somehow? Time Beetle, we can improve this right? | ||
|
|
||
| **Time Beetle**: Yes, but first things first, let's make Scipio happy. We need to have a chat with a Ms Lamarr on our next stop. |
|
|
||
| A. Inspector | ||
|
|
||
| B. Written client |
There was a problem hiding this comment.
Maybe change this to something like:
A custom MCP client
A "Written client" isn't super clear as to what that actually is.
No description provided.