eve-online-traffic-mcp

Instructions

Implementation Reference

• src/name-to-id-tools.ts:148-218 (handler)

  Full MCP tool definition including handler (execute function), schema (parameters), name, description, and annotations. The execute function calls esiClient.namesToIds and processes results into a unified response.

  export const universalNameToIdTool = {
    annotations: {
      openWorldHint: true, // This tool interacts with external ESI API
      readOnlyHint: true, // This tool doesn't modify anything
      title: "Universal Name to ID",
    },
    description: "Convert EVE Online entity names (systems, stations, regions, etc.) to their corresponding IDs using ESI API",
    execute: async (args: { names: string[] }) => {
      try {
        const results = await esiClient.namesToIds(args.names);
        
        const allResults: Array<{ id: number; name: string; type: string }> = [];
        
        // Collect all results from different categories
        if (results.systems) {
          allResults.push(...results.systems.map(item => ({ ...item, type: "solar_system" })));
        }
        if (results.stations) {
          allResults.push(...results.stations.map(item => ({ ...item, type: "station" })));
        }
        if (results.regions) {
          allResults.push(...results.regions.map(item => ({ ...item, type: "region" })));
        }
        if (results.constellations) {
          allResults.push(...results.constellations.map(item => ({ ...item, type: "constellation" })));
        }
        if (results.corporations) {
          allResults.push(...results.corporations.map(item => ({ ...item, type: "corporation" })));
        }
        if (results.alliances) {
          allResults.push(...results.alliances.map(item => ({ ...item, type: "alliance" })));
        }
        if (results.characters) {
          allResults.push(...results.characters.map(item => ({ ...item, type: "character" })));
        }
        if (results.factions) {
          allResults.push(...results.factions.map(item => ({ ...item, type: "faction" })));
        }
        if (results.inventory_types) {
          allResults.push(...results.inventory_types.map(item => ({ ...item, type: "inventory_type" })));
        }
        if (results.agents) {
          allResults.push(...results.agents.map(item => ({ ...item, type: "agent" })));
        }
  
        if (allResults.length === 0) {
          return JSON.stringify({
            success: false,
            message: "No entities found with the provided names",
            results: []
          });
        }
  
        return JSON.stringify({
          success: true,
          message: `Found ${allResults.length} entity/entities`,
          results: allResults
        });
      } catch (error) {
        return JSON.stringify({
          success: false,
          message: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
          results: []
        });
      }
    },
    name: "universal_name_to_id",
    parameters: z.object({
      names: z.array(z.string()).min(1).max(500).describe("Array of entity names to convert to IDs (max 500). Use English proper nouns only (e.g., 'Jita', 'Caldari State', 'Tritanium')")
    }),
  };

• src/server.ts:48-48 (registration)

  Registers the universalNameToIdTool with the FastMCP server.

  server.addTool(universalNameToIdTool);

• src/esi-client.ts:201-223 (helper)

  Helper method in ESIClient that performs the actual ESI API call to convert names to IDs across multiple entity categories.

  async namesToIds(names: string[]): Promise<ESINameToIdResult> {
    if (names.length === 0) {
      throw new Error('Names array cannot be empty');
    }
    if (names.length > 500) {
      throw new Error('Maximum 500 names allowed per request');
    }
  
    const response = await fetch(`${this.baseUrl}/universe/ids/`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'User-Agent': this.userAgent,
      },
      body: JSON.stringify(names),
    });
  
    if (!response.ok) {
      throw new Error(`ESI API error: ${response.status} ${response.statusText}`);
    }
  
    return await response.json() as ESINameToIdResult;
  }

• src/esi-client.ts:5-16 (schema)

  TypeScript interface defining the structure of the ESI name-to-ID response used by the tool.

  export interface ESINameToIdResult {
    agents?: Array<{ id: number; name: string }>;
    alliances?: Array<{ id: number; name: string }>;
    characters?: Array<{ id: number; name: string }>;
    constellations?: Array<{ id: number; name: string }>;
    corporations?: Array<{ id: number; name: string }>;
    factions?: Array<{ id: number; name: string }>;
    inventory_types?: Array<{ id: number; name: string }>;
    regions?: Array<{ id: number; name: string }>;
    stations?: Array<{ id: number; name: string }>;
    systems?: Array<{ id: number; name: string }>;
  }

• src/server.ts:2-6 (registration)

  Imports the universalNameToIdTool for registration in the MCP server.

  import {
    solarSystemNameToIdTool,
    stationNameToIdTool,
    regionNameToIdTool,
    universalNameToIdTool