# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Development Commands
```bash
# Development and testing
bun run dev # Run development server with .env file
bun run test # Run test suite
bun run test:watch # Run tests in watch mode
bun run typecheck # TypeScript type checking
bun run typecheck:watch # Type checking in watch mode
# Build and release
bun run build # Compile TypeScript to JavaScript
bun run release # Build and publish (with changesets)
# MCP Inspector for testing
bun run inspect # Test with MCP Inspector (dev)
bun run inspect:built # Test with MCP Inspector (built)
bun run inspect:http # Test with MCP Inspector (HTTP mode)
```
## Architecture Overview
This is an MCP (Model Context Protocol) server that provides weather data integration through OpenWeatherMap API. It implements 11 weather-related tools using the FastMCP framework.
### Core Components
- **Main Entry Point** (`src/main.ts`): Implements all 11 weather tools with FastMCP framework
- **Authentication System** (`src/auth/`): Handles both HTTP bearer token and stdio environment variable authentication
- **Schema Validation** (`src/schemas.ts`): Zod schemas for all 11 tools with comprehensive input validation
- **Transport Configuration** (`src/config/transport.ts`): Environment-driven transport selection (stdio/HTTP stream)
### Key Utilities
- **Client Resolver** (`src/utils/client-resolver.ts`): Manages OpenWeatherAPI client instances with session-based caching
- **Location Parser** (`src/utils/location-parser.ts`): Parses coordinates, city names, and various location formats
- **Weather Formatter** (`src/utils/weather-formatter.ts`): Formats API responses for display
### Transport Modes
The server supports dual transport modes:
- **Stdio Transport** (default): Uses `OPENWEATHER_API_KEY` environment variable
- **HTTP Stream Transport**: Uses Bearer token authentication
Transport selection is automatic based on environment detection in `src/config/transport.ts`.
### Weather Tools Available
11 weather tools covering current conditions, forecasts (hourly/daily/minutely), air quality, weather alerts, and location services. All tools use consistent error handling and session-based API client caching.
## Development Notes
- Built with Bun runtime and TypeScript (ES2022 modules)
- Uses `openweather-api-node` for OpenWeatherMap API integration
- Session-based authentication prevents repeated API key validation
- MCP Inspector configurations available for all transport modes
- Comprehensive error handling with context-aware messages
## Version Management
**IMPORTANT**: Keep the FastMCP server version in sync with package.json version.
When updating the version:
1. Update `package.json` version (done automatically by changesets)
2. Manually update the FastMCP server version in `src/main.ts` line 29 to match
3. Both versions must be identical for consistency