mcp-recipes 1.0.0

package/dist/sources/client.d.ts

@@ -0,0 +1,448 @@
+import { a as Language } from '../language-BgfmjwtF.js';
+
+/**
+ * Settings, read from the environment.
+ *
+ * A value that cannot be read warns and falls back rather than stopping the
+ * server: a typo in one variable should not take away every tool. Warnings go
+ * to stderr, because stdout carries the protocol and anything written there
+ * corrupts the session.
+ *
+ * One setting governs every source. Each is read through its own client, and
+ * each of those keeps a pacing floor of its own that nothing here can lower, so
+ * a value set here can only make this server more patient than it already is.
+ */
+declare const LOG_LEVELS: readonly ["silent", "error", "info", "debug"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+interface Config {
+    userAgent: string;
+    minIntervalMs: number;
+    timeoutMs: number;
+    maxRetries: number;
+    cacheTtlMs: number;
+    cacheMaxEntries: number;
+    logLevel: LogLevel;
+}
+interface Logger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+
+/** The shapes the source layer produces. Nothing here knows about MCP. */
+
+/**
+ * Which corpus a row, a recipe or a failure came from.
+ *
+ * A plain string rather than a closed set of names: the sources this server
+ * reads are registered rather than compiled in, so adding one is an entry in
+ * the registry and changes nothing here. What the server reads today is
+ * whatever the registry holds, and an answer names it.
+ */
+type SourceId = string;
+/** What a source is called, where it lives, and what it asks of a reader. */
+interface SourceProfile {
+    id: SourceId;
+    /** What to call the source in prose and in a credit line. */
+    name: string;
+    /** The source's own home, for a reader who wants to go there. */
+    homeUrl: string;
+    /** The language the source publishes in, which its lines are read in. */
+    language: Language;
+    /** What a caller has to say when repeating the source's text. */
+    attribution: string;
+    /**
+     * Whether the corpus files pages about ingredients beside recipes using
+     * them. Where it does, a search row can be either, and only reading the page
+     * tells them apart, so an answer holding rows from such a source says so.
+     */
+    mixesReferencePages: boolean;
+}
+/** A search row, trimmed to what picks one recipe out of a list. */
+interface RecipeRow {
+    /** Carries the source, and the string get_recipe takes back. */
+    id: string;
+    source: SourceId;
+    sourceName: string;
+    title: string;
+    url: string;
+    imageUrl: string | null;
+    /** The gloss or the matching passage the source offered, when it offered one. */
+    excerpt: string | null;
+}
+/** A rating, always with the scale it sits on. */
+interface Rating {
+    value: number;
+    count: number | null;
+    /** The top of the scale. A rating read without it means nothing. */
+    max: number | null;
+}
+/** One recipe, in the shape every source is read into. */
+interface RecipeDetail {
+    id: string;
+    source: SourceId;
+    sourceName: string;
+    /** The language this recipe's lines are written in. */
+    language: Language;
+    title: string;
+    url: string;
+    imageUrl: string | null;
+    /** Servings the page states as a number, when it states one. */
+    yieldCount: number | null;
+    /**
+     * The upper end when the page states a range, as in "4 à 6 personnes". Null
+     * when the page names one number, which is the ordinary case.
+     */
+    yieldMax: number | null;
+    /** The yield exactly as published, which can be "4 à 6 personnes" or "24 balls". */
+    yieldText: string | null;
+    /** What the yield counts, when it counts something other than people. */
+    yieldUnit: string | null;
+    /** The lines as published, before any scaling. */
+    ingredients: string[];
+    steps: string[];
+    prepMinutes: number | null;
+    cookMinutes: number | null;
+    totalMinutes: number | null;
+    category: string | null;
+    author: string | null;
+    rating: Rating | null;
+    /** The panel as published, key by key, with what the page left out omitted. */
+    nutrition: Record<string, string> | null;
+    equipment: string[];
+    tips: string[];
+    /** Terms the page is published under, when the source states them. */
+    license: {
+        title: string;
+        url: string;
+    } | null;
+    attribution: string;
+}
+/**
+ * What one source answered, or why it did not.
+ *
+ * The two travel together so an answer can never read as an absence: a caller
+ * seeing `status: "failed"` knows the source was asked and did not reply, which
+ * is a different statement from a source that answered and holds nothing.
+ */
+interface SourceReport {
+    source: SourceId;
+    name: string;
+    status: "answered" | "failed";
+    /** Rows this source contributed to the answer. */
+    count: number;
+    /** Rows the source said it saw, in the terms that source counts in. */
+    reportedTotal: number | null;
+    /** What `reportedTotal` counts on this source, in words. */
+    reportedTotalMeans: string | null;
+    /** Rows the source sent that could not be read, and were left out. */
+    skipped: number;
+    /** Whether this source files reference pages beside recipes. */
+    mixesReferencePages: boolean;
+    cached: boolean;
+    error: {
+        code: string;
+        message: string;
+        hint?: string;
+    } | null;
+}
+interface MergedSearch {
+    rows: RecipeRow[];
+    reports: SourceReport[];
+}
+
+/**
+ * What a source has to provide to be one.
+ *
+ * Everything above this file is written for however many sources the registry
+ * holds. A source knows four things nothing else does: what it is called, how
+ * to recognise one of its own identifiers, how to search it, and how to read one
+ * recipe off it. Adding a corpus is writing those four and registering it.
+ *
+ * The helpers below are the ones every adapter needs, because no source answers
+ * with a contract: a field can arrive missing, null, or holding something other
+ * than the type it usually holds.
+ */
+
+/** Rows that could be read, and how many could not. */
+interface ReadRows {
+    rows: RecipeRow[];
+    /** Rows the source sent in a shape this server could not read. */
+    skipped: number;
+    /** Rows the source said it saw, in the terms that source counts in. */
+    reportedTotal: number | null;
+    /** What `reportedTotal` counts on this source, in words. Null when it states none. */
+    reportedTotalMeans: string | null;
+    cached: boolean;
+}
+interface ReadRecipe {
+    recipe: RecipeDetail;
+    cached: boolean;
+}
+/** How a source recognised a raw identifier as one of its own. */
+interface Claim {
+    /** The string this source's own reader takes. */
+    reference: string;
+    /** Why the shape was read this way, for an answer that has to say so. */
+    why: string;
+    /**
+     * Whether reading it this way is a guess. A shape only this source mints is
+     * not; a shape it would merely accept is, and the answer says so.
+     */
+    guess: boolean;
+}
+interface SourceAdapter extends SourceProfile {
+    /**
+     * Recognise a raw identifier, or decline it.
+     *
+     * A source claims a shape it mints and declines everything else, so a string
+     * no source claims is refused, instead of being sent somewhere that would
+     * answer it with a confident absence.
+     */
+    claims(raw: string): Claim | null;
+    search(query: string, limit: number): Promise<ReadRows>;
+    getRecipe(reference: string): Promise<ReadRecipe>;
+}
+/** Build the identifier this server hands out for a row from a source. */
+declare function namespacedId(source: SourceId, reference: string): string;
+
+/**
+ * Identifiers that name the source they came from.
+ *
+ * Every source hands back an opaque string, and a caller holding a merged list
+ * has no way to tell one source's string from another's. Every identifier this
+ * server returns therefore carries a prefix, and `get_recipe` routes on it
+ * rather than trying each source in turn.
+ */
+
+interface ResolvedId {
+    source: SourceAdapter;
+    /** The string that source's own reader takes. */
+    reference: string;
+    /** Set when the shape was read rather than stated, so the answer can say so. */
+    inferred: string | null;
+}
+/**
+ * Work out which source an identifier belongs to.
+ *
+ * A prefixed identifier is routed on what it says. A raw one is offered to each
+ * source in turn, and a source claims only the shapes it mints: digits for one,
+ * a namespaced page key for another. Exactly one claim routes the read and the
+ * answer says which reading it used.
+ *
+ * More than one claim is refused rather than resolved, because picking a winner
+ * would send the read somewhere a caller did not intend and answer with a
+ * confident recipe for the wrong dish. No claim at all is refused too: a bare
+ * dish name is a search, not an identifier, and guessing a page name from it
+ * returns whatever that guess happens to hit.
+ */
+declare function resolveId(rawId: string, sources: readonly SourceAdapter[]): ResolvedId;
+
+/**
+ * The Cookbook on the English Wikibooks, as a source.
+ *
+ * A wiki written by whoever edits it, published under a licence that requires
+ * attribution, with no author and no reader rating by nature. Its identifiers
+ * are page keys carrying the namespace every Cookbook page lives in.
+ */
+
+/** A search row, as the Cookbook's own reader publishes one. */
+interface CookbookSummary {
+    key: string;
+    title: string;
+    description: string | null;
+    excerpt: string | null;
+    imageUrl: string | null;
+    sourceUrl: string;
+}
+/** A page, as the Cookbook's own reader publishes one. */
+interface CookbookRecipe {
+    key: string;
+    title: string;
+    sourceUrl: string;
+    license: {
+        title: string;
+        url: string;
+    } | null;
+    description: string | null;
+    category: string | null;
+    servings: number | null;
+    yieldText: string | null;
+    yieldUnit: string | null;
+    totalMinutes: number | null;
+    ingredients: string[];
+    equipment: string[];
+    steps: string[];
+    tips: string[];
+    nutrition: unknown;
+}
+/** The part of the Cookbook's client this server uses. */
+interface CookbookReader {
+    search(query: string, limit: number): Promise<{
+        data: {
+            results: CookbookSummary[];
+        };
+        cached: boolean;
+    }>;
+    getRecipe(reference: string): Promise<{
+        data: CookbookRecipe;
+        cached: boolean;
+    }>;
+}
+
+/**
+ * Marmiton, as a source.
+ *
+ * A French recipe site with reader ratings, whose identifiers are digits and
+ * whose search serves a single page it disallows paging past.
+ */
+
+/** A search row, as Marmiton's own reader publishes one. */
+interface MarmitonSummary {
+    id: string;
+    title: string;
+    url: string;
+    imageUrl: string | null;
+}
+/** A recipe, as Marmiton's own reader publishes one. */
+interface MarmitonRecipe {
+    id: string;
+    title: string;
+    url: string;
+    imageUrl: string | null;
+    ingredients: string[];
+    steps: string[];
+    recipeYield: {
+        count: number | null;
+        unit: string | null;
+        text: string;
+    };
+    prepMinutes: number | null;
+    cookMinutes: number | null;
+    totalMinutes: number | null;
+    category: string | null;
+    author: string | null;
+    rating: {
+        value: number;
+        count: number | null;
+        best: number | null;
+    } | null;
+    nutrition: unknown;
+}
+/** The part of Marmiton's client this server uses. */
+interface MarmitonReader {
+    search(query: string): Promise<{
+        data: MarmitonSummary[];
+        cached: boolean;
+    }>;
+    getRecipe(ref: {
+        id?: string;
+        url?: string;
+    }): Promise<{
+        data: MarmitonRecipe;
+        cached: boolean;
+    }>;
+}
+
+/**
+ * The sources this server reads.
+ *
+ * One list, and everything above it is written for however long the list is.
+ * Adding a corpus means writing an adapter and adding it here; no tool, no
+ * merge and no error path has a branch per source.
+ */
+
+/**
+ * A reader may be supplied in place of the one that talks to a site, so a
+ * program embedding this server can put its own cache in front of a corpus, and
+ * a test can drive it from fixed answers.
+ */
+interface Readers {
+    marmiton?: MarmitonReader;
+    cookbook?: CookbookReader;
+}
+/** The sources a caller can name, in the order an answer takes them. */
+declare const SOURCE_IDS: readonly SourceId[];
+
+/**
+ * The one place that talks to the sources.
+ *
+ * It asks them all at once and merges what comes back, so a question is
+ * answered by whichever of them holds something. It imports nothing from the
+ * MCP layer and is published on its own, so the same code serves a plain
+ * script.
+ *
+ * A source that fails is reported as a source that failed. It is never folded
+ * into the answer as an absence: "Marmiton was unreachable" and "Marmiton holds
+ * no such recipe" are different statements about the world, and a caller that
+ * cannot tell them apart will say the second when only the first is true.
+ */
+
+interface RecipesClientOptions {
+    config?: Partial<Config>;
+    logger?: Logger;
+    /** Stands in for one or more of the site readers. */
+    readers?: Readers;
+    /** Replaces the registry outright, for a program bringing its own corpora. */
+    sources?: SourceAdapter[];
+}
+/** The largest number of rows any one source is asked for in a single call. */
+declare const MAX_LIMIT_PER_SOURCE = 25;
+/**
+ * Interleave rows so no source opens the list twice before another has opened
+ * it once.
+ *
+ * Ranking them against each other would need a score every source carries, and
+ * there is none: one has reader ratings, another has no author and no rating by
+ * nature, and a single ordering would rank on a field most rows cannot have.
+ * Taking one from each in turn is an order a caller can describe exactly, which
+ * is what the answer does.
+ */
+declare function interleave(groups: RecipeRow[][]): RecipeRow[];
+declare class RecipesClient {
+    private readonly config;
+    private readonly logger;
+    private readonly sources;
+    constructor(options?: RecipesClientOptions);
+    /** What every source sees this client call itself. */
+    get userAgent(): string;
+    get intervalMs(): number;
+    get timeoutMs(): number;
+    get maxRetries(): number;
+    /** The sources this server reads, in the order an answer takes them. */
+    get profiles(): Array<{
+        id: SourceId;
+        name: string;
+        language: string;
+        homeUrl: string;
+    }>;
+    /**
+     * The backstop deadline over one source, covering every attempt it is
+     * entitled to make and the pacing between them.
+     */
+    private get deadlineMs();
+    /**
+     * Ask every source the same question and merge the rows.
+     *
+     * The calls go out together, so the answer takes as long as the slowest
+     * source rather than as long as all of them. Whichever of them fail, the rest
+     * still come back, and the report says which was which.
+     */
+    searchRecipes(query: string, limitPerSource: number, wanted?: readonly SourceId[]): Promise<MergedSearch>;
+    private searchOne;
+    /**
+     * Read one recipe, from whichever source the identifier names.
+     *
+     * Only that source is called. Trying another after a miss would turn "this
+     * source has no page by this name" into somebody else's recipe with a
+     * different title, which is a worse answer than the absence it replaced.
+     */
+    getRecipe(id: string): Promise<{
+        recipe: RecipeDetail;
+        cached: boolean;
+        read: ResolvedId;
+    }>;
+}
+
+export { type CookbookReader, MAX_LIMIT_PER_SOURCE, type MarmitonReader, type MergedSearch, type ReadRecipe, type ReadRows, type Readers, type RecipeDetail, type RecipeRow, RecipesClient, type RecipesClientOptions, SOURCE_IDS, type SourceAdapter, type SourceId, type SourceProfile, type SourceReport, interleave, namespacedId, resolveId };