Skip to main content
Glama
osnat-2

MalkaBruk-MCPProject

by osnat-2
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MCP Weather Forecast Project

📋 Project Overview

This project demonstrates a complete Model Context Protocol (MCP) Server implementation with Playwright-based browser automation. It enables Claude AI to fetch real-time weather forecasts from Israeli and USA weather websites by automating browser interactions without manual intervention.

The project implements two MCP servers:

  1. weather_USA.py - Fetches USA weather alerts and forecasts from the National Weather Service API

  2. weather_Israel.py - Automates browser interactions with the Israel Weather 2 Day website using Playwright

Related MCP server: weather-mcp-playwright

🎯 Learning Objectives

By working through this project, you will understand:

  • ✅ How to implement your own MCP Server for custom needs

  • ✅ How to use Playwright to add browser control capabilities to LLMs

  • ✅ How to manage browser automation sessions across multiple tool calls

  • ✅ How to create an orchestrator that manages multiple MCP clients

  • ✅ How to integrate Claude AI with custom tools

🛠️ Technology Stack

  • MCP SDK: Anthropic's official library for exposing tools to LLMs

  • Playwright: Microsoft's browser automation library for reliable browser control

  • FastMCP: Decorator-based framework for building MCP servers quickly

  • Cohere API: Cohere's advanced LLM for intelligent tool selection and execution

  • Python 3.13+: Async-first Python implementation

📦 Installation

Prerequisites

  • Python 3.13 or higher

  • Pip or Uv package manager

Setup Steps

  1. Clone or navigate to the project directory:

cd MCPProject

  1. Install dependencies:

uv sync

Or with pip:

pip install -r requirements.txt

  1. Set up environment variables: Create a .env file in the project root:

COHERE_API_KEY=your-cohere-api-key-here

You can get a Cohere API key from cohere.com

  1. Install Playwright browsers:

playwright install

🚀 How to Run

Running the Interactive Chat Host

uv run host.py

The host will:

  1. Connect to both MCP servers (USA and Israel weather)

  2. Display available tools

  3. Start an interactive chat loop

  4. Allow you to ask questions about weather forecasts

Type your weather-related questions and press Enter. Type quit to exit.

💬 Example Questions and Answers

For USA Weather:

Query: What are the active weather alerts in California?
[System connects to weather_USA MCP and calls get_alerts_in_USA tool]
Response: [Weather alerts for California displayed]
Query: What's the forecast for latitude 40.7128 and longitude -74.0060 (New York)?
[System calls get_forecast_in_USA tool with coordinates]
Response: [5-day forecast for NYC]

For Israel Weather:

Query: Tell me the weather forecast for Tel Aviv
[System performs the following steps]
1. Opens browser with open_weather_forecast_israel()
2. Enters "Tel Aviv" with enter_weather_forecast_city_israel("Tel Aviv")
3. Selects first city option with select_weather_forecast_city_israel()
4. Extracts forecast with extract_weather_forecast_israel()
Response: [Current weather and forecast for Tel Aviv]
Query: What's the weather like in Jerusalem?
[Same process as above, but for Jerusalem]
Response: [Weather forecast for Jerusalem]

📐 Architecture

System Components

┌─────────────────────────────────────────────────────────┐
│                 host.py (ChatHost)                       │
│  - Orchestrates multiple MCP clients                     │
│  - Manages tool discovery and execution                  │
│  - Handles Claude AI interaction                         │
└─────────────────────────────────────────────────────────┘
         │                                          │
         ▼                                          ▼
┌──────────────────────┐              ┌──────────────────────┐
│  weather_USA.py      │              │  weather_Israel.py   │
│  (MCP Server)        │              │  (MCP Server)        │
│                      │              │                      │
│ Tools:               │              │ Tools:               │
│ • get_alerts_in_USA  │              │ • open_browser       │
│ • get_forecast_USA   │              │ • enter_city         │
│                      │              │ • select_city        │
│                      │              │ • extract_forecast   │
└──────────────────────┘              └──────────────────────┘
         │                                          │
         ▼                                          ▼
┌──────────────────────┐              ┌──────────────────────┐
│ NWS API              │              │ Chromium Browser     │
│ (weather.gov)        │              │ (Playwright)         │
└──────────────────────┘              └──────────────────────┘

Tool Execution Flow

  1. User Query → ChatHost

  2. Tool Discovery → List available tools from all MCP servers

  3. Cohere Analysis → Cohere AI determines which tools to use

  4. Tool Execution → Execute tools in sequence with results

  5. Response Loop → If more tools needed, repeat; otherwise return final answer

🔧 Implementation Details

weather_USA.py - API-Based Approach

  • Uses the National Weather Service API

  • No browser automation needed

  • Direct HTTP requests to fetch structured data

  • Tools:

    • get_alerts_in_USA(state) - Fetches active alerts for a US state

    • get_forecast_in_USA(latitude, longitude) - Gets 5-day forecast for coordinates

weather_Israel.py - Browser Automation Approach

  • Uses Playwright for browser control

  • Automates the weather2day.co.il website

  • Maintains browser session across tool calls

  • Tools:

    • open_weather_forecast_israel() - Opens browser and navigates to website

    • enter_weather_forecast_city_israel(city_name) - Types city name in search field

    • select_weather_forecast_city_israel() - Clicks first matching city from dropdown

    • extract_weather_forecast_israel() - Extracts and cleans forecast data from page

Key Implementation Features

Browser Session Management:

# Global browser/page instances to keep browser open
_browser: Browser | None = None
_page: Page | None = None

async def ensure_browser_initialized():
    """Initialize browser if not already done"""
    # Browser persists across tool calls

Tool Definition with FastMCP:

@mcp.tool()
async def tool_name(param1: str) -> str:
    """Tool description for Claude"""
    # Implementation

MCP Client Integration:

  • Each MCP server runs as a subprocess

  • Host communicates via stdio (MCP protocol)

  • Tools are prefixed with server name to avoid conflicts

📝 Project Structure

MCPProject/
├── host.py                 # Main orchestrator
├── client.py              # MCP client implementation
├── weather_USA.py         # USA weather MCP server
├── weather_Israel.py      # Israel weather MCP server
├── pyproject.toml         # Project dependencies
├── python-version.txt     # Required Python version
└── README.md             # This file

🔍 Understanding MCP Tools

Tool Definition

Each tool is a Python async function decorated with @mcp.tool():

@mcp.tool()
async def my_tool(param: str) -> str:
    """
    Detailed description of what the tool does.
    This docstring is sent to Cohere to help it understand when to use this tool.
    
    Args:
        param: Parameter description
    
    Returns:
        str: Description of return value
    """
    # Implementation
    return result

Tool Discovery

When the host connects to an MCP server, it:

  1. Sends a list_tools() request

  2. Receives tool metadata (name, description, input schema)

  3. Registers tools with namespace: {server_name}__{tool_name}

  4. Sends full tool list to Claude

Tool Execution

When Cohere calls a tool:

  1. Host receives the tool name and arguments

  2. Maps to original tool name and MCP client

  3. Calls the tool on the specific MCP server

  4. Receives result and provides to Cohere

  5. Cohere uses result for next reasoning step

🧪 Testing Individual Tools

You can test tools directly in Python:

import asyncio
from weather_Israel import open_weather_forecast_israel, enter_weather_forecast_city_israel

async def test():
    result1 = await open_weather_forecast_israel()
    print(result1)
    
    result2 = await enter_weather_forecast_city_israel("Tel Aviv")
    print(result2)

asyncio.run(test())

🐛 Troubleshooting

Browser Not Opening

  • Ensure Playwright browsers are installed: playwright install

  • Check if Chromium is blocked by antivirus

  • Try adding headless=True to browser launch for background mode

Tool Not Found

  • Ensure both weather_*.py files are in the same directory

  • Check that MCP servers are starting successfully (look for "Connected to server with tools" messages)

  • Verify tool names match exactly

Timeout Issues

  • Increase the timeout in Playwright selectors

  • Check if the website structure has changed

  • Add wait conditions for specific elements

SSL/Certificate Issues

The code handles Netfree networks with SSL verification disabled. For production, remove verify=False from httpx configuration.

🎓 Extension Ideas

  1. Add more weather sources - Create additional MCP servers for different weather APIs

  2. Caching layer - Store forecast data to avoid repeated browser automation

  3. Notification system - Alert when severe weather is forecasted

  4. Multi-language support - Handle queries in Hebrew and English

  5. Historical data - Compare current forecast with historical weather patterns

  6. GUI Dashboard - Create a web interface showing forecasts from all sources

📚 Resources

🤝 Contributing

To add new weather sources:

  1. Create a new weather_*.py file with MCP server implementation

  2. Add MCPClient entry in host.py

  3. Test with sample queries

  4. Document tools in README

📄 License

This project is for educational purposes.

Happy weather forecasting! 🌤️

Available Tools

2 tools
get_alerts_in_USAB

Get weather alerts for a USA state

Args: state: Two-letter USA state code (e.g. CA, NY)

ParametersJSON Schema
NameRequiredDescriptionDefault
stateYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden, yet it discloses nothing about behavior beyond the bare purpose. It does not say the operation is read-only, whether alerts are US-national or state-scoped at runtime, freshness/rate limits, or auth needs. An output schema exists, so return-value explanation is legitimately omitted, but the behavioral gaps remain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence plus a compact Args block; the purpose is front-loaded and nothing is padded. The Args formatting is slightly redundant with the schema but not wasteful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with an output schema, the description covers purpose and the parameter format adequately. What is missing is routing guidance relative to the get_forecast_in_USA sibling and any read-only/safety framing, given zero annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% (the schema only labels the field 'State'), so the description must compensate, and it does: it specifies the format as a two-letter USA state code with examples (CA, NY). That is meaningful added meaning beyond the raw schema, though casing/validation rules are unstated.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get weather alerts') scoped to a USA state, which is clear enough to distinguish from the get_forecast_in_USA sibling in practice. It never explicitly names that sibling or clarifies the alerts-vs-forecast distinction, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no conditions or exclusions, and the sibling get_forecast_in_USA is not mentioned. The agent gets no help deciding between alerts and forecast from this description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_forecast_in_USAC

Get weather forecast for a location in USA.

Args: latitude: Latitude of the location longitude: Longitude of the location

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYes
longitudeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It implies a read-only operation by using 'Get', but does not state whether the tool requires authentication, has rate limits, or returns any particular forecast format, despite an output schema existing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the core purpose. The Args section is somewhat redundant with the input schema, but it does not obscure the main statement and remains easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter weather forecast tool with an output schema, the description covers the essential purpose but leaves gaps in usage guidance and parameter semantics. It is minimally viable, though an agent must infer coordinate conventions and when to prefer this tool over the sibling alerts tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It only repeats the parameter names with 'Latitude of the location' and 'Longitude of the location', adding no format, range, or coordinate-system details beyond the schema's titles and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get weather forecast for a location in USA.' This clearly distinguishes it from the sibling get_alerts_in_USA, which likely returns weather alerts rather than forecasts. However, it does not explicitly name or contrast with the sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus get_alerts_in_USA, nor does it mention prerequisites, limitations, or exclusions. Usage is only implied by the tool name and basic purpose statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_alerts_in_USA
    • First observedget_forecast_in_USA
Deploy Server
Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

TDQS

B3.2/5.0

Scored across 2 tools

Disambiguation5/5

get_alerts_in_USA and get_forecast_in_USA target clearly distinct things (alerts vs forecast) and even take different argument styles (state code vs lat/long). An agent can easily pick the right one.

Naming Consistency5/5

Both follow an identical get_<noun>_in_USA pattern, consistent verb and resource style. No deviation between the two tools.

Tool Count3/5

Only 2 tools for a weather server is on the thin side; common capabilities like current conditions or multi-day summaries are absent. Still, the two present cover recognizable distinct needs, so it is borderline rather than broken.

Completeness3/5

Alerts and forecast are covered, but there is no current-conditions, historical, or non-USA coverage, leaving notable gaps. The surface is functional for its narrow scope but has dead ends for typical weather queries.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Weather MCP Server

    agentventure
    F
    license
    B
    quality
    D
    maintenance
    An MCP server that provides weather information and alerts for US locations using the National Weather Service API, enabling retrieval of weather forecasts and active weather alerts.
    2
    -

  • Israel Weather MCP

    ruti1820-git
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server that provides Israeli weather forecasts using browser automation with Playwright.
    -

  • Weather Israel MCP

    avigail4408
    F
    license
    B
    quality
    C
    maintenance
    MCP server that enables LLMs to retrieve weather forecasts for Israeli cities by automating a browser with Playwright, and also provides US weather alerts and forecasts via NWS API.
    4
    -