@flightbyte/mcp 0.0.0-stage → 1.0.0

package/dist/http-app.js

@@ -0,0 +1,239 @@
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createMcpHandler, isLegacyRequest, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { VERSION } from './config.js';
+import { createServer } from './server.js';
+const CORS_HEADERS = {
+    'access-control-allow-origin': '*',
+    'access-control-allow-methods': 'POST, OPTIONS',
+    'access-control-allow-headers': 'authorization, x-api-key, content-type, accept, mcp-protocol-version, mcp-method, mcp-name, mcp-session-id, last-event-id',
+    'access-control-expose-headers': 'mcp-session-id, retry-after',
+    'access-control-max-age': '86400',
+};
+/** A fixed one-minute window per key. Small, in memory, and per process: enough to stop one client hammering the server. */
+export class RateLimiter {
+    limit;
+    windowMs;
+    now;
+    #hits = new Map();
+    constructor(limit, windowMs = 60_000, now = Date.now) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+        this.now = now;
+    }
+    take(key) {
+        const now = this.now();
+        let entry = this.#hits.get(key);
+        if (!entry || entry.resetAt <= now) {
+            entry = { count: 0, resetAt: now + this.windowMs };
+            this.#hits.set(key, entry);
+        }
+        entry.count++;
+        return { ok: entry.count <= this.limit, retryAfterSeconds: Math.max(1, Math.ceil((entry.resetAt - now) / 1000)) };
+    }
+    sweep() {
+        const now = this.now();
+        for (const [key, entry] of this.#hits)
+            if (entry.resetAt <= now)
+                this.#hits.delete(key);
+    }
+}
+/** The caller's FlightByte key from `Authorization: Bearer <key>` or `x-api-key`. */
+export function extractApiKey(headers) {
+    const bearer = headers.get('authorization')?.match(/^Bearer\s+(\S+)\s*$/i)?.[1];
+    if (bearer)
+        return bearer;
+    return headers.get('x-api-key')?.trim() || undefined;
+}
+export function clientIp(req, trustProxy) {
+    if (trustProxy > 0) {
+        const forwarded = first(req.headers['x-forwarded-for'])
+            ?.split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (forwarded && forwarded.length > 0)
+            return forwarded[Math.max(0, forwarded.length - trustProxy)];
+    }
+    return req.socket.remoteAddress ?? 'unknown';
+}
+export function createHttpApp(options) {
+    const maxBodyBytes = options.maxBodyBytes ?? 1_000_000;
+    const log = options.log ?? ((line) => console.error(line));
+    const now = options.now ?? Date.now;
+    const limiter = options.rateLimitPerMinute > 0 ? new RateLimiter(options.rateLimitPerMinute, 60_000, now) : undefined;
+    const allowedHosts = new Set(options.allowedHosts.map((h) => h.toLowerCase()));
+    const serverFor = (headers) => createServer({ apiUrl: options.apiUrl, apiKey: extractApiKey(headers), docs: options.docs, fetch: options.fetch });
+    // 2026-07-28 requests: the SDK entry builds a fresh server per request. Tools send nothing before their result, so it answers plain JSON.
+    const modern = createMcpHandler(({ requestInfo }) => serverFor(requestInfo?.headers ?? new Headers()), {
+        legacy: 'reject',
+        onerror: (err) => log(`mcp error: ${err.message}`),
+    });
+    // 2025-era requests (protocol 2024-11-05 to 2025-11-25): stateless Streamable HTTP with JSON responses, a fresh server per request.
+    const serveLegacy = async (request, body, res) => {
+        const server = serverFor(request.headers);
+        const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on('close', () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        return transport.handleRequest(request, { parsedBody: body });
+    };
+    const handler = async (req, res) => {
+        const started = now();
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        let note = '';
+        res.on('finish', () => {
+            // Never log headers or bodies: they carry API keys, webhook URLs and secrets.
+            log(`${req.method} ${url.pathname} ${res.statusCode} ${now() - started}ms${note}`);
+        });
+        try {
+            if (url.pathname === '/healthz' && (req.method === 'GET' || req.method === 'HEAD')) {
+                return sendJson(res, 200, { status: 'ok', version: VERSION });
+            }
+            if (url.pathname === '/' && req.method === 'GET') {
+                return sendJson(res, 200, {
+                    name: 'FlightByte MCP server',
+                    version: VERSION,
+                    mcp: '/mcp',
+                    transport: 'streamable-http',
+                    auth: 'Authorization: Bearer <FlightByte API key>',
+                    docs: 'https://flightbyte.dev/docs/ai',
+                });
+            }
+            if (url.pathname !== '/mcp')
+                return sendJson(res, 404, { error: 'Not found. The MCP endpoint is POST /mcp.' });
+            for (const [name, value] of Object.entries(CORS_HEADERS))
+                res.setHeader(name, value);
+            if (allowedHosts.size > 0) {
+                const host = hostname(first(req.headers.host));
+                if (!host || !allowedHosts.has(host))
+                    return sendRpcError(res, 403, -32000, 'Host not allowed.');
+            }
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204).end();
+                return;
+            }
+            if (req.method !== 'POST') {
+                res.setHeader('allow', 'POST, OPTIONS');
+                // Stateless server: no standalone SSE stream (GET) and no sessions to end (DELETE).
+                return sendRpcError(res, 405, -32000, 'Method not allowed. This server is stateless: send JSON-RPC requests with POST.');
+            }
+            if (limiter) {
+                const verdict = limiter.take(clientIp(req, options.trustProxy));
+                if (!verdict.ok) {
+                    res.setHeader('retry-after', String(verdict.retryAfterSeconds));
+                    return sendRpcError(res, 429, -32000, `Too many requests. Retry after ${verdict.retryAfterSeconds} seconds.`);
+                }
+            }
+            let raw;
+            let body;
+            try {
+                raw = await readBody(req, maxBodyBytes);
+                body = JSON.parse(raw);
+            }
+            catch (err) {
+                if (err instanceof BodyTooLargeError) {
+                    res.setHeader('connection', 'close');
+                    return sendRpcError(res, 413, -32600, `Request body over ${maxBodyBytes} bytes.`);
+                }
+                return sendRpcError(res, 400, -32700, 'Parse error: the body must be a JSON-RPC message.');
+            }
+            note = describeRpc(body);
+            // Aborted when the client goes away before the response is complete, which cancels the work behind it.
+            const abort = new AbortController();
+            res.on('close', () => {
+                if (!res.writableFinished)
+                    abort.abort();
+            });
+            const request = toWebRequest(req, url, raw, abort.signal);
+            const legacy = await isLegacyRequest(request, body);
+            note += `${extractApiKey(request.headers) ? ' key=yes' : ' key=no'} era=${legacy ? 'legacy' : 'modern'}`;
+            await sendResponse(res, legacy ? await serveLegacy(request, body, res) : await modern.fetch(request, { parsedBody: body }));
+        }
+        catch (err) {
+            log(`error handling ${req.method} ${url.pathname}: ${err instanceof Error ? err.message : String(err)}`);
+            if (!res.headersSent)
+                sendRpcError(res, 500, -32603, 'Internal server error.');
+            else
+                res.end();
+        }
+    };
+    return { handler, limiter, close: () => modern.close() };
+}
+/** Hop-by-hop headers describe this connection, not the request; a web Request must not carry them. */
+const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'transfer-encoding', 'content-length', 'upgrade', 'te', 'trailer']);
+function toWebRequest(req, url, body, signal) {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined || HOP_BY_HOP.has(name))
+            continue;
+        for (const v of Array.isArray(value) ? value : [value])
+            headers.append(name, v);
+    }
+    return new Request(url, { method: req.method, headers, body, signal });
+}
+async function sendResponse(res, response) {
+    res.statusCode = response.status;
+    response.headers.forEach((value, name) => res.setHeader(name, value));
+    if (!response.body) {
+        res.end();
+        return;
+    }
+    try {
+        await pipeline(Readable.fromWeb(response.body), res);
+    }
+    catch (err) {
+        // A client that hangs up mid-stream is not a server error.
+        if (!res.destroyed)
+            throw err;
+    }
+}
+class BodyTooLargeError extends Error {
+}
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                // Stop buffering but let the request drain, so the 413 still reaches the client.
+                req.removeAllListeners('data');
+                req.resume();
+                reject(new BodyTooLargeError());
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+function describeRpc(body) {
+    const messages = Array.isArray(body) ? body : [body];
+    const parts = messages.map((m) => {
+        const msg = m;
+        if (typeof msg?.method !== 'string')
+            return 'response';
+        return msg.method === 'tools/call' && typeof msg.params?.name === 'string' ? `tools/call:${msg.params.name}` : msg.method;
+    });
+    return parts.length > 0 ? ` ${parts.join(',')}` : '';
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+}
+function sendRpcError(res, status, code, message) {
+    sendJson(res, status, { jsonrpc: '2.0', error: { code, message }, id: null });
+}
+function first(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+function hostname(host) {
+    if (!host)
+        return undefined;
+    const lower = host.toLowerCase();
+    if (lower.startsWith('['))
+        return lower.slice(0, lower.indexOf(']') + 1);
+    return lower.split(':')[0];
+}

package/dist/http.js

@@ -0,0 +1,51 @@
+import { createServer as createHttpServer } from 'node:http';
+import { loadConfig, VERSION } from './config.js';
+import { DocsStore } from './docs.js';
+import { createHttpApp } from './http-app.js';
+const config = loadConfig();
+const port = intEnv('PORT', 8080);
+const host = process.env.HOST?.trim() || '127.0.0.1';
+const loopback = ['127.0.0.1', 'localhost', '::1'].includes(host);
+// Bound to loopback, only loopback Host headers are accepted (DNS rebinding protection), unless ALLOWED_HOSTS says otherwise.
+const allowedHosts = (process.env.ALLOWED_HOSTS ?? '')
+    .split(',')
+    .map((h) => h.trim())
+    .filter(Boolean);
+if (allowedHosts.length === 0 && loopback)
+    allowedHosts.push('localhost', '127.0.0.1', '[::1]');
+const app = createHttpApp({
+    apiUrl: config.apiUrl,
+    docs: new DocsStore({ docsUrl: config.docsUrl }),
+    rateLimitPerMinute: intEnv('RATE_LIMIT_PER_MINUTE', 120),
+    trustProxy: intEnv('TRUST_PROXY', 0),
+    allowedHosts,
+});
+const server = createHttpServer((req, res) => void app.handler(req, res));
+server.keepAliveTimeout = 65_000;
+server.headersTimeout = 66_000;
+server.requestTimeout = 120_000;
+const sweeper = setInterval(() => app.limiter?.sweep(), 60_000);
+sweeper.unref();
+server.listen(port, host, () => {
+    const address = server.address();
+    const bound = typeof address === 'object' && address ? address.port : port;
+    console.error(`flightbyte-mcp ${VERSION} listening on http://${host.includes(':') ? `[${host}]` : host}:${bound}/mcp`);
+});
+const shutdown = (signal) => {
+    console.error(`${signal} received, closing`);
+    // End in-flight 2026-era exchanges so open streams do not hold the server past the grace period.
+    void app.close();
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 10_000).unref();
+};
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+function intEnv(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error(`${name} must be a non-negative integer, got "${raw}"`);
+    return value;
+}

package/dist/server.js

@@ -0,0 +1,27 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { ApiClient } from './api.js';
+import { VERSION } from './config.js';
+import { DocsStore } from './docs.js';
+import { API_TOOLS, inputSchema, runApiTool } from './tools/api-tools.js';
+import { registerDocsTools } from './tools/docs-tools.js';
+export { VERSION } from './config.js';
+export { DocsStore } from './docs.js';
+export { API_TOOLS } from './tools/api-tools.js';
+const INSTRUCTIONS = `FlightByte is a flight status API with signed webhooks.
+
+- Questions about the API, its errors, webhooks or how to integrate: call search_docs, then get_doc_page for the full page. These work without an API key.
+- Flight status: get_flight with carrier (e.g. "TK"), flightNumber (e.g. "1848") and date, the local departure date at the origin (YYYY-MM-DD). A flight number can operate several legs on one date; pass origin when the user names a departure airport.
+- To be told about changes instead of asking repeatedly, create_subscription with the user's webhook URL. Each subscription is a billable watched flight, so create one only when the user asks. The response carries the webhook signing secret, shown once: relay it to the user.
+- Manage subscriptions with list_subscriptions, get_subscription, update_subscription, pause_subscription, resume_subscription and delete_subscription (ask before deleting); debug a receiver with send_test_event, list_deliveries and list_events.
+- When a tool returns an error, follow its "What to do" line; do not retry 400, 401, 402 or 404 errors unchanged.`;
+export function createServer(options) {
+    const server = new McpServer({ name: 'flightbyte', title: 'FlightByte', version: VERSION, websiteUrl: 'https://flightbyte.dev/docs/ai' }, 
+    // The tool list never changes, so clients have nothing to listen for.
+    { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false } } });
+    const client = new ApiClient({ baseUrl: options.apiUrl, apiKey: options.apiKey, fetch: options.fetch });
+    registerDocsTools(server, options.docs);
+    for (const def of API_TOOLS) {
+        server.registerTool(def.name, { title: def.title, description: def.description, inputSchema: inputSchema(def), annotations: def.annotations }, async (args) => runApiTool(def, client, args));
+    }
+    return server;
+}

package/dist/stdio.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { loadConfig, VERSION } from './config.js';
+import { DocsStore } from './docs.js';
+import { createServer } from './server.js';
+// stdout carries the protocol; anything human-readable goes to stderr.
+const args = process.argv.slice(2);
+if (args.includes('--version') || args.includes('-v')) {
+    console.error(VERSION);
+    process.exit(0);
+}
+if (args.includes('--help') || args.includes('-h')) {
+    console.error(`flightbyte-mcp ${VERSION}: the FlightByte MCP server over stdio.
+
+Environment:
+  FLIGHTBYTE_KEY        Your FlightByte API key (https://app.flightbyte.dev/signup). Docs tools work without it.
+  FLIGHTBYTE_API_URL    API base URL (default https://api.flightbyte.dev/v1)
+  FLIGHTBYTE_DOCS_URL   Docs site (default https://flightbyte.dev)
+
+Docs: https://flightbyte.dev/docs/ai`);
+    process.exit(0);
+}
+const config = loadConfig();
+const apiKey = process.env.FLIGHTBYTE_KEY?.trim() || undefined;
+const docs = new DocsStore({ docsUrl: config.docsUrl });
+// The client's opening message picks the protocol era (2025 initialize or 2026-07-28); one server instance serves the connection.
+const connection = serveStdio(() => createServer({ apiUrl: config.apiUrl, apiKey, docs }), {
+    onerror: (err) => console.error(`stdio error: ${err.message}`),
+});
+console.error(`flightbyte-mcp ${VERSION} running on stdio (${apiKey ? 'API key set' : 'no FLIGHTBYTE_KEY: docs tools only'})`);
+const shutdown = () => {
+    void connection.close().finally(() => process.exit(0));
+};
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);