@flightbyte/mcp 0.0.0-stage → 1.0.0

package/dist/docs.js

@@ -0,0 +1,414 @@
+import { USER_AGENT } from './config.js';
+/** Split at "---" lines followed by a blank line and a "# " title, ignoring any inside code fences (e.g. a SKILL.md example). */
+function splitPages(text) {
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    const chunks = [];
+    let start = 0;
+    let fence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        fence = trackFence(line, fence);
+        if (fence === null && line === '---' && lines[i + 1] === '' && lines[i + 2]?.startsWith('# ')) {
+            chunks.push(lines.slice(start, i).join('\n'));
+            start = i + 2;
+        }
+    }
+    chunks.push(lines.slice(start).join('\n'));
+    return chunks;
+}
+/** The fence that is open after this line: null outside code blocks. */
+function trackFence(line, open) {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1];
+    if (!marker)
+        return open;
+    if (open === null)
+        return marker;
+    return marker[0] === open[0] && marker.length >= open.length ? null : open;
+}
+export function parseLlmsFull(text) {
+    const pages = [];
+    for (const chunk of splitPages(text)) {
+        const markdown = chunk.trim();
+        const lines = markdown.split('\n');
+        const title = lines[0]?.match(/^# (.+)$/)?.[1]?.trim();
+        // Only real pages carry a Source line in their header; the file's own preamble does not.
+        const head = lines.slice(0, 8);
+        const url = head.find((l) => l.startsWith('Source: '))?.slice('Source: '.length).trim();
+        if (!title || !url)
+            continue;
+        const description = head.find((l) => l.startsWith('> '))?.slice(2).trim() ?? '';
+        const page = { title, description, url, markdown, sections: [] };
+        page.sections = splitSections(page, lines.slice(1).filter((l) => !l.startsWith('Source: ') && l !== `> ${description}`));
+        pages.push(page);
+    }
+    return pages;
+}
+function splitSections(page, lines) {
+    const sections = [];
+    const seen = new Map();
+    let current = { page, heading: null, anchor: null, text: '' };
+    let buffer = [];
+    let fence = null;
+    const flush = () => {
+        current.text = buffer.join('\n').trim();
+        if (current.text || current.heading)
+            sections.push(current);
+        buffer = [];
+    };
+    for (const line of lines) {
+        const wasInFence = fence !== null;
+        fence = trackFence(line, fence);
+        const heading = !wasInFence && fence === null ? line.match(/^(#{2,3}) (.+)$/) : null;
+        if (heading) {
+            flush();
+            const text = heading[2].trim();
+            current = { page, heading: stripInline(text), anchor: uniqueSlug(text, seen), text: '' };
+            continue;
+        }
+        buffer.push(line);
+    }
+    flush();
+    return sections;
+}
+/** github-slugger compatible: what the docs site uses for heading anchors. */
+export function slugify(heading) {
+    return stripInline(heading)
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+        .replace(/\s/g, '-');
+}
+function uniqueSlug(heading, seen) {
+    const base = slugify(heading);
+    const count = seen.get(base) ?? 0;
+    seen.set(base, count + 1);
+    return count === 0 ? base : `${base}-${count}`;
+}
+function stripInline(text) {
+    return text
+        .replace(/`([^`]*)`/g, '$1')
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+        .replace(/[*_]{1,2}([^*_]+)[*_]{1,2}/g, '$1')
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// Ranking: BM25 over sections, with the section heading and the page title and description counted as
+// extra, heavier occurrences, light stemming, and prefix matches at a discount.
+const STOPWORDS = new Set('a an and are as at be by can do does for from get how i if in into is it its me my of on or the this that to use what when where which with you your'.split(' '));
+export function tokenize(text) {
+    const out = [];
+    for (const raw of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+        if (!raw || STOPWORDS.has(raw))
+            continue;
+        out.push(stem(raw));
+    }
+    return out;
+}
+function stem(word) {
+    if (word.length > 4 && word.endsWith('ies'))
+        return `${word.slice(0, -3)}y`;
+    if (word.length > 5 && word.endsWith('ing'))
+        return word.slice(0, -3);
+    if (word.length > 4 && word.endsWith('ed'))
+        return word.slice(0, -2);
+    if (word.length > 3 && word.endsWith('s') && !word.endsWith('ss') && !word.endsWith('us'))
+        return word.slice(0, -1);
+    return word;
+}
+const WEIGHT_HEADING = 3;
+const WEIGHT_TITLE = 2;
+const WEIGHT_DESCRIPTION = 0.5;
+const WEIGHT_CODE = 0.3;
+const MIN_LENGTH = 30;
+const K1 = 1.2;
+const B = 0.75;
+export function buildIndex(pages) {
+    const sections = [];
+    const df = new Map();
+    for (const page of pages) {
+        const titleTokens = tokenize(page.title);
+        const descriptionTokens = tokenize(page.description);
+        for (const section of page.sections) {
+            const tf = new Map();
+            const add = (tokens, weight) => {
+                for (const t of tokens)
+                    tf.set(t, (tf.get(t) ?? 0) + weight);
+            };
+            // Code is mostly identifiers and punctuation: it counts, but lightly, and does not make a section "long".
+            const { prose, code } = splitCode(section.text);
+            const bodyTokens = tokenize(prose);
+            add(bodyTokens, 1);
+            add(tokenize(code), WEIGHT_CODE);
+            add(tokenize(section.heading ?? ''), WEIGHT_HEADING);
+            add(titleTokens, WEIGHT_TITLE);
+            add(descriptionTokens, WEIGHT_DESCRIPTION);
+            for (const t of tf.keys())
+                df.set(t, (df.get(t) ?? 0) + 1);
+            sections.push({
+                section,
+                tf,
+                // A floor, so a one-line section does not outrank the section that actually explains the topic.
+                length: Math.max(bodyTokens.length, MIN_LENGTH),
+                lowerText: `${page.title} ${section.heading ?? ''} ${section.text}`.toLowerCase(),
+            });
+        }
+    }
+    const avgLength = sections.reduce((sum, s) => sum + s.length, 0) / Math.max(1, sections.length);
+    return { pages, sections, df, avgLength };
+}
+function splitCode(text) {
+    const prose = [];
+    const code = [];
+    let fence = null;
+    for (const line of text.split('\n')) {
+        const wasInFence = fence !== null;
+        fence = trackFence(line, fence);
+        (wasInFence || fence !== null ? code : prose).push(line);
+    }
+    return { prose: prose.join('\n'), code: code.join('\n') };
+}
+export function search(index, query, limit = 5) {
+    const terms = [...new Set(tokenize(query))];
+    if (terms.length === 0)
+        return [];
+    const n = index.sections.length;
+    const idf = (t) => {
+        const df = index.df.get(t) ?? 0;
+        return Math.log(1 + (n - df + 0.5) / (df + 0.5));
+    };
+    // Each query term matches itself exactly, and vocabulary words it is a prefix of (or that are a prefix of it) at a discount.
+    const vocabulary = [...index.df.keys()];
+    const expansions = terms.map((q) => {
+        const matches = [];
+        if (index.df.has(q))
+            matches.push([q, 1]);
+        if (q.length >= 4) {
+            for (const t of vocabulary) {
+                if (t === q)
+                    continue;
+                if (t.startsWith(q) || (t.length >= 5 && q.startsWith(t)))
+                    matches.push([t, 0.5]);
+            }
+        }
+        return matches;
+    });
+    const phrase = query.trim().toLowerCase().replace(/\s+/g, ' ');
+    const scored = [];
+    for (const entry of index.sections) {
+        let score = 0;
+        let matchedTerms = 0;
+        for (const matches of expansions) {
+            let best = 0;
+            for (const [t, weight] of matches) {
+                const tf = entry.tf.get(t);
+                if (!tf)
+                    continue;
+                const norm = (tf * (K1 + 1)) / (tf + K1 * (1 - B + (B * entry.length) / index.avgLength));
+                best = Math.max(best, weight * idf(t) * norm);
+            }
+            if (best > 0)
+                matchedTerms++;
+            score += best;
+        }
+        if (score === 0)
+            continue;
+        // Favour sections that cover more of the query, and exact phrases.
+        score *= 0.5 + (0.5 * matchedTerms) / expansions.length;
+        if (terms.length > 1 && phrase.length > 3 && entry.lowerText.includes(phrase))
+            score *= 1.5;
+        // The reference pages are generated and long; the hand-written docs explain things.
+        const url = entry.section.page.url;
+        if (/\/docs(\/|$)/.test(url) && !url.includes('/docs/reference/'))
+            score *= 1.25;
+        scored.push({ entry, score });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    const hits = [];
+    const perPage = new Map();
+    const snippets = new Set();
+    for (const { entry, score } of scored) {
+        const { page, heading, anchor } = entry.section;
+        const count = perPage.get(page.url) ?? 0;
+        if (count >= 2)
+            continue;
+        // Generated reference pages repeat the same boilerplate sections; show each text once.
+        const text = snippet(entry.section.text || page.description, terms);
+        if (snippets.has(text))
+            continue;
+        snippets.add(text);
+        perPage.set(page.url, count + 1);
+        hits.push({
+            title: heading ? `${page.title} › ${heading}` : page.title,
+            page: page.title,
+            section: heading,
+            url: anchor ? `${page.url}#${anchor}` : page.url,
+            snippet: text,
+            score: Math.round(score * 100) / 100,
+        });
+        if (hits.length >= limit)
+            break;
+    }
+    return hits;
+}
+function snippet(text, terms, width = 320) {
+    const clean = text
+        .replace(/^\s*(`{3,}|~{3,}).*$/gm, ' ')
+        .replace(/\|?\s*:?-{3,}:?\s*/g, ' ')
+        .replace(/\s*\|\s*/g, ' | ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (clean.length <= width)
+        return clean;
+    const lower = clean.toLowerCase();
+    let at = -1;
+    for (const t of terms) {
+        const i = lower.search(new RegExp(`\\b${escapeRegExp(t)}`));
+        if (i !== -1 && (at === -1 || i < at))
+            at = i;
+    }
+    const start = Math.max(0, at === -1 ? 0 : at - Math.floor(width / 3));
+    const end = Math.min(clean.length, start + width);
+    return `${start > 0 ? '…' : ''}${clean.slice(start, end).trim()}${end < clean.length ? '…' : ''}`;
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Canonical docs host; links in the docs use it even when FLIGHTBYTE_DOCS_URL points somewhere else. */
+const CANONICAL_ORIGINS = new Set(['https://flightbyte.dev', 'https://www.flightbyte.dev']);
+const PAGE_ROOTS = ['/docs', '/guides', '/glossary'];
+const MAX_PAGE_CHARS = 120_000;
+export class DocsStore {
+    docsUrl;
+    #origin;
+    #ttlMs;
+    #timeoutMs;
+    #fetch;
+    #now;
+    #index;
+    #loading;
+    #pages = new Map();
+    constructor(options) {
+        this.docsUrl = options.docsUrl.replace(/\/+$/, '');
+        this.#origin = new URL(this.docsUrl).origin;
+        this.#ttlMs = options.ttlMs ?? 15 * 60_000;
+        this.#timeoutMs = options.timeoutMs ?? 20_000;
+        this.#fetch = options.fetch ?? fetch;
+        this.#now = options.now ?? Date.now;
+    }
+    /** The parsed docs, refreshed after the TTL. A failed refresh keeps serving the previous copy. */
+    async index() {
+        const cached = this.#index;
+        if (cached && cached.expires > this.#now())
+            return cached.value;
+        this.#loading ??= this.#load().finally(() => {
+            this.#loading = undefined;
+        });
+        try {
+            return await this.#loading;
+        }
+        catch (err) {
+            if (cached)
+                return cached.value;
+            throw err;
+        }
+    }
+    async #load() {
+        const url = `${this.docsUrl}/llms-full.txt`;
+        const res = await this.#get(url, 'text/plain');
+        if (!res.ok)
+            throw new Error(`GET ${url} answered ${res.status}`);
+        const pages = parseLlmsFull(await res.text());
+        if (pages.length === 0)
+            throw new Error(`${url} contained no pages`);
+        const value = buildIndex(pages);
+        this.#index = { value, expires: this.#now() + this.#ttlMs };
+        return value;
+    }
+    async search(query, limit) {
+        return search(await this.index(), query, limit);
+    }
+    /** Map a docs path or URL to the page's canonical URL on the configured docs site. */
+    resolve(input) {
+        const value = input.trim();
+        if (!value)
+            return { ok: false, message: 'Pass a docs path such as "/docs/webhooks" or a URL from search_docs.' };
+        let url;
+        try {
+            url = /^[a-z][a-z\d+.-]*:/i.test(value) ? new URL(value) : new URL(value.startsWith('/') ? value : `/${value}`, this.docsUrl);
+        }
+        catch {
+            return { ok: false, message: `"${value}" is not a docs path or URL.` };
+        }
+        if (url.origin !== this.#origin && !CANONICAL_ORIGINS.has(url.origin)) {
+            return { ok: false, message: `Only FlightByte docs pages can be fetched (${this.docsUrl}/docs, /guides, /glossary), not ${url.origin}.` };
+        }
+        let path = decodeURIComponent(url.pathname).replace(/\/+$/, '').replace(/\.md$/, '');
+        if (path === '' || path === '/llms-full.txt' || path === '/llms.txt')
+            path = '/docs';
+        if (!PAGE_ROOTS.some((root) => path === root || path.startsWith(`${root}/`)))
+            path = `/docs${path}`;
+        if (!/^[\w/.-]+$/.test(path) || path.includes('..'))
+            return { ok: false, message: `"${value}" is not a docs path.` };
+        return { ok: true, pageUrl: `${this.docsUrl}${path}`, path };
+    }
+    async page(input) {
+        const resolved = this.resolve(input);
+        if (!resolved.ok)
+            return { ok: false, status: 'invalid', message: resolved.message };
+        const { pageUrl, path } = resolved;
+        const cached = this.#pages.get(pageUrl);
+        if (cached && cached.expires > this.#now())
+            return { ok: true, url: pageUrl, markdown: cached.markdown, from: 'markdown' };
+        let fetchError;
+        try {
+            const res = await this.#get(`${pageUrl}.md`, 'text/markdown');
+            const type = res.headers.get('content-type') ?? '';
+            if (res.ok && !type.includes('text/html')) {
+                const markdown = truncate(await res.text());
+                this.#remember(pageUrl, markdown);
+                return { ok: true, url: pageUrl, markdown, from: 'markdown' };
+            }
+            if (res.status !== 404 && !res.ok)
+                fetchError = `${pageUrl}.md answered ${res.status}`;
+        }
+        catch (err) {
+            fetchError = err instanceof Error ? err.message : String(err);
+        }
+        // Guides and glossary entries have no .md twin; llms-full.txt has every page.
+        try {
+            const index = await this.index();
+            const page = index.pages.find((p) => samePath(p.url, path));
+            if (page)
+                return { ok: true, url: page.url, markdown: truncate(page.markdown), from: 'llms-full' };
+        }
+        catch (err) {
+            fetchError ??= err instanceof Error ? err.message : String(err);
+        }
+        if (fetchError)
+            return { ok: false, status: 'unavailable', message: `Could not fetch ${pageUrl}: ${fetchError}. Retry shortly.` };
+        return { ok: false, status: 'not_found', message: `No docs page at ${pageUrl}.` };
+    }
+    #remember(url, markdown) {
+        if (this.#pages.size >= 200)
+            this.#pages.delete(this.#pages.keys().next().value);
+        this.#pages.set(url, { markdown, expires: this.#now() + this.#ttlMs });
+    }
+    #get(url, accept) {
+        return this.#fetch(url, {
+            headers: { accept, 'user-agent': USER_AGENT },
+            signal: AbortSignal.timeout(this.#timeoutMs),
+        });
+    }
+}
+function samePath(url, path) {
+    try {
+        return new URL(url).pathname.replace(/\/+$/, '') === path;
+    }
+    catch {
+        return false;
+    }
+}
+function truncate(markdown) {
+    if (markdown.length <= MAX_PAGE_CHARS)
+        return markdown;
+    return `${markdown.slice(0, MAX_PAGE_CHARS)}\n\n[Truncated at ${MAX_PAGE_CHARS} characters.]`;
+}

package/dist/errors.js

@@ -0,0 +1,119 @@
+import { KEYS_URL, PLAN_URL, REMOTE_URL, SIGNUP_URL } from './config.js';
+export function toolError(text) {
+    return { isError: true, content: [{ type: 'text', text }] };
+}
+export function missingKeyError(tool) {
+    return toolError([
+        `No FlightByte API key is configured, so \`${tool}\` cannot call the API. Do not retry until a key is set.`,
+        '',
+        'Tell the user to add their key to this MCP server, then restart or reconnect it:',
+        '- Local server (npx @flightbyte/mcp): set the FLIGHTBYTE_KEY environment variable in the MCP client config, e.g. `claude mcp add flightbyte --env FLIGHTBYTE_KEY=<key> -- npx -y @flightbyte/mcp`.',
+        `- Remote server (${REMOTE_URL}): send the header \`Authorization: Bearer <key>\` (or \`x-api-key: <key>\`).`,
+        `A free key comes from ${SIGNUP_URL}. The docs tools (search_docs, get_doc_page) work without a key.`,
+    ].join('\n'));
+}
+/** Turn a failed API call into an `isError` result that tells the model what to do next. */
+export function apiErrorResult(result, ctx) {
+    if (result.kind === 'network_error') {
+        return toolError(`Could not reach the FlightByte API (${result.url}): ${result.message}. ` +
+            'This is usually temporary: retry once after a few seconds, and tell the user if it keeps failing.');
+    }
+    const env = isObject(result.body) ? result.body : {};
+    const status = result.status;
+    const message = Array.isArray(env.message) ? env.message.join('; ') : env.message;
+    const lines = [];
+    lines.push(`FlightByte API error ${status}${env.error ? ` ${env.error}` : ''}${env.code ? ` (code: ${env.code})` : ''}.`);
+    if (message)
+        lines.push(`Message: ${message}`);
+    else if (!isObject(result.body) && result.text)
+        lines.push(`Body: ${result.text.slice(0, 500)}`);
+    lines.push('');
+    lines.push(`What to do: ${guidance(status, env, result.headers, ctx)}`);
+    const legs = Array.isArray(env.legs) ? env.legs : [];
+    if (legs.length > 0) {
+        lines.push('', 'Legs this flight number operates on that date:');
+        for (const leg of legs)
+            lines.push(`- ${describeLeg(leg)}`);
+    }
+    if (env.requestId)
+        lines.push('', `requestId: ${env.requestId} (quote it if the user contacts FlightByte support)`);
+    return toolError(lines.join('\n'));
+}
+function guidance(status, env, headers, ctx) {
+    const { tool } = ctx;
+    switch (status) {
+        case 400:
+            if (Array.isArray(env.legs) && env.legs.length > 0) {
+                return ('This flight number operates more than one leg on that date, and FlightByte will not guess which one is meant. ' +
+                    'Use the departure airport the user mentioned, or ask them which leg, then call ' +
+                    `\`${tool}\` again with \`origin\` (add \`destination\` if two legs leave the same airport), or with \`flightId\` from the list below.`);
+            }
+            return 'The request failed validation. Fix the arguments named in the message and try again; repeating it unchanged gets the same answer.';
+        case 401:
+            return ('The API key is missing, invalid, revoked or expired. Do not retry. Ask the user to check the key configured for this MCP server ' +
+                `(FLIGHTBYTE_KEY locally, or the Authorization header for ${REMOTE_URL}); keys are managed at ${KEYS_URL}, and a free one comes from ${SIGNUP_URL}.`);
+        case 402: {
+            if (env.code === 'watched_flight_limit') {
+                const usage = env.used !== undefined && env.limit !== undefined ? ` (${env.used}/${env.limit} this month)` : '';
+                const reset = env.resetsAt ? ` The allowance resets at ${env.resetsAt}.` : '';
+                return (`The plan's monthly cap on watched flights is reached${usage}, so no new subscription can be created.${reset} ` +
+                    `The existing subscriptions keep running. Do not retry; tell the user they can wait for the reset or upgrade at ${PLAN_URL}.`);
+            }
+            return `The plan does not allow this request. Do not retry; tell the user to check their plan at ${PLAN_URL}.`;
+        }
+        case 403:
+            return 'This key is not allowed to do that. Do not retry; tell the user.';
+        case 404:
+            if (ctx.resource === 'subscription') {
+                return ('No subscription with this id exists for this API key (subscriptions belong to the key that created them). ' +
+                    'Call `list_subscriptions` to find the right id instead of guessing.');
+            }
+            return ('No such flight, or no leg matching the selector. If you passed origin, destination or flightId, the message names the legs that exist: retry with one of them. ' +
+                'Otherwise check carrier, flightNumber and date (the local departure date at the origin, YYYY-MM-DD). ' +
+                'Live records cover a few days back to about two days ahead; a subscription can still be created up to seven days ahead and waits as `pending`.');
+        case 409:
+            return ('A subscription for this flight and webhook URL already exists under the same Idempotency-Key. ' +
+                'Call `list_subscriptions` (filter by carrier, flightNumber and date) to find it rather than creating another.');
+        case 429: {
+            const wait = retryAfterSeconds(env, headers);
+            const window = env.window ? `the ${env.window} quota window` : 'a quota window';
+            return (`Rate limited: ${window} is full.${wait !== undefined ? ` Wait ${wait} seconds (Retry-After) before calling the API again.` : ' Wait before calling the API again.'} ` +
+                'Do not retry in a loop; if the wait is long, tell the user. Refused requests do not count against the quota.');
+        }
+        case 502:
+        case 503:
+        case 504:
+            return 'A temporary failure on FlightByte\'s side or upstream. Safe to retry once after a few seconds; tell the user if it persists.';
+        default:
+            if (status >= 500)
+                return 'An unexpected server error. Retry once after a few seconds; if it persists, tell the user and include the requestId.';
+            return 'The API refused the request. Read the message, fix the arguments, and do not repeat the same call unchanged.';
+    }
+}
+function retryAfterSeconds(env, headers) {
+    const header = headers.get('retry-after');
+    if (header) {
+        const seconds = Number(header);
+        if (Number.isFinite(seconds))
+            return Math.max(0, Math.ceil(seconds));
+        const at = Date.parse(header);
+        if (!Number.isNaN(at))
+            return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+    }
+    return typeof env.retryAfterSeconds === 'number' ? env.retryAfterSeconds : undefined;
+}
+function describeLeg(leg) {
+    const route = `${leg.origin ?? '?'} → ${leg.destination ?? '?'}`;
+    const parts = [route];
+    if (leg.carrier)
+        parts.push(`operated by ${leg.carrier}`);
+    if (leg.scheduledDepartureLocal)
+        parts.push(`departs ${leg.scheduledDepartureLocal} local`);
+    const pick = [leg.origin ? `origin "${leg.origin}"` : undefined, leg.flightId ? `flightId "${leg.flightId}"` : undefined]
+        .filter(Boolean)
+        .join(' or ');
+    return pick ? `${parts.join(', ')}: pass ${pick}` : parts.join(', ');
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}