searchFlightsByNumber
Search flight details by entering the flight number, date, and optional departure/arrival airport codes. Use IATA 3-letter codes for airports and ensure the date format is YYYY-MM-DD.
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)MCP tool handler function that destructures parameters, calls the flight service method, formats the JSON response, and handles errors.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)Zod schema defining input parameters for the tool: fnum (required), date (required), dep and arr (optional). Includes validation regex and descriptions.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)Registration of the searchFlightsByNumber tool using server.tool, specifying name, 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)Helper method in OpenAlService that constructs query parameters conditionally and invokes the generic makeRequest to the 'flight' API endpoint.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); }