Weather MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is an HTTP-based MCP (Model Context Protocol) server built with TypeScript that provides temperature conversion tools. The server is designed for deployment on AWS. ## Commands ### Development - `npm run dev` - Run the server in development mode with hot reload using tsx - `npm run build` - Compile TypeScript to JavaScript (output in `build/`) - `npm start` - Run the compiled server from `build/index.js` ### Deployment - `npm run deploy` - First-time deployment with guided setup (builds + deploys to AWS Lambda) - `npm run deploy:quick` - Quick deployment using saved config (builds + deploys) - `sam delete --stack-name weather-mcp` - Delete all AWS resources ### Environment Variables - `PORT` - Server port (default: 3000) - `NODE_ENV` - Set to `production` in Lambda - `AWS_LAMBDA_FUNCTION_NAME` - Auto-set by Lambda (used to detect Lambda environment) ## Architecture ### Server Structure The server uses the MCP SDK with an HTTP transport layer: - **Transport**: `StreamableHTTPServerTransport` for HTTP-based MCP communication - **Framework**: Express.js handles HTTP requests on the `/mcp` endpoint - **Server**: `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js` ### Tool Registration Tools are registered using `server.registerTool()` with: - Tool name (identifier) - Configuration object with title, description, inputSchema (Zod), and outputSchema (Zod) - Async handler function that returns content and structuredContent Example: ```typescript server.registerTool( 'toolName', { title: 'Display Name', description: 'What the tool does', inputSchema: { param: z.number() }, outputSchema: { result: z.number() } }, async ({ param }) => ({ content: [{ type: 'text', text: JSON.stringify(output) }], structuredContent: output }) ); ``` ### Request Handling - Each HTTP request creates a new `StreamableHTTPServerTransport` to prevent request ID collisions - Transport is connected to the server for each request - Transport is closed when the response closes ### Module System - Uses ES modules (`"type": "module"` in package.json) - All imports use `.js` extensions (TypeScript convention for ES modules) - TypeScript config: `"module": "Node16"`, `"moduleResolution": "Node16"` ### Lambda Deployment - Server runs both locally (Express listening on port) and on AWS Lambda (serverless handler) - Uses `@vendia/serverless-express` to adapt Express app for Lambda - Lambda handler exported as `export const handler = serverlessExpress({ app })` - Deployment configured in `template.yaml` (AWS SAM template) - Stack name: `weather-mcp` - Region configured in `samconfig.toml` (default: us-east-1) **Deployment files:** - `template.yaml` - AWS SAM CloudFormation template - `samconfig.toml` - SAM CLI configuration - `DEPLOYMENT.md` - Step-by-step deployment guide ## Current Tools - **transformFahrenheitToCelsius**: Converts Fahrenheit to Celsius using the formula `(F - 32) × 5/9` ## AWS Deployment Quick Reference **Prerequisites:** AWS CLI + SAM CLI installed, AWS credentials configured **First deploy:** ```bash npm run deploy ``` **Update deployment:** ```bash npm run deploy:quick ``` **Delete everything:** ```bash sam delete --stack-name weather-mcp ``` **View logs:** ```bash sam logs -n WeatherMcpFunction --stack-name weather-mcp --tail ``` See `DEPLOYMENT.md` for detailed setup instructions.