@nestr/mcp 0.1.72 → 0.1.89

package/build/help/articles.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Help-article integration. Sources `/help/articles/<slug>` URLs from the
+ * public nestr.io sitemap, exposes simple token-overlap search by slug, and
+ * fetches an article page lazily on demand (converting it to markdown so it
+ * fits in a tool response).
+ *
+ * The internal `nestr_help` topics in topics.ts are curated MCP-flavoured
+ * guidance. Articles are end-user UI docs. The tool routes between them:
+ * exact internal topic match first, then article search/fetch.
+ */
+export type ArticleIndexEntry = {
+    slug: string;
+    url: string;
+};
+export type ArticleSearchHit = ArticleIndexEntry & {
+    score: number;
+};
+export declare function _resetCaches(): void;
+/**
+ * Load (or return cached) the list of help-article slugs from the sitemap.
+ * Sitemap is plain XML with `<loc>...</loc>` entries; we only need the URLs,
+ * so a regex extract is cheaper than pulling in an XML parser.
+ */
+export declare function loadArticleIndex(): Promise<ArticleIndexEntry[]>;
+/**
+ * Token-overlap search against slug-as-words plus curated keywords. Slugs are
+ * descriptive (e.g. `building-your-org-structure-roles-circles`), so
+ * dash-to-space gives a usable signal without fetching every article's title.
+ * Exact substring matches score 1; a typo rescued by Levenshtein scores 0.5,
+ * so an exact hit always outranks a fuzzy one.
+ */
+export declare function searchArticleIndex(entries: ArticleIndexEntry[], query: string, limit?: number): ArticleSearchHit[];
+/**
+ * Fetch a single article and convert to a readable markdown payload. Cached
+ * per-slug for ARTICLE_TTL_MS. The conversion is intentionally lossy —
+ * Webflow output is noisy, and the LLM only needs the textual body.
+ */
+export declare function fetchArticleMarkdown(slug: string): Promise<{
+    slug: string;
+    url: string;
+    title: string;
+    description: string;
+    markdown: string;
+}>;
+/**
+ * Fetch just an article's title + description, for search-result snippets,
+ * without converting the whole body. Reuses a full-article or prior meta cache
+ * entry when one is fresh, and caches meta separately so repeated searches are
+ * cheap. Throws on a non-OK response — callers enrich best-effort and fall back
+ * to the bare slug on failure.
+ */
+export declare function fetchArticleMeta(slug: string): Promise<{
+    slug: string;
+    title: string;
+    description: string;
+}>;
+export type ArticleImage = {
+    url: string;
+    caption: string;
+    decorative: boolean;
+};
+/**
+ * Pull the in-body images out of converted article markdown as structured data
+ * so callers can surface screenshots as first-class items (some MCP hosts
+ * render them inline; text-only clients still get the caption + URL). SVGs are
+ * skipped — on these pages they're UI chrome/icons, not content. Dedupes by
+ * URL, preserves document order. Run this on the article body markdown so nav
+ * and marketing imagery (already cut by extractArticleBody) stays out.
+ *
+ * Each image is flagged `decorative` when it has no caption OR appears before
+ * the first content heading (the header/category-bar thumbnail at the top of an
+ * article). Decorative images are listed and remain addressable by index, but
+ * are never part of the default selection. "First content heading" is the second
+ * heading in the body — the first is the article title — so when a body has no
+ * sub-headings the position rule is skipped and only the caption test applies.
+ */
+export declare function extractImages(markdown: string): ArticleImage[];
+export type InlineArticleImage = ArticleImage & {
+    index: number;
+    data: string;
+    mimeType: string;
+};
+/** Clamp a caller-supplied maxImages to [1, MAX_INLINE_IMAGES_CAP], default 3. */
+export declare function clampMaxImages(max?: number): number;
+/**
+ * Decide which images (by index into `images`) to attach inline.
+ *
+ * - Explicit `indexes`: the caller picked specific entries from the numbered
+ *   list, so honour them verbatim — valid, de-duped, in the given order, with
+ *   NO cap (overrides maxImages and the default selection, so a decorative
+ *   image can still be attached on explicit request).
+ * - Default: the first `max` non-decorative (content) images in document order.
+ *   This skips the uncaptioned hero/avatar and any header thumbnail before the
+ *   first content heading; masthead/footer imagery is already gone because we
+ *   only see body markdown.
+ */
+export declare function selectImageIndexes(images: ArticleImage[], opts?: {
+    indexes?: number[];
+    max?: number;
+}): number[];
+/**
+ * Fetch a single image and return it as base64 + MIME type for an MCP `image`
+ * content block, or null if it can't be safely inlined (disallowed URL,
+ * non-image content, too large, or any network error). Wide images are
+ * downscaled to bound token cost. Best-effort by design — callers fall back to
+ * the text URL list. Bounded FIFO cache by URL (oldest entry evicted once the
+ * cap is reached).
+ */
+export declare function fetchImageAsBase64(url: string): Promise<{
+    data: string;
+    mimeType: string;
+} | null>;
+/**
+ * Fetch the selected article images (see selectImageIndexes) as inline base64
+ * blocks, carrying each image's index in the full list. Concurrent and
+ * best-effort — any that can't be inlined are dropped.
+ */
+export declare function collectArticleImages(images: ArticleImage[], opts?: {
+    indexes?: number[];
+    max?: number;
+}): Promise<InlineArticleImage[]>;
+/**
+ * Pull title + description from the article's JSON-LD `TechArticle` block
+ * when present (every article currently includes one). Falls back to
+ * `<title>` / `<meta name="description">` tags.
+ */
+export declare function extractArticleMeta(html: string): {
+    title: string;
+    description: string;
+};
+/**
+ * Best-effort extraction of the article body. We can't rely on a single
+ * named container on Webflow output, so we cut from the article's `<h1>`
+ * down to where chrome resumes (footer / nav). When the page has multiple
+ * `<h1>` elements (Webflow's hidden signup form puts one in before the
+ * article), pass `headlineHint` so we can pick the matching one.
+ */
+export declare function extractArticleBody(html: string, headlineHint?: string): string;
+/**
+ * Minimal HTML → markdown converter. Handles the elements that actually show
+ * up in the article body (headings, paragraphs, lists, links, emphasis,
+ * inline code, line breaks). Anything else is reduced to its text content.
+ * Not a general-purpose converter — just enough that the LLM can read it.
+ */
+export declare function htmlToMarkdown(html: string): string;
+//# sourceMappingURL=articles.d.ts.map

package/build/help/articles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"articles.d.ts","sourceRoot":"","sources":["../../src/help/articles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgBH,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAcrE,wBAAgB,YAAY,IAAI,IAAI,CAKnC;AAYD;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAmBrE;AAiDD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,EAAE,EAC5B,KAAK,EAAE,MAAM,EACb,KAAK,SAAK,GACT,gBAAgB,EAAE,CA4BpB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CA4BD;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAiBlH;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,EAAE,CAe9D;AAED,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EAAE,EACtB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,MAAM,EAAE,CAmBV;AA6DD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA4BxG;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,YAAY,EAAE,EACtB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9C,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAS/B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAgCvF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAoD9E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoDnD"}