# Model Context Protocol (MCP) - Weather Tool Server & Agent Interoperability

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![Protocol](https://img.shields.io/badge/MCP-Standardized-green.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)

An implementation of Anthropic's **Model Context Protocol (MCP)** using the Python MCP SDK. This repository demonstrates how to standardize communication between an AI agent and external tools, separating tool execution from agent logic for true cross-framework interoperability.

---

## 🌟 Overview

The **Model Context Protocol (MCP)** defines an open standard for AI models to discover and call tools, read data resources, and utilize prompt templates over a unified interface (using JSON-RPC 2.0).

This project implements:
1. **Custom MCP Server** (`weather_server.py`): Exposes `get_weather` and `get_forecast` over standard input/output (`stdio`).
2. **MCP Client** (`mcp_client.py`): Demonstrates protocol initialization, dynamic tool discovery (`list_tools`), and structured tool calls (`call_tool`).
3. **Interoperability Demo** (`mcp_client_interop.py`): Demonstrates how multiple distinct agent client implementations consume the exact same MCP tool server without modifying server-side code.
4. **Complete Experiment Report** (`experiment_report.md`): Comprehensive lab documentation with JSON-RPC payload breakdowns.

---

## 📁 Repository Structure

```
.
├── weather_server.py       # MCP Tool Server implementation
├── mcp_client.py           # Standard async MCP Client
├── mcp_client_interop.py   # Multi-agent framework interoperability test
├── requirements.txt        # Dependencies (mcp SDK)
├── experiment_report.md    # Detailed experiment writeup & JSON-RPC spec
└── README.md               # Project documentation
```

---

## 🚀 Getting Started

### Prerequisites
- Python 3.10 or higher
- `pip` package manager

### 1. Installation

Clone the repository and install the dependencies:

```bash
git clone https://github.com/your-username/mcp-weather-server.git
cd mcp-weather-server
pip install -r requirements.txt
```

---

## 🛠️ Usage

### Run Primary MCP Client & Server Interaction

Executes the client, spawns `weather_server.py` via `stdio`, initializes the session, discovers tools, and invokes `get_weather` for **Mumbai** and `get_forecast` for **Chennai**:

```bash
python mcp_client.py
```

**Expected Output:**
```text
==================================================
  Model Context Protocol (MCP) Client Initializing
==================================================
[Transport] Connecting via Stdio: python weather_server.py

[Step 1] Initializing MCP Session...
  -> Connected to Server: weather-server v0.1.0
  -> Server Protocol Version: 2025-06-18

[Step 2] Executing list_tools() Request...
  -> Discovered 2 tool(s):
     - Tool Name: get_weather
     - Tool Name: get_forecast

[Step 3] Executing call_tool('get_weather', city='Mumbai')...
  -> Response received from server:
     [TextContent]: Mumbai: 28 deg C, Partly Cloudy, Humidity 65%

[Step 4] Executing call_tool('get_forecast', city='Chennai')...
  -> Response received from server:
     [TextContent]: Chennai 3-day: Day1: 28C Sunny | Day2: 25C Rainy | Day3: 30C Sunny
```

---

### Run Interoperability Test

Demonstrates two different simulated agent frameworks executing against the same MCP tool server without code modifications:

```bash
python mcp_client_interop.py
```

---

## 🔌 Connecting to Claude Desktop

You can easily plug this `weather_server.py` into **Claude Desktop**:

1. Open your Claude Desktop configuration file:
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

2. Add your server under `mcpServers`:

```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "C:/path/to/repository/weather_server.py"
      ]
    }
  }
}
```

3. Restart Claude Desktop. You will now see the `get_weather` and `get_forecast` tools available directly in your chat interface!

---

## 📜 Protocol Flow Breakdown (JSON-RPC 2.0)

### 1. Initialization (`initialize`)
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "clientInfo": { "name": "mcp-python-sdk", "version": "1.19.0" }
  }
}
```

### 2. Tool Discovery (`tools/list`)
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```

### 3. Tool Invocation (`tools/call`)
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "Mumbai" }
  }
}
```

---

## 📝 License

Distributed under the MIT License. See `LICENSE` for details.