searchFlightsByNumber
Search flight details by flight number, date, and optional departure/arrival airport codes. Use this tool to retrieve specific flight information for trip planning and tracking without hardcoding dates.
Instructions
Search flights by flight number and date. Flight number should include airline code (e.g. MU2157, CZ3969). dep and arr are optional, keep empty if you don't know them. Date format: YYYY-MM-DD. IMPORTANT: For today's date, you MUST use getTodayDate tool instead of hardcoding any date. Airport codes (optional) should be IATA 3-letter codes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| arr | No | Arrival airport IATA 3-letter code (e.g. CAN for Guangzhou) | |
| date | Yes | Flight date in YYYY-MM-DD format. IMPORTANT: If user input only cotains month and date, you should use getTodayDate tool to get the year. For today's date, use getTodayDate tool instead of hardcoding | |
| dep | No | Departure airport IATA 3-letter code (e.g. HFE for Hefei) | |
| fnum | Yes | Flight number including airline code (e.g. MU2157, CZ3969) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"arr": {
"description": "Arrival airport IATA 3-letter code (e.g. CAN for Guangzhou)",
"maxLength": 3,
"minLength": 3,
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"date": {
"description": "Flight date in YYYY-MM-DD format. IMPORTANT: If user input only cotains month and date, you should use getTodayDate tool to get the year. For today's date, use getTodayDate tool instead of hardcoding",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"dep": {
"description": "Departure airport IATA 3-letter code (e.g. HFE for Hefei)",
"maxLength": 3,
"minLength": 3,
"pattern": "^[A-Z]{3}$",
"type": "string"
},
"fnum": {
"description": "Flight number including airline code (e.g. MU2157, CZ3969)",
"pattern": "^[A-Z0-9]{2,3}[0-9]{1,4}$",
"type": "string"
}
},
"required": [
"fnum",
"date"
],
"type": "object"
}
Implementation Reference
- dist/index.js:76-94 (handler)Executes the tool logic by querying the flight service with provided parameters and returning the JSON-formatted flights data or an error message.try { const flights = await flightService.getFlightByNumber(fnum, date, dep, arr); return { content: [ { type: "text", text: JSON.stringify(flights, null, 2) } ] }; } catch (error) { console.error('Error searching flights by number:', error); return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true }; } });
- dist/index.js:59-75 (schema)Defines and validates the tool's input parameters using Zod: required flight number (fnum) and date, optional departure (dep) and arrival (arr) airports.fnum: z.string() .regex(/^[A-Z0-9]{2,3}[0-9]{1,4}$/) .describe("Flight number including airline code (e.g. MU2157, CZ3969)"), date: z.string() .regex(/^\d{4}-\d{2}-\d{2}$/) .describe("Flight date in YYYY-MM-DD format. IMPORTANT: If user input only cotains month and date, you should use getTodayDate tool to get the year. For today's date, use getTodayDate tool instead of hardcoding"), dep: z.string() .length(3) .regex(/^[A-Z]{3}$/) .describe("Departure airport IATA 3-letter code (e.g. HFE for Hefei)") .optional(), arr: z.string() .length(3) .regex(/^[A-Z]{3}$/) .describe("Arrival airport IATA 3-letter code (e.g. CAN for Guangzhou)") .optional(), }, async ({ fnum, date, dep, arr }) => {
- dist/index.js:58-58 (registration)Registers the 'searchFlightsByNumber' tool on the MCP server with its description, input schema, and handler function.server.tool("searchFlightsByNumber", "Search flights by flight number and date. Flight number should include airline code (e.g. MU2157, CZ3969). dep and arr are optional, keep empty if you don't know them. Date format: YYYY-MM-DD. IMPORTANT: For today's date, you MUST use getTodayDate tool instead of hardcoding any date. Airport codes (optional) should be IATA 3-letter codes. ", {
- dist/services/openalService.js:31-41 (helper)Prepares the API parameters for flight search by number and delegates to the generic makeRequest method with endpoint 'flight'.async getFlightByNumber(fnum, date, dep, arr) { const params = { fnum, date, }; if (dep) params.dep = dep; if (arr) params.arr = arr; return this.makeRequest('flight', params); }
- dist/services/openalService.js:3-21 (helper)Generic method to make POST requests to the Variflight API, constructing the request body with endpoint and params, using the configured API key.async makeRequest(endpoint, params) { const url = new URL(config.api.baseUrl); const request_body = { endpoint: endpoint, params: params }; const response = await fetch(url.toString(), { method: 'post', headers: { 'X-VARIFLIGHT-KEY': config.api.apiKey || '', 'Content-Type': 'application/json', }, body: JSON.stringify(request_body), }); if (!response.ok) { throw new Error(`API request failed: ${response.status} ${response.statusText}`); } return response.json(); }