mcp-server-yr-weather

thebacons/mcp-server-yr-weather

3.2

If you are the rightful owner of mcp-server-yr-weather and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The YR Weather MCP Server is a Node.js application that provides a unified interface to the weather data APIs from the Norwegian Meteorological Institute (YR.no), facilitating easy consumption of weather information by AI agents and automated systems.

YR Weather MCP Server

The YR Weather MCP Server is a Node.js application that acts as a standardized "Model Context Protocol" (MCP) server. It provides a unified interface to the various weather data APIs offered by the Norwegian Meteorological Institute (YR.no), making it easy for AI agents and other automated systems to consume weather information.

The server includes a discovery mechanism, a standardized tool execution endpoint, and a real-time activity monitor via WebSockets. It also features a simple web-based UI for manual testing and demonstration.

Project Principles & Workflow

This project adheres to a strict development workflow. Before beginning any work, it is crucial to read and understand the guidelines in the following files:

  • GEMINI.md: Outlines the core principles for AI-assisted development, including planning, step-by-step execution, and testing.
  • PREFERENCES.md: Contains critical operational preferences and lessons learned for this specific project.

The core development cycle is as follows:

  1. Always work on a feature branch. The main branch is protected. Create a new branch for any new feature or bugfix (e.g., features/my-new-feature).
  2. Deep-Think & Plan: Before writing any code, analyze the requirements and create a clear implementation plan.
  3. Develop & Test: Implement the changes and create or update tests (unit, integration, functional) to ensure correctness and prevent regressions.
  4. Merge: Once all tests are successful, the feature branch can be merged into the main branch.

Features

  • MCP Manifest: A /mcp-manifest.json endpoint for service discovery, allowing clients to dynamically learn the server's capabilities.
  • Standardized Tool Execution: A single /execute endpoint to run any of the available weather tools.
  • Real-Time Activity Monitoring: A WebSocket interface that broadcasts all tool execution events (successes and failures) to connected clients.
  • Web UI Dashboard: An easy-to-use web interface for manual testing, map generation, and viewing the live activity log.
  • Modular Tool System: Each API integration is a separate module, making the system easy to extend.
  • Resilient Logic: Includes handling for API-specific constraints, such as the geographical limitations of the Nowcast API.

Architecture Overview

The application consists of three main parts:

  1. server.js: The core of the application. It's an Express.js server that sets up the HTTP endpoints (/execute, /mcp-manifest.json, /map) and the WebSocket server. It routes incoming requests to the appropriate tool.
  2. tools/ directory: Contains individual JavaScript modules, each acting as a client for a specific YR.no API endpoint (e.g., weather.js, sunrise.js).
  3. public/ directory: Contains the static assets (HTML, CSS, JS) for the frontend web UI. The UI is built with vanilla JavaScript and styled with Bootstrap 5.

Getting Started

Prerequisites

  • Node.js (v14 or later recommended)
  • npm (usually included with Node.js)

Installation

  1. Clone the repository:

    git clone https://github.com/thebacons/GeminiCLI-YR_Weather_MCP_Server.git
cd GeminiCLI-YR_Weather_MCP_Server

  2. Install the dependencies:

    npm install

Running the Server

To start the server, run the following command from the project root:

node mcp_servers/yr_weather_server/server.js

The server will start, and you will see a confirmation message in the console: YR Weather MCP Server with UI and WebSocket listening at http://localhost:3000

Development & Testing

A test script is available to verify the server's functionality.

Location: mcp_servers/yr_weather_server/test/test-server.js

To Run Tests:

node mcp_servers/yr_weather_server/test/test-server.js

This script will test all API endpoints and the WebSocket connection.

Lessons Learned & Technical Challenges

During development, several key challenges were encountered and resolved. Remembering these points will prevent repeating the same issues:

  1. API Geographical Constraints: The get_nowcast tool initially failed with a 500 Internal Server Error. The root cause was not a bug in our code, but that the API is only functional for locations within Scandinavia. The fix was to add a geographical check and return a user-friendly message for out-of-bounds locations. Lesson: Always assume an external API can have undocumented constraints; test edge cases like different geographical locations.
  2. Client-Side JavaScript Errors: The UI became unresponsive due to simple syntax errors in app.js (e.g., a missing catch block for a try, a missing parenthesis). These errors were not immediately obvious because they caused the script to fail silently. Lesson: Use the browser's developer console (F12) to check for JavaScript errors on the client-side. An unresponsive UI is often a sign of a critical syntax error.
  3. Server Restart Issues: The AI agent (Gemini) encountered EADDRINUSE errors when attempting to restart the server because the previous process was still running. Lesson: The user must manually stop the existing server process before the agent can restart it. This is a critical operational preference noted in PREFERENCES.md.

External & Protocol References