universal_name_to_id
Convert EVE Online entity names like systems, stations, and regions into their corresponding IDs using the ESI API. Input up to 500 proper nouns in English.
Instructions
Convert EVE Online entity names (systems, stations, regions, etc.) to their corresponding IDs using ESI API
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| names | Yes | Array of entity names to convert to IDs (max 500). Use English proper nouns only (e.g., 'Jita', 'Caldari State', 'Tritanium') |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"names": {
"description": "Array of entity names to convert to IDs (max 500). Use English proper nouns only (e.g., 'Jita', 'Caldari State', 'Tritanium')",
"items": {
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
}
},
"required": [
"names"
],
"type": "object"
}
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