APRS.fi MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Development Commands ### Building and Running - `npm run build` - Compile TypeScript to JavaScript in dist/ - `npm start` - Run the compiled MCP server - `npm run dev` - Watch mode for development (TypeScript compilation with --watch) ### From Parent Project - `npm run mcp:build` - Build this MCP server from parent project - `npm run mcp:start` - Start this MCP server from parent project - `npm run mcp:dev` - Development mode from parent project ## Architecture ### MCP Server Structure This is a Model Context Protocol (MCP) server that provides APRS.fi API integration for ham radio position tracking. The architecture follows a service-oriented pattern: - **APRSMCPService**: Core service class handling APRS.fi API interactions - **APRSMCPServer**: MCP server wrapper that exposes service methods as MCP tools - **Single File Architecture**: All code is contained in `index.ts` for simplicity ### Key Components #### APRSMCPService (lines 42-240) - Manages APRS.fi API communication with rate limiting (1-second delay) - Handles error conversion from API responses to APRSError instances - Provides methods: `getPosition`, `getPositionHistory`, `getMultiplePositions`, `validateApiKey` - Converts Unix timestamps from seconds to milliseconds for consistency #### APRSMCPServer (lines 242-442) - Initializes MCP server with stdio transport - Registers 4 MCP tools: `get_aprs_position`, `get_aprs_history`, `track_multiple_callsigns`, `validate_aprs_key` - Converts service responses to MCP tool response format (JSON stringified text content) - Wraps APRSError instances in McpError for proper MCP error handling ### Data Flow 1. MCP client calls tool → APRSMCPServer receives request 2. Server validates arguments → calls appropriate APRSMCPService method 3. Service makes HTTP request to APRS.fi API → processes response 4. Service returns APRSPosition[] → Server wraps in MCP response format ### Error Handling Pattern - Custom `APRSError` class for service-level errors - Network errors detected via TypeError with 'fetch' message - API validation through response.result field checking - All errors converted to `McpError` at MCP layer ### TypeScript Configuration - Target: ES2022 with ESNext modules - Output: `dist/` directory with declarations - Strict mode enabled for type safety