eve-online-traffic-mcp

Instructions

Implementation Reference

• src/station-services-tools.ts:94-289 (handler)

  The primary handler implementation for the 'get_station_agents' tool. This exported constant defines the complete tool object for MCP, including annotations, description, the async execute function that handles station ID resolution, agent fetching from SDEClient and ESIClient, name resolution, and structured JSON response with agent details.

  export const getStationAgentsTool = {
    annotations: {
      openWorldHint: true, // This tool interacts with external APIs
      readOnlyHint: true, // This tool doesn't modify anything
      title: "Get Station Agents",
    },
    description: "Get information about agents located at specific stations, including their types, levels, and specializations",
    execute: async (args: { 
      stations: (string | number)[];
      includeResearchAgents?: boolean;
    }) => {
      try {
        if (args.stations.length === 0) {
          return JSON.stringify({
            success: false,
            message: "At least one station must be provided",
            stations: []
          });
        }
  
        if (args.stations.length > 20) {
          return JSON.stringify({
            success: false,
            message: "Maximum 20 stations allowed per request",
            stations: []
          });
        }
  
        const results: Array<{
          station_id: number;
          station_name?: string;
          system_name?: string;
          agents: Array<{
            agent_id: number;
            agent_name?: string;
            agent_type?: string;
            corporation_name?: string;
            division_id?: number;
            level?: number;
            quality?: number;
            is_locator?: boolean;
            is_research_agent?: boolean;
          }>;
        }> = [];
        const errors: string[] = [];
  
        // Convert station names to IDs if needed
        const stationIds: number[] = [];
        const stringStations = args.stations.filter(s => typeof s === 'string') as string[];
        const numericStations = args.stations.filter(s => typeof s === 'number') as number[];
  
        stationIds.push(...numericStations);
  
        if (stringStations.length > 0) {
          try {
            const stationIdResults = await esiClient.getStationIds(stringStations);
            stationIds.push(...stationIdResults.map(s => s.id));
            
            // Check for stations that weren't found
            const foundNames = stationIdResults.map(s => s.name.toLowerCase());
            const notFound = stringStations.filter(name => 
              !foundNames.includes(name.toLowerCase())
            );
            notFound.forEach(name => {
              errors.push(`Station '${name}' not found`);
            });
          } catch (error) {
            errors.push(`Error converting station names to IDs: ${error instanceof Error ? error.message : 'Unknown error'}`);
          }
        }
  
        // Get research agent IDs if requested
        let researchAgentIds: Set<number> = new Set();
        if (args.includeResearchAgents) {
          try {
            const researchIds = await sdeClient.getAllResearchAgentIds();
            researchAgentIds = new Set(researchIds);
          } catch (error) {
            console.warn('Failed to get research agent IDs:', error);
          }
        }
  
        // Process each station
        for (const stationId of stationIds) {
          try {
            // Get station basic info
            let stationName: string | undefined;
            let systemName: string | undefined;
            
            try {
              const stationInfo = await esiClient.getStationInfo(stationId);
              stationName = stationInfo.name;
              
              const systemInfo = await esiClient.getSolarSystemInfo(stationInfo.system_id);
              systemName = systemInfo.name;
            } catch (error) {
              console.warn(`Failed to get station info for ${stationId}:`, error);
            }
  
            // Get agents at this station
            const agents = await sdeClient.getAgentsByLocation(stationId);
            
            const agentInfos: Array<{
              agent_id: number;
              agent_name?: string;
              agent_type?: string;
              corporation_name?: string;
              division_id?: number;
              level?: number;
              quality?: number;
              is_locator?: boolean;
              is_research_agent?: boolean;
            }> = [];
  
            // Process each agent
            for (const agent of agents) {
              try {
                // Get agent name and corporation info
                const idsToResolve: number[] = [agent.characterID];
                if (agent.corporationID) idsToResolve.push(agent.corporationID);
                
                let nameMap = new Map<number, string>();
                try {
                  const nameResults = await esiClient.idsToNames(idsToResolve);
                  nameMap = new Map(nameResults.map(result => [result.id, result.name]));
                } catch (error) {
                  console.warn('Failed to resolve agent names:', error);
                }
  
                // Get agent type info
                let agentTypeName: string | undefined;
                if (agent.agentTypeID) {
                  try {
                    const agentTypeInfo = await sdeClient.getAgentTypeInfo(agent.agentTypeID);
                    agentTypeName = agentTypeInfo.agentType;
                  } catch (error) {
                    console.warn(`Failed to get agent type ${agent.agentTypeID}:`, error);
                  }
                }
  
                agentInfos.push({
                  agent_id: agent.characterID,
                  agent_name: nameMap.get(agent.characterID),
                  agent_type: agentTypeName,
                  corporation_name: agent.corporationID ? nameMap.get(agent.corporationID) : undefined,
                  division_id: agent.divisionID,
                  level: agent.level,
                  quality: agent.quality,
                  is_locator: agent.isLocator || false,
                  is_research_agent: researchAgentIds.has(agent.characterID)
                });
              } catch (error) {
                console.warn(`Failed to process agent ${agent.characterID}:`, error);
              }
            }
  
            results.push({
              station_id: stationId,
              station_name: stationName,
              system_name: systemName,
              agents: agentInfos
            });
          } catch (error) {
            errors.push(`Error processing station ${stationId}: ${error instanceof Error ? error.message : 'Unknown error'}`);
          }
        }
  
        const totalAgents = results.reduce((sum, station) => sum + station.agents.length, 0);
  
        return JSON.stringify({
          success: results.length > 0,
          message: `Found ${totalAgents} agent(s) across ${results.length} station(s)`,
          stations: results,
          errors: errors.length > 0 ? errors : undefined,
          summary: {
            total_stations_requested: args.stations.length,
            successful_stations: results.length,
            failed_stations: errors.length,
            total_agents_found: totalAgents,
            research_agents_included: args.includeResearchAgents || false
          }
        });
      } catch (error) {
        return JSON.stringify({
          success: false,
          message: `Error getting station agents: ${error instanceof Error ? error.message : 'Unknown error'}`,
          stations: []
        });
      }
    },
    name: "get_station_agents",
    parameters: z.object({
      stations: z.array(z.union([z.string(), z.number()])).min(1).max(20).describe("Array of station names (English proper nouns like 'Jita IV - Moon 4 - Caldari Navy Assembly Plant') or IDs to get agent information for (max 20)"),
      includeResearchAgents: z.boolean().optional().default(false).describe("Whether to identify research agents (may be slower)")
    }),
  };

• src/station-services-tools.ts:285-289 (schema)

  Zod schema defining the input parameters for the get_station_agents tool, validating stations array (1-20 items, string or number) and optional boolean for research agents.

    parameters: z.object({
      stations: z.array(z.union([z.string(), z.number()])).min(1).max(20).describe("Array of station names (English proper nouns like 'Jita IV - Moon 4 - Caldari Navy Assembly Plant') or IDs to get agent information for (max 20)"),
      includeResearchAgents: z.boolean().optional().default(false).describe("Whether to identify research agents (may be slower)")
    }),
  };

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

  Registration of the getStationAgentsTool with the FastMCP server instance.

  server.addTool(getStationAgentsTool);

• src/server.ts:27-31 (registration)

  Import of the getStationAgentsTool from station-services-tools.js for use in the server.

    getStationServicesTool,
    getSystemStationsTool,
    findStationsWithServicesTool,
    getStationAgentsTool
  } from "./station-services-tools.js";