Add FlightSeatMap skill

skills/jackculpan/flightseatmap/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: flightseatmap
+description: Search flight seat maps, find best seats, and get seat details for any airline flight. Use when user mentions flights, seats, seatmaps, seating charts, legroom, window seats, aisle seats, exit rows, or a flight number like QF1, AA716, BA178.
+version: 1.0.0
+metadata:
+  openclaw:
+    emoji: "✈️"
+    homepage: https://flightseatmap.com
+    requires:
+      bins:
+        - curl
+---
+
+# FlightSeatMap
+
+Look up seat maps for any airline flight, find the best seats based on preferences, and get detailed seat information.
+
+## How It Works
+
+Use the FlightSeatMap public API to fetch seatmap data. The API returns seat layouts, cabin classes, seat characteristics (window, aisle, legroom, exit row), and availability.
+
+### API Endpoint
+
+```
+GET https://flightseatmap.com/api/seatmaps/{flight_number}
+```
+
+Returns JSON with decks, seats, cabin classes, and aircraft info. No authentication required for cached flights.
+
+### MCP Server (Optional)
+
+For richer tool integration, users can add the MCP server to Claude Desktop, Claude Code, or Cursor:
+
+```
+https://mcp.flightseatmap.com/mcp
+```
+
+## Usage
+
+When the user asks about a flight seat map, follow these steps:
+
+### Step 1: Fetch the seatmap
+
+```bash
+curl -s "https://flightseatmap.com/api/seatmaps/FLIGHT_NUMBER" | head -c 5000
+```
+
+Replace `FLIGHT_NUMBER` with the actual flight number (e.g., `QF1`, `AA716`). The response is JSON.
+
+### Step 2: Parse the response
+
+The JSON response contains:
+- `flightNumber` — The flight number
+- `airline` — Airline name
+- `aircraftName` — Aircraft type
+- `origin` / `destination` — Route
+- `totalSeats` / `availableSeats` — Seat counts
+- `decks` — Array of deck objects, each with:
+  - `deckType` — "MAIN" or "UPPER"
+  - `seats` — Array of seat objects
+
+Each seat has:
+- `number` — Seat number (e.g., "12A")
+- `cabin` — Cabin class: FIRST, BUSINESS, PREMIUM_ECONOMY, or ECONOMY
+- `characteristicsCodes` — Array of codes:
+  - `W` = Window
+  - `A` = Aisle
+  - `E` = Exit row (extra legroom)
+  - `L` = Extra legroom
+  - `B` = Bulkhead
+  - `1` = First/Business class
+  - `CH` = Chargeable
+  - `K` = Blocked/unavailable
+- `travelerPricing` — Availability and price info
+  - `seatAvailabilityStatus` — "AVAILABLE", "BLOCKED", or "OCCUPIED"
+
+### Step 3: Present results
+
+Organize seats by cabin class. Highlight:
+- Available vs blocked seats
+- Window (W) and aisle (A) positions
+- Extra legroom seats (E or L codes)
+- Exit row locations
+
+If the user has preferences (e.g., "window with legroom"), filter and rank seats accordingly.
+
+### Step 4: If flight not found
+
+If the API returns 404, the flight isn't in the database. Suggest:
+1. Check the flight number is correct (airline code + number, e.g., QF1 not Qantas 1)
+2. Search at https://flightseatmap.com to add it
+3. For paid users: use the MCP server's `search_flight` tool with an API token
+
+## Example Prompts
+
+- "Show me the seatmap for QF1"
+- "What are the best window seats on BA178?"
+- "Is seat 12A good on AA716?"
+- "Find me an aisle seat with extra legroom on EK1 in economy"
+- "Compare seats 14A and 22F on UA900"
+
+## Seat Recommendation Logic
+
+When ranking seats, prioritize:
+1. **Match user preferences** — window, aisle, legroom, etc.
+2. **Availability** — Only recommend AVAILABLE seats
+3. **Position** — Front of cabin = faster deplaning; rear = quieter
+4. **Exit rows** — More legroom but restricted recline, no children
+5. **Bulkhead** — More legroom but no underseat storage, bassinet wall
+
+## Tips
+
+- Flight numbers are always airline code + number: `QF1`, `AA716`, `BA178`, `EK1`
+- Uppercase the flight number before querying
+- The API uses the Amadeus seat characteristic codes standard
+- For date-specific data, append `?flight_date=YYYY-MM-DD` to the API URL

skills/jackculpan/flightseatmap/references/api-reference.md

@@ -0,0 +1,100 @@
+# FlightSeatMap API Reference
+
+## Public API
+
+### Get Seatmap
+```
+GET https://flightseatmap.com/api/seatmaps/{flight_number}
+```
+
+No authentication required. Returns cached seatmap data.
+
+**Query Parameters:**
+- `flight_date` (optional) — Date in YYYY-MM-DD format
+
+**Response (200):**
+```json
+{
+  "flightNumber": "QF1",
+  "airline": "Qantas",
+  "airlineCode": "QF",
+  "origin": "SYD",
+  "destination": "LHR",
+  "aircraftName": "Airbus A380-800",
+  "aircraftCode": "388",
+  "totalSeats": 485,
+  "availableSeats": 312,
+  "decks": [
+    {
+      "deckType": "MAIN",
+      "seats": [
+        {
+          "number": "12A",
+          "cabin": "ECONOMY",
+          "characteristicsCodes": ["W"],
+          "coordinates": { "x": 0, "y": 12 },
+          "travelerPricing": [
+            { "seatAvailabilityStatus": "AVAILABLE" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Response (404):**
+```json
+{ "error": "Flight not found" }
+```
+
+## MCP Server
+
+### Endpoint
+```
+https://mcp.flightseatmap.com/mcp
+```
+
+### Tools
+
+| Tool | Description | Auth |
+|------|-------------|------|
+| `get_seatmap` | Full seat map for a flight | None |
+| `find_best_seats` | Ranked seats by preference | None |
+| `get_seat_info` | Details on a specific seat | None |
+| `search_flight` | Fetch fresh data (uses credit) | JWT |
+| `interactive_seat_finder` | Guided seat selection | None |
+
+### Setup
+
+**Claude Desktop / Cursor:**
+```json
+{
+  "mcpServers": {
+    "flightseatmap": {
+      "url": "https://mcp.flightseatmap.com/mcp"
+    }
+  }
+}
+```
+
+**Claude Code:**
+```bash
+claude mcp add flightseatmap https://mcp.flightseatmap.com/mcp
+```
+
+## Seat Characteristic Codes
+
+| Code | Meaning |
+|------|---------|
+| W | Window seat |
+| A | Aisle seat |
+| E | Exit row |
+| L | Extra legroom |
+| B | Bulkhead |
+| 1 | First/Business class |
+| K | Blocked seat |
+| CH | Chargeable |
+| UP | Upper deck |
+| GN | No inflight entertainment |
+| MA | Medically restricted |