ninerouter-mcp 1.2.0 → 1.3.0

package/dist/lib/countries.js

@@ -0,0 +1,352 @@
+/**
+ * Country name <-> ISO 3166-1 alpha-2 conversion for the `country` search filter:
+ * Tavily wants a country name, Serper and friends want an ISO code.
+ */
+/**
+ * Lookup key. Case, accents and separators are folded away, so "Côte d'Ivoire"
+ * and "cote divoire" resolve to the same country.
+ */
+function normalizeKey(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/&/g, ' and ')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+}
+/**
+ * ISO 3166-1 alpha-2 code -> country name, spelled the way Tavily lists them.
+ * Tavily accepts only these names, so the list stays as long as its enum.
+ */
+const COUNTRY_LIST = [
+    ['af', 'afghanistan'],
+    ['al', 'albania'],
+    ['dz', 'algeria'],
+    ['ad', 'andorra'],
+    ['ao', 'angola'],
+    ['ar', 'argentina'],
+    ['am', 'armenia'],
+    ['au', 'australia'],
+    ['at', 'austria'],
+    ['az', 'azerbaijan'],
+    ['bs', 'bahamas'],
+    ['bh', 'bahrain'],
+    ['bd', 'bangladesh'],
+    ['bb', 'barbados'],
+    ['by', 'belarus'],
+    ['be', 'belgium'],
+    ['bz', 'belize'],
+    ['bj', 'benize'],
+    ['bt', 'bhutan'],
+    ['bo', 'bolivia'],
+    ['ba', 'bosnia and herzegovina'],
+    ['bw', 'botswana'],
+    ['br', 'brazil'],
+    ['bn', 'brunei'],
+    ['bg', 'bulgaria'],
+    ['bf', 'burkina faso'],
+    ['bi', 'burundi'],
+    ['kh', 'cambodia'],
+    ['cm', 'cameroon'],
+    ['ca', 'canada'],
+    ['cv', 'cape verde'],
+    ['cf', 'central african republic'],
+    ['td', 'chad'],
+    ['cl', 'chile'],
+    ['cn', 'china'],
+    ['co', 'colombia'],
+    ['km', 'comoros'],
+    ['cg', 'congo'],
+    ['cr', 'costa rica'],
+    ['hr', 'croatia'],
+    ['cu', 'cuba'],
+    ['cy', 'cyprus'],
+    ['cz', 'czech republic'],
+    ['dk', 'denmark'],
+    ['dj', 'djibouti'],
+    ['do', 'dominican republic'],
+    ['ec', 'ecuador'],
+    ['eg', 'egypt'],
+    ['sv', 'el salvador'],
+    ['gq', 'equatorial guinea'],
+    ['er', 'eritrea'],
+    ['ee', 'estonia'],
+    ['et', 'ethiopia'],
+    ['fj', 'fiji'],
+    ['fi', 'finland'],
+    ['fr', 'france'],
+    ['ga', 'gabon'],
+    ['gm', 'gambia'],
+    ['ge', 'georgia'],
+    ['de', 'germany'],
+    ['gh', 'ghana'],
+    ['gr', 'greece'],
+    ['gt', 'guatemala'],
+    ['gn', 'guinea'],
+    ['ht', 'haiti'],
+    ['hn', 'honduras'],
+    ['hu', 'hungary'],
+    ['is', 'iceland'],
+    ['in', 'india'],
+    ['id', 'indonesia'],
+    ['ir', 'iran'],
+    ['iq', 'iraq'],
+    ['ie', 'ireland'],
+    ['il', 'israel'],
+    ['it', 'italy'],
+    ['jm', 'jamaica'],
+    ['jp', 'japan'],
+    ['jo', 'jordan'],
+    ['kz', 'kazakhstan'],
+    ['ke', 'kenya'],
+    ['kw', 'kuwait'],
+    ['kg', 'kyrgyzstan'],
+    ['lv', 'latvia'],
+    ['lb', 'lebanon'],
+    ['ls', 'lesotho'],
+    ['lr', 'liberia'],
+    ['ly', 'libya'],
+    ['li', 'liechtenstein'],
+    ['lt', 'lithuania'],
+    ['lu', 'luxembourg'],
+    ['mg', 'madagascar'],
+    ['mw', 'malawi'],
+    ['my', 'malaysia'],
+    ['mv', 'maldives'],
+    ['ml', 'mali'],
+    ['mt', 'malta'],
+    ['mr', 'mauritania'],
+    ['mu', 'mauritius'],
+    ['mx', 'mexico'],
+    ['md', 'moldova'],
+    ['mc', 'monaco'],
+    ['mn', 'mongolia'],
+    ['me', 'montenegro'],
+    ['ma', 'morocco'],
+    ['mz', 'mozambique'],
+    ['mm', 'myanmar'],
+    ['na', 'namibia'],
+    ['np', 'nepal'],
+    ['nl', 'netherlands'],
+    ['nz', 'new zealand'],
+    ['ni', 'nicaragua'],
+    ['ne', 'niger'],
+    ['ng', 'nigeria'],
+    ['kp', 'north korea'],
+    ['mk', 'north macedonia'],
+    ['no', 'norway'],
+    ['om', 'oman'],
+    ['pk', 'pakistan'],
+    ['pa', 'panama'],
+    ['pg', 'papua new guinea'],
+    ['py', 'paraguay'],
+    ['pe', 'peru'],
+    ['ph', 'philippines'],
+    ['pl', 'poland'],
+    ['pt', 'portugal'],
+    ['qa', 'qatar'],
+    ['ro', 'romania'],
+    ['ru', 'russia'],
+    ['rw', 'rwanda'],
+    ['sa', 'saudi arabia'],
+    ['sn', 'senegal'],
+    ['rs', 'serbia'],
+    ['sg', 'singapore'],
+    ['sk', 'slovakia'],
+    ['si', 'slovenia'],
+    ['so', 'somalia'],
+    ['za', 'south africa'],
+    ['kr', 'south korea'],
+    ['ss', 'south sudan'],
+    ['es', 'spain'],
+    ['lk', 'sri lanka'],
+    ['sd', 'sudan'],
+    ['se', 'sweden'],
+    ['ch', 'switzerland'],
+    ['sy', 'syria'],
+    ['tw', 'taiwan'],
+    ['tj', 'tajikistan'],
+    ['tz', 'tanzania'],
+    ['th', 'thailand'],
+    ['tg', 'togo'],
+    ['tt', 'trinidad and tobago'],
+    ['tn', 'tunisia'],
+    ['tr', 'turkey'],
+    ['tm', 'turkmenistan'],
+    ['ug', 'uganda'],
+    ['ua', 'ukraine'],
+    ['ae', 'united arab emirates'],
+    ['gb', 'united kingdom'],
+    ['us', 'united states'],
+    ['uy', 'uruguay'],
+    ['uz', 'uzbekistan'],
+    ['ve', 'venezuela'],
+    ['vn', 'vietnam'],
+    ['ye', 'yemen'],
+    ['zm', 'zambia'],
+    ['zw', 'zimbabwe'],
+];
+/**
+ * Names outside the list above, plus the spellings agents actually produce.
+ * They resolve to a code but have no country-name form.
+ */
+const COUNTRY_ALIASES = {
+    'aland islands': 'ax',
+    'american samoa': 'as',
+    anguilla: 'ai',
+    antarctica: 'aq',
+    'antigua and barbuda': 'ag',
+    aruba: 'aw',
+    bermuda: 'bm',
+    bosnia: 'ba',
+    'bouvet island': 'bv',
+    'british indian ocean territory': 'io',
+    'british virgin islands': 'vg',
+    burma: 'mm',
+    'cape verde islands': 'cv',
+    'caribbean netherlands': 'bq',
+    'cayman islands': 'ky',
+    'christmas island': 'cx',
+    'cocos keeling islands': 'cc',
+    'congo brazzaville': 'cg',
+    'congo kinshasa': 'cd',
+    'cook islands': 'ck',
+    'cote d ivoire': 'ci',
+    'cote divoire': 'ci',
+    curacao: 'cw',
+    czechia: 'cz',
+    'democratic republic of the congo': 'cd',
+    dominica: 'dm',
+    'dr congo': 'cd',
+    'east timor': 'tl',
+    england: 'gb',
+    eswatini: 'sz',
+    'falkland islands': 'fk',
+    'faroe islands': 'fo',
+    'french guiana': 'gf',
+    'french polynesia': 'pf',
+    'french southern territories': 'tf',
+    gibraltar: 'gi',
+    'great britain': 'gb',
+    greenland: 'gl',
+    grenada: 'gd',
+    guadeloupe: 'gp',
+    guam: 'gu',
+    guernsey: 'gg',
+    'guinea bissau': 'gw',
+    guyana: 'gy',
+    'heard and mcdonald islands': 'hm',
+    holland: 'nl',
+    'hong kong': 'hk',
+    'hong kong sar china': 'hk',
+    'isle of man': 'im',
+    'ivory coast': 'ci',
+    jersey: 'je',
+    kiribati: 'ki',
+    korea: 'kr',
+    laos: 'la',
+    'macao sar china': 'mo',
+    macedonia: 'mk',
+    'marshall islands': 'mh',
+    martinique: 'mq',
+    mayotte: 'yt',
+    micronesia: 'fm',
+    montserrat: 'ms',
+    'myanmar burma': 'mm',
+    nauru: 'nr',
+    'new caledonia': 'nc',
+    niue: 'nu',
+    'norfolk island': 'nf',
+    'northern ireland': 'gb',
+    'northern mariana islands': 'mp',
+    palau: 'pw',
+    palestine: 'ps',
+    'palestinian territories': 'ps',
+    'pitcairn islands': 'pn',
+    'puerto rico': 'pr',
+    'republic of korea': 'kr',
+    reunion: 're',
+    'russian federation': 'ru',
+    samoa: 'ws',
+    'san marino': 'sm',
+    'sao tome and principe': 'st',
+    scotland: 'gb',
+    seychelles: 'sc',
+    'sierra leone': 'sl',
+    'sint maarten': 'sx',
+    'slovak republic': 'sk',
+    'solomon islands': 'sb',
+    'south georgia and south sandwich islands': 'gs',
+    'south korean republic': 'kr',
+    'sri lanka': 'lk',
+    'st barthelemy': 'bl',
+    'st helena': 'sh',
+    'st kitts and nevis': 'kn',
+    'st lucia': 'lc',
+    'st martin': 'mf',
+    'st pierre and miquelon': 'pm',
+    'st vincent and grenadines': 'vc',
+    suriname: 'sr',
+    'svalbard and jan mayen': 'sj',
+    swaziland: 'sz',
+    'timor leste': 'tl',
+    tokelau: 'tk',
+    tonga: 'to',
+    'trinidad tobago': 'tt',
+    'turks and caicos islands': 'tc',
+    tuvalu: 'tv',
+    'u s': 'us',
+    'u k': 'gb',
+    'u s outlying islands': 'um',
+    'u s virgin islands': 'vi',
+    'u.s.a.': 'us',
+    uae: 'ae',
+    'united states of america': 'us',
+    usa: 'us',
+    vanuatu: 'vu',
+    vatican: 'va',
+    'vatican city': 'va',
+    'wallis and futuna': 'wf',
+    wales: 'gb',
+    'western sahara': 'eh',
+};
+const CODE_TO_NAME = new Map(COUNTRY_LIST);
+const NAME_TO_CODE = new Map();
+for (const [code, name] of COUNTRY_LIST) {
+    NAME_TO_CODE.set(normalizeKey(name), code);
+}
+for (const [alias, code] of Object.entries(COUNTRY_ALIASES)) {
+    NAME_TO_CODE.set(normalizeKey(alias), code);
+}
+/** True for anything shaped like an ISO 3166-1 alpha-2 code, known or not. */
+export function isCountryCode(value) {
+    return /^[a-z]{2}$/.test(value.trim().toLowerCase());
+}
+/**
+ * Country name or ISO code -> ISO 3166-1 alpha-2 code.
+ * Returns undefined when the value names no known country.
+ */
+export function toCountryCode(value) {
+    const key = normalizeKey(value);
+    if (!key) {
+        return undefined;
+    }
+    return NAME_TO_CODE.get(key) ?? (isCountryCode(key) ? key : undefined);
+}
+/**
+ * Country name or ISO code -> the country name Tavily accepts.
+ * Returns undefined when no name form is known.
+ */
+export function toCountryName(value) {
+    const key = normalizeKey(value);
+    if (!key) {
+        return undefined;
+    }
+    const direct = CODE_TO_NAME.get(key);
+    if (direct) {
+        return direct;
+    }
+    const code = NAME_TO_CODE.get(key);
+    return code ? CODE_TO_NAME.get(code) : undefined;
+}

package/dist/lib/download-links.js

@@ -0,0 +1,106 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+/** How long a download URL stays valid. */
+export const DOWNLOAD_TTL_MS = 15 * 60 * 1000;
+/** Strip characters that would break out of the Content-Disposition header. */
+function safeFileName(name) {
+    return name.replace(/["\\\r\n]/g, '');
+}
+/**
+ * Signed, time-limited download URLs. The server holds a random secret for its
+ * lifetime; a link carries the session, the file id and an expiry, and the HMAC
+ * over all three is the only thing that authorizes the download. That lets a
+ * browser fetch the file without the MCP session, while the secret stays local.
+ *
+ * A session id is assigned when the transport does not report one, so every
+ * link is bound to a session either way.
+ */
+export class DownloadStore {
+    secret;
+    ttlMs;
+    entries = new Map();
+    constructor(secret = randomBytes(32), ttlMs = DOWNLOAD_TTL_MS) {
+        this.secret = secret;
+        this.ttlMs = ttlMs;
+    }
+    key(sessionId, id) {
+        return `${sessionId}:${id}`;
+    }
+    sign(sessionId, id, expiresAt) {
+        return createHmac('sha256', this.secret)
+            .update(`${sessionId}:${id}:${expiresAt}`)
+            .digest('base64url');
+    }
+    mint(file, now = Date.now()) {
+        const sessionId = file.sessionId ?? randomUUID();
+        const id = randomUUID();
+        const expiresAt = now + this.ttlMs;
+        this.entries.set(this.key(sessionId, id), {
+            path: file.path,
+            contentType: file.contentType,
+            fileName: safeFileName(file.fileName),
+            sessionId,
+            expiresAt,
+        });
+        return { sessionId, id, expiresAt, token: this.sign(sessionId, id, expiresAt) };
+    }
+    /** The entry a valid token points at, or undefined when it is forged or expired. */
+    verify(sessionId, id, expiresAt, token, now = Date.now()) {
+        if (!Number.isFinite(expiresAt) || expiresAt <= now) {
+            return undefined;
+        }
+        const expected = Buffer.from(this.sign(sessionId, id, expiresAt));
+        const given = Buffer.from(token);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given)) {
+            return undefined;
+        }
+        const entry = this.entries.get(this.key(sessionId, id));
+        if (!entry || entry.expiresAt !== expiresAt) {
+            return undefined;
+        }
+        return entry;
+    }
+    prune(now = Date.now()) {
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt <= now) {
+                this.entries.delete(key);
+            }
+        }
+    }
+}
+/**
+ * Build an exposer that mints links against the origin the client reached the
+ * server on. `publicUrl` wins when set (a deployment behind a proxy), then the
+ * request's own host, then `fallbackOrigin` when the transport reports none.
+ */
+export function createUrlExposer(store, filesPath, publicUrl, fallbackOrigin = '') {
+    return (file) => {
+        const { sessionId, id, expiresAt, token } = store.mint(file);
+        const origin = publicUrl ?? (originFromRequest(file.request) || fallbackOrigin);
+        return {
+            location: `${origin}${filesPath}/${sessionId}/${id}?exp=${expiresAt}&sig=${token}`,
+            kind: 'url',
+            expiresAt,
+        };
+    };
+}
+/** Prefer the proxy headers when present, then the Host the client used. */
+function originFromRequest(request) {
+    if (!request) {
+        return '';
+    }
+    let parsed;
+    try {
+        parsed = new URL(request.url);
+    }
+    catch {
+        return '';
+    }
+    const forwardedProto = request.headers.get('x-forwarded-proto')?.split(',')[0]?.trim();
+    const forwardedHost = request.headers.get('x-forwarded-host')?.split(',')[0]?.trim();
+    const host = forwardedHost || request.headers.get('host') || parsed.host;
+    if (!host) {
+        return '';
+    }
+    const proto = forwardedProto || parsed.protocol.replace(':', '') || 'http';
+    return `${proto}://${host}`;
+}

package/dist/lib/media-output.js

@@ -0,0 +1,23 @@
+/**
+ * How generated media reaches the caller. Under stdio the MCP server shares the
+ * client's filesystem, so a path is enough. Under HTTP the server may sit on
+ * another host, where a path points at a filesystem the client cannot open and
+ * the bytes need a URL instead.
+ */
+export const LOCAL_RUNTIME = { remote: false };
+/**
+ * `auto` inlines the bytes under stdio and hands back a URL over HTTP. A remote
+ * server without an exposer falls back to inlining, because a path it cannot
+ * serve is worse than a large response.
+ */
+export function resolveMediaDelivery(mode, runtime) {
+    if (mode === 'path') {
+        return { inline: false, url: false };
+    }
+    if (mode === 'inline') {
+        return { inline: true, url: false };
+    }
+    return runtime.remote && runtime.expose
+        ? { inline: false, url: true }
+        : { inline: true, url: false };
+}

package/dist/lib/web-capabilities.js

@@ -0,0 +1,220 @@
+import { requestGetJson } from '../ninerouter-client.js';
+import { isCountryCode, toCountryCode, toCountryName } from './countries.js';
+/** Catalog alias -> provider id, for the providers whose alias differs. */
+const PROVIDER_ALIASES = {
+    brave: 'brave-search',
+    gpse: 'google-pse',
+    pplx: 'perplexity',
+    pw: 'perplexity-web',
+};
+// Mirrors 9Router's per-provider request builders; keep in step with them.
+const CAPABILITIES = {
+    tavily: {
+        country: true,
+        countryFormat: 'name',
+        language: false,
+        timeRange: false,
+        domainFilter: true,
+    },
+    exa: {
+        country: false,
+        countryFormat: 'any',
+        language: false,
+        timeRange: false,
+        domainFilter: true,
+    },
+    serper: {
+        country: true,
+        countryFormat: 'iso2-lower',
+        language: true,
+        timeRange: false,
+        domainFilter: false,
+    },
+    'brave-search': {
+        country: true,
+        countryFormat: 'iso2-upper',
+        language: true,
+        timeRange: false,
+        domainFilter: false,
+    },
+    // Searches through a chat model, which forwards the query and the result
+    // count only.
+    perplexity: {
+        country: false,
+        countryFormat: 'any',
+        language: false,
+        timeRange: false,
+        domainFilter: false,
+    },
+    'google-pse': {
+        country: true,
+        countryFormat: 'iso2-lower',
+        language: true,
+        timeRange: true,
+        domainFilter: false,
+    },
+    linkup: {
+        country: false,
+        countryFormat: 'any',
+        language: false,
+        timeRange: true,
+        domainFilter: true,
+    },
+    searchapi: {
+        country: true,
+        countryFormat: 'iso2-lower',
+        language: true,
+        timeRange: false,
+        domainFilter: false,
+    },
+    youcom: {
+        country: true,
+        countryFormat: 'iso2-upper',
+        language: true,
+        timeRange: true,
+        domainFilter: true,
+    },
+    searxng: {
+        country: false,
+        countryFormat: 'any',
+        language: true,
+        timeRange: true,
+        domainFilter: false,
+    },
+    xquik: {
+        country: false,
+        countryFormat: 'any',
+        language: true,
+        timeRange: false,
+        domainFilter: false,
+    },
+    tinyfish: {
+        country: true,
+        countryFormat: 'iso2-upper',
+        language: true,
+        timeRange: false,
+        domainFilter: true,
+    },
+    // Ollama forwards the country and language to its own API, which documents
+    // only the query and the result count, and ignores both.
+    'ollama-search': {
+        country: false,
+        countryFormat: 'any',
+        language: false,
+        timeRange: false,
+        domainFilter: false,
+    },
+    glm: {
+        country: false,
+        countryFormat: 'any',
+        language: false,
+        timeRange: false,
+        domainFilter: false,
+    },
+};
+/** Providers that read each field, used to explain a dropped filter. */
+const SUPPORTED_BY = {
+    country: 'tavily, serper, brave-search, google-pse, searchapi, youcom, tinyfish',
+    language: 'serper, brave-search, google-pse, searchapi, youcom, searxng, xquik, tinyfish',
+    timeRange: 'google-pse, linkup, youcom, searxng',
+    domainFilter: 'tavily, exa, linkup, youcom, tinyfish',
+};
+/**
+ * Capabilities of a provider, or undefined for an unknown one (a combo, or a
+ * provider added to 9Router later). Unknown providers get every field as-is.
+ */
+export function lookupWebCapabilities(modelId) {
+    const key = modelId.trim().toLowerCase();
+    const providerId = PROVIDER_ALIASES[key] ?? key;
+    return CAPABILITIES[providerId];
+}
+/**
+ * Rewrite a country filter into the format the provider expects. A value the
+ * provider cannot accept is dropped, not forwarded: Tavily rejects the whole
+ * request when its country enum does not match.
+ */
+export function convertCountry(value, format, provider) {
+    const raw = value.trim();
+    if (format === 'any') {
+        return { action: 'send', value: raw };
+    }
+    if (format === 'name') {
+        const name = toCountryName(raw);
+        if (!name) {
+            return {
+                action: 'drop',
+                warning: `country "${raw}" has no name that ${provider} accepts, so the filter was dropped.`,
+            };
+        }
+        if (name === raw) {
+            return { action: 'send', value: name };
+        }
+        return {
+            action: 'send',
+            value: name,
+            warning: `country "${raw}" went out as "${name}" because ${provider} expects a country name.`,
+        };
+    }
+    const code = toCountryCode(raw);
+    if (!code) {
+        return {
+            action: 'drop',
+            warning: `country "${raw}" is not a known country, so the filter was dropped.`,
+        };
+    }
+    const out = format === 'iso2-upper' ? code.toUpperCase() : code;
+    if (out === raw) {
+        return { action: 'send', value: out };
+    }
+    if (format === 'iso2-upper') {
+        return {
+            action: 'send',
+            value: out,
+            warning: `country "${raw}" went out as "${out}" because ${provider} expects an uppercase ISO 3166-1 alpha-2 code.`,
+        };
+    }
+    if (isCountryCode(raw)) {
+        // The provider lowercases the code itself, so the case difference never
+        // reaches it.
+        return { action: 'send', value: out };
+    }
+    return {
+        action: 'send',
+        value: out,
+        warning: `country "${raw}" went out as "${out}" because ${provider} expects an ISO 3166-1 alpha-2 code.`,
+    };
+}
+/** Message for a filter the provider never reads. */
+export function unsupportedFilterWarning(parameter, provider) {
+    return `${provider} does not read ${parameter}, so the filter was dropped. Only ${SUPPORTED_BY[parameter]} read it.`;
+}
+const INFO_CACHE_TTL_MS = 60_000;
+const infoCache = new Map();
+/**
+ * Per-provider metadata from 9Router's catalog. Providers without a dedicated
+ * search API have no entry, and the caller gets no extra detail.
+ */
+export async function fetchProviderInfo(config, modelId, action) {
+    const key = `${action}:${modelId}`;
+    const cached = infoCache.get(key);
+    if (cached && cached.expires > Date.now()) {
+        return cached.info;
+    }
+    let info;
+    try {
+        const payload = await requestGetJson(config, '/v1/models/info', {
+            id: `${modelId}/${action}`,
+        });
+        info = {
+            searchTypes: Array.isArray(payload.searchTypes)
+                ? payload.searchTypes.filter((value) => typeof value === 'string')
+                : undefined,
+            maxResults: typeof payload.maxResults === 'number' ? payload.maxResults : undefined,
+        };
+    }
+    catch {
+        info = undefined;
+    }
+    infoCache.set(key, { expires: Date.now() + INFO_CACHE_TTL_MS, info });
+    return info;
+}