eve-online-traffic-mcp

Instructions

Input Schema

Input Schema (JSON Schema)

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";