MCP Weather Server

# MCP Weather Server A Model Context Protocol (MCP) server that provides weather information for any city using the Open-Meteo API. ## Overview This MCP server implements a simple weather tool that allows you to get current weather conditions for any city worldwide. It uses the Open-Meteo geocoding API to resolve city names to coordinates and then fetches current weather data including temperature and wind speed. ## Features - **City Weather Lookup**: Get current weather for any city by name - **Geocoding Integration**: Automatically resolves city names to coordinates - **Current Conditions**: Returns temperature and wind speed information - **Error Handling**: Graceful handling of invalid cities or API failures - **MCP Compatible**: Built using the official MCP SDK ## Prerequisites - Node.js (version 14 or higher) - npm or yarn package manager ## Installation 1. Clone this repository: ```bash git clone <repository-url> cd mcp-weather-server ``` 2. Install dependencies: ```bash npm install ``` ## Usage ### Local Development #### Building and Running the Server 1. Build the TypeScript code: ```bash npm run build ``` 2. Start the MCP Weather Server: ```bash npm start ``` Or for development (builds and runs in one command): ```bash npm run dev ``` The server will start and listen for MCP connections via stdio transport. ### Docker Deployment #### Quick Start with Docker 1. **Build the Docker images:** ```bash ./scripts/docker-build.sh ``` 2. **Run in production mode:** ```bash ./scripts/docker-run.sh production ``` 3. **Run in development mode (with hot reload):** ```bash ./scripts/docker-run.sh development ``` #### Manual Docker Commands **Build production image:** ```bash docker build -t mcp-weather-server:latest . ``` **Build development image:** ```bash docker build -f Dockerfile.dev -t mcp-weather-server:dev . ``` **Run with Docker Compose (production):** ```bash docker-compose up mcp-weather-server ``` **Run with Docker Compose (development):** ```bash docker-compose --profile dev up mcp-weather-server-dev ``` **Run standalone container:** ```bash docker run -it --rm --name mcp-weather-server mcp-weather-server:latest ``` #### Docker Features - **Multi-stage builds** for optimized production images - **Non-root user** for enhanced security - **Health checks** for container monitoring - **Resource limits** for controlled resource usage - **Development mode** with hot reload and volume mounting - **Node.js Inspector** for debugging support - **Persistent logging** with volume mounts ### Debugging #### MCP Inspector (Recommended) The MCP Inspector provides a specialized debugging interface for MCP protocol communications: **Start MCP Inspector:** ```bash npm run inspector ``` **Start with build and inspector:** ```bash npm run dev:inspector ``` **Access the Inspector:** - Open your browser to `http://localhost:5173` - The inspector provides a web-based interface to: - Monitor MCP protocol messages - Inspect tool calls and responses - Debug server-client communication - View real-time message flow #### Node.js Debugging **Start with Node.js inspector enabled:** ```bash npm run dev:debug ``` **Start with inspector and break on first line:** ```bash npm run dev:debug-brk ``` **Watch mode for TypeScript compilation:** ```bash npm run dev:watch ``` #### Docker Debugging **Run development container with all debugging tools:** ```bash ./scripts/docker-run.sh development ``` Or manually: ```bash docker-compose --profile dev up mcp-weather-server-dev ``` This exposes: - Port 9229: Node.js inspector - Port 5173: MCP inspector web interface - Port 3000: Application port (if needed) #### Connecting Debuggers 1. **MCP Inspector (Web Interface):** - Navigate to `http://localhost:5173` - Configure your MCP server connection - Monitor protocol messages in real-time 2. **Chrome DevTools:** - Open Chrome and navigate to `chrome://inspect` - Click "Configure" and add `localhost:9229` - Your Node.js process should appear under "Remote Target" - Click "inspect" to open DevTools 3. **VS Code:** - Add this configuration to your `.vscode/launch.json`: ```json { "type": "node", "request": "attach", "name": "Attach to MCP Server", "address": "localhost", "port": 9229, "localRoot": "${workspaceFolder}", "remoteRoot": "/app", "skipFiles": ["<node_internals>/**"] } ``` 4. **WebStorm/IntelliJ:** - Create a new "Attach to Node.js/Chrome" configuration - Set host to `localhost` and port to `9229` #### Debug Scripts Explained - `inspector`: Starts the MCP Inspector web interface - `dev:inspector`: Builds and starts the MCP Inspector - `dev:debug`: Starts with Node.js inspector on port 9229 - `dev:debug-brk`: Starts with Node.js inspector and breaks on the first line - `dev:watch`: Runs TypeScript in watch mode for continuous compilation #### Debugging Workflow 1. **For MCP Protocol Issues:** - Use `npm run dev:inspector` to monitor MCP messages - Check tool calls, responses, and protocol compliance 2. **For Code-Level Debugging:** - Use `npm run dev:debug` with Chrome DevTools or VS Code - Set breakpoints in your TypeScript source files 3. **For Docker Development:** - Use `./scripts/docker-run.sh development` - Access both MCP Inspector (port 5173) and Node.js inspector (port 9229) ### Available Tools #### `get-weather` Retrieves current weather information for a specified city. **Parameters:** - `city` (string): The name of the city to get weather for **Example Response:** ``` The current temperature in London is 15°C with a wind speed of 12 km/h. ``` ### Integration with MCP Clients This server can be integrated with any MCP-compatible client. The server exposes the `get-weather` tool that can be called with a city name parameter. ## API Dependencies This server relies on the following free APIs: - **Open-Meteo Geocoding API**: For converting city names to coordinates - **Open-Meteo Weather API**: For fetching current weather data No API keys are required as Open-Meteo provides free access to their weather data. ## Project Structure ``` mcp-weather-server/ ├── src/ # Source code │ ├── index.ts # Main entry point │ ├── server/ # Server implementation │ │ └── index.ts # MCP server setup │ ├── tools/ # Tool implementations │ │ └── weather-tool.ts # Weather tool logic │ ├── types/ # TypeScript type definitions │ │ └── weather.ts # Weather-related types │ └── utils/ # Utility functions │ └── api.ts # API client utilities ├── dist/ # Compiled JavaScript output ├── examples/ # Example configurations │ └── mcp-config.json # MCP client configuration example ├── docs/ # Documentation ├── tests/ # Test files ├── tsconfig.json # TypeScript configuration ├── package.json # Project dependencies and metadata ├── package-lock.json # Locked dependency versions ├── .gitignore # Git ignore rules └── README.md # This file ``` ## Dependencies - `@modelcontextprotocol/sdk`: Official MCP SDK for building servers - `zod`: Schema validation library for input validation ## Error Handling The server includes robust error handling for common scenarios: - **Invalid City Names**: Returns a helpful message when a city cannot be found - **API Failures**: Gracefully handles network errors or API unavailability - **Malformed Requests**: Input validation ensures proper request format ## Development ### Building This project uses ES modules. Make sure your Node.js version supports ES modules or use a transpiler if needed. ### Testing Currently, no automated tests are included. To test the server: 1. Start the server 2. Connect with an MCP client 3. Call the `get-weather` tool with various city names ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test thoroughly 5. Submit a pull request ## License ISC License ## Changelog ### Version 1.0.0 - Initial release - Basic weather lookup functionality - MCP SDK integration - Open-Meteo API integration ## Support For issues or questions, please open an issue in the repository.