Skip to main content
Glama

Weather Forecast MCP Portfolio Project

This project is an advanced portfolio piece that demonstrates a professional-grade workflow for integrating LLMs with custom MCP servers and browser automation.

It showcases how to build a multi-agent system in Python that uses:

  • Anthropic MCP SDK for exposing custom tools to a language model.

  • Playwright for automated browser control and web interaction.

  • Groq for LLM orchestration and tool selection.


Project Overview

The solution includes three main components:

  • host.py — the chat host that connects to multiple MCP clients, discovers available tools, and forwards user requests to the LLM.

  • client.py — a generic MCP client wrapper that launches MCP server scripts and manages STDIO communication.

  • weather_USA.py — a classic MCP server that fetches weather data from the NWS API for the USA.

  • weather_Israel.py — a new MCP server that performs browser automation to retrieve Israeli weather forecast data from a website.

The architecture intentionally separates concerns: one MCP handles API-based weather data, while another MCP handles browser-driven Israeli weather retrieval.


Related MCP server: Israel Weather MCP Server

Why this project is portfolio-worthy

This project is designed to reflect both technical depth and learning progress:

  • Building a custom MCP Server from scratch.

  • Integrating browser automation with an LLM workflow.

  • Enabling the model to choose and orchestrate tools dynamically.

  • Solving a real-world problem with non-conventional data access.

It demonstrates the ability to design and implement advanced AI tooling, not just consume existing APIs.


Learning Goals

This project highlights the key professional and educational outcomes:

  • Build an independent MCP Server that exposes custom tools to an LLM.

  • Use Playwright to extend the LLM with browser automation capabilities.

  • Design a multi-step flow that answers real user queries through tool orchestration.

  • Apply RAG-style contextual enrichment by extracting and using page content.


Technical Stack

  • MCP SDK — Anthropic's official toolkit for defining the MCP protocol and exposing tools to the model.

  • Playwright — Microsoft's modern browser automation framework, used here to automate a real website and perform human-like interactions.


Project Requirements

The main goal is to build a new MCP Server that handles Israeli weather forecast requests by opening a browser and navigating to a specific site, rather than using a conventional API.

Recruiter-worthy highlights:

  • A custom MCP Server focused on browser-based data retrieval.

  • Playwright-driven automation for searching and selecting a city in a live website.

  • A multi-step tool chain that simulates manual browsing from within an AI agent.

  • Page extraction and contextualization for the LLM.


Development Stages

Stage 0 — Project Structure

project-template/
├── client.py          # generic MCP Client
├── host.py            # terminal chat host that ties everything together
├── weather_USA.py     # MCP Server for USA using API
└── weather_Israel.py  # ← your core Israel-focused MCP

Stage A — Implement Tools with Playwright

Goal: implement MCP tools that allow the LLM to fetch Israeli weather forecast directly from the browser.

The new MCP should load the forecast page from: https://www.weather2day.co.il/forecast

The MCP exposes three Playwright-based tools that automate the complete flow:

  1. open_weather_forecast_israel — open the browser and navigate to the weather page.

  2. enter_weather_forecast_city_israel — enter the city name into the search field.

  3. select_weather_forecast_city_israel — select the first city suggestion from the list.

To make this work professionally:

  • define each function as an MCP tool using the decorator.

  • add the new MCP to the host's MCP client list.

  • run the system and verify the host selects the new MCP and executes the functions sequentially.

Example command:

uv run host.py

Then ask the system for a forecast in a given city and confirm that the host opened the forecast page in the browser.


Stage B — Let the LLM Finish the Answer

Goal: move beyond tool execution and give the LLM page content so it can answer directly in chat.

Add another tool that extracts the page content, cleans it, and returns a useful context snippet for the LLM. This is the RAG-style enhancement: the model receives actual page text and can incorporate it into the response.


How it works

  1. host.py connects to the MCP clients defined in client.py.

  2. It asks Groq to decide which tool should run for a given user query.

  3. The selected MCP tool runs and returns real data.

  4. If the browser-based MCP is used, Playwright drives the website and extracts context from the page.

  5. The result is returned to the user as a fully formed chat answer.


Why this project matters for AI recruiting

This project shows that I can:

  • architect multi-agent systems.

  • implement custom MCP tools for business logic.

  • use browser automation to access data behind interactive websites.

  • enrich LLM responses with real-world context.

  • solve engineering problems that involve both AI and automation.


Run Instructions

  1. Install dependencies:

python -m pip install -U pip
python -m pip install groq>=0.4.0 mcp>=1.27.0 python-dotenv>=1.2.2 playwright>=1.44.0
python -m playwright install
  1. Create a .env file with:

GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=mixtral-8x7b-32768
  1. Run the host:

python host.py
  1. Ask a query about weather forecast in Israel or the USA.


Sample Questions

  • What is the weather forecast for Jerusalem today?

  • Open the Israeli weather site and get the forecast for Tel Aviv.

  • Are there any weather alerts in California?

  • Use the Israel browser tool and answer from the page content.

  • How do I get a 5-day forecast for a US location?


Notes

  • The Israeli MCP is intentionally browser-driven rather than API-driven.

  • The project emphasizes autonomous tool orchestration and dynamic LLM-driven execution.

  • This is a strong portfolio example for AI engineering, agent design, and browser automation skills.

Available Tools

4 tools
enter_weather_forecast_city_israelB

Enter city name in the weather forecast search field.

Args: city_name: Name of the city to search for weather forecast

Returns: dict: Operation result with city entered and search ready

ParametersJSON Schema
NameRequiredDescriptionDefault
city_nameYes

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions that the operation results in 'city entered and search ready,' implying a state change, but does not disclose side effects such as clearing previous input, requiring a loaded page, or whether it is safe/idempotent. This is minimal for a UI interaction.

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 concise and structured with an Args and Returns section, making it easy to parse. It contains no redundant content and front-loads the primary action. The format is slightly formal but appropriate.

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 tool with one parameter and no output schema, the description covers the core action and parameter meaning. However, it lacks any guidance on when to use it relative to siblings and does not elaborate on behavioral details or expected outcomes beyond a basic return dict. This is adequate but not comprehensive.

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 coverage is 0%, so the description is the only source of parameter meaning. It defines 'city_name' as 'Name of the city to search for weather forecast,' which adds clarity beyond the schema's simple 'City Name' title. This effectively compensates for the lack of schema descriptions.

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 clearly states the action: 'Enter city name in the weather forecast search field.' The verb 'enter' and resource 'city name' specify what the tool does. It is not a tautology and distinguishes itself from siblings implicitly (e.g., 'select' and 'open' would be different actions), though it does not explicitly name alternatives.

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 guidance is provided on when to use this tool versus siblings like select_weather_forecast_city_israel or open_weather_forecast_israel. There is no mention of prerequisites, sequencing, or context. The description only states the action, leaving the agent without direction on tool selection.

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

extract_page_context_for_llmA

Extract page content, clean it, and return context-ready text for an LLM.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations provided, the description carries the behavioral burden, and it does so by disclosing the extraction, cleaning, and final text output. It does not enumerate potential limitations like truncation or source-page assumptions, but the stated behavior is clear and non-destructive in nature.

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

Conciseness5/5

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

A single concise sentence states the operation, the transformation, and the output. Every word contributes information, with no filler.

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

Completeness4/5

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

Given the zero-parameter schema and low complexity, the description is complete enough for an agent to understand the tool's role. It explains the input source ('page') and the expected deliverable, though it leaves the exact page source implicit.

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?

The tool has zero parameters, and the schema already fully documents that. The description adds relevant context about the result format ('context-ready text for an LLM'), satisfying the 0-parameter baseline.

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

Purpose5/5

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

Description uses a specific verb ('Extract'), identifies the resource ('page content'), and states the outcome ('return context-ready text for an LLM'). It is unambiguous and clearly differentiates from the weather-focused sibling tools.

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

Usage Guidelines4/5

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

The description clearly implies the use case: use this tool when an LLM needs cleaned page content. It provides no exclusions, and the sibling tools are unrelated weather tools, so there is no real alternative-usage ambiguity.

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

open_weather_forecast_israelA

Open browser and navigate to Israel weather forecast page.

Returns: dict: Operation result with open and ready page for further queries

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description must disclose behavior. It states that it opens a browser and returns a dict indicating the page is ready. However, it does not mention failure scenarios, what happens to the browser session, or any additional side effects beyond opening the page.

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

Conciseness5/5

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

The description is two sentences with no redundancy. The action is front-loaded, and the return value is briefly stated. Every sentence serves a purpose.

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

Completeness4/5

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

For a zero-parameter tool with no output schema, the description provides the core information: what it does and what it returns. It could mention the specific weather site or the relation to sibling tools, but for a simple browser-navigation operation, this is sufficiently complete.

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?

The tool has zero parameters, so the schema fully covers the input. The description does not need to add parameter meaning, and the baseline of 4 applies. It correctly omits unnecessary parameter details.

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

Purpose5/5

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

The description clearly states the action: open a browser and navigate to the Israel weather forecast page. This is specific with a clear verb and resource, and it distinguishes itself from sibling tools that handle city entry, city selection, and page context extraction.

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?

There is no guidance on when to use this tool versus the siblings. It does not mention that it is a prerequisite for the other weather-related tools or any context for choosing it. The agent is left to infer usage.

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

select_weather_forecast_city_israelB

Select the first item from the city suggestions list.

Returns: dict: Operation result with selected city

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations provided, the description must disclose all behavioral traits, but it only states the action and return type. It does not describe whether the selection is a click or keyboard action, any side effects on the UI state, or prerequisites like an existing suggestions list. This minimal disclosure is inadequate for a mutation-like tool.

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

Conciseness5/5

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

The description is extremely concise, consisting of two sentences that front-load the primary action and follow with the return type. Every word earns its place; there is no redundancy or irrelevant detail. This is a model of concise specification.

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

Completeness2/5

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

For a tool with no parameters and no output schema, the description is still minimal. It fails to explain the prerequisite that a city suggestions list must be visible (likely after calling enter_weather_forecast_city_israel), and it does not describe the exact interaction (e.g., clicking or pressing Enter). An agent would lack sufficient context to call this correctly within the overall flow.

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?

The tool has zero parameters and the schema is trivially complete. The description adds no parameter-specific information, but there is nothing to add. Per the rubric, a parameterless tool receives a baseline of 4, and the description does not harm that baseline.

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 ('Select') and resource ('the first item from the city suggestions list'), which clearly indicates a UI selection action. It distinguishes from sibling tools like enter_weather_forecast_city_israel (which likely inputs text) and open_weather_forecast_israel (which opens a forecast), though it does not explicitly name them. The purpose is clear but could be more explicit about the list context.

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 its siblings. It does not mention that it should be called after entering a city or before opening a forecast, nor does it list any alternatives or exclusions. The usage context is left entirely to inference, which is insufficient for an agent to decide when to invoke it.

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. 4 tool updatesv0.1.0
    • First observedenter_weather_forecast_city_israel
    • First observedextract_page_context_for_llm
    • First observedopen_weather_forecast_israel
    • First observedselect_weather_forecast_city_israel

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool maps to a discrete step in the weather forecast automation flow: open the page, enter a city, select the suggestion, and extract content. The descriptions clearly separate entering from selecting, so an agent should have little trouble picking the right tool.

Naming Consistency3/5

The first three tools follow a similar verb_weather_forecast_city_israel pattern, but extract_page_context_for_llm breaks the convention entirely. The naming is still readable overall, but the mix of domain-specific and generic names prevents it from being highly consistent.

Tool Count5/5

Four tools is well-scoped for a focused browser automation workflow: open, enter, select, and extract. Each tool has a distinct role and none feels redundant or missing.

Completeness4/5

The set covers the core weather forecast workflow end-to-end, from opening the page to returning LLM-ready content. There are minor assumptions, such as always selecting the first suggestion, but the flow is complete enough for its stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers