@iflow-mcp/flightradar24-mcp-server 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+# Flightradar24 API Configuration
+FR24_API_KEY=your-api-key-here
+# Flightradar24 API URL, shouldn't need to change this
+FR24_API_URL=https://fr24api.flightradar24.com
+# Server Configuration
+PORT=3000 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 sunsetcoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# Flightradar24 MCP Server 🛩️
+
+A Claude Desktop MCP server that helps you track flights in real-time using Flightradar24 data. Perfect for aviation enthusiasts, travel planners, or anyone curious about flights overhead!
+
+## What Can This Do? ✨
+
+- 🔍 Track any flight in real-time
+- ⏰ Get arrival and departure times for specific flights
+- 🌉 View the status of flights at an airport
+- 🚨 Monitor emergency flights
+
+<img width="1466" alt="Anthropic Claude MCP Hackathon - FlightRadar24 MCP server" src="https://github.com/user-attachments/assets/719444ae-2c8b-4441-84f8-5150337d871f" />
+
+## Setup Guide 🚀
+
+### 1. Prerequisites
+- [Claude Desktop](https://claude.ai/desktop) installed on your computer
+- A Flightradar24 API key (get one from [Flightradar24's website](https://www.flightradar24.com/premium))*
+
+### 2. Installation
+
+1. Clone this repository somewhere on your computer:
+   ```bash
+   git clone https://github.com/sunsetcoder/flightradar24-mcp-server.git
+   ```
+
+2. Install dependencies & build the project:
+   ```bash
+   cd flightradar24-mcp-server
+   npm install
+   npm run build
+   ```
+
+### 3. Integration with Claude Desktop
+
+1. Open your Claude Desktop configuration file:
+   ```
+   # On Mac:
+   ~/Library/Application Support/Claude/claude_desktop_config.json
+   
+   # On Windows:
+   %APPDATA%/Claude/claude_desktop_config.json
+   ```
+
+2. Add the following to the `mcpServers` object in your config:
+   ```json
+   {
+     "mcpServers": {
+       "flightradar24-server": {
+         "command": "node",
+         "args": [
+           "/Users/<username>/<FULL_PATH...>/flightradar24-mcp-server/dist/index.js"
+         ],
+         "env": {
+           "FR24_API_KEY": "your_api_key_here",
+           "FR24_API_URL": "https://fr24api.flightradar24.com"
+         }
+       }
+     }
+   }
+   ```
+
+3. Important Steps:
+   - Replace `/FULL/PATH/TO/flightradar24-mcp-server` with the actual full path to where you cloned the repository
+   - Add your Flightradar24 API key in the `env` section
+   - Make sure to use forward slashes (`/`) in the path, even on Windows
+
+4. Restart Claude Desktop for the changes to take effect
+
+## Environment Setup
+
+1. Copy `.env.example` to `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Update the `.env` file with your actual Flightradar24 API key:
+   ```env
+   FR24_API_KEY=your_actual_api_key_here
+   ```
+
+Note: Never commit your actual API key to version control. The `.env` file is ignored by git for security reasons.
+
+## Let's Try It Out! 🎮
+
+Once the server is configured, you can ask Claude questions like:
+
+1. "What's the ETA for United Airlines flight UA123?"
+2. "Show me all flights currently at SFO"
+3. "Are there any emergency flights in the area?"
+4. "Show me all international flights arriving at SFO in the next 2 hours"
+5. "How many commercial flights are currently over the Pacific Ocean?"
+6. "Identify any flights that have declared an emergency in the California region"
+
+Example conversation with Claude:
+```
+You: What's the status of flight UA123?
+Claude: Let me check that for you...
+[Claude will use the MCP server to fetch real-time flight information]
+```
+
+## Common Questions & Troubleshooting 🤔
+
+### "Claude can't connect to the server"
+- Check if the path in `claude_desktop_config.json` is correct
+- Make sure you're using the full absolute path
+- Verify your API key is correct
+- Try restarting Claude Desktop
+
+### "The server isn't responding"
+- Make sure your Flightradar24 API key is valid
+- Check if the API URL is correct
+- Look for any error messages in server logs
+
+### FlightRadar API Access
+- Note: Using Flightradar24's API requires a [subscription](https://fr24api.flightradar24.com/subscriptions-and-credits)
+
+## Need More Help? 🆘
+
+1. Make sure Claude Desktop is properly installed
+2. Verify your Flightradar24 API key is active
+3. Check the path in your configuration file is correct
+4. Look for error messages in MCP server logs
+
+## License 📄
+
+MIT
+
+---
+
+Made with ❤️ for aviation enthusiasts

package/dist/config.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import dotenv from 'dotenv';
+// Load environment variables
+dotenv.config();
+/**
+ * Environment variable schema validation
+ */
+const envSchema = z.object({
+    FR24_API_KEY: z.string({
+        required_error: "FR24_API_KEY is required in environment variables",
+        invalid_type_error: "FR24_API_KEY must be a string"
+    }).min(1, { message: "FR24_API_KEY cannot be empty" }).default("test_api_key_for_demo"),
+    FR24_API_URL: z.string({
+        required_error: "FR24_API_URL is required in environment variables",
+        invalid_type_error: "FR24_API_URL must be a string"
+    }).url({ message: "FR24_API_URL must be a valid URL" }).default("https://fr24api.flightradar24.com")
+});
+/**
+ * Validate and extract environment variables
+ * @throws {Error} If validation fails
+ */
+export const env = envSchema.parse(process.env);

package/dist/index.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import axios from 'axios';
+import { isValidFlightTrackingParams } from './types.js';
+import { env } from './config.js';
+// API client configuration
+const fr24Client = axios.create({
+    baseURL: env.FR24_API_URL,
+    headers: {
+        'Accept': 'application/json',
+        'Accept-Version': 'v1',
+        'Authorization': `Bearer ${env.FR24_API_KEY}`
+    }
+});
+/**
+ * MCP Server implementation for Flightradar24 API
+ * Provides tools for tracking flights and monitoring air traffic
+ */
+class FlightTrackingServer {
+    server;
+    constructor() {
+        this.server = new Server({ name: 'flightradar24-server', version: '1.0.0' }, {
+            capabilities: {
+                tools: {},
+                jsonrpc: true // Add this to enable JSON-RPC support
+            }
+        });
+        this.setupHandlers();
+        this.setupErrorHandling();
+    }
+    setupErrorHandling() {
+        this.server.onerror = (error) => {
+            console.error('[MCP Error]', error);
+        };
+        process.on('SIGINT', async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    setupHandlers() {
+        this.setupToolHandlers();
+    }
+    /**
+     * Configure available tools and their handlers
+     */
+    setupToolHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async (request) => ({
+            tools: [
+                {
+                    name: 'get_flight_positions',
+                    description: 'Get real-time flight positions with various filtering options',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            airports: { type: 'string', description: 'Comma-separated list of airport ICAO codes' },
+                            bounds: { type: 'string', description: 'Geographical bounds (lat1,lon1,lat2,lon2)' },
+                            categories: { type: 'string', description: 'Aircraft categories (P,C,J)' },
+                            limit: { type: 'number', description: 'Maximum number of results' }
+                        }
+                    }
+                },
+                {
+                    name: 'get_flight_eta',
+                    description: 'Get estimated arrival time for a specific flight',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            flightNumber: {
+                                type: 'string',
+                                description: 'Flight number (e.g., UA123)',
+                                pattern: '^[A-Z0-9]{2,8}$'
+                            }
+                        },
+                        required: ['flightNumber']
+                    }
+                }
+            ]
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                const toolName = request.params.name;
+                const toolArgs = request.params.arguments;
+                switch (toolName) {
+                    case 'get_flight_positions': {
+                        const params = {
+                            ...toolArgs,
+                            limit: toolArgs?.limit ? parseInt(toolArgs.limit) : undefined
+                        };
+                        if (!isValidFlightTrackingParams(params)) {
+                            throw new McpError(ErrorCode.InvalidParams, 'Invalid or missing query parameters. At least one valid parameter is required.');
+                        }
+                        const response = await fr24Client.get('/api/live/flight-positions/light', { params });
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify(response.data, null, 2)
+                                }]
+                        };
+                    }
+                    case 'get_flight_eta': {
+                        const { flightNumber } = toolArgs || {};
+                        const flightNumberStr = String(flightNumber || '');
+                        if (!flightNumberStr || !/^[A-Z0-9]{2,8}$/.test(flightNumberStr)) {
+                            throw new McpError(ErrorCode.InvalidParams, 'Invalid flight number format');
+                        }
+                        const response = await fr24Client.get('/api/flights/detail', {
+                            params: {
+                                flight: flightNumberStr,
+                                format: 'eta'
+                            }
+                        });
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify(response.data, null, 2)
+                                }]
+                        };
+                    }
+                    default:
+                        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
+                }
+            }
+            catch (error) {
+                if (axios.isAxiosError(error)) {
+                    return {
+                        isError: true,
+                        content: [{
+                                type: "text",
+                                text: `Flightradar24 API error: ${error.response?.data?.message || error.message || 'Unknown error'}`
+                            }]
+                    };
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Start the MCP server using stdio transport
+     */
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+}
+// Create and start the server
+const server = new FlightTrackingServer();
+server.run().catch(console.error);
+//console.log(env.FR24_API_KEY)
+//console.log(env.FR24_API_URL)

package/dist/test.js

@@ -0,0 +1,40 @@
+// Test requests
+const requests = [
+    // List tools request
+    {
+        jsonrpc: "2.0",
+        id: "1",
+        method: "list_tools",
+        params: {}
+    },
+    // Test flight positions request
+    {
+        jsonrpc: "2.0",
+        id: "2",
+        method: "call_tool",
+        params: {
+            name: "get_flight_positions",
+            arguments: {
+                airports: "KJFK,KLAX",
+                limit: "5"
+            }
+        }
+    },
+    // Test flight ETA request
+    {
+        jsonrpc: "2.0",
+        id: "3",
+        method: "call_tool",
+        params: {
+            name: "get_flight_eta",
+            arguments: {
+                flightNumber: "UA123"
+            }
+        }
+    }
+];
+// Print each request with a delay
+requests.forEach((request, index) => {
+    console.log(JSON.stringify(request));
+});
+export {};

package/dist/types.js

@@ -0,0 +1,38 @@
+/**
+ * Validates flight tracking parameters
+ */
+export function isValidFlightTrackingParams(params) {
+    if (!params || typeof params !== 'object') {
+        return false;
+    }
+    const typedParams = params;
+    // Check that at least one valid parameter is provided
+    const validParams = [
+        'bounds', 'flights', 'callsigns', 'registrations', 'painted_as',
+        'operating_as', 'airports', 'routes', 'aircraft', 'altitude_ranges',
+        'squawks', 'categories', 'data_sources', 'airspaces', 'limit'
+    ];
+    const hasValidParam = validParams.some(param => {
+        const value = typedParams[param];
+        if (param === 'limit') {
+            return typeof value === 'number' && value > 0;
+        }
+        return typeof value === 'string' && value.length > 0;
+    });
+    return hasValidParam;
+}
+export var FlightCategory;
+(function (FlightCategory) {
+    FlightCategory["PASSENGER"] = "P";
+    FlightCategory["CARGO"] = "C";
+    FlightCategory["MILITARY_AND_GOVERNMENT"] = "M";
+    FlightCategory["BUSINESS_JETS"] = "J";
+    FlightCategory["GENERAL_AVIATION"] = "T";
+    FlightCategory["HELICOPTERS"] = "H";
+    FlightCategory["LIGHTER_THAN_AIR"] = "B";
+    FlightCategory["GLIDERS"] = "G";
+    FlightCategory["DRONES"] = "D";
+    FlightCategory["GROUND_VEHICLES"] = "V";
+    FlightCategory["OTHER"] = "O";
+    FlightCategory["NON_CATEGORIZED"] = "N";
+})(FlightCategory || (FlightCategory = {}));

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@iflow-mcp/flightradar24-mcp-server",
+  "version": "1.0.0",
+  "description": "Model Context Protocol server for FlightRadar24 API",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "flightradar24-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "flightradar24",
+    "api",
+    "mcp",
+    "flight-tracking"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "axios": "^1.6.0",
+    "dotenv": "^16.4.7",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.4",
+    "tsc-watch": "^6.0.4",
+    "typescript": "^5.3.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod'
+import dotenv from 'dotenv'
+
+// Load environment variables
+dotenv.config()
+
+/**
+ * Environment variable schema validation
+ */
+const envSchema = z.object({
+    FR24_API_KEY: z.string({
+        required_error: "FR24_API_KEY is required in environment variables",
+        invalid_type_error: "FR24_API_KEY must be a string"
+    }).min(1, { message: "FR24_API_KEY cannot be empty" }).default("test_api_key_for_demo"),
+    FR24_API_URL: z.string({
+        required_error: "FR24_API_URL is required in environment variables",
+        invalid_type_error: "FR24_API_URL must be a string"
+    }).url({ message: "FR24_API_URL must be a valid URL" }).default("https://fr24api.flightradar24.com")
+})
+
+/**
+ * Validate and extract environment variables
+ * @throws {Error} If validation fails
+ */
+export const env = envSchema.parse(process.env)

package/src/index.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ErrorCode,
+  McpError,
+  ListToolsRequest,
+  CallToolRequest
+} from '@modelcontextprotocol/sdk/types.js';
+import axios from 'axios';
+import {
+  FlightTrackingParams,
+  FlightPositionsResponse,
+  FlightETAResponse,
+  isValidFlightTrackingParams
+} from './types.js';
+import { env } from './config.js';
+
+// API client configuration
+const fr24Client = axios.create({
+  baseURL: env.FR24_API_URL,
+  headers: {
+    'Accept': 'application/json',
+    'Accept-Version': 'v1',
+    'Authorization': `Bearer ${env.FR24_API_KEY}`
+  }
+});
+
+/**
+ * MCP Server implementation for Flightradar24 API
+ * Provides tools for tracking flights and monitoring air traffic
+ */
+class FlightTrackingServer {
+  private server: Server;
+
+  constructor() {
+    this.server = new Server(
+      { name: 'flightradar24-server', version: '1.0.0' },
+      {
+        capabilities: {
+          tools: {},
+          jsonrpc: true  // Add this to enable JSON-RPC support
+        }
+      }
+    );
+
+    this.setupHandlers();
+    this.setupErrorHandling();
+  }
+
+  private setupErrorHandling(): void {
+    this.server.onerror = (error) => {
+      console.error('[MCP Error]', error);
+    };
+
+    process.on('SIGINT', async () => {
+      await this.server.close();
+      process.exit(0);
+    });
+  }
+
+  private setupHandlers(): void {
+    this.setupToolHandlers();
+  }
+
+  /**
+   * Configure available tools and their handlers
+   */
+  private setupToolHandlers(): void {
+    this.server.setRequestHandler(ListToolsRequestSchema, async (request: ListToolsRequest) => ({
+      tools: [
+        {
+          name: 'get_flight_positions',
+          description: 'Get real-time flight positions with various filtering options',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              airports: { type: 'string', description: 'Comma-separated list of airport ICAO codes' },
+              bounds: { type: 'string', description: 'Geographical bounds (lat1,lon1,lat2,lon2)' },
+              categories: { type: 'string', description: 'Aircraft categories (P,C,J)' },
+              limit: { type: 'number', description: 'Maximum number of results' }
+            }
+          }
+        },
+        {
+          name: 'get_flight_eta',
+          description: 'Get estimated arrival time for a specific flight',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              flightNumber: {
+                type: 'string',
+                description: 'Flight number (e.g., UA123)',
+                pattern: '^[A-Z0-9]{2,8}$'
+              }
+            },
+            required: ['flightNumber']
+          }
+        }
+      ]
+    }));
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => {
+      try {
+        const toolName = request.params.name;
+        const toolArgs = request.params.arguments;
+
+        switch (toolName) {
+          case 'get_flight_positions': {
+            const params: FlightTrackingParams = {
+              ...toolArgs,
+              limit: toolArgs?.limit ? parseInt(toolArgs.limit as string) : undefined
+            };
+
+            if (!isValidFlightTrackingParams(params)) {
+              throw new McpError(
+                ErrorCode.InvalidParams,
+                'Invalid or missing query parameters. At least one valid parameter is required.'
+              );
+            }
+
+            const response = await fr24Client.get<FlightPositionsResponse>(
+              '/api/live/flight-positions/light',
+              { params }
+            );
+
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify(response.data, null, 2)
+              }]
+            };
+          }
+
+          case 'get_flight_eta': {
+            const { flightNumber } = toolArgs || {};
+            const flightNumberStr = String(flightNumber || '');
+
+            if (!flightNumberStr || !/^[A-Z0-9]{2,8}$/.test(flightNumberStr)) {
+              throw new McpError(
+                ErrorCode.InvalidParams,
+                'Invalid flight number format'
+              );
+            }
+
+            const response = await fr24Client.get<FlightETAResponse>(
+              '/api/flights/detail',
+              {
+                params: {
+                  flight: flightNumberStr,
+                  format: 'eta'
+                }
+              }
+            );
+
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify(response.data, null, 2)
+              }]
+            };
+          }
+
+          default:
+            throw new McpError(
+              ErrorCode.MethodNotFound,
+              `Unknown tool: ${toolName}`
+            );
+        }
+      } catch (error) {
+        if (axios.isAxiosError(error)) {
+          return {
+            isError: true,
+            content: [{
+              type: "text",
+              text: `Flightradar24 API error: ${error.response?.data?.message || error.message || 'Unknown error'}`
+            }]
+          };
+        }
+        throw error;
+      }
+    });
+  }
+
+  /**
+   * Start the MCP server using stdio transport
+   */
+  async run(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+  }
+}
+
+// Create and start the server
+const server = new FlightTrackingServer();
+server.run().catch(console.error);
+//console.log(env.FR24_API_KEY)
+//console.log(env.FR24_API_URL)

package/src/test.ts

@@ -0,0 +1,42 @@
+// Test requests
+const requests = [
+    // List tools request
+    {
+        jsonrpc: "2.0",
+        id: "1",
+        method: "list_tools",
+        params: {}
+    },
+
+    // Test flight positions request
+    {
+        jsonrpc: "2.0",
+        id: "2",
+        method: "call_tool",
+        params: {
+            name: "get_flight_positions",
+            arguments: {
+                airports: "KJFK,KLAX",
+                limit: "5"
+            }
+        }
+    },
+
+    // Test flight ETA request
+    {
+        jsonrpc: "2.0",
+        id: "3",
+        method: "call_tool",
+        params: {
+            name: "get_flight_eta",
+            arguments: {
+                flightNumber: "UA123"
+            }
+        }
+    }
+];
+
+// Print each request with a delay
+requests.forEach((request, index) => {
+    console.log(JSON.stringify(request));
+}); 

package/src/types/global.d.ts

@@ -0,0 +1,6 @@
+declare namespace NodeJS {
+    interface ProcessEnv {
+        FR24_API_KEY: string;
+        FR24_API_URL: string;
+    }
+} 

package/src/types/modelcontextprotocol-sdk.d.ts

@@ -0,0 +1,5 @@
+declare module '@modelcontextprotocol/sdk' {
+    export class MCPServer {
+        constructor(config: { apiKey: string });
+    }
+} 

package/src/types.ts

@@ -0,0 +1,123 @@
+export interface Coordinate {
+  lat: number;
+  lng: number;
+}
+
+export interface ApiResponse {
+  contents: {
+    uri: string;
+    mimeType: string;
+    text: string;
+  }[];
+}
+
+/**
+ * Flightradar24 API Types
+ */
+
+export interface FlightPosition {
+  fr24_id: string;
+  hex: string;
+  callsign: string;
+  lat: number;
+  lon: number;
+  track: number;
+  alt: number;
+  gspeed: number;
+  vspeed: number;
+  squawk: string;
+  timestamp: string;
+  source: 'ADSB' | 'MLAT' | 'ESTIMATED';
+}
+
+export interface FlightPositionsResponse {
+  data: FlightPosition[];
+}
+
+export interface FlightETA {
+  flight_number: string;
+  departure: {
+    airport: string;
+    scheduled: string;
+    actual: string;
+    delay?: number;
+  };
+  arrival: {
+    airport: string;
+    scheduled: string;
+    estimated: string;
+    delay?: number;
+  };
+  status: 'scheduled' | 'active' | 'landed' | 'cancelled';
+}
+
+export interface FlightETAResponse {
+  data: FlightETA;
+}
+
+export interface FlightTrackingParams {
+  bounds?: string;
+  flights?: string;
+  callsigns?: string;
+  registrations?: string;
+  painted_as?: string;
+  operating_as?: string;
+  airports?: string;
+  routes?: string;
+  aircraft?: string;
+  altitude_ranges?: string;
+  squawks?: string;
+  categories?: string;
+  data_sources?: string;
+  airspaces?: string;
+  limit?: number;
+}
+
+/**
+ * Validates flight tracking parameters
+ */
+export function isValidFlightTrackingParams(params: unknown): params is FlightTrackingParams {
+  if (!params || typeof params !== 'object') {
+    return false;
+  }
+
+  const typedParams = params as Record<string, unknown>;
+
+  // Check that at least one valid parameter is provided
+  const validParams = [
+    'bounds', 'flights', 'callsigns', 'registrations', 'painted_as',
+    'operating_as', 'airports', 'routes', 'aircraft', 'altitude_ranges',
+    'squawks', 'categories', 'data_sources', 'airspaces', 'limit'
+  ];
+
+  const hasValidParam = validParams.some(param => {
+    const value = typedParams[param];
+    if (param === 'limit') {
+      return typeof value === 'number' && value > 0;
+    }
+    return typeof value === 'string' && value.length > 0;
+  });
+
+  return hasValidParam;
+}
+
+export enum FlightCategory {
+  PASSENGER = 'P',
+  CARGO = 'C',
+  MILITARY_AND_GOVERNMENT = 'M',
+  BUSINESS_JETS = 'J',
+  GENERAL_AVIATION = 'T',
+  HELICOPTERS = 'H',
+  LIGHTER_THAN_AIR = 'B',
+  GLIDERS = 'G',
+  DRONES = 'D',
+  GROUND_VEHICLES = 'V',
+  OTHER = 'O',
+  NON_CATEGORIZED = 'N'
+}
+
+export interface ApiError {
+  code: string;
+  message: string;
+  details?: any;
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}