# MCP Server – `Weather MCP Server`

This project implements an MCP server built using the Model Context Protocol. It follows the [“Build an MCP server” tutorial](https://modelcontextprotocol.io/docs/develop/build-server) and provides custom tools for your application.

## Table of Contents

- [MCP Server – `Weather MCP Server`](#mcp-server--weather-mcp-server)
  - [Table of Contents](#table-of-contents)
  - [What this does](#what-this-does)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Usage](#usage)
  - [Tools / Endpoints](#tools--endpoints)
  - [Architecture \& How it Works](#architecture--how-it-works)
  - [Logging \& Best Practices](#logging--best-practices)
  - [Troubleshooting](#troubleshooting)

## What this does

This server exposes MCP tools that can be called by MCP clients (such as the Claude for Desktop client) to perform specific operations.  
In the tutorial you followed, the example implements two tools: `get_alerts(state)` and `get_forecast(latitude, longitude)`.  
In your version, you may have modified or added tools according to your use-case.

## Prerequisites

- Python 3.10 or higher (or whichever version you used)
- MCP SDK version ≥ 1.2.0 (for Python) as described.
- (If applicable) `uv` tool (or equivalent) for running the server.
- Internet connection (if the tools query external APIs).
- For integration with Claude for Desktop: ensure you have the client installed and configured correctly.

## Installation

1. Clone this repository:

   ```bash
   git clone <repo-url>
   cd <repo-name>
   ```

2. Create and activate a virtual environment:

   ```python3 -m venv .venv
   source .venv/bin/activate   # (on macOS/Linux)
   # or on Windows: .venv\Scripts\activate
   ```

3. Install dependencies:

   ```
   pip install mcp[cli] httpx
   ```

## Usage

To start the MCP server:

    uv run <server_file>.py

or if you don’t use uv, simply:

    python <server_file>.py

The server will start listening for MCP host messages (via stdio or HTTP depending on your transport).

If you’re integrating with Claude for Desktop, update your claude_desktop_config.json like this:

```
{
  "mcpServers": {
    "<server-name>": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/<server-dir>",
        "run",
        "<server_file>.py"
      ]
    }
  }
}
```

Then restart Claude for Desktop to pick up this configuration.

## Tools / Endpoints

Below are the tools exposed by the server:

get_alerts(state: str) -> str

Gets weather alerts for a US state (2-letter code, e.g., “CA”, “NY”).
Returns a formatted string of alerts or an informative message if none available.

get_forecast(latitude: float, longitude: float) -> str

Gets a weather forecast for a given latitude & longitude (US only, based on external API).
Returns a readable string summarizing the next few forecast periods.

(Modify this section if you added additional tools.)

## Architecture & How it Works

When a client sends a request:

1. The client sends your question to the LLM host.

2. The host selects which tool(s) to call (based on MCP tooling metadata).

3. The MCP server receives a tool invocation via JSON-RPC (or HTTP) and executes it.

4. The result is returned to the host, which then uses the LLM to formulate a natural language response to the user.
   (This flow is based on the “What’s happening under the hood” section of the tutorial.)

## Logging & Best Practices

- Do not write to stdout for stdio-transport servers (in Python: avoid print() statements) as it may corrupt JSON-RPC messages. Use a logging library that writes to stderr or file instead.

- Tool names should follow the naming conventions specified by MCP.

- Validate inputs and handle errors gracefully (e.g., when external API fails or returns unexpected data).

## Troubleshooting

- If the server isn’t showing up in the client (e.g., Claude for Desktop):

  - Check your JSON config syntax.

  - Ensure the path to your server script is absolute.

  - Make sure you fully quit and restart the client application.

- If tool calls fail silently:
  - Check client logs (e.g., ~/Library/Logs/Claude/mcp\*.log on macOS).
  - Verify that your server runs without startup errors.
  - Confirm that your network/API access is working (for example, if using an external weather API).
- If you're working outside the US and the example API only supports US locations: consider switching to a global API or adjust the logic accordingly.