ai-agentic-mcp-demo

vinod-soni-microsoft/ai-agentic-mcp-demo

3.2

If you are the rightful owner of ai-agentic-mcp-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Weather Demo is a simple, end-to-end agent-ready demonstration built on the Model Context Protocol (MCP), showcasing how to expose tools, resources, and prompts that an agent could use.

Tools
2
Resources
0
Prompts
0

MCP Weather Demo

A simple, end-to-end agent‑ready demo built on Model Context Protocol (MCP) — not an agent by itself:

  • A local Python MCP server that exposes weather tools, a resource, and a reusable prompt
  • A Python MCP client that spawns the server via stdio and lets you call each capability
  • Ready-to-run VS Code tasks and a PowerShell script for quick demos on Windows

The goal is to show how to expose tools/resources/prompts that an agent could use, and how to drive them via a simple CLI.

What this solution does

The MCP server provides:

  • Tools
    • get_weather(city, unit): Real-time current conditions using Open‑Meteo (geocoding + forecast)
    • get_alerts(city): Active warnings using Open‑Meteo Warnings (best-effort, may be empty by region/time)
  • Resource
    • weather://city/{city}: A quick human-readable snapshot for any city
  • Prompt
    • weather_report(city): A concise, reusable instruction to turn tool output into a readable summary

The MCP client spawns the server over stdio and offers a CLI to:

  • List available tools and prompts
  • Call get_weather or get_alerts
  • Read the weather resource for a city
  • Fetch and display the prompt template

Architecture overview

Prerequisites

  • Windows (PowerShell) or any OS with Python 3.10+
  • Python 3.10 or newer
  • VS Code recommended (tasks included)

Setup

You can use the included VS Code task ā€œInstall dependenciesā€, or do it manually:

PowerShell (Windows):

python -m venv .venv
. .venv/Scripts/Activate.ps1
pip install -r requirements.txt

Quick start

Using VS Code tasks (recommended):

  • Run ā€œInstall dependenciesā€
  • Run ā€œRun Client (spawns server)ā€ to see default output for London

Or run the PowerShell script:

pwsh ./run.ps1

Usage (client CLI)

Activate your venv first, then call the client with an action and city.

. .venv/Scripts/Activate.ps1

# List tools and prompts
python client/client.py --action list

# Get current weather (Celsius)
python client/client.py --city "New Delhi" --unit c --action get_weather

# Get active alerts (if any)
python client/client.py --city "New Delhi" --action get_alerts

# Read the resource
python client/client.py --city "New Delhi" --action resource

# Fetch the reusable prompt
python client/client.py --city "New Delhi" --action prompt

# End-to-end: list + weather + alerts + resource + prompt
python client/client.py --city "New Delhi" --action all

Notes:

  • Cities with spaces are handled by the client (URL-encoded for the resource); the server decodes them.
  • If geocoding cannot find a place (e.g., misspelling), the tool returns a clear error.
  • Alerts are real-time. An empty list means no current warnings for that location or limited coverage in the region.
  • The included CLI is a manual driver for demo purposes and does not include an LLM loop.

Is this an agent?

Short answer: No. This repository is agent‑ready.

  • What this repo includes:
    • An MCP server that exposes tools (get_weather, get_alerts), a resource (weather://city/{city}), and a reusable prompt (weather_report)
    • A simple CLI client that manually calls those capabilities over stdio
  • What makes it ā€œagenticā€:
    • When an LLM‑driven client (or agent framework) plans which tool(s) to call, executes them via MCP, and then synthesizes the result using the provided prompt
  • How to make it agentic:
    • Replace or wrap the CLI with an LLM loop that uses MCP to decide and act (plan → call tools → summarize with prompt)

Server capabilities

  • get_weather(city, unit)
    • Geocodes city → latitude/longitude
    • Fetches current variables: temperature_2m, relative_humidity_2m, wind_speed_10m, weather_code
    • Returns structured output with rounded values and a readable condition
  • get_alerts(city)
    • Geocodes city
    • Queries Open‑Meteo Warnings
    • Normalizes severity/title/description into a simple format
  • Resource: weather://city/{city}
    • Quick, human-readable one-liner for current conditions
  • Prompt: weather_report(city)
    • Returns a single instruction string to guide an LLM in writing a concise weather summary

Project structure

README.md
requirements.txt
run.ps1
client/
  client.py
server/
  server.py

Troubleshooting

  • Permission denied on .venv/Scripts/python.exe
    • Close other terminals using the venv and retry the VS Code task
    • Ensure antivirus or file locks aren’t blocking the venv
  • City not found
    • Check spelling or try a broader/canonical place name (e.g., ā€œKingstonā€ vs ā€œKingston, Jamaicaā€)
  • Alerts are empty
    • No active warnings at this time or limited coverage by the warnings endpoint
  • Networking issues
    • Ensure your machine can reach the Open‑Meteo endpoints

Contributing

See CONTRIBUTING.md for guidelines on setting up your environment, running the demo, and opening PRs.

Security

Please see SECURITY.md for how to report vulnerabilities.

License

Licensed under the MIT License. See LICENSE for details.

Release notes

See CHANGELOG.md for version history.

What you get

  • MCP server with tools, a resource, and a prompt:
    • get_weather(city, unit) returns structured JSON (Pydantic) with temp, humidity, etc.
    • get_alerts(city) returns structured alerts list.
    • Resource: weather://{city} renders a short human string.
    • Prompt: Weather Report shows a reusable prompt template.
  • MCP client that spawns the server via stdio and calls those APIs.
  • VS Code tasks to install deps and run the demo.
  • Optional Azure resource group provisioning commands (separate RG).

Requirements

  • Python 3.10+
  • pip (or uv if you prefer)

Setup

  1. Create a virtual environment and install deps
python -m venv .venv
. .venv/Scripts/Activate.ps1
pip install -r requirements.txt
  1. Run the client (it spawns the server process)
python client/client.py

Set a city:

$env:CITY = "Seattle"
python client/client.py

Expected output (abbrev.):

  • Lists available tools
  • Prints structured weather JSON and any alerts
  • Reads the weather://{city} resource
  • Lists prompts

Project layout

  • server/server.py — FastMCP server exposing tools, resource, and a prompt
  • client/client.py — MCP client that connects to the server over stdio
  • requirements.txt — Python deps (mcp SDK + pydantic)
  • .vscode/tasks.json — Run/install tasks
  • .gitignore — Ignore venv, caches, etc.

VS Code tasks

Open the Command Palette → "Run Task" and choose:

  • Install dependencies
  • Run Client (spawns server)
  • Run Server (advanced/dev)

How it works

  • The server uses the official MCP Python SDK (FastMCP) to declare tools/resources/prompts. MCP handles schema generation and structured outputs for you.
  • The client launches the server as a child process and speaks MCP over stdio. It initializes a session, lists capabilities, calls tools, reads resources, and inspects prompts.

Optional: Azure resource group for related infra

This demo does not require Azure. If you want to keep any future cloud resources isolated, create and later delete a dedicated resource group. See the commands below in the Azure section generated by the assistant.

Publish to GitHub

  • Initialize a git repo, commit, and push:
git init
git add .
git commit -m "MCP weather demo"
# Create a new repo on GitHub, then
git remote add origin https://github.com/<your-username>/mcp-weather-demo.git
git branch -M main
git push -u origin main

Troubleshooting

  • Ensure your venv is activated when running commands.
  • If you prefer uv:
uv venv
. .venv/Scripts/Activate.ps1
uv pip install -r requirements.txt
uv run python client/client.py