N2YO Satellite Tracker MCP Server

Instructions

Implementation Reference

• src/server.ts:581-744 (handler)

  Main handler function that executes the tool logic: parses natural language query for location and time, fetches satellites above the location via N2YOClient, applies category filter, and returns structured JSON response.
  private async querySatellitesNatural( query: string, categoryFilter: string = "all" ): Promise<CallToolResult> { try { // Parse the natural language query const parsed = LocationTimeParser.extractLocationAndTime(query); if (!parsed.location) { return { content: [ { type: "text", text: "Could not identify a location in your query. Please specify a location like 'France', 'New York', or 'Germany'.", }, ], isError: true, }; } // Default to current time if no time specified const targetTime = parsed.time?.timestamp || Math.floor(Date.now() / 1000); const timeDescription = parsed.time?.description || "right now"; // Determine which satellites to get based on the query context let satellites; const categoryId = categoryFilter !== "all" ? this.n2yoClient.getCategoryId(categoryFilter) : 0; // Check if query is asking about future time (for predictions) or current/past time (for current position) const timeDiff = targetTime - Math.floor(Date.now() / 1000); if (timeDiff > 300) { // More than 5 minutes in the future // This is a future prediction query - but N2YO "above" endpoint only shows current satellites // We'll get current satellites and note the limitation satellites = await this.n2yoClient.getSatellitesAbove( parsed.location.latitude, parsed.location.longitude, 0, // altitude 85, // search radius categoryId ); const filteredSatellites = categoryFilter !== "all" ? satellites.filter((sat) => this.matchesCategoryFilter(sat, categoryFilter) ) : satellites; const response = { query: query, location: { name: parsed.location.name, coordinates: { latitude: parsed.location.latitude, longitude: parsed.location.longitude, }, }, time: { requested: timeDescription, note: "Showing satellites currently above the location. N2YO API provides current positions, not future predictions for overhead satellites.", }, categoryFilter: categoryFilter, satellites: filteredSatellites.map((sat) => ({ noradId: sat.satid, name: sat.satname, position: { latitude: sat.satlat, longitude: sat.satlng, altitude: sat.satalt, }, launchDate: sat.launchDate, internationalDesignator: sat.intDesignator, })), count: filteredSatellites.length, summary: `Found ${filteredSatellites.length} ${ categoryFilter === "all" ? "" : categoryFilter + " " }satellites currently above ${parsed.location.name}`, }; return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; } else { // This is a current or near-current time query satellites = await this.n2yoClient.getSatellitesAbove( parsed.location.latitude, parsed.location.longitude, 0, // altitude 85, // search radius categoryId ); const filteredSatellites = categoryFilter !== "all" ? satellites.filter((sat) => this.matchesCategoryFilter(sat, categoryFilter) ) : satellites; const response = { query: query, location: { name: parsed.location.name, coordinates: { latitude: parsed.location.latitude, longitude: parsed.location.longitude, }, }, time: { description: timeDescription, timestamp: targetTime, }, categoryFilter: categoryFilter, satellites: filteredSatellites.map((sat) => ({ noradId: sat.satid, name: sat.satname, position: { latitude: sat.satlat, longitude: sat.satlng, altitude: sat.satalt, }, launchDate: sat.launchDate, internationalDesignator: sat.intDesignator, })), count: filteredSatellites.length, summary: `Found ${filteredSatellites.length} ${ categoryFilter === "all" ? "" : categoryFilter + " " }satellites above ${parsed.location.name} ${timeDescription}`, }; return { content: [ { type: "text", text: JSON.stringify(response, null, 2), }, ], }; } } catch (error) { return { content: [ { type: "text", text: `Error processing natural language query: ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } }
• src/server.ts:34-63 (registration)

  Tool registration in the getTools() method, defining name, description, and input schema.
  { name: "query_satellites_natural", description: "Answer natural language questions about satellites like 'What satellites will be over France at 6:00 tonight?'", inputSchema: { type: "object", properties: { query: { type: "string", description: "Natural language query about satellites (e.g., 'What satellites will be over France at 6:00 tonight?', 'Show me military satellites above Germany now')", }, categoryFilter: { type: "string", enum: [ "all", "military", "weather", "gps", "amateur", "starlink", "space-stations", ], default: "all", description: "Optional filter for satellite category", }, }, required: ["query"], }, },
• src/server.ts:38-62 (schema)

  Input schema defining the expected parameters: query (required string) and optional categoryFilter.
  inputSchema: { type: "object", properties: { query: { type: "string", description: "Natural language query about satellites (e.g., 'What satellites will be over France at 6:00 tonight?', 'Show me military satellites above Germany now')", }, categoryFilter: { type: "string", enum: [ "all", "military", "weather", "gps", "amateur", "starlink", "space-stations", ], default: "all", description: "Optional filter for satellite category", }, }, required: ["query"], },
• src/server.ts:432-433 (helper)

  Dispatch case in callTool method that routes the tool call to the specific handler.
  case "query_satellites_natural": return await this.querySatellitesNatural(args.query, args.categoryFilter);
• src/server.ts:746-796 (helper)

  Helper function to filter satellites by category based on name keywords.
  private matchesCategoryFilter( satellite: any, categoryFilter: string ): boolean { const satName = satellite.satname?.toLowerCase() || ""; switch (categoryFilter) { case "military": return ( satName.includes("military") || satName.includes("defense") || satName.includes("nrol") || (satName.includes("usa") && satName.includes("classified")) ); case "weather": return ( satName.includes("weather") || satName.includes("noaa") || satName.includes("goes") || satName.includes("meteosat") ); case "gps": return ( satName.includes("gps") || satName.includes("navstar") || satName.includes("navigation") ); case "amateur": return ( satName.includes("amateur") || satName.includes("amsat") || satName.includes("cubesat") ); case "starlink": return satName.includes("starlink"); case "space-stations": return ( satName.includes("space station") || satName.includes("iss") || satName.includes("tiangong") ); default: return true; } }