Weather MCP Server 🌤️

A production-ready Model Context Protocol (MCP) server for weather data, based on the official MCP quickstart guide. This project extends the basic tutorial with enterprise-grade features including containerization, production builds, and advanced deployment options that go beyond the standard Claude Desktop integration.

🚀 Features

Real-time Weather Data: Get current weather conditions and forecasts
Weather Alerts: Receive weather alerts for US states
MCP Compatible: Full Model Context Protocol implementation following the official guide
Production Ready: Container support with multi-stage builds
Beyond Claude Desktop: Extended deployment options beyond the basic tutorial
Developer Friendly: TypeScript with comprehensive tooling
Multiple Transports: Stdio, SSE, and HTTP support via supergateway
DXT Package Support: Generate deployment packages for easy Claude Desktop integration

🎯 About This Project

This project starts with the official MCP server quickstart guide and extends it with production-grade features:

Enterprise Deployment: Containerization with Red Hat UBI images
Production Builds: Optimized builds with proper dependency management
DXT Packaging: Simplified deployment packages for Claude Desktop
Multiple Transports: Beyond stdio to include web interfaces
CI/CD Ready: GitHub Actions and container registry integration
Development Tools: Enhanced debugging and testing capabilities

If you're following the official MCP guide, this repository shows you how to take your weather server to production.

📦 Installation

Prerequisites

Node.js 20+ with npm
TypeScript 5.x
Docker/Podman (for containerized deployment)

Local Development

# Clone the repository
git clone https://github.com/alpha-hack-program/weather-mcp-js.git
cd weather-mcp-js

# Install dependencies
make install

# Build the project
make build

# Test the server
make test-stdio

Using with Claude Desktop

Method 1: Quick Setup with DXT Package (Recommended)

Create a deployment package for easy Claude Desktop integration:

# Create a DXT deployment package
make pack

This creates a weather-mcp.dxt file containing:

Compiled JavaScript code
Production dependencies only
Ready-to-use configuration
Installation instructions

To install the DXT package:

Copy the generated weather-mcp.dxt file to your desired location
Extract it: tar -xzf weather-mcp.dxt
Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/extracted/weather-mcp/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["C:\\path\\to\\extracted\\weather-mcp\\build\\index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Method 2: Direct Development Setup

For development or if you prefer to build from source:

macOS/Linux:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/weather-mcp-js/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Note: After updating your Claude Desktop configuration, restart Claude Desktop to load the new server.

🛠️ Usage

Available Tools

The weather MCP server provides the following tools:

`get_forecast`

Get weather forecast for a specific location.

{
  "name": "get_forecast",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

`get_alerts`

Get weather alerts for a US state.

{
  "name": "get_alerts",
  "arguments": {
    "state": "CA"
  }
}

Testing with MCP Inspector

# Start the MCP Inspector for interactive testing
make test-inspector

# Or test the stdio transport directly
make test-stdio

The inspector will open a web interface at http://localhost:5173 where you can interact with the server.

🐳 Container Deployment

Building Container Images

# Make the image script executable
chmod +x image.sh

# Build the container image
./image.sh build

# Push to registry
./image.sh push

# Run locally
./image.sh run

# Run from remote registry
./image.sh run-remote

Environment Configuration

The container build uses environment variables from .env:

# Container configuration
BASE_TAG="9.6"
BASE_IMAGE="registry.access.redhat.com/ubi9/nodejs-22-minimal"
CACHE_FLAG=""

# Registry settings
ORG=atarazana
REGISTRY=quay.io/${ORG}

# Application
APP_NAME=weather-mcp

Container Usage

# Run with Docker/Podman
docker run -it quay.io/atarazana/weather-mcp:latest

# Or with supergateway for web access
docker run -p 3000:3000 -it quay.io/atarazana/weather-mcp:latest

🧪 Development

Project Structure

weather-mcp-js/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── Containerfile         # Container build definition
├── image.sh             # Container management script
├── tsconfig.json        # TypeScript configuration
├── package.json         # Node.js dependencies and scripts
├── Makefile            # Build automation
└── .env                # Environment configuration

Available Make Targets

# Development
make install           # Install dependencies
make build            # Build TypeScript
make clean            # Clean build artifacts

# Testing
make test-stdio       # Test stdio transport
make test-inspector   # Test with MCP Inspector
make test-sse         # Test SSE transport

# Production
make pack             # Create DXT deployment package
make build-prod       # Production build only

# Container Management
make docker-build     # Build container image
make docker-push      # Push to registry
make docker-run       # Run container locally
make docker-clean     # Clean up containers

Build Automation

The project uses Make for consistent build automation following enterprise practices:

# Quick development cycle
make clean build test-stdio

# Production deployment
make pack

# Container workflow
make docker-build docker-push

🔧 Configuration

Environment Variables

NODE_ENV: Set to production for production builds
LOG_LEVEL: Logging level (debug, info, warn, error)

TypeScript Configuration

The project uses modern TypeScript with ES modules:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true
  }
}

🚀 Deployment Options

1. DXT Package Deployment (Recommended for Claude Desktop)

The easiest way to deploy for Claude Desktop:

# Create deployment package
make pack

# This generates weather-mcp.dxt containing:
# - Compiled JavaScript
# - Production dependencies
# - Installation instructions

Extract and configure in Claude Desktop:

tar -xzf weather-mcp.dxt
# Then update claude_desktop_config.json with the extracted path

2. Direct Node.js Deployment

For development or custom deployments:

# Production build
make build-prod

# Run directly
node build/index.js

3. Container Deployment

Enterprise container deployment:

# Build and run container
make docker-build
make docker-run

4. Web Interface with Supergateway

Beyond the official MCP guide - serve via HTTP/SSE:

# Install supergateway globally
npm install -g supergateway

# Build and serve with web interface
make build
supergateway --stdio "node build/index.js"

This enables web-based interaction and testing beyond Claude Desktop integration.

📚 API Reference

MCP Protocol

This server implements the Model Context Protocol specification:

Initialize: Establishes connection and capabilities
Tools: Provides weather-related tools
Tool Calls: Executes weather data requests

Tool Schemas

All tools use JSON Schema for input validation:

// Forecast tool schema
{
  type: "object",
  properties: {
    latitude: { type: "number", minimum: -90, maximum: 90 },
    longitude: { type: "number", minimum: -180, maximum: 180 }
  },
  required: ["latitude", "longitude"]
}

// Alerts tool schema
{
  type: "object",
  properties: {
    state: { type: "string", minLength: 2, maxLength: 2 }
  },
  required: ["state"]
}

🤝 Contributing

We welcome contributions! This project extends the official MCP quickstart guide with production features.

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Build and test: make clean build test-stdio
Test with the inspector: make test-inspector
Create a deployment package: make pack
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Code Style

Follow the official MCP guide patterns
Use TypeScript strict mode
Follow ESLint configuration
Add JSDoc comments for public APIs
Write meaningful commit messages
Test both stdio and web transports

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol for the official specification and quickstart guide
MCP Server Quickstart - the foundation of this project
Anthropic for Claude Desktop integration and MCP development
Alpha Hack Program for supporting production-grade MCP implementations

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Official MCP Guide: MCP Server Quickstart
MCP Documentation: Model Context Protocol Docs

🔄 Changelog

See CHANGELOG.md for version history and updates.

Built with ❤️ extending the official MCP guide for production use
From tutorial to production-ready deployment

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
src		src
.env.sample		.env.sample
.gitignore		.gitignore
Containerfile		Containerfile
Makefile		Makefile
README.md		README.md
icon.png		icon.png
image.sh		image.sh
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.prod.json		tsconfig.prod.json

alpha-hack-program/weather-mcp-js

Folders and files

Latest commit

History

Repository files navigation