Skip to content

Commit 85a17c1

Browse files
pamelafoxpamelafox
committed
Adding README
1 parent 7467d92 commit 85a17c1

File tree

1 file changed

+206
-55
lines changed

1 file changed

+206
-55
lines changed

‎README.md‎

Lines changed: 206 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,130 @@
11
# Python MCP Demo
22

3-
A demonstration project showcasing Model Context Protocol (MCP) implementations using FastMCP, with examples of stdio, HTTP transports, and integration with LangChain and Agent Framework.
3+
A demonstration project showcasing Model Context Protocol (MCP) implementations using FastMCP, with examples of stdio and HTTP transports, integration with LangChain and Agent Framework, and deployment to Azure Container Apps.
44

55
## Table of Contents
66

7-
- [Prerequisites](#prerequisites)
8-
- [Setup](#setup)
9-
- [Python Scripts](#python-scripts)
10-
- [MCP Server Configuration](#mcp-server-configuration)
11-
- [Debugging](#debugging)
7+
- [Getting started](#getting-started)
8+
- [GitHub Codespaces](#github-codespaces)
9+
- [VS Code Dev Containers](#vs-code-dev-containers)
10+
- [Local environment](#local-environment)
11+
- [Run local MCP servers](#run-local-mcp-servers)
12+
- [Use with GitHub Copilot](#use-with-github-copilot)
13+
- [Debug with VS Code](#debug-with-vs-code)
14+
- [Inspect with MCP inspector](#inspect-with-mcp-inspector)
15+
- [Run local Agents <-> MCP](#run-local-agents---mcp)
16+
- [Deploy to Azure](#deploy-to-azure)
17+
- [Azure account setup](#azure-account-setup)
18+
- [Deploying with azd](#deploying-with-azd)
19+
- [Costs](#costs)
20+
- [Deploy to Azure with private networking](#deploy-to-azure-with-private-networking)
1221

13-
## Prerequisites
22+
## Getting started
1423

15-
- Python 3.13 or higher
16-
- [uv](https://docs.astral.sh/uv/)
17-
- API access to one of the following:
18-
- GitHub Models (GitHub token)
19-
- Azure OpenAI (Azure credentials)
20-
- Ollama (local installation)
21-
- OpenAI API (API key)
24+
You have a few options for setting up this project. The quickest way to get started is GitHub Codespaces, since it will setup all the tools for you, but you can also set it up locally.
2225

23-
## Setup
26+
### GitHub Codespaces
2427

25-
1. Install dependencies using `uv`:
28+
You can run this project virtually by using GitHub Codespaces. Click the button to open a web-based VS Code instance in your browser:
29+
30+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/pamelafox/python-mcp-demo)
31+
32+
Once the Codespace is open, open a terminal window and continue with the deployment steps.
33+
34+
### VS Code Dev Containers
35+
36+
A related option is VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
37+
38+
1. Start Docker Desktop (install it if not already installed)
39+
2. Open the project: [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/pamelafox/python-mcp-demo)
40+
3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
41+
4. Continue with the deployment steps.
42+
43+
### Local environment
44+
45+
If you're not using one of the above options, then you'll need to:
46+
47+
1. Make sure the following tools are installed:
48+
- [Azure Developer CLI (azd)](https://aka.ms/install-azd)
49+
- [Python 3.13+](https://www.python.org/downloads/)
50+
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
51+
- [Git](https://git-scm.com/downloads)
52+
53+
2. Clone the repository and open the project folder.
54+
55+
3. Create a [Python virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments) and activate it.
56+
57+
4. Install the dependencies:
2658

2759
```bash
2860
uv sync
2961
```
3062

31-
2. Copy `.env-sample` to `.env` and configure your environment variables:
63+
5. Copy `.env-sample` to `.env` and configure your environment variables:
3264

3365
```bash
3466
cp .env-sample .env
3567
```
3668

37-
3. Edit `.env` with your API credentials. Choose one of the following providers by setting `API_HOST`:
69+
6. Edit `.env` with your API credentials. Choose one of the following providers by setting `API_HOST`:
3870
- `github` - GitHub Models (requires `GITHUB_TOKEN`)
3971
- `azure` - Azure OpenAI (requires Azure credentials)
4072
- `ollama` - Local Ollama instance
4173
- `openai` - OpenAI API (requires `OPENAI_API_KEY`)
4274

43-
## Python Scripts
75+
## Run local MCP servers
76+
77+
This project includes two MCP servers in the [`servers/`](servers/) directory:
4478

45-
Run any script with: `uv run <script_path>`
79+
| File | Description |
80+
|------|-------------|
81+
| [servers/basic_mcp_stdio.py](servers/basic_mcp_stdio.py) | MCP server with stdio transport for VS Code integration |
82+
| [servers/basic_mcp_http.py](servers/basic_mcp_http.py) | MCP server with HTTP transport on port 8000 |
4683

47-
- **servers/basic_mcp_http.py** - MCP server with HTTP transport on port 8000
48-
- **servers/basic_mcp_stdio.py** - MCP server with stdio transport for VS Code integration
49-
- **agents/langchainv1_http.py** - LangChain agent with MCP integration
50-
- **agents/langchainv1_github.py** - LangChain tool filtering demo with GitHub MCP (requires `GITHUB_TOKEN`)
51-
- **agents/agentframework_learn.py** - Microsoft Agent Framework integration with MCP
52-
- **agents/agentframework_http.py** - Microsoft Agent Framework integration with local Expenses MCP server
84+
Both servers implement an "Expenses Tracker" with a tool to add expenses to a CSV file.
5385

54-
## MCP Server Configuration
86+
### Use with GitHub Copilot
5587

56-
### Using with MCP Inspector
88+
The `.vscode/mcp.json` file configures MCP servers for GitHub Copilot integration:
89+
90+
**Available Servers:**
91+
92+
- **expenses-mcp**: stdio transport server for production use
93+
- **expenses-mcp-debug**: stdio server with debugpy on port 5678
94+
- **expenses-mcp-http**: HTTP transport server at `http://localhost:8000/mcp`. You must start this server manually with `uv run servers/basic_mcp_http.py` before using it.
95+
96+
**Switching Servers:**
97+
98+
Configure which server GitHub Copilot uses by opening the Chat panel, selecting the tools icon, and choosing the desired MCP server from the list.
99+
100+
![Servers selection dialog](readme_serverselect.png)
101+
102+
**Example input:**
103+
104+
Use a query like this to test the expenses MCP server:
105+
106+
```text
107+
Log expense for 50 bucks of pizza on my amex today
108+
```
109+
110+
![Example GitHub Copilot Chat Input](readme_samplequery.png)
111+
112+
### Debug with VS Code
113+
114+
The `.vscode/launch.json` provides a debug configuration to attach to an MCP server.
115+
116+
**To debug an MCP server with GitHub Copilot Chat:**
117+
118+
1. Set breakpoints in the MCP server code in `servers/basic_mcp_stdio.py`
119+
2. Start the debug server via `mcp.json` configuration by selecting `expenses-mcp-debug`
120+
3. Press `Cmd+Shift+D` to open Run and Debug
121+
4. Select "Attach to MCP Server (stdio)" configuration
122+
5. Press `F5` or the play button to start the debugger
123+
6. Select the expenses-mcp-debug server in GitHub Copilot Chat tools
124+
7. Use GitHub Copilot Chat to trigger the MCP tools
125+
8. Debugger pauses at breakpoints
126+
127+
### Inspect with MCP inspector
57128

58129
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a developer tool for testing and debugging MCP servers.
59130

@@ -86,45 +157,125 @@ The inspector provides a web interface to:
86157
- Inspect server responses and errors
87158
- Debug server communication
88159

89-
### Using with GitHub Copilot
160+
---
90161

91-
The `.vscode/mcp.json` file configures MCP servers for GitHub Copilot integration:
162+
## Run local Agents <-> MCP
92163

93-
**Available Servers:**
164+
This project includes example agents in the [`agents/`](agents/) directory that demonstrate how to connect AI agents to MCP servers:
94165

95-
- **expenses-mcp**: stdio transport server for production use
96-
- **expenses-mcp-debug**: stdio server with debugpy on port 5678
97-
- **expenses-mcp-http**: HTTP transport server at `http://localhost:8000/mcp`. You must start this server manually with `uv run servers/basic_mcp_http.py` before using it.
166+
| File | Description |
167+
|------|-------------|
168+
| [agents/agentframework_learn.py](agents/agentframework_learn.py) | Microsoft Agent Framework integration with MCP |
169+
| [agents/agentframework_http.py](agents/agentframework_http.py) | Microsoft Agent Framework integration with local Expenses MCP server |
170+
| [agents/langchainv1_http.py](agents/langchainv1_http.py) | LangChain agent with MCP integration |
171+
| [agents/langchainv1_github.py](agents/langchainv1_github.py) | LangChain tool filtering demo with GitHub MCP (requires `GITHUB_TOKEN`) |
98172

99-
**Switching Servers:**
173+
**To run an agent:**
100174

101-
Configure which server GitHub Copilot uses by opening the Chat panel, selecting the tools icon, and choosing the desired MCP server from the list.
175+
1. First start the HTTP MCP server:
102176

103-
![Servers selection dialog](readme_serverselect.png)
177+
```bash
178+
uv run servers/basic_mcp_http.py
179+
```
104180

105-
**Example input**
181+
2. In another terminal, run an agent:
106182

107-
Use a query like this to test the expenses MCP server:
183+
```bash
184+
uv run agents/agentframework_http.py
185+
```
108186

109-
```
110-
Log expense for 50 bucks of pizza on my amex today
111-
```
187+
The agents will connect to the MCP server and allow you to interact with the expense tracking tools through a chat interface.
112188

113-
![Example GitHub Copilot Chat Input](readme_samplequery.png)
189+
---
114190

115-
## Debugging
191+
## Deploy to Azure
116192

117-
The `.vscode/launch.json` provides one debug configuration:
193+
This project can be deployed to Azure Container Apps using the Azure Developer CLI (azd). The deployment provisions:
118194

119-
**Attach to MCP Server (stdio)**: Attaches to server started via `expenses-mcp-debug` in `mcp.json`
195+
- **Azure Container Apps** - Hosts both the MCP server and agent
196+
- **Azure OpenAI** - Provides the LLM for the agent
197+
- **Azure Cosmos DB** - Stores expenses data
198+
- **Azure Container Registry** - Stores container images
199+
- **Log Analytics** - Monitoring and diagnostics
120200

121-
To debug an MCP server with GitHub Copilot Chat:
201+
### Azure account setup
122202

123-
1. Set breakpoints in the MCP server code in `servers/basic_mcp_stdio.py`
124-
1. Start the debug server via `mcp.json` configuration by selecting `expenses-mcp-debug`
125-
1. Press `Cmd+Shift+D` to open Run and Debug
126-
1. Select "Attach to MCP Server (stdio)" configuration
127-
1. Press `F5` or the play button to start the debugger
128-
1. Select the expenses-mcp-debug server in GitHub Copilot Chat tools
129-
1. Use GitHub Copilot Chat to trigger the MCP tools
130-
1. Debugger pauses at breakpoints
203+
1. Sign up for a [free Azure account](https://azure.microsoft.com/free/) and create an Azure Subscription.
204+
2. Check that you have the necessary permissions:
205+
- Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner).
206+
- Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
207+
208+
### Deploying with azd
209+
210+
1. Login to Azure:
211+
212+
```bash
213+
azd auth login
214+
```
215+
216+
For GitHub Codespaces users, if the previous command fails, try:
217+
218+
```bash
219+
azd auth login --use-device-code
220+
```
221+
222+
2. Create a new azd environment:
223+
224+
```bash
225+
azd env new
226+
```
227+
228+
This will create a folder inside `.azure` with the name of your environment.
229+
230+
3. Provision and deploy the resources:
231+
232+
```bash
233+
azd up
234+
```
235+
236+
It will prompt you to select a subscription and location. This will take several minutes to complete.
237+
238+
4. Once deployment is complete, a `.env` file will be created with the necessary environment variables to run the agents locally against the deployed resources.
239+
240+
### Costs
241+
242+
Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage.
243+
244+
You can try the [Azure pricing calculator](https://azure.com/e/3987c81282c84410b491d28094030c9a) for the resources:
245+
246+
- **Azure OpenAI Service**: S0 tier, GPT-4o-mini model. Pricing is based on token count. [Pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/)
247+
- **Azure Container Apps**: Consumption tier. [Pricing](https://azure.microsoft.com/pricing/details/container-apps/)
248+
- **Azure Container Registry**: Standard tier. [Pricing](https://azure.microsoft.com/pricing/details/container-registry/)
249+
- **Azure Cosmos DB**: Serverless tier. [Pricing](https://azure.microsoft.com/pricing/details/cosmos-db/)
250+
- **Log Analytics** (Optional): Pay-as-you-go tier. Costs based on data ingested. [Pricing](https://azure.microsoft.com/pricing/details/monitor/)
251+
252+
⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use, either by deleting the resource group in the Portal or running `azd down`.
253+
254+
---
255+
256+
### Deploy to Azure with private networking
257+
258+
To demonstrate enhanced security for production deployments, this project supports deploying with a virtual network (VNet) configuration that restricts public access to Azure resources.
259+
260+
1. Set these azd environment variables to set up a virtual network and private endpoints for the Container App, Cosmos DB, and OpenAI resources:
261+
262+
```bash
263+
azd env set USE_VNET true
264+
azd env set USE_PRIVATE_INGRESS true
265+
```
266+
267+
The Log Analytics and ACR resources will still have public access enabled, so that you can deploy and monitor the app without needing a VPN. In production, you would typically restrict these as well.
268+
269+
2. Provision and deploy:
270+
271+
```bash
272+
azd up
273+
```
274+
275+
### Additional costs for private networking
276+
277+
When using VNet configuration, additional Azure resources are provisioned:
278+
279+
- **Virtual Network**: Pay-as-you-go tier. Costs based on data processed. [Pricing](https://azure.microsoft.com/pricing/details/virtual-network/)
280+
- **Azure Private DNS Resolver**: Pricing per month, endpoints, and zones. [Pricing](https://azure.microsoft.com/pricing/details/dns/)
281+
- **Azure Private Endpoints**: Pricing per hour per endpoint. [Pricing](https://azure.microsoft.com/pricing/details/private-link/)

0 commit comments

Comments
 (0)