@flightbyte/mcp 0.0.0-stage → 1.0.0

package/dist/tools/api-tools.js

@@ -0,0 +1,437 @@
+import { z } from 'zod';
+import { apiErrorResult, missingKeyError } from '../errors.js';
+/** The 23 change types a subscription can filter on (CreateSubscriptionDto.events in the OpenAPI document). */
+export const CHANGE_TYPES = [
+    'status.changed',
+    'flight.departed',
+    'flight.arrived',
+    'flight.cancelled',
+    'flight.diverted',
+    'flight.reinstated',
+    'departure.gate.changed',
+    'departure.terminal.changed',
+    'arrival.gate.changed',
+    'arrival.terminal.changed',
+    'arrival.baggage.changed',
+    'departure.scheduled.changed',
+    'departure.estimated.changed',
+    'departure.actual.changed',
+    'arrival.scheduled.changed',
+    'arrival.estimated.changed',
+    'arrival.actual.changed',
+    'delay.increased',
+    'delay.decreased',
+    'aircraft.changed',
+    'aircraft.tail.changed',
+    'route.changed',
+    'codeshares.changed',
+];
+export const SUBSCRIPTION_STATUSES = ['active', 'pending', 'paused', 'completed', 'suspended'];
+// ---------------------------------------------------------------------------
+// Shared parameter schemas. Patterns mirror the API's own validation, case-insensitively
+// (the API upper-cases codes before validating them).
+const carrier = z
+    .string()
+    .regex(/^[A-Za-z0-9]{2,3}$/)
+    .describe('Airline code: the 2-character IATA code (e.g. "TK") or 3-character ICAO code (e.g. "THY"). For flight "TK1848" this is "TK".');
+const flightNumber = z
+    .string()
+    .regex(/^\d{1,4}[A-Za-z]?$/)
+    .describe('Flight number without the airline code: 1 to 4 digits and an optional letter suffix. For "TK1848" this is "1848". Leading zeros are ignored.');
+const date = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/)
+    .describe('Local departure date at the origin airport, YYYY-MM-DD. A flight that leaves at 23:50 and lands the next morning belongs to the day it left. Live records cover a few days back to about two days ahead.');
+const origin = z
+    .string()
+    .regex(/^[A-Za-z0-9]{3,4}$/)
+    .describe('Departure airport, IATA code (e.g. "IST"; the upstream code such as "ISL" also works). Picks the leg when the flight number operates more than one leg that day.');
+const destination = z
+    .string()
+    .regex(/^[A-Za-z0-9]{3,4}$/)
+    .describe('Arrival airport, IATA code (e.g. "JFK"). Narrows further when several legs leave the same airport.');
+const flightId = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,32}$/)
+    .describe("Exact leg pick: a providerFlightId from a previous response's `alternates`, or a flightId from an error's list of legs.");
+const refresh = z
+    .boolean()
+    .describe("true skips FlightByte's cache and asks upstream now (counts as a normal request). Leave unset unless the user needs a guaranteed fresh answer.");
+const subscriptionId = z
+    .string()
+    .min(1)
+    .max(64)
+    .describe('Subscription id, e.g. "sub_7Kd91mQx0Zb2", as returned by create_subscription or list_subscriptions.');
+const webhookUrl = z
+    .url({ protocol: /^https?$/ })
+    .max(2048)
+    .describe("The user's public http(s) endpoint that receives a signed POST for every change. Addresses that resolve to private, loopback or link-local ranges are refused. Never invent one.");
+const events = z
+    .array(z.enum(CHANGE_TYPES))
+    .min(1)
+    .describe('Change types to deliver; omit to deliver all 23. Common picks: "flight.departed", "flight.arrived", "flight.cancelled", "flight.diverted", "departure.gate.changed", "arrival.baggage.changed", "delay.increased".');
+const delayThresholdMinutes = z
+    .number()
+    .int()
+    .min(1)
+    .max(240)
+    .describe('Delay changes smaller than this many minutes are not delivered. 1 to 240; the default is 1.');
+const deliveryHeaders = z
+    .record(z.string(), z.string())
+    .describe('Extra HTTP headers sent with every delivery, e.g. {"Authorization": "Bearer <receiver token>"}.');
+const metadata = z
+    .record(z.string(), z.string())
+    .describe('String map echoed back in every webhook, e.g. {"bookingId": "BK-1042"}. Use it to tie deliveries to your own records.');
+const flightSelectors = {
+    origin: { in: 'query', schema: origin.optional() },
+    destination: { in: 'query', schema: destination.optional() },
+};
+const flightKeyPath = {
+    carrier: { in: 'path', schema: carrier },
+    flightNumber: { in: 'path', schema: flightNumber },
+    date: { in: 'path', schema: date },
+};
+const idPath = { id: { in: 'path', schema: subscriptionId } };
+const READ = { readOnlyHint: true, openWorldHint: true };
+const READ_ACCOUNT = { readOnlyHint: true, openWorldHint: false };
+const SNAPSHOT_SUMMARY = "Returns FlightByte's flight snapshot: `status.phase` to branch on (scheduled, boarding, departed, en_route, landed, arrived, cancelled, diverted, redirected, unknown) " +
+    'with `delayed`/`cancelled`/`diverted` flags; departure and arrival airports with terminal, gate and baggage carousel; scheduled, estimated and actual gate and runway times in UTC and local time ' +
+    '(`bestTimeUtc` is the best single time, `delayMinutes` the gate delay); aircraft, codeshares, the airline timeline, `cached`, and `alternates`: every leg this flight number operates that day.';
+// ---------------------------------------------------------------------------
+export const API_TOOLS = [
+    {
+        name: 'get_flight',
+        operationId: 'get-flight',
+        method: 'GET',
+        path: '/flights/{carrier}/{flightNumber}/{date}',
+        title: 'Get a flight',
+        resource: 'flight',
+        description: 'Look up the live status of one flight leg by airline code, flight number and local departure date, e.g. TK1848 on 2026-10-18 → carrier "TK", flightNumber "1848", date "2026-10-18". ' +
+            `${SNAPSHOT_SUMMARY} ` +
+            'Some numbers fly more than one leg a day (TK1 is SAW→AMS in the morning and IST→JFK later): without a selector the default leg is returned, so pass `origin` when the user named a departure airport. ' +
+            'For updates over time, create a subscription instead of calling this repeatedly.',
+        annotations: { ...READ, title: 'Get a flight' },
+        params: {
+            ...flightKeyPath,
+            ...flightSelectors,
+            flightId: { in: 'query', schema: flightId.optional() },
+            refresh: { in: 'query', schema: refresh.optional() },
+        },
+        notes: legNotes,
+    },
+    {
+        name: 'search_flights',
+        operationId: 'search-flights',
+        method: 'GET',
+        path: '/flights/search',
+        title: 'Search flights',
+        resource: 'flight',
+        description: 'The same lookup as get_flight (same parameters, same snapshot), sent as query parameters to /v1/flights/search. Use either one, not both. ' +
+            `${SNAPSHOT_SUMMARY} ` +
+            'When the flight number operates several legs that day, pass `origin` (and optionally `destination`) to pick one; without a selector the default leg is returned and every leg is listed under `alternates`.',
+        annotations: { ...READ, title: 'Search flights' },
+        params: {
+            carrier: { in: 'query', schema: carrier },
+            flightNumber: { in: 'query', schema: flightNumber },
+            date: { in: 'query', schema: date },
+            ...flightSelectors,
+            flightId: { in: 'query', schema: flightId.optional() },
+            refresh: { in: 'query', schema: refresh.optional() },
+        },
+        notes: legNotes,
+    },
+    {
+        name: 'get_flight_timeline',
+        operationId: 'flight-timeline',
+        method: 'GET',
+        path: '/flights/{carrier}/{flightNumber}/{date}/timeline',
+        title: 'Flight timeline',
+        resource: 'flight',
+        description: "The airline's own change history for one flight leg, newest first, as `{flightKey, count, data}`; each entry has `occurredAt`, `title`, `source` and `events` in the airline's words " +
+            '(e.g. "Actual Gate Arrival changed to 13:35"). Use it for "what changed" or "why is it late" questions. get_flight already contains the same timeline, so call this only when the history alone is needed.',
+        annotations: { ...READ, title: 'Flight timeline' },
+        params: { ...flightKeyPath, ...flightSelectors },
+    },
+    {
+        name: 'create_subscription',
+        operationId: 'create-subscription',
+        method: 'POST',
+        path: '/subscriptions',
+        title: 'Create a subscription',
+        resource: 'flight',
+        description: 'Watch a flight: FlightByte polls it on an adaptive schedule and POSTs a signed webhook to `webhookUrl` for every change (status, gates, terminals, times, delays, departure, arrival, baggage carousel, cancellation, diversion, aircraft, route, codeshares) until the flight is over. ' +
+            "Each new subscription counts as a watched flight on the user's plan (Free: 3 per month) and starts outbound requests to the URL, so only call this when the user asked to watch or be notified about a specific flight and gave the webhook URL. " +
+            'If the flight number operates more than one leg that day the call is refused with the list of legs: pass `origin`. Flights up to seven days ahead are accepted and wait as `pending` until published. ' +
+            'The response includes the signing secret in full; this is the only time it is shown, so relay it to the user to store for webhook signature verification. Pass `Idempotency-Key` to make a retry return the same subscription.',
+        annotations: { title: 'Create a subscription', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        params: {
+            carrier: { in: 'body', schema: carrier },
+            flightNumber: { in: 'body', schema: flightNumber },
+            date: { in: 'body', schema: date },
+            origin: { in: 'body', schema: origin.optional() },
+            destination: { in: 'body', schema: destination.optional() },
+            flightId: { in: 'body', schema: flightId.optional() },
+            webhookUrl: { in: 'body', schema: webhookUrl },
+            events: { in: 'body', schema: events.optional() },
+            delayThresholdMinutes: { in: 'body', schema: delayThresholdMinutes.optional() },
+            headers: { in: 'body', schema: deliveryHeaders.optional() },
+            metadata: { in: 'body', schema: metadata.optional() },
+            secret: {
+                in: 'body',
+                schema: z
+                    .string()
+                    .min(1)
+                    .max(200)
+                    .optional()
+                    .describe("Bring your own signing secret, only when the user explicitly provides one their receiver already uses. Normally omit it: FlightByte generates one and returns it once."),
+            },
+            'Idempotency-Key': {
+                in: 'header',
+                schema: z
+                    .string()
+                    .min(1)
+                    .max(255)
+                    .optional()
+                    .describe('Any unique string (e.g. a UUID). Replaying the same key within 24 hours returns the original subscription instead of creating a second one.'),
+            },
+        },
+        notes: (data) => {
+            const sub = asRecord(data);
+            const lines = [
+                'Subscription created.',
+                'IMPORTANT: `secret` below is the webhook signing secret, shown in full only in this response; later reads show only `secretHint`. ' +
+                    'Give it to the user now so they can store it on their webhook receiver (the docs call it FLIGHTBYTE_WEBHOOK_SECRET) and verify the HMAC-SHA256 signature on every delivery. ' +
+                    'This MCP server cannot reveal or rotate it later; that is done in the FlightByte dashboard or the API.',
+            ];
+            if (sub?.status === 'pending') {
+                lines.push('Status is `pending`: the flight is not published upstream yet. It activates by itself and the receiver gets `subscription.activated` when it does.');
+            }
+            lines.push('Tip: send_test_event sends a signed test webhook to check the receiver now.');
+            return lines;
+        },
+    },
+    {
+        name: 'list_subscriptions',
+        operationId: 'list-subscriptions',
+        method: 'GET',
+        path: '/subscriptions',
+        title: 'List subscriptions',
+        resource: 'subscription',
+        description: 'List the subscriptions owned by this API key, newest first, as `{total, data}`. All filters are optional; page with `limit` and `offset`. ' +
+            'Secrets are masked (`secretHint`). Use it to find a subscription id before get, update, pause, resume, delete or log calls.',
+        annotations: { ...READ_ACCOUNT, title: 'List subscriptions' },
+        params: {
+            status: {
+                in: 'query',
+                schema: z
+                    .enum(SUBSCRIPTION_STATUSES)
+                    .optional()
+                    .describe('Only subscriptions in this state: active (being polled), pending (flight not published yet), paused, completed (flight over) or suspended (20 failed deliveries in a row).'),
+            },
+            carrier: { in: 'query', schema: carrier.optional() },
+            flightNumber: { in: 'query', schema: flightNumber.optional() },
+            date: { in: 'query', schema: date.optional() },
+            offset: { in: 'query', schema: z.number().int().min(0).optional().describe('How many to skip, for paging. Default 0.') },
+            limit: { in: 'query', schema: z.number().int().min(1).max(200).optional().describe('Page size, 1 to 200. Default 25.') },
+        },
+    },
+    {
+        name: 'get_subscription',
+        operationId: 'get-subscription',
+        method: 'GET',
+        path: '/subscriptions/{id}',
+        title: 'Get a subscription',
+        resource: 'subscription',
+        description: 'Fetch one subscription: `status` (active, pending, paused, completed, suspended) and `statusReason`, `flightKey`, `flightResolved`, webhook URL, event filter, delay threshold, ' +
+            '`deliveredCount`/`failedCount`, and the last poll, change and delivery times. The secret is masked.',
+        annotations: { ...READ_ACCOUNT, title: 'Get a subscription' },
+        params: { ...idPath },
+    },
+    {
+        name: 'update_subscription',
+        operationId: 'update-subscription',
+        method: 'PATCH',
+        path: '/subscriptions/{id}',
+        title: 'Update a subscription',
+        resource: 'subscription',
+        description: "Change a subscription's `webhookUrl`, `events` filter, `delayThresholdMinutes`, `headers` or `metadata`. Send only the fields to change; `headers` and `metadata` replace the stored maps. " +
+            'The flight cannot be changed: create a new subscription for a different flight.',
+        annotations: { title: 'Update a subscription', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        params: {
+            ...idPath,
+            webhookUrl: { in: 'body', schema: webhookUrl.optional() },
+            events: { in: 'body', schema: events.optional() },
+            delayThresholdMinutes: { in: 'body', schema: delayThresholdMinutes.optional() },
+            headers: { in: 'body', schema: deliveryHeaders.optional() },
+            metadata: { in: 'body', schema: metadata.optional() },
+        },
+    },
+    {
+        name: 'pause_subscription',
+        operationId: 'pause-subscription',
+        method: 'POST',
+        path: '/subscriptions/{id}/pause',
+        title: 'Pause a subscription',
+        resource: 'subscription',
+        description: 'Stop polling and webhook deliveries for a subscription without deleting it. Nothing is lost; resume_subscription continues it. Returns the updated subscription.',
+        annotations: { title: 'Pause a subscription', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        params: { ...idPath },
+    },
+    {
+        name: 'resume_subscription',
+        operationId: 'resume-subscription',
+        method: 'POST',
+        path: '/subscriptions/{id}/resume',
+        title: 'Resume a subscription',
+        resource: 'subscription',
+        description: 'Resume a paused subscription, or one that was suspended after 20 consecutive failed deliveries (fix the receiver first; send_test_event checks it). ' +
+            'A completed subscription cannot be resumed: create a new one. Returns the updated subscription.',
+        annotations: { title: 'Resume a subscription', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        params: { ...idPath },
+    },
+    {
+        name: 'delete_subscription',
+        operationId: 'delete-subscription',
+        method: 'DELETE',
+        path: '/subscriptions/{id}',
+        title: 'Delete a subscription',
+        resource: 'subscription',
+        description: 'Permanently delete a subscription: its polling and webhook deliveries stop and it cannot be restored. Confirm with the user first, and prefer pause_subscription if they may want it back. ' +
+            "Events and deliveries already recorded stay on FlightByte's side for 30 days.",
+        annotations: { title: 'Delete a subscription', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        params: { ...idPath },
+        emptyText: (args) => `Subscription ${String(args.id)} deleted. Its polling and deliveries have stopped; recorded events and deliveries stay readable for 30 days.`,
+    },
+    {
+        name: 'send_test_event',
+        operationId: 'send-test-event',
+        method: 'POST',
+        path: '/subscriptions/{id}/test',
+        title: 'Send a test event',
+        resource: 'subscription',
+        description: "Send a signed `subscription.test` webhook through the real delivery pipeline to the subscription's webhookUrl, signed with its real secret, and return the `eventId`. " +
+            'Use it to prove a receiver and its signature check work before the first real change, then call list_deliveries to see how the delivery went.',
+        annotations: { title: 'Send a test event', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        params: { ...idPath },
+    },
+    {
+        name: 'list_deliveries',
+        operationId: 'list-deliveries',
+        method: 'GET',
+        path: '/subscriptions/{id}/deliveries',
+        title: 'List deliveries',
+        resource: 'subscription',
+        description: 'Recent webhook delivery attempts for a subscription, newest first: `eventId`, `attempt`, `status`, `httpStatus`, `error`, `durationMs`, `at` and `changeTypes`. ' +
+            'Use it to debug a receiver that is not getting webhooks or is answering with errors. Records are kept for 30 days.',
+        annotations: { ...READ_ACCOUNT, title: 'List deliveries' },
+        params: {
+            ...idPath,
+            limit: { in: 'query', schema: z.number().int().min(1).max(100).optional().describe('How many attempts, 1 to 100. Default 25.') },
+        },
+    },
+    {
+        name: 'list_events',
+        operationId: 'list-events',
+        method: 'GET',
+        path: '/subscriptions/{id}/events',
+        title: 'List sent events',
+        resource: 'subscription',
+        description: 'Recent events generated for a subscription, newest first, with the exact webhook payloads that were sent (the list of changes and the flight snapshot at the time). ' +
+            'Use it to see what changed and when, or to replay a payload into a local receiver.',
+        annotations: { ...READ_ACCOUNT, title: 'List sent events' },
+        params: {
+            ...idPath,
+            limit: { in: 'query', schema: z.number().int().min(1).max(100).optional().describe('How many events, 1 to 100. Default 25.') },
+        },
+    },
+];
+/** Codes the API upper-cases anyway; sending them normalised keeps cache keys and logs tidy. */
+const UPPERCASE = new Set(['carrier', 'flightNumber', 'origin', 'destination']);
+export function buildRequest(def, args) {
+    let path = def.path;
+    const query = {};
+    const headers = {};
+    const body = {};
+    for (const [name, param] of Object.entries(def.params)) {
+        let value = args[name];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === 'string') {
+            value = value.trim();
+            if (UPPERCASE.has(name))
+                value = value.toUpperCase();
+        }
+        switch (param.in) {
+            case 'path':
+                path = path.replace(`{${name}}`, encodeURIComponent(String(value)));
+                break;
+            case 'query':
+                query[name] = String(value);
+                break;
+            case 'header':
+                headers[name] = String(value);
+                break;
+            case 'body':
+                body[name] = value;
+                break;
+        }
+    }
+    const request = { method: def.method, path, query, headers };
+    if (Object.values(def.params).some((p) => p.in === 'body'))
+        request.body = body;
+    return request;
+}
+export function inputSchema(def) {
+    return z.object(Object.fromEntries(Object.entries(def.params).map(([name, p]) => [name, p.schema])));
+}
+export async function runApiTool(def, client, args) {
+    if (!client.hasKey)
+        return missingKeyError(def.name);
+    if (def.name === 'update_subscription') {
+        const fields = Object.entries(def.params).filter(([name, p]) => p.in === 'body' && args[name] !== undefined);
+        if (fields.length === 0) {
+            return {
+                isError: true,
+                content: [
+                    { type: 'text', text: 'Nothing to update: pass at least one of webhookUrl, events, delayThresholdMinutes, headers or metadata.' },
+                ],
+            };
+        }
+    }
+    const result = await client.request(buildRequest(def, args));
+    if (result.kind !== 'ok')
+        return apiErrorResult(result, { tool: def.name, resource: def.resource });
+    if (result.data === undefined) {
+        const text = def.emptyText?.(args) ?? `Done (HTTP ${result.status}, no response body).`;
+        return { content: [{ type: 'text', text }] };
+    }
+    const content = [];
+    const notes = def.notes?.(result.data, args) ?? [];
+    if (notes.length > 0)
+        content.push({ type: 'text', text: notes.join('\n') });
+    content.push({ type: 'text', text: JSON.stringify(result.data) });
+    const out = { content };
+    const record = asRecord(result.data);
+    if (record)
+        out.structuredContent = record;
+    return out;
+}
+function legNotes(data, args) {
+    const snapshot = asRecord(data);
+    const alternates = Array.isArray(snapshot?.alternates) ? snapshot.alternates : [];
+    if (alternates.length < 2)
+        return [];
+    const legs = alternates
+        .map((leg) => `${String(leg.departureIata)}→${String(leg.arrivalIata)}${leg.selected ? ' (this snapshot)' : ''}`)
+        .join(', ');
+    const selected = args.origin || args.destination || args.flightId;
+    return [
+        `This flight number operates ${alternates.length} legs on ${String(snapshot?.date ?? args.date)}: ${legs}. ` +
+            (selected
+                ? 'The snapshot below is the leg matching the selector.'
+                : 'No selector was given, so this is the default leg; if the user meant another one, call again with `origin`.'),
+    ];
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}

package/dist/tools/docs-tools.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { toolError } from '../errors.js';
+/** Path and URL parts that say nothing about which page was meant. */
+const ROOT_WORDS = new Set(['docs', 'guides', 'glossary', 'reference', 'md', 'http', 'https', 'www', 'flightbyte', 'dev']);
+export function registerDocsTools(server, docs) {
+    server.registerTool('search_docs', {
+        title: 'Search the FlightByte docs',
+        description: 'Keyword search over the whole FlightByte documentation: the docs, the API reference, the engineering guides and the glossary. ' +
+            'Returns the best-matching sections with title, URL and a snippet. Use it before answering questions about the API (authentication, quotas, errors, flight lookups, leg selection, ' +
+            'subscriptions, webhook payloads and change types, signature verification, retries) or before writing integration code, then read the full page with get_doc_page. Works without an API key.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .min(1)
+                .max(300)
+                .describe('Keywords, e.g. "verify webhook signature", "429 retry", "flight number two legs origin", "baggage carousel event".'),
+            limit: z.number().int().min(1).max(10).optional().describe('How many sections to return, 1 to 10. Default 5.'),
+        }),
+        annotations: { title: 'Search the FlightByte docs', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ query, limit }) => {
+        let hits;
+        try {
+            hits = await docs.search(query, limit ?? 5);
+        }
+        catch (err) {
+            return toolError(`The docs could not be loaded (${err instanceof Error ? err.message : String(err)}). Retry shortly; the same content is at ${docs.docsUrl}/llms-full.txt.`);
+        }
+        if (hits.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `No docs section matched "${query}". Try fewer or different keywords, or open the index with get_doc_page("/docs").`,
+                    },
+                ],
+                structuredContent: { query, results: [] },
+            };
+        }
+        const text = [
+            `Top ${hits.length} docs sections for "${query}":`,
+            '',
+            ...hits.flatMap((hit, i) => [`${i + 1}. ${hit.title}`, `   ${hit.url}`, `   ${hit.snippet}`, '']),
+            'Read a full page with get_doc_page, passing its URL.',
+        ].join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: { query, results: hits.map(({ title, url, snippet }) => ({ title, url, snippet })) },
+        };
+    });
+    server.registerTool('get_doc_page', {
+        title: 'Read a FlightByte docs page',
+        description: 'Fetch one FlightByte documentation page as Markdown. Accepts a URL from search_docs (anchors are ignored) or a path such as "/docs/webhooks", "/docs/reference/subscriptions/create-subscription", ' +
+            '"/guides/verifying-webhook-signatures" or "/glossary/flight-phase". "/docs" is the introduction, with links to every page. Works without an API key.',
+        inputSchema: z.object({
+            path: z
+                .string()
+                .min(1)
+                .max(500)
+                .describe('Docs path or URL, e.g. "/docs/errors" or "https://flightbyte.dev/docs/webhooks#verifying-signatures".'),
+        }),
+        annotations: { title: 'Read a FlightByte docs page', readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ path }) => {
+        const page = await docs.page(path);
+        if (page.ok)
+            return { content: [{ type: 'text', text: page.markdown }] };
+        if (page.status === 'not_found') {
+            let suggestions = '';
+            try {
+                const words = path
+                    .split(/[/#?.:-]+/)
+                    .filter((w) => w && !ROOT_WORDS.has(w.toLowerCase()))
+                    .join(' ');
+                const hits = words ? await docs.search(words, 3) : [];
+                if (hits.length > 0)
+                    suggestions = `\nClosest pages: ${hits.map((h) => h.url.split('#')[0]).filter((u, i, a) => a.indexOf(u) === i).join(', ')}`;
+            }
+            catch {
+                // Suggestions are a courtesy; the error stands without them.
+            }
+            return toolError(`${page.message} Use search_docs to find the right page, or get_doc_page("/docs") for the index.${suggestions}`);
+        }
+        return toolError(page.message);
+    });
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@flightbyte/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "MCP server for FlightByte, the flight status API with signed webhooks: look flights up, watch them with webhook subscriptions, and search the docs from any AI assistant.",
+  "mcpName": "dev.flightbyte/mcp",
+  "license": "MIT",
+  "author": "FlightByte (https://flightbyte.dev)",
+  "homepage": "https://flightbyte.dev/docs/ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flightbyte-dev/flightbyte-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/flightbyte-dev/flightbyte-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "flightbyte",
+    "flight-status",
+    "flight-tracking",
+    "flights",
+    "webhooks",
+    "aviation",
+    "ai"
+  ],
+  "type": "module",
+  "bin": {
+    "flightbyte-mcp": "dist/stdio.js"
+  },
+  "exports": {
+    ".": "./dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "npm run build && vitest run",
+    "test:watch": "vitest",
+    "check": "npm run typecheck && npm run lint && npm test",
+    "start": "node dist/stdio.js",
+    "start:http": "node dist/http.js",
+    "sync:openapi": "node scripts/sync-openapi.mjs",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.3.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@types/node": "^22.20.5",
+    "eslint": "^10.13.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
+  }
+}

package/server.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "dev.flightbyte/mcp",
+  "title": "FlightByte",
+  "description": "Live flight status, flight watches with signed webhooks, and FlightByte docs search.",
+  "version": "1.0.0",
+  "websiteUrl": "https://flightbyte.dev/docs/ai",
+  "repository": {
+    "url": "https://github.com/flightbyte-dev/flightbyte-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@flightbyte/mcp",
+      "version": "1.0.0",
+      "runtimeHint": "npx",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "FLIGHTBYTE_KEY",
+          "description": "Your FlightByte API key (free at https://app.flightbyte.dev/signup). The docs tools work without it.",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.flightbyte.dev/mcp",
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Your FlightByte API key as a bearer token: Bearer <key>. The docs tools work without it.",
+          "value": "Bearer {flightbyte_key}",
+          "isRequired": true,
+          "isSecret": true,
+          "variables": {
+            "flightbyte_key": {
+              "description": "Your FlightByte API key (free at https://app.flightbyte.dev/signup)",
+              "isRequired": true,
+              "isSecret": true
+            }
+          }
+        }
+      ]
+    }
+  ]
+}