Skip to content

Commit eea3213

Browse files
softchrissoftchris
committed
updating ch3 README and separating out content two ch3.7 and 3.8
1 parent 76c2e87 commit eea3213

File tree

5 files changed

+294
-360
lines changed

5 files changed

+294
-360
lines changed

‎03-GettingStarted/01-first-server/README.md‎

Lines changed: 0 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -108,32 +108,6 @@ Here's a screenshot of what it can look like:
108108

109109
![](/03-GettingStarted/01-first-server/assets/connected.png)
110110

111-
### Manual Testing
112-
113-
You can test MCP servers directly using HTTP requests:
114-
115-
```bash
116-
# Example: Test server metadata
117-
curl http://localhost:3000/v1/metadata
118-
119-
# Example: Execute a tool
120-
curl -X POST http://localhost:3000/v1/tools/execute \
121-
-H "Content-Type: application/json" \
122-
-d '{"name": "calculator", "parameters": {"expression": "2+2"}}'
123-
```
124-
125-
### Unit Testing
126-
127-
Create unit tests for your tools and resources to ensure they work as expected:
128-
129-
```javascript
130-
// Example using Jest
131-
test('Calculator tool returns correct result', async () => {
132-
const response = await calculatorTool.handler({ expression: '5+5' });
133-
expect(response.result).toBe(10);
134-
});
135-
```
136-
137111
## Common Setup Issues and Solutions
138112

139113
| Issue | Possible Solution |

‎03-GettingStarted/04-vscode/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,29 @@ By the end of this lesson, you will be able to:
1414
- Run capabilities like tools via GitHub Copilot.
1515
- Configure Visual Studio Code to find and manage your MCP Server.
1616

17+
## Usage
18+
19+
You can control your MCP server in two different ways:
20+
21+
- User interface, you will see how this is done later in this chapter.
22+
- Terminal, it's possible to control things from the terminal using the `code` exectuable:
23+
24+
To add an MCP server to your user profile, use the --add-mcp command line option, and provide the JSON server configuration in the form {\"name\":\"server-name\",\"command\":...}.
25+
26+
```
27+
code --add-mcp "{\"name\":\"my-server\",\"command\": \"uvx\",\"args\": [\"mcp-server-fetch\"]}"
28+
```
29+
<details>
30+
<summary>Screenshots</summary>
31+
32+
![Guided MCP server configuration in Visual Studio Code](../images/03-GettingStarted/chat-mode-agent.png)
33+
![Tool selection per agent session](../images/03-GettingStarted/agent-mode-select-tools.png)
34+
![Easily debug errors during MCP development](../images/03-GettingStarted/mcp-list-servers.png)
35+
</details>
36+
37+
Let's talk more about how we use the visual interface in the next sections.
38+
39+
1740
## Approach
1841

1942
Here's how we need to approach this at high level:

‎03-GettingStarted/07-testing/README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
## Testing and Debugging
2+
3+
Before you begin testing your MCP server, it's important to understand the available tools and best practices for debugging. Effective testing ensures your server behaves as expected and helps you quickly identify and resolve issues. The following section outlines recommended approaches for validating your MCP implementation.
4+
5+
## Overview
6+
7+
This lesson covers how to select the right testing approach and the most effective testing tool.
8+
9+
## Learning Objectives
10+
11+
By the end of this lesson, you will be able to:
12+
13+
- Describe various approaches for testing.
14+
- Use different tools to effectively test your code.
15+
16+
17+
## Testing MCP Servers
18+
19+
MCP provides tools to help you test and debug your servers:
20+
21+
- **MCP Inspector**: A command line tool that can be run both as a CLI tool and as a visual tool.
22+
- **Manual testing**: You can use a tool like curl to run web requests, but any tool capabable of running HTTP will do.
23+
- **Unit testing**: It's possible to use your preferred testing framework to test the features of both server and client.
24+
25+
### Using MCP Inspector
26+
27+
We've describes the usage of this tool in previous lessons but let's talk about it a bit at high level. It's a tool built in Node.js and you can use it by calling the `npx` executable which will download and install the tool itself temporarily and will clean itself up once it's done running your request.
28+
29+
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) helps you:
30+
31+
- **Discover Server Capabilities**: Automatically detect available resources, tools, and prompts
32+
- **Test Tool Execution**: Try different parameters and see responses in real-time
33+
- **View Server Metadata**: Examine server info, schemas, and configurations
34+
35+
A typical run of the tool looks like so:
36+
37+
```bash
38+
npx @modelcontextprotocol/inspector node build/index.js
39+
```
40+
41+
The above command starts an MCP and its visual interface and launches a local web interface in your browser. You can expect to see a dashboard displaying your registered MCP servers, their available tools, resources, and prompts. The interface allows you to interactively test tool execution, inspect server metadata, and view real-time responses, making it easier to validate and debug your MCP server implementations.
42+
43+
Here's what it can look like: ![Inspector](/03-GettingStarted/01-first-server/assets/connect.png)
44+
45+
You can also run this tool in CLI mode in which case you add `--cli` attribute. Here's an example of running the tool in "CLI" mode which lists all the tools on the server:
46+
47+
```sh
48+
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
49+
```
50+
51+
### Manual Testing
52+
53+
Apart from running the inspector tool to test server capabilities, another similar approach is to run a client capable of using HTTP lik for example curl.
54+
55+
With curl, you can test MCP servers directly using HTTP requests:
56+
57+
```bash
58+
# Example: Test server metadata
59+
curl http://localhost:3000/v1/metadata
60+
61+
# Example: Execute a tool
62+
curl -X POST http://localhost:3000/v1/tools/execute \
63+
-H "Content-Type: application/json" \
64+
-d '{"name": "calculator", "parameters": {"expression": "2+2"}}'
65+
```
66+
67+
As you can see from above usage of curl, you use a POST request to invoke a tool using a payload consisting of the tools name and its parameters. Use the approach that fits you best. CLI tools in general tends to be faster to use and lends themselves to be scripted which can be useful in a CI/CD environment.
68+
69+
### Unit Testing
70+
71+
Create unit tests for your tools and resources to ensure they work as expected. Here's some example testing code.
72+
73+
```python
74+
import pytest
75+
76+
from mcp.server.fastmcp import FastMCP
77+
from mcp.shared.memory import (
78+
create_connected_server_and_client_session as create_session,
79+
)
80+
81+
# Mark the whole module for async tests
82+
pytestmark = pytest.mark.anyio
83+
84+
85+
async def test_list_tools_cursor_parameter():
86+
"""Test that the cursor parameter is accepted for list_tools.
87+
88+
Note: FastMCP doesn't currently implement pagination, so this test
89+
only verifies that the cursor parameter is accepted by the client.
90+
"""
91+
92+
server = FastMCP("test")
93+
94+
# Create a couple of test tools
95+
@server.tool(name="test_tool_1")
96+
async def test_tool_1() -> str:
97+
"""First test tool"""
98+
return "Result 1"
99+
100+
@server.tool(name="test_tool_2")
101+
async def test_tool_2() -> str:
102+
"""Second test tool"""
103+
return "Result 2"
104+
105+
async with create_session(server._mcp_server) as client_session:
106+
# Test without cursor parameter (omitted)
107+
result1 = await client_session.list_tools()
108+
assert len(result1.tools) == 2
109+
110+
# Test with cursor=None
111+
result2 = await client_session.list_tools(cursor=None)
112+
assert len(result2.tools) == 2
113+
114+
# Test with cursor as string
115+
result3 = await client_session.list_tools(cursor="some_cursor_value")
116+
assert len(result3.tools) == 2
117+
118+
# Test with empty string cursor
119+
result4 = await client_session.list_tools(cursor="")
120+
assert len(result4.tools) == 2
121+
122+
```
123+
124+
The preceding code does the following:
125+
126+
- Leverages pytest framework which lets you create tests as functions and use assert statements.
127+
- Creates an MCP Server with two different tools.
128+
- Uses `assert` statement to check that certain conditions are fulfilled.
129+
130+
Have a look at the [full file here](https://github.com/modelcontextprotocol/python-sdk/blob/main/tests/client/test_list_methods_cursor.py)
131+
132+
Given the above file, you can test your own server to ensure capabilities are created as they should.
133+
134+
All major SDKs have similar testing sections so you can adjust to your chosen runtime.
135+
136+
## Samples
137+
138+
- [Java Calculator](../samples/java/calculator/README.md)
139+
- [.Net Calculator](../samples/csharp/)
140+
- [JavaScript Calculator](../samples/javascript/README.md)
141+
- [TypeScript Calculator](../samples/typescript/README.md)
142+
- [Python Calculator](../samples/python/)
143+
144+
## Additional Resources
145+
146+
- [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
147+
148+
## What's Next
149+
150+
- Next: [Deployment](/03-GettingStarted/08-deployment/README.md)

‎03-GettingStarted/08-deployment/README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Deploying MCP Servers
2+
3+
Deploying your MCP server allows others to access its tools and resources beyond your local environment. There are several deployment strategies to consider, depending on your requirements for scalability, reliability, and ease of management. Below you'll find guidance for deploying MCP servers locally, in containers, and to the cloud.
4+
5+
## Overview
6+
7+
This lesson covers how to deploy your MCP Server app.
8+
9+
## Learning Objectives
10+
11+
By the end of this lesson, you will be able to:
12+
13+
- Evaluate different deployment approaches.
14+
- Deploy your app.
15+
16+
## Local development and deployment
17+
18+
If your server is meant to be consumed by running on users machine, you can follow the following steps:
19+
20+
1. **Download the server**. If you didn't write the server, then download it first to your machine.
21+
1. **Start the server process**: Run your MCP server application
22+
23+
For SSE (not needed for stdio type server)
24+
25+
1. **Configure networking**: Ensure the server is accessible on the expected port
26+
1. **Connect clients**: Use local connection URLs like `http://localhost:3000`
27+
28+
## Cloud Deployment
29+
30+
MCP servers can be deployed to various cloud platforms:
31+
32+
- **Serverless Functions**: Deploy lightweight MCP servers as serverless functions
33+
- **Container Services**: Use services like Azure Container Apps, AWS ECS, or Google Cloud Run
34+
- **Kubernetes**: Deploy and manage MCP servers in Kubernetes clusters for high availability
35+
36+
### Example: Azure Container Apps
37+
38+
Azure Container Apps support deployment of MCP Servers. It's still a work in progress and it currently supports SSE servers.
39+
40+
Here's how you can go about it:
41+
42+
1. Clone a repo:
43+
44+
```sh
45+
git clone https://github.com/anthonychu/azure-container-apps-mcp-sample.git
46+
```
47+
48+
1. Run it locally to test things out:
49+
50+
```sh
51+
uv venv
52+
uv sync
53+
54+
# linux/macOS
55+
export API_KEYS=<AN_API_KEY>
56+
# windows
57+
set API_KEYS=<AN_API_KEY>
58+
59+
uv run fastapi dev main.py
60+
```
61+
62+
1. To try it locally, create a *mcp.json* file in a *.vscode* directory and add the following content:
63+
64+
```json
65+
{
66+
"inputs": [
67+
{
68+
"type": "promptString",
69+
"id": "weather-api-key",
70+
"description": "Weather API Key",
71+
"password": true
72+
}
73+
],
74+
"servers": {
75+
"weather-sse": {
76+
"type": "sse",
77+
"url": "http://localhost:8000/sse",
78+
"headers": {
79+
"x-api-key": "${input:weather-api-key}"
80+
}
81+
}
82+
}
83+
}
84+
```
85+
86+
Once the SSE server is started, you can click the play icon in the JSON file, you should now see tools on the server be picked up by GitHub Copilot, see the Tool icon.
87+
88+
1. To deploy, run the following command:
89+
90+
```sh
91+
az containerapp up -g <RESOURCE_GROUP_NAME> -n weather-mcp --environment mcp -l westus --env-vars API_KEYS=<AN_API_KEY> --source .
92+
```
93+
94+
There you have it, deploy it locally, deploy it to Azure through these steps.
95+
96+
## Additional Resources
97+
98+
- [Azure Functions + MCP](https://learn.microsoft.com/en-us/samples/azure-samples/remote-mcp-functions-dotnet/remote-mcp-functions-dotnet/)
99+
- [Azure Container Apps article](https://techcommunity.microsoft.com/blog/appsonazureblog/host-remote-mcp-servers-in-azure-container-apps/4403550)
100+
- [Azure Container Apps MCP repo](https://github.com/anthonychu/azure-container-apps-mcp-sample)
101+
102+
103+
## What's Next
104+
105+
- Next: [Practical Implementation](/04-PracticalImplementation/README.md)

0 commit comments

Comments
 (0)