APRS.fi MCP Server

Instructions

Implementation Reference

• index.ts:61-114 (handler)

  Core handler function that executes the get_aprs_position tool logic: validates inputs, calls APRS.fi API, parses response, and returns position data.

  async getPosition(callsign: string, apiKey?: string): 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'
    });
  
    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}`);
      }
  
      if (data.found === 0) {
        return [];
      }
  
      return data.entries.map(entry => ({
        ...entry,
        timestamp: entry.timestamp * 1000,
      }));
  
    } 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:288-305 (registration)

  Registration of the get_aprs_position tool in the ListTools handler, defining name, description, and input schema.

  {
    name: 'get_aprs_position',
    description: 'Get current position data for a specific callsign from APRS.fi',
    inputSchema: {
      type: 'object',
      properties: {
        callsign: {
          type: 'string',
          description: 'The callsign to look up (e.g., "W1AW")',
        },
        apiKey: {
          type: 'string',
          description: 'APRS.fi API key (optional if set via /set-api-key)',
        },
      },
      required: ['callsign'],
    },
  },

• index.ts:380-392 (handler)

  MCP CallToolRequestSchema switch case handler that invokes the APRS service's getPosition method and returns the result as JSON text.

  case 'get_aprs_position':
    const positions = await this.aprsService.getPosition(
      args.callsign as string,
      args.apiKey as string
    );
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(positions, null, 2),
        },
      ],
    };

• index.ts:15-27 (schema)

  TypeScript interface defining the structure of APRS position data returned by the 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;
  }