mcp-marmiton 0.1.0

package/dist/marmiton/client.js

@@ -0,0 +1,631 @@
+// src/version.ts
+var PKG_VERSION = "0.1.0";
+var REPO_URL = "https://github.com/smeet666/mcp-marmiton";
+
+// src/config.ts
+var DEFAULT_USER_AGENT = `mcp-marmiton v${PKG_VERSION} (${REPO_URL})`;
+var DEFAULTS = {
+  minIntervalMs: 1e3,
+  timeoutMs: 15e3,
+  maxRetries: 3,
+  cacheTtlMs: 15 * 60 * 1e3,
+  cacheMaxEntries: 200,
+  logLevel: "error"
+};
+var MIN_ALLOWED_INTERVAL_MS = 500;
+var LOG_LEVELS = ["silent", "error", "info", "debug"];
+function readNumber(name, env, range) {
+  const raw = env[name];
+  if (raw === void 0 || raw.trim() === "") return range.fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    warn(`${name}="${raw}" is not a number, using ${range.fallback}`);
+    return range.fallback;
+  }
+  const rounded = Math.round(parsed);
+  if (rounded < range.min || rounded > range.max) {
+    warn(
+      `${name}=${raw} is outside the accepted range ${range.min}-${range.max} and was ignored; using ${range.fallback}`
+    );
+    return range.fallback;
+  }
+  return rounded;
+}
+function warn(message) {
+  process.stderr.write(`[mcp-marmiton] ${message}
+`);
+}
+function readInterval(env) {
+  const raw = env.MARMITON_MIN_INTERVAL_MS;
+  if (raw === void 0 || raw.trim() === "") return DEFAULTS.minIntervalMs;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    warn(`MARMITON_MIN_INTERVAL_MS="${raw}" is not a number, using ${DEFAULTS.minIntervalMs}ms`);
+    return DEFAULTS.minIntervalMs;
+  }
+  const rounded = Math.round(parsed);
+  if (rounded < MIN_ALLOWED_INTERVAL_MS) {
+    warn(
+      `MARMITON_MIN_INTERVAL_MS=${raw} is below the ${MIN_ALLOWED_INTERVAL_MS}ms floor and was ignored; using ${DEFAULTS.minIntervalMs}ms. Marmiton serves these pages for readers, so this client paces itself.`
+    );
+    return DEFAULTS.minIntervalMs;
+  }
+  return Math.min(6e4, rounded);
+}
+function loadConfig(env = process.env) {
+  const rawUserAgent = env.MARMITON_USER_AGENT?.trim();
+  const rawLogLevel = env.MARMITON_LOG_LEVEL?.trim().toLowerCase();
+  let logLevel = DEFAULTS.logLevel;
+  if (rawLogLevel) {
+    if (LOG_LEVELS.includes(rawLogLevel)) {
+      logLevel = rawLogLevel;
+    } else {
+      warn(`MARMITON_LOG_LEVEL="${rawLogLevel}" is unknown, using "${DEFAULTS.logLevel}"`);
+    }
+  }
+  return {
+    userAgent: rawUserAgent || DEFAULT_USER_AGENT,
+    minIntervalMs: readInterval(env),
+    timeoutMs: readNumber("MARMITON_TIMEOUT_MS", env, {
+      min: 1e3,
+      max: 12e4,
+      fallback: DEFAULTS.timeoutMs
+    }),
+    maxRetries: readNumber("MARMITON_MAX_RETRIES", env, {
+      min: 0,
+      max: 10,
+      fallback: DEFAULTS.maxRetries
+    }),
+    cacheTtlMs: readNumber("MARMITON_CACHE_TTL_MS", env, {
+      min: 0,
+      max: 24 * 60 * 60 * 1e3,
+      fallback: DEFAULTS.cacheTtlMs
+    }),
+    cacheMaxEntries: readNumber("MARMITON_CACHE_MAX_ENTRIES", env, {
+      min: 0,
+      max: 1e4,
+      fallback: DEFAULTS.cacheMaxEntries
+    }),
+    logLevel
+  };
+}
+var LEVEL_RANK = { silent: 0, error: 1, info: 2, debug: 3 };
+function createLogger(level) {
+  const emit = (at, message) => {
+    if (LEVEL_RANK[level] >= LEVEL_RANK[at]) {
+      process.stderr.write(`[mcp-marmiton] ${message}
+`);
+    }
+  };
+  return {
+    error: (message) => emit("error", message),
+    info: (message) => emit("info", message),
+    debug: (message) => emit("debug", message)
+  };
+}
+
+// src/marmiton/cache.ts
+var TtlLruCache = class {
+  constructor(maxEntries, ttlMs) {
+    this.maxEntries = maxEntries;
+    this.ttlMs = ttlMs;
+  }
+  maxEntries;
+  ttlMs;
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() >= entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.maxEntries <= 0 || this.ttlMs <= 0) return;
+    this.store.delete(key);
+    this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    while (this.store.size > this.maxEntries) {
+      const oldest = this.store.keys().next();
+      if (oldest.done) break;
+      this.store.delete(oldest.value);
+    }
+  }
+  get size() {
+    return this.store.size;
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/errors.ts
+var MarmitonError = class extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "MarmitonError";
+  }
+  code;
+  details;
+};
+var ISSUES_URL = "https://github.com/smeet666/mcp-marmiton/issues";
+function notFound(url, what) {
+  return new MarmitonError("not_found", `Marmiton has no recipe at ${what}.`, {
+    url,
+    status: 404,
+    hint: "Use search_recipes to find a recipe and its id, then call this tool with that id."
+  });
+}
+function invalidInput(message, hint) {
+  return new MarmitonError("invalid_input", message, hint ? { hint } : {});
+}
+function rateLimited(url, retryAfterMs) {
+  return new MarmitonError(
+    "rate_limited",
+    "Marmiton is rate limiting this client. This does NOT mean the recipe does not exist.",
+    {
+      url,
+      retryAfterMs,
+      hint: `Wait about ${Math.ceil(retryAfterMs / 1e3)} seconds, then call the same tool again with the same arguments. If it keeps happening, raise MARMITON_MIN_INTERVAL_MS.`
+    }
+  );
+}
+function parseFailure(url, what) {
+  return new MarmitonError(
+    "parse_failure",
+    `The page loaded but the expected structured recipe data was not found (${what}). Marmiton may have changed how it publishes it.`,
+    { url, hint: `Please report this, with the recipe you asked for, at ${ISSUES_URL}` }
+  );
+}
+function upstreamError(url, status) {
+  return new MarmitonError("network_error", `Marmiton returned HTTP ${status}.`, {
+    url,
+    status,
+    ...status >= 500 ? { hint: "This is a problem on Marmiton's side. Try again shortly." } : {}
+  });
+}
+
+// src/marmiton/rateLimiter.ts
+var DEFAULT_MAX_INTERVAL_MS = 1e4;
+var RateLimiter = class {
+  baseIntervalMs;
+  maxIntervalMs;
+  intervalMs;
+  /** Tail of the queue: each task chains onto the previous one. */
+  tail = Promise.resolve();
+  lastStart = 0;
+  constructor(options) {
+    this.baseIntervalMs = Math.max(0, options.minIntervalMs);
+    this.maxIntervalMs = Math.max(
+      this.baseIntervalMs,
+      options.maxIntervalMs ?? DEFAULT_MAX_INTERVAL_MS
+    );
+    this.intervalMs = this.baseIntervalMs;
+  }
+  get currentIntervalMs() {
+    return this.intervalMs;
+  }
+  /** Queue a task. Tasks run in call order, one at a time. */
+  schedule(task) {
+    const run = this.tail.then(async () => {
+      await this.waitForSlot();
+      this.lastStart = Date.now();
+      return task();
+    });
+    this.tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  /** Called after the site signals it is under load. */
+  penalize() {
+    const next = this.intervalMs === 0 ? 250 : this.intervalMs * 2;
+    this.intervalMs = Math.min(this.maxIntervalMs, next);
+  }
+  /** Called after a success, so a single hiccup does not slow things down forever. */
+  relax() {
+    this.intervalMs = Math.max(this.baseIntervalMs, Math.floor(this.intervalMs * 0.75));
+  }
+  async waitForSlot() {
+    if (this.intervalMs === 0 || this.lastStart === 0) return;
+    const elapsed = Date.now() - this.lastStart;
+    const remaining = this.intervalMs - elapsed;
+    if (remaining > 0) await sleep(remaining);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/marmiton/http.ts
+var BACKOFF_BASE_MS = 2e3;
+var BACKOFF_FACTOR = 2;
+var BACKOFF_MAX_MS = 2e4;
+var MIN_PLAUSIBLE_HTML = 2e3;
+function backoffDelay(attempt, random = Math.random) {
+  const capped = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * BACKOFF_FACTOR ** attempt);
+  return Math.round(capped * (0.5 + random() * 0.5));
+}
+async function fetchHtml(url, deps) {
+  const { config, limiter, logger } = deps;
+  const doFetch = deps.fetchImpl ?? fetch;
+  return limiter.schedule(async () => {
+    let lastError;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+      if (attempt > 0) {
+        const delay = backoffDelay(attempt - 1);
+        logger.info(`retry ${attempt}/${config.maxRetries} in ${delay}ms for ${url}`);
+        await sleep(delay);
+      }
+      let status;
+      let body;
+      try {
+        const response = await doFetch(url, {
+          headers: {
+            "User-Agent": config.userAgent,
+            Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+            "Accept-Language": "fr-FR,fr;q=0.9,en;q=0.8"
+          },
+          redirect: "follow",
+          signal: AbortSignal.timeout(config.timeoutMs)
+        });
+        status = response.status;
+        body = await response.text();
+      } catch (error) {
+        lastError = asTransportError(error, url);
+        logger.debug(`${lastError.code} for ${url}: ${lastError.message}`);
+        continue;
+      }
+      if (status === 429 || status === 503) {
+        limiter.penalize();
+        lastError = rateLimited(url, backoffDelay(attempt));
+        logger.info(`rate limited on ${url}, interval now ${limiter.currentIntervalMs}ms`);
+        continue;
+      }
+      if (status === 404) throw notFound(url, "that address");
+      if (status >= 500) {
+        lastError = upstreamError(url, status);
+        continue;
+      }
+      if (status >= 400) throw upstreamError(url, status);
+      const trimmed = body.trim();
+      if (trimmed.length < MIN_PLAUSIBLE_HTML && !/<\/html>/i.test(trimmed)) {
+        limiter.penalize();
+        lastError = rateLimited(url, backoffDelay(attempt));
+        logger.info(`implausibly short body on ${url}, treating as rate limiting`);
+        continue;
+      }
+      limiter.relax();
+      return body;
+    }
+    throw lastError ?? new MarmitonError("network_error", `Could not fetch ${url}.`, { url });
+  });
+}
+function asTransportError(error, url) {
+  if (error instanceof MarmitonError) return error;
+  const name = error instanceof Error ? error.name : "";
+  if (name === "TimeoutError" || name === "AbortError") {
+    return new MarmitonError("timeout", "Marmiton did not answer in time.", {
+      url,
+      hint: "Raise MARMITON_TIMEOUT_MS if this happens often on a slow connection."
+    });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new MarmitonError("network_error", `Could not reach Marmiton: ${message}`, { url });
+}
+
+// src/recipe/duration.ts
+var ISO_DURATION = /^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+function parseIsoDuration(value) {
+  if (typeof value !== "string") return null;
+  const match = ISO_DURATION.exec(value.trim().toUpperCase());
+  if (!match) return null;
+  const [, days, hours, minutes, seconds] = match;
+  const total = Number(days ?? 0) * 1440 + Number(hours ?? 0) * 60 + Number(minutes ?? 0) + Number(seconds ?? 0) / 60;
+  if (total === 0 && !minutes && !hours && !days && !seconds) return null;
+  return Math.round(total);
+}
+function parseYield(value) {
+  const text = typeof value === "number" && Number.isFinite(value) ? String(value) : typeof value === "string" ? value.trim() : Array.isArray(value) ? String(value[0] ?? "").trim() : "";
+  if (!text) return { count: null, unit: null, text: "" };
+  const match = /^(\d+(?:[.,]\d+)?)\s*(.*)$/.exec(text);
+  if (!match) return { count: null, unit: null, text };
+  const count = Number(match[1].replace(",", "."));
+  const unit = (match[2] ?? "").trim() || null;
+  return { count: Number.isFinite(count) ? count : null, unit, text };
+}
+
+// src/marmiton/jsonld.ts
+var LD_JSON_BLOCK = /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+function extractJsonLdNodes(html) {
+  const nodes = [];
+  LD_JSON_BLOCK.lastIndex = 0;
+  let match;
+  while ((match = LD_JSON_BLOCK.exec(html)) !== null) {
+    const raw = match[1]?.trim();
+    if (!raw) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    for (const node of flatten(parsed)) nodes.push(node);
+  }
+  return nodes;
+}
+function flatten(value) {
+  if (Array.isArray(value)) return value.flatMap(flatten);
+  if (typeof value !== "object" || value === null) return [];
+  const node = value;
+  const graph = node["@graph"];
+  if (graph !== void 0) return flatten(graph);
+  return [node];
+}
+function hasType(node, type) {
+  if (typeof node !== "object" || node === null) return false;
+  const declared = node["@type"];
+  if (typeof declared === "string") return declared === type;
+  if (Array.isArray(declared)) return declared.includes(type);
+  return false;
+}
+function findNodeOfType(nodes, type) {
+  const found = nodes.find((node) => hasType(node, type));
+  return found ?? null;
+}
+function asString(value) {
+  if (typeof value === "string") return value.trim() || null;
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const found = asString(entry);
+      if (found) return found;
+    }
+  }
+  if (typeof value === "object" && value !== null) {
+    const url = value.url;
+    if (typeof url === "string") return url.trim() || null;
+    const name = value.name;
+    if (typeof name === "string") return name.trim() || null;
+  }
+  return null;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number(value.replace(",", "."));
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+function asStringList(value) {
+  if (typeof value === "string") return [value.trim()].filter(Boolean);
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const entry of value) {
+    if (typeof entry === "string") {
+      const text = entry.trim();
+      if (text) out.push(text);
+      continue;
+    }
+    if (typeof entry === "object" && entry !== null) {
+      const record = entry;
+      const text = asString(record.text) ?? asString(record.name);
+      if (text) out.push(text);
+    }
+  }
+  return out;
+}
+
+// src/marmiton/urls.ts
+var BASE_URL = "https://www.marmiton.org";
+var RECIPE_PATH_RE = /\/recettes\/recette[_-][a-z0-9%\-.]*?_(\d+)\.aspx/i;
+var ALLOWED_HOSTS = /* @__PURE__ */ new Set(["marmiton.org", "www.marmiton.org"]);
+function buildSearchUrl(query) {
+  const url = new URL(`${BASE_URL}/recettes/recherche.aspx`);
+  url.searchParams.set("aqt", query);
+  return url.toString();
+}
+function buildRecipeUrl(id) {
+  return `${BASE_URL}/recettes/recette_r_${id}.aspx`;
+}
+function isMarmitonHost(rawUrl) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return false;
+  return ALLOWED_HOSTS.has(parsed.hostname.toLowerCase());
+}
+function extractRecipeId(hrefOrUrl) {
+  let path = hrefOrUrl;
+  if (/^https?:\/\//i.test(hrefOrUrl)) {
+    if (!isMarmitonHost(hrefOrUrl)) return null;
+    path = new URL(hrefOrUrl).pathname;
+  }
+  const match = RECIPE_PATH_RE.exec(path);
+  return match?.[1] ?? null;
+}
+function resolveRecipeRef(input) {
+  if (input.id) {
+    if (!/^\d+$/.test(input.id)) {
+      throw invalidInput(
+        `"${input.id}" is not a Marmiton recipe id.`,
+        "Ids are digits only, as returned by search_recipes."
+      );
+    }
+    return { id: input.id, url: buildRecipeUrl(input.id) };
+  }
+  if (input.url) {
+    if (!isMarmitonHost(input.url)) {
+      throw invalidInput(
+        "Only marmiton.org URLs are accepted.",
+        "Pass the url returned by search_recipes, or use the numeric id instead."
+      );
+    }
+    const id = extractRecipeId(input.url);
+    if (!id) {
+      throw invalidInput(
+        "That Marmiton URL is not a recipe page.",
+        "Recipe pages look like https://www.marmiton.org/recettes/recette_tarte-aux-pommes_18588.aspx"
+      );
+    }
+    return { id, url: input.url };
+  }
+  throw invalidInput("Either 'id' or 'url' must be provided.");
+}
+function toAbsoluteUrl(href) {
+  return new URL(href, BASE_URL).toString();
+}
+
+// src/marmiton/parseRecipe.ts
+function parseRecipePage(html, options) {
+  const nodes = extractJsonLdNodes(html);
+  const node = findNodeOfType(nodes, "Recipe");
+  if (!node) {
+    throw parseFailure(options.url, "no schema.org Recipe node in the page");
+  }
+  const title = asString(node.name);
+  const ingredients = asStringList(node.recipeIngredient);
+  const steps = asStringList(node.recipeInstructions);
+  if (!title) throw parseFailure(options.url, "the Recipe node has no name");
+  if (ingredients.length === 0) {
+    throw parseFailure(options.url, "the Recipe node carries no ingredient list");
+  }
+  return {
+    id: options.id,
+    title,
+    url: asString(node.mainEntityOfPage) ?? options.url,
+    imageUrl: asString(node.image),
+    ingredients,
+    steps,
+    recipeYield: parseYield(node.recipeYield),
+    prepMinutes: parseIsoDuration(node.prepTime),
+    cookMinutes: parseIsoDuration(node.cookTime),
+    totalMinutes: parseIsoDuration(node.totalTime),
+    category: asString(node.recipeCategory),
+    author: asString(node.author),
+    rating: parseRating(node.aggregateRating),
+    nutrition: parseNutrition(node.nutrition)
+  };
+}
+function parseRating(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const record = value;
+  const ratingValue = asNumber(record.ratingValue);
+  if (ratingValue === null) return null;
+  return {
+    value: ratingValue,
+    count: asNumber(record.ratingCount) ?? asNumber(record.reviewCount),
+    best: asNumber(record.bestRating)
+  };
+}
+function parseNutrition(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const record = value;
+  const nutrition = {
+    calories: asString(record.calories),
+    protein: asString(record.proteinContent),
+    fat: asString(record.fatContent),
+    carbohydrate: asString(record.carbohydrateContent),
+    fiber: asString(record.fiberContent),
+    sodium: asString(record.sodiumContent),
+    servingSize: asString(record.servingSize)
+  };
+  const hasAny = Object.values(nutrition).some((entry) => entry !== null);
+  return hasAny ? nutrition : null;
+}
+function parseSearchPage(html, url) {
+  const nodes = extractJsonLdNodes(html);
+  const list = findNodeOfType(nodes, "ItemList");
+  if (!list) {
+    throw parseFailure(url, "no schema.org ItemList node on the search page");
+  }
+  const elements = list.itemListElement;
+  if (!Array.isArray(elements)) {
+    throw parseFailure(url, "the ItemList node carries no itemListElement array");
+  }
+  const results = [];
+  let skipped = 0;
+  for (const element of elements) {
+    if (typeof element !== "object" || element === null) {
+      skipped += 1;
+      continue;
+    }
+    const record = element;
+    const href = asString(record.url);
+    const title = asString(record.name);
+    const id = href ? extractRecipeId(href) : null;
+    if (!href || !title || !id) {
+      skipped += 1;
+      continue;
+    }
+    results.push({ id, title, url: toAbsoluteUrl(href), imageUrl: asString(record.image) });
+  }
+  if (results.length === 0 && elements.length > 0) {
+    throw parseFailure(url, `${elements.length} list entries but none could be read`);
+  }
+  if (skipped > 0) {
+    process.stderr.write(`[mcp-marmiton] skipped ${skipped} unreadable search entries on ${url}
+`);
+  }
+  return results;
+}
+
+// src/marmiton/client.ts
+var MarmitonClient = class {
+  config;
+  logger;
+  limiter;
+  cache;
+  fetchImpl;
+  constructor(options = {}) {
+    this.config = options.config ?? loadConfig();
+    this.logger = options.logger ?? createLogger(this.config.logLevel);
+    this.limiter = new RateLimiter({ minIntervalMs: this.config.minIntervalMs });
+    this.cache = new TtlLruCache(this.config.cacheMaxEntries, this.config.cacheTtlMs);
+    this.fetchImpl = options.fetchImpl;
+  }
+  /**
+   * Search recipes.
+   *
+   * One page only: Marmiton's robots.txt disallows the paginated form of this
+   * URL, so there is no page parameter to pass.
+   */
+  async search(query) {
+    const url = buildSearchUrl(query);
+    const { html, cached } = await this.fetchPage(url);
+    return { data: parseSearchPage(html, url), cached };
+  }
+  async getRecipe(ref) {
+    const { id, url } = resolveRecipeRef(ref);
+    const { html, cached } = await this.fetchPage(url);
+    return { data: parseRecipePage(html, { id, url }), cached };
+  }
+  async fetchPage(url) {
+    const hit = this.cache.get(url);
+    if (hit !== void 0) {
+      this.logger.debug(`cache hit ${url}`);
+      return { html: hit, cached: true };
+    }
+    const html = await fetchHtml(url, {
+      config: this.config,
+      limiter: this.limiter,
+      logger: this.logger,
+      ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
+    });
+    this.cache.set(url, html);
+    return { html, cached: false };
+  }
+};
+export {
+  MarmitonClient
+};
+//# sourceMappingURL=client.js.map