ask-refined-element-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Refined Element, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+<!-- mcp-name: io.github.refined-element/ask-refined-element -->
+
+Part of [Refined Element](https://refinedelement.com) — an independent consultancy for Xperience by Kentico upgrades, AI-driven development, and agent-first marketing (GEO).
+
+# Ask Refined Element MCP Server
+
+An open-source MCP (Model Context Protocol) server that lets AI agents query Refined Element's knowledge pack: field-tested guidance on Xperience by Kentico upgrades, GEO (generative engine optimization), AI-driven development, Sentinel for Xperience by Kentico, and agent-ready CMS architecture.
+
+The knowledge pack is **authored once in Xperience by Kentico and served headless** — to humans on the website, to AI crawlers via `llms.txt`, and to agents through this MCP server. This server is one of those delivery surfaces, and a working example of the agent-ready CMS pattern the pack itself describes.
+
+Most of the pack is free — including priority consultation requests. Two knowledge items are premium, gated behind a single **L402 (Lightning) payment of 100 sats** — a demonstration of metered, pay-per-access content on the same content model.
+
+## What It Does
+
+Give your AI agent this server and it can:
+
+- **Search the knowledge pack** — ranked, answer-first summaries it can cite directly, across blog articles, FAQs, case studies, services, checklists, and premium playbooks on Kentico upgrades, GEO, AI development, Sentinel, and CMS architecture.
+- **Fetch a full checklist** — complete, ordered, actionable steps by slug (e.g. the GEO readiness checklist).
+- **Read the blog** — list recent Refined Element articles and read any one in full, with its HTML converted to clean text (headings, lists, and links preserved).
+- **Request a consultation** — send a message straight to Mike Rahel; set `priority: true` to flag it as urgent (free — no payment).
+- **Buy a premium playbook** — retrieve an L402-gated item: the tool returns the Lightning invoice on the first call, then the full content once the agent has paid.
+
+## Tools
+
+| Tool | Paid | What you get |
+|------|------|--------------|
+| `search_refined_element_knowledge` | Free | Ranked matches with answer-first summaries across articles, FAQs, case studies, services, checklists, and playbooks. Article hits point at `get_article`; premium hits are flagged with their price and the slug to buy them. |
+| `get_checklist` | Free | One full free checklist by slug — title, summary, topic, audience, and every ordered step. |
+| `list_articles` | Free | Recent blog articles, newest first — title, publish date, one-line summary, url, and the slug to read each in full. |
+| `get_article` | Free | One full blog article by slug — HTML converted to readable text (headings, lists, and links preserved), plus its canonical URL. |
+| `request_consultation` | Free | Send a consultation request to Mike Rahel. Set `priority: true` to flag it as urgent — still free, no payment. |
+| `get_paid_playbook` | 100 sats (L402) | One premium item by slug. First call returns a Lightning invoice + macaroon; a second call with the paid credential returns the full content. |
+
+### `search_refined_element_knowledge`
+
+Full-text search over the pack. Returns ranked matches, each with an answer-first summary you can cite directly or use to decide which item to fetch in full. Premium items return a summary and slug only — get their body with `get_paid_playbook`. Free checklists can be pulled in full with `get_checklist`.
+
+```json
+{
+  "query": "kentico upgrade risk",
+  "topic": "kentico-upgrades",       // optional filter
+  "audience": "decision-maker",       // optional filter
+  "limit": 5                          // optional, default 5, max 20
+}
+```
+
+`topic` and `audience` accept any string and are matched exactly against each result — the taxonomy is owned by the CMS, so new values keep working without a package upgrade. Known `topic` values today (examples): `kentico-upgrades`, `geo`, `ai-development`, `sentinel`, `cms-architecture`. Known `audience` values today (examples): `developer`, `marketer`, `decision-maker`, `agent`. Only `query` is required.
+
+### `get_checklist`
+
+Fetch one full free checklist by slug, e.g. `geo-readiness-checklist-basic`. Returns the complete ordered step list — each step with its one-line action and an explanatory sentence — ready to follow, quote, or hand to a user. If the slug is a premium checklist, the response points you to `get_paid_playbook`. Unknown slugs return a not-found result.
+
+```json
+{ "slug": "geo-readiness-checklist-basic" }
+```
+
+### `list_articles`
+
+List the most recent posts from the Refined Element blog, newest first. Each entry has its title, publish date, a one-line summary, the canonical URL, and the slug to read it in full with `get_article`.
+
+```json
+{ "limit": 10 }   // optional, default 10, max 50
+```
+
+### `get_article`
+
+Read one full blog article by slug (discover slugs with `list_articles` or `search_refined_element_knowledge`). Returns the title, publish date, summary, the complete body converted from HTML to readable text — headings, lists, and links preserved — and the canonical URL. Unknown slugs return a not-found result.
+
+```json
+{ "slug": "agent-ready-cms-xperience" }
+```
+
+### `request_consultation`
+
+Send a consultation request straight to Mike Rahel — for Xperience by Kentico upgrades, AI-driven development, or agent-first (GEO) work. The email is shape-checked locally (a quick `@`/length sanity check) and fully validated by the API.
+
+```json
+{
+  "name": "Ada Lovelace",
+  "email": "ada@example.com",
+  "message": "We need help upgrading a KX13 site to Xperience by Kentico.",
+  "company": "Analytical Engines Ltd",  // optional
+  "priority": false                      // optional; true = flag as urgent (free)
+}
+```
+
+Mike reads every request personally, so include enough context for him to act on it. Set `priority: true` to flag the request as urgent so Mike sees the urgency — priority is free, no payment required.
+
+### `get_paid_playbook` (L402-gated)
+
+Retrieve one premium item by slug, gated at 100 sats via L402. Discover the current premium items and their slugs with `search_refined_element_knowledge` — they are flagged `[PREMIUM]`. (Examples at the time of writing: `agent-ready-cms-checklist-full`, `kentico-upgrade-risk-triage` — the CMS owns the catalog, so this list can grow without a package release.)
+
+```json
+{
+  "slug": "kentico-upgrade-risk-triage",
+  "macaroon": "…",   // omit on the first call
+  "preimage": "…"     // omit on the first call
+}
+```
+
+See [The L402 payment flow](#the-l402-payment-flow) below.
+
+## Requirements
+
+- **Node.js ≥ 22.**
+- **The Ask Refined Element API (`/api/ask/*`) must be live at the configured base URL.** The default is the production site, `https://refinedelement.com`. If the API is not reachable there — for example while it is still being deployed, or when you run the site locally — point the server at the right host with the `ASK_RE_BASE_URL` environment variable (see [Development](#development)). When the base URL answers with an HTML page instead of API JSON, the tools report that the API is not deployed/reachable there rather than pretending content does not exist.
+
+## Quick Install
+
+Run it with no install:
+
+```bash
+npx -y ask-refined-element-mcp
+```
+
+## Claude Code
+
+```bash
+claude mcp add ask-refined-element -- npx -y ask-refined-element-mcp
+```
+
+Or add it to `.mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "ask-refined-element": {
+      "command": "npx",
+      "args": ["-y", "ask-refined-element-mcp"]
+    }
+  }
+}
+```
+
+## Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ask-refined-element": {
+      "command": "npx",
+      "args": ["-y", "ask-refined-element-mcp"]
+    }
+  }
+}
+```
+
+Config file locations:
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux:** `~/.config/claude/claude_desktop_config.json`
+
+No API key, wallet, or secret is needed to install or run this server — it calls only public endpoints. A Lightning wallet is needed only to unlock the two premium items (see below).
+
+## The L402 Payment Flow
+
+Two knowledge items are premium and gated with **L402** — the HTTP 402 "Payment Required" standard for pay-per-access over Lightning. `get_paid_playbook` handles both halves of the exchange:
+
+1. **Ask for the item.** Call `get_paid_playbook` with only the `slug`. The endpoint answers `402 Payment Required` with a Lightning **invoice** (100 sats) and a **macaroon**. The tool returns these as structured payment instructions — it does not error.
+2. **Pay the invoice.** Pay the Lightning invoice with any wallet that returns a payment **preimage**. The easiest path for an agent is the free [**Lightning Enable MCP server**](https://github.com/refined-element/lightning-enable-mcp) and its `pay_invoice` tool — connect a wallet via NWC or Strike ([docs.lightningenable.com](https://docs.lightningenable.com)) and it pays, tracks, and budgets automatically.
+3. **Unlock the content.** Call `get_paid_playbook` again with the **same slug** plus the `macaroon` from step 1 and the `preimage` from step 2. The tool sends `Authorization: L402 <macaroon>:<preimage>` and returns the full item.
+
+If a credential fails to verify, the tool returns a fresh challenge with the same guidance, so the agent can retry cleanly. Run both the Lightning Enable MCP and this server together and an agent can discover, pay for, and read a premium playbook end to end without a human in the loop.
+
+## Development
+
+Clone, install, build, and run the smoke tests:
+
+```bash
+git clone https://github.com/refined-element/ask-refined-element.git
+cd ask-refined-element
+npm install
+npm run build      # tsc → dist/
+npm test           # vitest — mocks fetch, asserts each tool + the 402 flow
+```
+
+Run against a local Ask Refined Element API instead of production with the `ASK_RE_BASE_URL` environment variable:
+
+```bash
+# Default is https://refinedelement.com
+ASK_RE_BASE_URL=http://localhost:23918 npx -y ask-refined-element-mcp
+
+# The local re-xbk app may serve the API on :23918 or :23917
+ASK_RE_BASE_URL=http://localhost:23917 node dist/index.js
+```
+
+In a client config, set it under `env`:
+
+```json
+{
+  "mcpServers": {
+    "ask-refined-element": {
+      "command": "node",
+      "args": ["/absolute/path/to/ask-refined-element/dist/index.js"],
+      "env": { "ASK_RE_BASE_URL": "http://localhost:23918" }
+    }
+  }
+}
+```
+
+`npm run dev` runs the TypeScript entry point directly via `tsx` without a build step.
+
+### Project structure
+
+```
+ask-refined-element/
+├── src/
+│   ├── index.ts    # stdio entry point (bin)
+│   ├── server.ts   # MCP server + tool registration (zod schemas)
+│   ├── tools.ts    # tool logic + response formatting
+│   ├── api.ts      # public HTTP client (10s timeout, clean error shaping)
+│   └── types.ts    # API response shapes
+├── test/
+│   └── tools.test.ts
+├── package.json
+├── tsconfig.json
+└── LICENSE
+```
+
+## Related Projects
+
+- [Lightning Enable MCP](https://github.com/refined-element/lightning-enable-mcp) — give your agent a Lightning wallet; pays L402 challenges (including this server's premium items) automatically.
+- [Lightning Enable](https://lightningenable.com) — infrastructure for agent commerce over Lightning.
+- [Lightning Enable Docs](https://docs.lightningenable.com) — wallet setup (NWC, Strike) and the full L402 guide.
+
+## Links
+
+- [Refined Element](https://refinedelement.com) — the consultancy, and the live knowledge pack.
+- [Sentinel for Xperience by Kentico](https://github.com/refined-element/xperience-community-sentinel) — the free, open-source Kentico health scanner referenced throughout the pack.
+
+## License
+
+MIT © Refined Element, LLC — see [LICENSE](LICENSE).

package/dist/api.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Thin HTTP client for the public Ask Refined Element API.
+ *
+ * The knowledge pack is authored in Xperience by Kentico and served headless;
+ * this client is how the MCP tools read it. Every method targets a PUBLIC
+ * endpoint — there are no secrets, credentials, or API keys anywhere in this
+ * server. The only auth this client ever sends is an L402 credential the agent
+ * itself supplies (macaroon + payment preimage) for the paid playbook endpoint.
+ *
+ * All methods resolve to a discriminated {@link HttpOutcome} and never throw:
+ * network failures and timeouts come back as `network-error` so tools can turn
+ * them into helpful text instead of a stack trace.
+ */
+import type { ContactRequest } from "./types.js";
+/**
+ * How long any single request — including reading the response body — is
+ * allowed to run before it is aborted.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** Default base URL — the production Refined Element site. */
+export declare const DEFAULT_BASE_URL = "https://refinedelement.com";
+/** Result of a single HTTP request. Never thrown — always returned. */
+export type HttpOutcome = {
+    kind: "ok";
+    status: number;
+    json: unknown;
+    headers: Headers;
+} | {
+    kind: "http-error";
+    status: number;
+    json: unknown | null;
+    text: string | null;
+    headers: Headers;
+}
+/**
+ * The host answered, but with an HTML page instead of API JSON — the
+ * `/api/ask` routes are not served at this base URL (e.g. the site's generic
+ * 404 page). Distinct from `http-error` so tools never translate it into
+ * "no item with slug X".
+ */
+ | {
+    kind: "api-unavailable";
+    status: number;
+    message: string;
+} | {
+    kind: "network-error";
+    message: string;
+};
+export interface AskReClientOptions {
+    /** Base URL of the Ask Refined Element API. Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to {@link DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Injectable fetch, primarily for tests. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+export declare class AskReClient {
+    readonly baseUrl: string;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options?: AskReClientOptions);
+    /** GET /api/ask/knowledge?q={query} */
+    searchKnowledge(query: string): Promise<HttpOutcome>;
+    /** GET /api/ask/checklists/{slug} */
+    getChecklist(slug: string): Promise<HttpOutcome>;
+    /**
+     * GET /api/ask/playbooks/{slug}
+     *
+     * Without a credential the endpoint answers 402 with an L402 challenge.
+     * With `Authorization: L402 <macaroon>:<preimage>` it returns the full item.
+     */
+    getPlaybook(slug: string, credential?: {
+        macaroon: string;
+        preimage: string;
+    }): Promise<HttpOutcome>;
+    /** GET /api/ask/articles?limit={limit} */
+    listArticles(limit: number): Promise<HttpOutcome>;
+    /** GET /api/ask/articles/{slug} */
+    getArticle(slug: string): Promise<HttpOutcome>;
+    /** POST /api/ask/contact — free-lane consultation request. */
+    submitContact(body: ContactRequest): Promise<HttpOutcome>;
+    /**
+     * POST /api/ask/contact/priority — free priority-flagged consultation.
+     *
+     * Same free delivery as {@link submitContact}, but the API tags the inquiry
+     * with a priority subject prefix so the flagged urgency is visible. Returns
+     * `{ status: "received", priority: true }`.
+     */
+    submitPriorityContact(body: ContactRequest): Promise<HttpOutcome>;
+    /** GET wrapper over {@link request}. */
+    private get;
+    /** POST wrapper over {@link request}: sends `body` as JSON. */
+    private post;
+    /**
+     * Core request helper: applies the timeout to BOTH the headers phase and the
+     * body read, parses the body, never throws. Shared by GET and POST so both
+     * verbs inherit the same timeout-covers-body, HTML-detection, null-body, and
+     * clean-error-shaping behavior.
+     */
+    private request;
+}

package/dist/api.js

@@ -0,0 +1,212 @@
+/**
+ * Thin HTTP client for the public Ask Refined Element API.
+ *
+ * The knowledge pack is authored in Xperience by Kentico and served headless;
+ * this client is how the MCP tools read it. Every method targets a PUBLIC
+ * endpoint — there are no secrets, credentials, or API keys anywhere in this
+ * server. The only auth this client ever sends is an L402 credential the agent
+ * itself supplies (macaroon + payment preimage) for the paid playbook endpoint.
+ *
+ * All methods resolve to a discriminated {@link HttpOutcome} and never throw:
+ * network failures and timeouts come back as `network-error` so tools can turn
+ * them into helpful text instead of a stack trace.
+ */
+/**
+ * How long any single request — including reading the response body — is
+ * allowed to run before it is aborted.
+ */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/** Default base URL — the production Refined Element site. */
+export const DEFAULT_BASE_URL = "https://refinedelement.com";
+export class AskReClient {
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    /** GET /api/ask/knowledge?q={query} */
+    searchKnowledge(query) {
+        const path = `/api/ask/knowledge?q=${encodeURIComponent(query)}`;
+        return this.get(path);
+    }
+    /** GET /api/ask/checklists/{slug} */
+    getChecklist(slug) {
+        return this.get(`/api/ask/checklists/${encodeURIComponent(slug)}`);
+    }
+    /**
+     * GET /api/ask/playbooks/{slug}
+     *
+     * Without a credential the endpoint answers 402 with an L402 challenge.
+     * With `Authorization: L402 <macaroon>:<preimage>` it returns the full item.
+     */
+    getPlaybook(slug, credential) {
+        const headers = {};
+        if (credential) {
+            headers.Authorization = `L402 ${credential.macaroon}:${credential.preimage}`;
+        }
+        return this.get(`/api/ask/playbooks/${encodeURIComponent(slug)}`, headers);
+    }
+    /** GET /api/ask/articles?limit={limit} */
+    listArticles(limit) {
+        return this.get(`/api/ask/articles?limit=${encodeURIComponent(String(limit))}`);
+    }
+    /** GET /api/ask/articles/{slug} */
+    getArticle(slug) {
+        return this.get(`/api/ask/articles/${encodeURIComponent(slug)}`);
+    }
+    /** POST /api/ask/contact — free-lane consultation request. */
+    submitContact(body) {
+        return this.post("/api/ask/contact", body);
+    }
+    /**
+     * POST /api/ask/contact/priority — free priority-flagged consultation.
+     *
+     * Same free delivery as {@link submitContact}, but the API tags the inquiry
+     * with a priority subject prefix so the flagged urgency is visible. Returns
+     * `{ status: "received", priority: true }`.
+     */
+    submitPriorityContact(body) {
+        return this.post("/api/ask/contact/priority", body);
+    }
+    /** GET wrapper over {@link request}. */
+    get(path, headers = {}) {
+        return this.request("GET", path, { headers });
+    }
+    /** POST wrapper over {@link request}: sends `body` as JSON. */
+    post(path, body, headers = {}) {
+        return this.request("POST", path, { headers, body });
+    }
+    /**
+     * Core request helper: applies the timeout to BOTH the headers phase and the
+     * body read, parses the body, never throws. Shared by GET and POST so both
+     * verbs inherit the same timeout-covers-body, HTML-detection, null-body, and
+     * clean-error-shaping behavior.
+     */
+    async request(method, path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            let res;
+            try {
+                const init = {
+                    method,
+                    headers: {
+                        Accept: "application/json",
+                        ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                        ...(options.headers ?? {}),
+                    },
+                    signal: controller.signal,
+                };
+                if (options.body !== undefined) {
+                    init.body = JSON.stringify(options.body);
+                }
+                res = await this.fetchImpl(url, init);
+            }
+            catch (err) {
+                if (isAborted(controller, err)) {
+                    return {
+                        kind: "network-error",
+                        message: `Timed out after ${this.timeoutMs / 1000}s reaching ${this.baseUrl}. The API may be slow or unreachable — try again shortly.`,
+                    };
+                }
+                const detail = err instanceof Error ? err.message : String(err);
+                return {
+                    kind: "network-error",
+                    message: `Could not reach the Ask Refined Element API at ${this.baseUrl} (${detail}).`,
+                };
+            }
+            // The body read stays under the same timeout: a server that sends
+            // headers and then stalls (or trickles) the body must not hang the tool
+            // call forever. Racing against the abort signal also covers bodies that
+            // are not tied to the fetch signal (e.g. injected test responses).
+            let parsed;
+            const bodyRead = readBody(res);
+            // If the abort wins the race, handle the late body-read rejection so it
+            // never surfaces as an unhandled promise rejection.
+            bodyRead.catch(() => { });
+            try {
+                parsed = await Promise.race([bodyRead, rejectOnAbort(controller.signal)]);
+            }
+            catch (err) {
+                if (isAborted(controller, err)) {
+                    return {
+                        kind: "network-error",
+                        message: `Timed out after ${this.timeoutMs / 1000}s reading the response from ${this.baseUrl}. The API may be slow or unreachable — try again shortly.`,
+                    };
+                }
+                parsed = { json: null, text: null };
+            }
+            // An HTML page where API JSON belongs means the /api/ask routes are not
+            // served at this base URL at all (e.g. the site's generic 404 page, or a
+            // fallback page on 200) — NOT that a specific item is missing.
+            if (parsed.json === null && isHtmlBody(res, parsed.text) && (res.status === 404 || res.ok)) {
+                return {
+                    kind: "api-unavailable",
+                    status: res.status,
+                    message: `The Ask Refined Element API does not appear to be deployed or reachable at ${this.baseUrl} — ` +
+                        `the server answered HTTP ${res.status} with an HTML page instead of API JSON. ` +
+                        `If you are running the API locally, set the ASK_RE_BASE_URL environment variable to its base URL ` +
+                        `(e.g. http://localhost:23918).`,
+                };
+            }
+            if (res.ok) {
+                return { kind: "ok", status: res.status, json: parsed.json, headers: res.headers };
+            }
+            return {
+                kind: "http-error",
+                status: res.status,
+                json: parsed.json,
+                text: parsed.text,
+                headers: res.headers,
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Reads a response body once, returning parsed JSON when possible plus raw
+ * text. May reject (e.g. when the read is aborted mid-stream) — the caller
+ * shapes that into a clean outcome.
+ */
+async function readBody(res) {
+    const raw = await res.text();
+    if (!raw) {
+        return { json: null, text: null };
+    }
+    try {
+        return { json: JSON.parse(raw), text: raw };
+    }
+    catch {
+        return { json: null, text: raw };
+    }
+}
+/** A promise that rejects with an AbortError as soon as the signal aborts. */
+function rejectOnAbort(signal) {
+    return new Promise((_resolve, reject) => {
+        const abort = () => reject(new DOMException("The response body read was aborted", "AbortError"));
+        if (signal.aborted) {
+            abort();
+            return;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+/** True when the error (or the request's own controller) indicates our timeout abort. */
+function isAborted(controller, err) {
+    return controller.signal.aborted || (err instanceof Error && err.name === "AbortError");
+}
+/** True when the response body is an HTML document rather than API JSON. */
+function isHtmlBody(res, text) {
+    const contentType = res.headers.get("content-type")?.toLowerCase() ?? "";
+    if (contentType.includes("text/html")) {
+        return true;
+    }
+    return Boolean(text && text.trimStart().startsWith("<"));
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * ask-refined-element-mcp — stdio entry point.
+ *
+ * Boots the MCP server over stdio. The knowledge pack is authored in Xperience
+ * by Kentico and served headless; this process is one of its delivery surfaces.
+ *
+ * Configuration (all optional, all non-secret):
+ *   ASK_RE_BASE_URL  Base URL of the Ask Refined Element API.
+ *                    Default: https://refinedelement.com
+ *                    Local dev: http://localhost:23918 (or :23917)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * ask-refined-element-mcp — stdio entry point.
+ *
+ * Boots the MCP server over stdio. The knowledge pack is authored in Xperience
+ * by Kentico and served headless; this process is one of its delivery surfaces.
+ *
+ * Configuration (all optional, all non-secret):
+ *   ASK_RE_BASE_URL  Base URL of the Ask Refined Element API.
+ *                    Default: https://refinedelement.com
+ *                    Local dev: http://localhost:23918 (or :23917)
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+async function main() {
+    const baseUrl = process.env.ASK_RE_BASE_URL?.trim() || undefined;
+    const server = createServer({ baseUrl });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is reserved for the MCP protocol stream.
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} ready (base URL: ${baseUrl ?? "https://refinedelement.com"}).`);
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Fatal: ${message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAEjE,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,gEAAgE;IAChE,OAAO,CAAC,KAAK,CACX,GAAG,WAAW,KAAK,cAAc,qBAAqB,OAAO,IAAI,4BAA4B,IAAI,CAClG,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP server wiring for Ask Refined Element.
+ *
+ * Registers six tools over a shared {@link AskReClient}. Tool descriptions
+ * are written for agent consumption (what you get, when to use it) and mirror
+ * the product's Agent Endpoints spec. The heavy lifting lives in tools.ts.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type AskReClientOptions } from "./api.js";
+export declare const SERVER_NAME = "ask-refined-element";
+export declare const SERVER_VERSION = "0.1.0";
+export declare function createServer(clientOptions?: AskReClientOptions): McpServer;