# 🌤️ MCP Weather Server

A simple **Model Context Protocol (MCP) Weather Server** built with Node.js that exposes weather functionality as an MCP tool.

This project demonstrates how an MCP server can expose tools that an AI application or MCP client can discover and execute.

> 🚀 Built as a practical project to understand **MCP Servers, MCP Tools, stdio transport, Zod validation, and external API integration**.

---

## ✨ Features

* 🔌 MCP server using the official MCP SDK
* 🛠️ Custom MCP tool: `getWeatherDataByCityName`
* 📍 Weather lookup by city name
* 🔐 Environment-variable based API configuration
* ✅ Input validation using Zod
* 📡 MCP communication using `StdioServerTransport`
* ⚡ Built with Node.js and JavaScript
* 🧪 Testable with MCP Inspector
* 🤖 Compatible with MCP clients that support stdio transport

---

## 🏗️ Architecture

```text
                ┌─────────────────────┐
                │     MCP Client      │
                │                     │
                │ Cursor / Inspector  │
                │ Other MCP Client    │
                └──────────┬──────────┘
                           │
                           │ MCP / stdio
                           ▼
                ┌─────────────────────┐
                │    MCP Weather      │
                │       Server        │
                │      index.js       │
                └──────────┬──────────┘
                           │
                           ▼
              ┌─────────────────────────┐
              │ getWeatherDataByCityName│
              └────────────┬────────────┘
                           │
                           ▼
                ┌─────────────────────┐
                │   Weather Service   │
                │    External API     │
                └─────────────────────┘
```

---

## 🧰 Tech Stack

| Technology    | Purpose                       |
| ------------- | ----------------------------- |
| Node.js       | Runtime                       |
| JavaScript    | Application language          |
| MCP SDK       | Model Context Protocol server |
| Zod           | Input validation              |
| pnpm          | Package manager               |
| MCP Inspector | MCP server testing            |
| Weather API   | Real-time weather data        |

---

## 📂 Project Structure

```text
MyMcp/
│
├── index.js
├── package.json
├── pnpm-lock.yaml
├── .env
├── .env.example
├── .gitignore
└── README.md
```

---

## 📦 Installation

### 1. Clone the repository

```bash
git clone https://github.com/YOUR_USERNAME/mcp-weather-server.git
```

```bash
cd mcp-weather-server
```

### 2. Install dependencies

This project uses pnpm.

```bash
pnpm install
```

---

## 🔐 Environment Variables

Create a `.env` file:

```env
WEATHER_API_KEY=your_weather_api_key
```

> ⚠️ Never commit your `.env` file or API key to GitHub.

The repository should contain `.env.example` instead:

```env
WEATHER_API_KEY=your_weather_api_key_here
```

---

## ▶️ Run the MCP Server

Start the server with:

```bash
node index.js
```

For an MCP stdio server, **no web page or server URL is expected to appear in the terminal**.

The process waits for an MCP client to communicate with it through stdin/stdout.

---

## 🧪 Test With MCP Inspector

You can test the MCP server without Cursor Agent.

Run:

```bash
pnpm dlx @modelcontextprotocol/inspector node index.js
```

The MCP Inspector will provide a local URL.

Open it in your browser.

You should see the available MCP tool:

```text
getWeatherDataByCityName
```

### Tool Input

```json
{
  "city": "Delhi"
}
```

The MCP server then calls the weather service and returns weather information.

---

## 🛠️ Available MCP Tool

### `getWeatherDataByCityName`

Gets weather information for a specified city.

#### Input

```json
{
  "city": "Delhi"
}
```

#### Example Response

```json
{
  "temp": "30°C",
  "forecast": "Clear"
}
```

---

## 🔄 How MCP Works in This Project

The request flow is:

```text
User
 ↓
AI / MCP Client
 ↓
MCP Tool Call
 ↓
getWeatherDataByCityName
 ↓
Weather API
 ↓
Weather Data
 ↓
MCP Server
 ↓
MCP Client
 ↓
AI Response
```

The important concept is that the AI does not directly contain the weather functionality.

Instead, the AI can discover and call an MCP tool exposed by the server.

---

## 🧠 What I Learned

This project helped me understand:

* What MCP is
* Why MCP servers are useful
* MCP server architecture
* MCP tools
* Tool schemas
* Zod validation
* `StdioServerTransport`
* MCP client/server communication
* External API integration
* API key management
* Environment variables
* MCP Inspector
* Testing MCP tools without relying on a paid AI agent

---

## 🔒 Security

Never expose API keys in source code.

❌ Don't do:

```javascript
const API_KEY = "my-secret-key";
```

✅ Use environment variables:

```javascript
const API_KEY = process.env.WEATHER_API_KEY;
```

And add `.env` to `.gitignore`:

```gitignore
.env
node_modules/
```

---

## 📚 MCP Concepts Demonstrated

```text
MCP
│
├── MCP Server
│
├── MCP Client
│
├── Tools
│
├── Tool Schema
│
├── Transport
│   └── stdio
│
└── External APIs
```

---