eve-online-traffic-mcp

Instructions

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,
      };
    }
  }