APRS.fi MCP Server

Instructions

Implementation Reference

• index.ts:116-170 (handler)

  Core handler function that implements the get_aprs_history tool by querying the APRS.fi API for historical position data of a callsign over the last N hours.

  async getPositionHistory(
    callsign: string, 
    apiKey?: string,
    lastHours: number = 24
  ): Promise<APRSPosition[]> {
    const keyToUse = apiKey || this.apiKey;
    if (!keyToUse) {
      throw new APRSError('APRS API key not provided. Use /set-api-key command or provide apiKey parameter.');
    }
  
    if (!callsign?.trim()) {
      throw new APRSError('Callsign is required');
    }
  
    const params = new URLSearchParams({
      name: callsign.trim().toUpperCase(),
      what: 'loc',
      apikey: keyToUse,
      format: 'json',
      last: lastHours.toString()
    });
  
    try {
      const response = await fetch(`${this.baseUrl}?${params}`);
      
      if (!response.ok) {
        throw new APRSError(
          `APRS API request failed: ${response.status} ${response.statusText}`,
          response.status
        );
      }
  
      const data: APRSResponse = await response.json();
  
      if (data.result !== 'ok') {
        throw new APRSError(`APRS API error: ${data.result}`);
      }
  
      return data.entries.map(entry => ({
        ...entry,
        timestamp: entry.timestamp * 1000,
      })).sort((a, b) => a.timestamp - b.timestamp);
  
    } catch (error) {
      if (error instanceof APRSError) {
        throw error;
      }
      
      if (error instanceof TypeError && error.message.includes('fetch')) {
        throw new APRSError('Network error: Unable to connect to APRS.fi API. Check your internet connection.');
      }
      
      throw new APRSError(`Unexpected error: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• index.ts:394-407 (handler)

  MCP CallToolRequestSchema handler case for get_aprs_history that invokes the service method and returns the result as JSON text content.

  case 'get_aprs_history':
    const history = await this.aprsService.getPositionHistory(
      args.callsign as string,
      args.apiKey as string,
      args.lastHours as number
    );
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(history, null, 2),
        },
      ],
    };

• index.ts:306-328 (registration)

  Tool registration in ListToolsRequestSchema response, defining the name, description, and input schema for get_aprs_history.

  {
    name: 'get_aprs_history',
    description: 'Get position history for a callsign with time range',
    inputSchema: {
      type: 'object',
      properties: {
        callsign: {
          type: 'string',
          description: 'The callsign to look up',
        },
        apiKey: {
          type: 'string',
          description: 'APRS.fi API key (optional if set via /set-api-key)',
        },
        lastHours: {
          type: 'number',
          description: 'Number of hours to look back (default: 24)',
          default: 24,
        },
      },
      required: ['callsign'],
    },
  },

• index.ts:29-35 (schema)

  Type definition for the API response structure used in get_aprs_history.

  interface APRSResponse {
    command: string;
    result: string;
    what: string;
    found: number;
    entries: APRSPosition[];
  }

• index.ts:15-27 (schema)

  Type definition for individual APRS position data returned by the get_aprs_history tool.

  interface APRSPosition {
    name: string;
    callsign: string;
    lat: number;
    lng: number;
    altitude?: number;
    timestamp: number;
    comment?: string;
    speed?: number;
    course?: number;
    symbol?: string;
    path?: string;
  }