swmcc/ship_angel_mcp_server

mcp-weather-ruby

Description

A minimal MCP (Model Context Protocol) server written in Ruby that exposes a single tool: weather_by_area. It lets MCP‑aware clients (e.g. Claude Desktop) answer:

“What’s the current weather in a specific ZIP/postcode/area code?”

This repo is intentionally small and time‑boxed to demonstrate approach, tests, and workflow.

Notes

This is a running log of my development workflow — thoughts, decisions, and reasoning captured alongside commits.

It’s deliberately rough and incremental: a place to record what worked, what failed, and why certain choices were made in the moment.

The goal is to keep a transparent trail of the project’s evolution, so that the final write-up (WRITEUP.md) can be more polished and structured.

Write-Up

This is a work-in and serves as the final, polished summary of the project.

Where NOTES.md captures my raw, in-progress thoughts and debugging trails, this write-up will explain the project’s goals, design, implementation, and lessons learned in a clean narrative.

It provides enough context for someone new to the repository to quickly understand what was built, why, and how — without having to dig through the commit history or development notes.

Scope

• Tool name: weather_by_area
• Inputs:
  • area (string, required) – ZIP/postcode/area code (e.g., 10001, SW1A1AA)
  • country (string, optional, default: "US") – ISO‑2 code (e.g., US, GB, CA)
  • units (string, optional, default: "metric") – one of standard, metric, imperial
• Behaviour:
  • Defaults to US if country not supplied (honours the original “ZIP” wording).
  • Uses WeatherAPI’s current weather endpoint with zip=<area>,<country>.
  • Returns a concise summary (conditions, temperature, feels‑like, humidity, wind).
  • On missing/unknown locations, responds gracefully with a clear not‑found message.

⚠️ International note: Some non‑US postcodes work when you pass country, but true global coverage typically needs a geocoding step (see Next Steps).

Prerequisites

• Ruby 3.2+
• Bundler
• An WeatherAPI API key (free tier is fine)

Setup

make install
cp .env.example .env # set WEATHERAPI_KEY=your_key_here
make tests

Run the MCP server

make run

Use with Claude Desktop

Add this entry to Claude Desktop’s local MCP configuration (Settings → Developer/Extensions → Add local MCP server), or your JSON config:

{
  "mcpServers": {
    "mcp-weather-ruby": {
      "command": "/absolute/path/to/mcp-weather-ruby/bin/server",
      "args": []
    }
  }
}

Examples to ask Claude: • “What’s the current weather in 10001?” • “Weather for 94016, imperial units.” • “What’s the weather for SW1A1AA, GB?”

Claude will discover the tool, call it with structured args, and include the result in its answer.

Testing

This project uses RSpec and WebMock to avoid live API calls.

make tests

Included specs cover:

• Happy path (valid ZIP returns formatted text)
• 404 “not found” handled gracefully
• Missing API key error path

Design Choices (brief)

• Ruby + MCP gem: idiomatic and minimal; keeps the spike focused on MCP mechanics.
• Transport: stdio, which Claude Desktop expects for local servers.
• Provider: WeatherAPI for a simple zip,country lookup and predictable responses.
• Naming: weather_by_area avoids US‑only assumptions while still meeting the “ZIP” prompt.
• Errors: Clear, human‑readable messages for 404 and config issues.
• Tests: Behaviour‑focused with WebMock stubs; fast and deterministic.

Next Steps (if time allowed)

• Add a geocoding step (e.g., postal code → lat/lon) for robust international support.
• Rename fields to be more precise (postal_code) and validate via regex per country.
• Add a tiny in‑memory cache (~60–120s) to limit external calls.
• Optional second tool: forecast or units conversion.
• CI via GitHub Actions (ruby/setup-ruby, run RSpec).