eve-online-traffic-mcp

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/route-tools.ts:13-123 (handler)

  The complete implementation of the calculate_route tool, including the execute handler that resolves system names/IDs, calculates route using ESI client, adds system names, and returns structured JSON response.
  export const calculateRouteTool = { annotations: { openWorldHint: true, // This tool interacts with external ESI API readOnlyHint: true, // This tool doesn't modify anything title: "Calculate Route", }, description: "Calculate the shortest route between two EVE Online solar systems using ESI API. Supports system names or IDs.", execute: async (args: { origin: string | number; destination: string | number; flag?: 'shortest' | 'secure' | 'insecure'; avoidSystems?: (string | number)[]; }) => { try { let originId: number; let destinationId: number; let avoidSystemIds: number[] | undefined; // Convert origin to ID if it's a string if (typeof args.origin === 'string') { const originResult = await esiClient.getSolarSystemIds([args.origin]); if (originResult.length === 0) { return JSON.stringify({ success: false, message: `Origin system '${args.origin}' not found`, route: null }); } originId = originResult[0].id; } else { originId = args.origin; } // Convert destination to ID if it's a string if (typeof args.destination === 'string') { const destinationResult = await esiClient.getSolarSystemIds([args.destination]); if (destinationResult.length === 0) { return JSON.stringify({ success: false, message: `Destination system '${args.destination}' not found`, route: null }); } destinationId = destinationResult[0].id; } else { destinationId = args.destination; } // Convert avoid systems to IDs if provided if (args.avoidSystems && args.avoidSystems.length > 0) { avoidSystemIds = []; for (const system of args.avoidSystems) { if (typeof system === 'string') { const avoidResult = await esiClient.getSolarSystemIds([system]); if (avoidResult.length > 0) { avoidSystemIds.push(avoidResult[0].id); } } else { avoidSystemIds.push(system); } } } // Calculate route with details const routeInfo = await esiClient.calculateRouteWithDetails( originId, destinationId, args.flag || 'shortest', avoidSystemIds ); // Get system names for the route const routeNames = await esiClient.idsToNames(routeInfo.route); const routeWithNames = routeInfo.route.map(systemId => { const systemName = routeNames.find(s => s.id === systemId); return { id: systemId, name: systemName?.name || `System ${systemId}` }; }); return JSON.stringify({ success: true, message: `Route calculated: ${routeInfo.jumps} jumps from ${routeInfo.origin.name} to ${routeInfo.destination.name}`, route: { ...routeInfo, route_with_names: routeWithNames, summary: { total_systems: routeInfo.route.length, total_jumps: routeInfo.jumps, route_type: routeInfo.flag, avoided_systems_count: avoidSystemIds?.length || 0 } } }); } catch (error) { return JSON.stringify({ success: false, message: `Error calculating route: ${error instanceof Error ? error.message : 'Unknown error'}`, route: null }); } }, name: "calculate_route", parameters: z.object({ origin: z.union([z.string(), z.number()]).describe("Origin solar system name (English proper noun like 'Jita') or ID"), destination: z.union([z.string(), z.number()]).describe("Destination solar system name (English proper noun like 'Amarr') or ID"), flag: z.enum(['shortest', 'secure', 'insecure']).optional().default('shortest').describe("Route preference: shortest (default), secure (high-sec only), or insecure (low/null-sec allowed)"), avoidSystems: z.array(z.union([z.string(), z.number()])).optional().describe("Optional array of solar system names (English proper nouns) or IDs to avoid in the route") }), };
• src/route-tools.ts:117-122 (schema)

  Zod input schema defining parameters for the calculate_route tool.
  parameters: z.object({ origin: z.union([z.string(), z.number()]).describe("Origin solar system name (English proper noun like 'Jita') or ID"), destination: z.union([z.string(), z.number()]).describe("Destination solar system name (English proper noun like 'Amarr') or ID"), flag: z.enum(['shortest', 'secure', 'insecure']).optional().default('shortest').describe("Route preference: shortest (default), secure (high-sec only), or insecure (low/null-sec allowed)"), avoidSystems: z.array(z.union([z.string(), z.number()])).optional().describe("Optional array of solar system names (English proper nouns) or IDs to avoid in the route") }),
• src/server.ts:18-63 (registration)

  Import of calculateRouteTool from route-tools.js and registration via server.addTool(calculateRouteTool). Also documented in the server info resource.
  import { calculateRouteTool, calculateMultipleRoutesTool, findSystemsInRangeTool } from "./route-tools.js"; import { getSystemCombatStatsTool } from "./combat-stats-tools.js"; import { getStationServicesTool, getSystemStationsTool, findStationsWithServicesTool, getStationAgentsTool } from "./station-services-tools.js"; import { findNearestLandmarksTool } from "./landmark-tools.js"; import { findNearestTradeHubTool } from "./nearest-trade-hub-tool.js"; const server = new FastMCP({ name: "EVE Online Traffic MCP", version: "1.0.0", }); // Add name to ID conversion tools server.addTool(solarSystemNameToIdTool); server.addTool(stationNameToIdTool); server.addTool(regionNameToIdTool); server.addTool(universalNameToIdTool); // Add system information tools server.addTool(solarSystemInfoTool); server.addTool(stargateInfoTool); server.addTool(systemConnectionMapTool); // Add region information tools server.addTool(regionInfoTool); server.addTool(constellationInfoTool); server.addTool(regionSystemsListTool); // Add route calculation tools server.addTool(calculateRouteTool); server.addTool(calculateMultipleRoutesTool); server.addTool(findSystemsInRangeTool);
• src/esi-client.ts:432-481 (helper)

  Supporting ESI client method called by the tool handler to compute the actual route using EVE Online ESI API /route/ endpoint.
  async calculateRouteWithDetails( originId: number, destinationId: number, flag: 'shortest' | 'secure' | 'insecure' = 'shortest', avoidSystems?: number[] ): Promise<ESIRouteInfo> { try { // Get the route const route = await this.calculateRoute(originId, destinationId, flag, avoidSystems); if (route.length === 0) { return { route: [], jumps: -1, origin: { id: originId, name: '' }, destination: { id: destinationId, name: '' }, flag, }; } // Get system names for origin and destination const systemNames = await this.idsToNames([originId, destinationId]); const originName = systemNames.find(s => s.id === originId)?.name || `System ${originId}`; const destinationName = systemNames.find(s => s.id === destinationId)?.name || `System ${destinationId}`; return { route, jumps: route.length - 1, // Number of jumps is route length minus 1 origin: { id: originId, name: originName }, destination: { id: destinationId, name: destinationName }, flag, avoided_systems: avoidSystems }; } catch (error) { // If route calculation fails, return a result indicating failure return { route: [], jumps: -1, origin: { id: originId, name: '' }, destination: { id: destinationId, name: '' }, flag, }; } }