@finrock/mcp 0.0.0-stage → 1.0.0

package/dist/api/tools.js

@@ -0,0 +1,300 @@
+import { z } from "zod";
+import { errorMessage, FinrockApiError } from "./client.js";
+export function apiToolMode(env = process.env) {
+    const on = (v) => /^(1|true|yes)$/i.test(v ?? "");
+    return { readOnly: on(env.FINROCK_READ_ONLY), enableSensitive: on(env.FINROCK_ENABLE_SENSITIVE_TOOLS) };
+}
+export function describeMode(opts) {
+    if (opts.readOnly)
+        return "read-only (FINROCK_READ_ONLY is set)";
+    if (opts.enableSensitive)
+        return "full access, including tools that move funds";
+    return "read and create; tools that move funds or change security settings are disabled until FINROCK_ENABLE_SENSITIVE_TOOLS=true";
+}
+const asset = z.string().min(1).describe("Asset name from Supported Assets, e.g. BTC, ETH, USDT_TRX");
+const json = (v) => ({ content: [{ type: "text", text: JSON.stringify(v ?? null, null, 2) }] });
+function errorResult(err) {
+    let msg = errorMessage(err);
+    if (err instanceof FinrockApiError) {
+        if (err.status === 401)
+            msg += "\nCheck FINROCK_API_KEY, that the uploaded public key matches FINROCK_PRIVATE_KEY, and that this machine's clock is correct.";
+        if (err.status === 403)
+            msg += "\nThe API user lacks permission for this action, or this IP is not whitelisted for the key.";
+        if (err.body.includes("DUPLICATE_SEQUENCE_ID"))
+            msg += "\nA transaction with this sequence_id already exists, so nothing was sent again. Find it with list_transactions.";
+        if (err.status === 429)
+            msg += `\nRate limited${err.retryAfter ? `; the window resets at ${err.retryAfter}` : ""}. Wait before retrying.`;
+    }
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+export function registerApiTools(server, api, opts = {}) {
+    const registered = [];
+    function tool(name, tier, meta, run) {
+        if (tier === "write" && opts.readOnly)
+            return;
+        if (tier === "sensitive" && (opts.readOnly || !opts.enableSensitive))
+            return;
+        server.registerTool(name, {
+            title: meta.title,
+            description: meta.description,
+            inputSchema: meta.inputSchema,
+            annotations: {
+                readOnlyHint: tier === "read",
+                destructiveHint: tier === "sensitive" || meta.destructive === true,
+                idempotentHint: tier === "read" || meta.idempotent === true,
+                openWorldHint: true,
+            },
+        }, 
+        // The SDK infers handler args from the schema; the cast keeps this generic helper simple.
+        (async (args) => {
+            try {
+                return json(await run(args));
+            }
+            catch (err) {
+                return errorResult(err);
+            }
+        }));
+        registered.push(name);
+    }
+    // ---- Wallets and addresses -------------------------------------------------
+    tool("list_wallets", "read", {
+        title: "List wallets",
+        description: "Balances, frozen state and auto-forwarding settings for the account's wallets.",
+        inputSchema: { asset: asset.optional() },
+    }, (a) => api.get("/dac/v1/wallets", { asset: a.asset }));
+    tool("list_addresses", "read", {
+        title: "List deposit addresses",
+        description: "Deposit addresses for one asset with balances, labels and omnibus/auto-refill settings. Filter by label to find a customer's address.",
+        inputSchema: {
+            asset,
+            label: z.string().optional(),
+            address: z.string().optional(),
+            index: z.string().optional().describe("Address index, e.g. '0'"),
+        },
+    }, (a) => api.get("/dac/v1/addresses", { asset: a.asset, label: a.label, address: a.address, index: a.index }));
+    tool("validate_address", "read", {
+        title: "Validate an address",
+        description: "Check an address (and destination tag for XRP/XLM) is valid for an asset before sending to it.",
+        inputSchema: { asset, address: z.string().min(1), address_tag: z.string().optional() },
+    }, (a) => api.get("/dac/v1/validate-address", { asset: a.asset, address: a.address, address_tag: a.address_tag }));
+    tool("create_wallet", "write", {
+        title: "Create a wallet",
+        description: "Provision the MPC wallet for an asset. Only one wallet per asset per sub-account; call list_wallets first.",
+        inputSchema: { asset },
+    }, (a) => api.post("/dac/v1/wallet", { asset: a.asset }));
+    tool("create_address", "write", {
+        title: "Create a deposit address",
+        description: "Generate a new deposit address. Use the label for your customer or purpose so deposits can be reconciled.",
+        inputSchema: {
+            asset,
+            label: z.string().min(1).describe("e.g. customer-42"),
+            omnibus: z.boolean().default(false).describe("true adds the address to the shared omnibus pool; false keeps it isolated"),
+            auto_refill: z.boolean().default(false).describe("Top up gas from the Gas Tank automatically (always on for omnibus)"),
+        },
+    }, (a) => api.post("/dac/v1/generate-address", a));
+    tool("update_address", "write", {
+        title: "Update a deposit address",
+        description: "Change an address's label, omnibus membership or gas auto-refill. Omitted fields stay unchanged.",
+        inputSchema: {
+            asset,
+            address: z.string().min(1),
+            address_tag: z.string().default("").describe("Destination tag/memo; empty for chains without tags"),
+            label: z.string().optional(),
+            omnibus: z.boolean().optional(),
+            auto_refill: z.boolean().optional(),
+        },
+        idempotent: true,
+    }, (a) => api.patch("/dac/v1/address", dropUndefined(a)));
+    tool("generate_xrp_destination_tag", "write", {
+        title: "Generate an XRP destination tag",
+        description: "Create a new XRP destination tag to route deposits to a customer on a shared XRP address.",
+        inputSchema: {},
+    }, () => api.get("/dac/v1/xrp-dt-memo"));
+    // ---- Invoices --------------------------------------------------------------
+    tool("create_invoice", "write", {
+        title: "Create a payment invoice",
+        description: "Create a hosted crypto invoice. crypto.asset_id (the coin to collect) is required; price it with fiat (converted to the coin) or crypto.amount. Returns payment_url to send the payer to, plus the deposit address and expiry. Statuses: Pending, Processing, Paid, Expired, Failed, Cancelled, Refunded.",
+        inputSchema: {
+            memo: z.string().min(1).describe("Your reference, e.g. an order ID; used to find the invoice later"),
+            fiat: z.object({ asset_id: z.string().describe("USD, EUR, GBP, AED…"), amount: z.number().positive() }).optional(),
+            crypto: z
+                .object({ asset_id: z.string().min(1).describe("e.g. USDT_TRX"), amount: z.number().positive().optional() })
+                .describe("The coin to collect, and optionally its amount when not pricing in fiat"),
+            payer: z
+                .object({
+                name: z.string().optional(),
+                email: z.string().optional(),
+                mobile: z.string().optional(),
+                country_code: z.string().optional(),
+            })
+                .optional(),
+            ipn_url: z.string().url().optional().describe("URL notified when the payment status changes"),
+            success_url: z.string().url().optional(),
+            failed_url: z.string().url().optional(),
+        },
+    }, async (a) => {
+        if (!a.fiat && a.crypto.amount === undefined)
+            throw new Error("Give a price: fiat, or crypto.amount.");
+        return api.post("/dac/v1/invoice", dropUndefined(a));
+    });
+    tool("list_invoices", "read", {
+        title: "List invoices",
+        description: "Find invoices by ID or memo and check their payment status. An unknown ID or memo returns INVOICE_NOT_FOUND.",
+        inputSchema: { id: z.string().optional(), memo: z.string().optional() },
+    }, (a) => api.get("/dac/v1/invoice", { id: a.id, memo: a.memo }));
+    // ---- Transactions and fees -------------------------------------------------
+    tool("list_transactions", "read", {
+        title: "List transactions",
+        description: "Deposits, withdrawals and sweeps with status, confirmations, fees and explorer links. All filters optional.",
+        inputSchema: {
+            id: z.string().optional().describe("Finrock transaction ID or on-chain hash"),
+            asset: z.string().optional(),
+            status: z.string().optional().describe("e.g. Pending, Success, Failed"),
+            memo: z.string().optional(),
+            source_type: z.string().optional(),
+            source_id: z.string().optional(),
+            dest_type: z.string().optional(),
+            dest_id: z.string().optional(),
+            after: z.number().int().optional().describe("Unix seconds"),
+            before: z.number().int().optional().describe("Unix seconds"),
+            page: z.number().int().min(1).optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+    }, (a) => api.get("/dac/v1/transactions", a));
+    tool("estimate_fee", "read", {
+        title: "Estimate a network fee",
+        description: "Estimate the network fee for a transfer at a fee rate (get rates from get_network_fee_rates). Units: Sat/Byte for UTXO, GWei for EVM, Sun for TRX, Drop for XRP, Stroop for XLM, Lovelace for ADA, Lamport for SOL.",
+        inputSchema: {
+            asset,
+            fee_rate: z.number().positive(),
+            amount: z.number().positive().optional().describe("Required for UTXO chains (BTC, LTC, DASH, DOGE, BCH)"),
+        },
+    }, (a) => api.get("/dac/v1/estimate-fee", a));
+    tool("get_network_fee_rates", "read", {
+        title: "Get network fee rates",
+        description: "Current Slow/Normal/Fast fee rates for an asset's network.",
+        inputSchema: { asset },
+    }, (a) => api.get("/dac/v1/network-fee-rates", { asset: a.asset }));
+    tool("create_transaction", "sensitive", {
+        title: "Send a transaction",
+        description: "MOVES FUNDS. Withdraw to an external address, move between sub-accounts, or transfer to/from a connected exchange. Confirm the asset, amount and destination with the user first and validate external addresses with validate_address. Track the result with list_transactions.",
+        inputSchema: {
+            asset,
+            amount: z.number().positive().describe("Native units, up to 8 decimals; ignored when max_amount is true"),
+            source_type: z.enum(["INTERNAL", "EXCHANGE"]),
+            source_id: z.string().optional().describe("Address/label to spend from, or exchange name when source_type is EXCHANGE"),
+            source_tag: z.string().optional(),
+            destination_type: z.enum(["EXTERNAL", "INTERNAL", "SUBACCOUNT", "EXCHANGE"]),
+            destination_id: z.string().min(1).describe("Address, label, sub-account or exchange name"),
+            destination_tag: z.string().optional().describe("Required for XRP/XLM destinations that use tags"),
+            sequence_id: z
+                .string()
+                .min(1)
+                .describe("Unique idempotency key (e.g. your payout ID). Reusing it fails with DUPLICATE_SEQUENCE_ID instead of paying twice."),
+            memo: z.string().optional(),
+            max_amount: z.boolean().optional().describe("Send the whole balance minus fees"),
+            aml_cid: z.string().optional().describe("Your customer ID; required when AML screening is on"),
+        },
+    }, (a) => api.post("/dac/v1/transaction", dropUndefined(a)));
+    tool("bump_fee", "sensitive", {
+        title: "Speed up a pending transaction",
+        description: "Raise the fee rate of a pending transaction. Spends more on fees.",
+        inputSchema: { txn_id: z.string().min(1), fee_rate: z.number().positive().describe("New rate in the chain's fee unit") },
+    }, (a) => api.post("/dac/v1/bump-fee", a));
+    tool("sweep_address", "sensitive", {
+        title: "Sweep an address into the omnibus wallet",
+        description: "Move the whole balance of a non-omnibus deposit address into the omnibus wallet (uses network fees; EVM and TRON need a funded Gas Tank).",
+        inputSchema: { asset, address: z.string().min(1) },
+    }, (a) => api.post("/dac/v1/invoke-sweep", a));
+    tool("update_wallet", "sensitive", {
+        title: "Freeze or configure a wallet",
+        description: "Freeze/unfreeze a wallet or set auto-forwarding of incoming funds to an external address (forwarding moves funds; addresses on this account are rejected with INTERNAL_DESTINATION_NOT_ALLOWED). Pass forwarding: null to remove forwarding.",
+        inputSchema: {
+            asset,
+            is_frozen: z.boolean().optional(),
+            forwarding: z
+                .object({ address: z.string().min(1), frequency: z.enum(["Nightly", "RealTime"]).optional() })
+                .nullable()
+                .optional(),
+        },
+    }, (a) => api.patch("/dac/v1/wallet", dropUndefined(a)));
+    // ---- Gas tanks -------------------------------------------------------------
+    tool("list_gas_tanks", "read", {
+        title: "List gas tanks",
+        description: "Gas tank addresses, minimum-balance alerts and status per network.",
+        inputSchema: {},
+    }, () => api.get("/dac/v1/gas-tanks"));
+    tool("get_gas_tank_balance", "read", {
+        title: "Get gas tank balance",
+        description: "Native-token balance (and USD value) of a gas tank, e.g. ETH, BNB, POL, TRX.",
+        inputSchema: { asset: z.string().min(1).describe("Gas tank asset from list_gas_tanks") },
+    }, (a) => api.get(`/dac/v1/gas-tank-bal/${encodeURIComponent(a.asset)}`));
+    tool("get_prepaid_fee", "read", {
+        title: "Get prepaid fee account",
+        description: "Prepaid platform-fee balance and the fee structure of the subscription tier.",
+        inputSchema: {},
+    }, () => api.get("/dac/v1/prepaid-fee"));
+    // ---- Exchanges -------------------------------------------------------------
+    tool("list_exchange_accounts", "read", {
+        title: "List exchange connections",
+        description: "Supported exchanges (Binance, Coinbase, OKX, KuCoin, Bybit), whether each is connected, and send/receive support.",
+        inputSchema: {},
+    }, () => api.get("/dac/v1/exchange-accounts"));
+    tool("get_exchange_balance", "read", {
+        title: "Get exchange balance",
+        description: "Asset balances on a connected exchange.",
+        inputSchema: { exchange: z.string().min(1).describe("e.g. Binance") },
+    }, (a) => api.get("/dac/v1/exchange-balance", { exchange: a.exchange }));
+    // ---- AML -------------------------------------------------------------------
+    tool("get_aml_status", "read", {
+        title: "Get AML configuration",
+        description: "Current AML screening provider, risk levels and whether deposits/withdrawals are screened.",
+        inputSchema: {},
+    }, () => api.get("/dac/v1/aml"));
+    tool("list_frozen_addresses", "read", {
+        title: "List AML-frozen addresses",
+        description: "Addresses frozen by AML screening, with the reason.",
+        inputSchema: {},
+    }, () => api.get("/dac/v1/frozen-addresses"));
+    tool("configure_aml", "sensitive", {
+        title: "Configure AML screening",
+        description: "Change AML provider, provider token, blocking risk levels and what is screened. Changes compliance controls.",
+        inputSchema: {
+            provider: z.enum(["Chainalysis", "Cipertrace", "AMLBot"]),
+            aml_token: z.string().min(1).describe("The provider's API key"),
+            aml_risk_levels: z.string().default("SEVERE,HIGH").describe("Comma-separated: SEVERE, HIGH, MEDIUM, LOW"),
+            aml_deposit: z.boolean().default(true),
+            aml_withdrawal: z.boolean().default(true),
+        },
+    }, (a) => api.post("/dac/v1/aml", a));
+    tool("unfreeze_address", "sensitive", {
+        title: "Unfreeze an AML-frozen address",
+        description: "Clear an address frozen by AML screening so it can transact again. Overrides a compliance hold.",
+        inputSchema: { asset, address: z.string().min(1), address_tag: z.string().optional() },
+    }, (a) => api.post("/dac/v1/unfreeze-address", dropUndefined(a)));
+    // ---- TRON resources ----------------------------------------------------------
+    const tronResource = {
+        address: z.string().min(1).describe("Tron address"),
+        resource: z.enum(["ENERGY", "BANDWIDTH"]).default("ENERGY"),
+        amount: z.number().positive().describe("TRX amount"),
+    };
+    tool("stake_trx", "sensitive", {
+        title: "Stake TRX for energy or bandwidth",
+        description: "Lock TRX to obtain ENERGY or BANDWIDTH for a Tron address. Staked TRX stays locked until unstaked and released.",
+        inputSchema: tronResource,
+    }, (a) => api.post("/dac/v1/stake", { asset: "TRX", ...a }));
+    tool("unstake_trx", "sensitive", {
+        title: "Unstake TRX",
+        description: "Start the unstaking cooldown for staked TRX. Afterwards call release_unstaked_trx to make it spendable.",
+        inputSchema: tronResource,
+    }, (a) => api.post("/dac/v1/unstake", { asset: "TRX", ...a }));
+    tool("release_unstaked_trx", "sensitive", {
+        title: "Release unstaked TRX",
+        description: "Return TRX whose unstaking cooldown has ended to the available balance.",
+        inputSchema: { address: z.string().min(1).describe("Tron address that unstaked TRX") },
+    }, (a) => api.post("/dac/v1/release-unstaked", { asset: "TRX", address: a.address }));
+    return registered;
+}
+function dropUndefined(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}

package/dist/docs.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Live client for the Finrock documentation site.
+ *
+ * The docs are published with an llms.txt index and a raw Markdown copy of every
+ * page (`<page>.md`), so the server always serves the current docs instead of a
+ * snapshot baked into the build.
+ */
+export interface DocPage {
+    title: string;
+    /** Path relative to the docs root, without extension, e.g. `guides/webhooks`. */
+    path: string;
+    /** Top-level group derived from the path, e.g. `guides`, `api-reference`. */
+    section: string;
+    description: string;
+    url: string;
+}
+export interface SearchHit extends DocPage {
+    score: number;
+    snippet: string;
+}
+export interface DocsClientOptions {
+    baseUrl?: string;
+    /** How long fetched pages and the index stay cached. */
+    ttlMs?: number;
+    fetch?: typeof fetch;
+    /** Per-request timeout. */
+    timeoutMs?: number;
+}
+export declare const DEFAULT_DOCS_URL = "https://apidocs.finrock.io";
+export declare class DocsClient {
+    readonly baseUrl: string;
+    private readonly ttlMs;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private index?;
+    private pages;
+    private inflight;
+    constructor(opts?: DocsClientOptions);
+    listPages(): Promise<DocPage[]>;
+    /**
+     * Fetch one page as Markdown. Accepts `guides/webhooks`, `/guides/webhooks.md`
+     * or a full docs URL. Anything outside the docs host is rejected.
+     */
+    readPage(ref: string): Promise<{
+        path: string;
+        url: string;
+        markdown: string;
+    }>;
+    /**
+     * Rank pages for a free-text query. Titles and descriptions always count;
+     * page bodies count too when `fullText` is set (fetched in parallel and cached).
+     */
+    search(query: string, opts?: {
+        limit?: number;
+        fullText?: boolean;
+    }): Promise<SearchHit[]>;
+    normalizePath(ref: string): string;
+    private get;
+}
+/** Parse the `- [Title](url): description` lines of an llms.txt file. */
+export declare function parseLlmsTxt(text: string, baseUrl: string): DocPage[];

package/dist/docs.js

@@ -0,0 +1,190 @@
+/**
+ * Live client for the Finrock documentation site.
+ *
+ * The docs are published with an llms.txt index and a raw Markdown copy of every
+ * page (`<page>.md`), so the server always serves the current docs instead of a
+ * snapshot baked into the build.
+ */
+export const DEFAULT_DOCS_URL = "https://apidocs.finrock.io";
+export class DocsClient {
+    baseUrl;
+    ttlMs;
+    timeoutMs;
+    fetchImpl;
+    index;
+    pages = new Map();
+    inflight = new Map();
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_DOCS_URL).replace(/\/+$/, "");
+        this.ttlMs = opts.ttlMs ?? 60 * 60 * 1000;
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+        this.fetchImpl = opts.fetch ?? fetch;
+    }
+    async listPages() {
+        if (this.index && this.index.expires > Date.now())
+            return this.index.value;
+        const text = await this.get(`${this.baseUrl}/llms.txt`);
+        const pages = parseLlmsTxt(text, this.baseUrl);
+        if (pages.length === 0)
+            throw new Error("Finrock docs index (llms.txt) contained no pages");
+        this.index = { value: pages, expires: Date.now() + this.ttlMs };
+        return pages;
+    }
+    /**
+     * Fetch one page as Markdown. Accepts `guides/webhooks`, `/guides/webhooks.md`
+     * or a full docs URL. Anything outside the docs host is rejected.
+     */
+    async readPage(ref) {
+        const path = this.normalizePath(ref);
+        const url = `${this.baseUrl}/${path}.md`;
+        const cached = this.pages.get(path);
+        if (cached && cached.expires > Date.now())
+            return { path, url, markdown: cached.value };
+        let pending = this.inflight.get(path);
+        if (!pending) {
+            pending = this.get(url).finally(() => this.inflight.delete(path));
+            this.inflight.set(path, pending);
+        }
+        const markdown = await pending;
+        this.pages.set(path, { value: markdown, expires: Date.now() + this.ttlMs });
+        return { path, url, markdown };
+    }
+    /**
+     * Rank pages for a free-text query. Titles and descriptions always count;
+     * page bodies count too when `fullText` is set (fetched in parallel and cached).
+     */
+    async search(query, opts = {}) {
+        const limit = opts.limit ?? 8;
+        const terms = tokenize(query);
+        if (terms.length === 0)
+            return [];
+        const pages = await this.listPages();
+        const bodies = new Map();
+        if (opts.fullText ?? true) {
+            await mapLimit(pages, 8, async (p) => {
+                try {
+                    bodies.set(p.path, (await this.readPage(p.path)).markdown);
+                }
+                catch {
+                    // A page that fails to load still ranks on its title and description.
+                }
+            });
+        }
+        const phrase = query.trim().toLowerCase();
+        const hits = [];
+        for (const page of pages) {
+            const title = page.title.toLowerCase();
+            const desc = page.description.toLowerCase();
+            const path = page.path.toLowerCase();
+            const body = bodies.get(page.path)?.toLowerCase() ?? "";
+            let score = 0;
+            for (const t of terms) {
+                if (title.includes(t))
+                    score += 6;
+                if (path.includes(t))
+                    score += 3;
+                if (desc.includes(t))
+                    score += 2;
+                score += Math.min(countOccurrences(body, t), 5) * 0.5;
+            }
+            if (phrase.length > 3 && (title.includes(phrase) || body.includes(phrase)))
+                score += 4;
+            if (score > 0) {
+                hits.push({ ...page, score, snippet: makeSnippet(bodies.get(page.path) ?? page.description, terms) });
+            }
+        }
+        return hits.sort((a, b) => b.score - a.score).slice(0, limit);
+    }
+    normalizePath(ref) {
+        let s = ref.trim();
+        if (/^https?:\/\//i.test(s)) {
+            const u = new URL(s);
+            if (u.origin !== new URL(this.baseUrl).origin) {
+                throw new Error(`Only pages on ${this.baseUrl} can be read`);
+            }
+            s = u.pathname;
+        }
+        s = s.split(/[?#]/)[0].replace(/^\/+/, "").replace(/\.(md|mdx)$/i, "").replace(/\/+$/, "");
+        if (!s || !/^[A-Za-z0-9._/-]+$/.test(s) || s.split("/").some((seg) => seg === ".." || seg === ".")) {
+            throw new Error(`Not a valid docs page path: ${ref}`);
+        }
+        return s;
+    }
+    async get(url) {
+        const res = await this.fetchImpl(url, {
+            headers: { accept: "text/markdown, text/plain;q=0.9, */*;q=0.1" },
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok)
+            throw new Error(`GET ${url} failed with HTTP ${res.status}`);
+        return res.text();
+    }
+}
+/** Parse the `- [Title](url): description` lines of an llms.txt file. */
+export function parseLlmsTxt(text, baseUrl) {
+    const origin = new URL(baseUrl).origin;
+    const pages = [];
+    const seen = new Set();
+    const line = /^\s*[-*]\s*\[([^\]]+)\]\(([^)\s]+)\)\s*(?::\s*(.*))?$/;
+    for (const raw of text.split(/\r?\n/)) {
+        const m = line.exec(raw);
+        if (!m)
+            continue;
+        let url;
+        try {
+            url = new URL(m[2], baseUrl);
+        }
+        catch {
+            continue;
+        }
+        if (url.origin !== origin)
+            continue;
+        const path = url.pathname.replace(/^\/+/, "").replace(/\.(md|mdx)$/i, "").replace(/\/+$/, "") || "index";
+        if (seen.has(path))
+            continue;
+        seen.add(path);
+        pages.push({
+            title: m[1].trim(),
+            path,
+            section: path.includes("/") ? path.split("/")[0] : "overview",
+            description: (m[3] ?? "").trim(),
+            url: `${origin}/${path}`,
+        });
+    }
+    return pages;
+}
+function tokenize(q) {
+    const stop = new Set(["the", "a", "an", "to", "of", "and", "or", "in", "on", "for", "how", "do", "i", "is", "with", "what"]);
+    return [...new Set(q.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length > 1 && !stop.has(t)))];
+}
+function countOccurrences(hay, needle) {
+    if (!hay)
+        return 0;
+    let n = 0;
+    for (let i = hay.indexOf(needle); i !== -1; i = hay.indexOf(needle, i + needle.length))
+        n++;
+    return n;
+}
+function makeSnippet(text, terms, radius = 120) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const lower = flat.toLowerCase();
+    let at = -1;
+    for (const t of terms) {
+        at = lower.indexOf(t);
+        if (at !== -1)
+            break;
+    }
+    if (at === -1)
+        return flat.slice(0, radius * 2);
+    const start = Math.max(0, at - radius);
+    const end = Math.min(flat.length, at + radius);
+    return `${start > 0 ? "…" : ""}${flat.slice(start, end)}${end < flat.length ? "…" : ""}`;
+}
+async function mapLimit(items, limit, fn) {
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length)
+            await fn(items[next++]);
+    });
+    await Promise.all(workers);
+}

package/dist/guides.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Integration recipes live as Markdown under `guides/<goal>/`:
+ *   overview.md       frontmatter (title, summary, docs, client) + stack-neutral steps
+ *   <stack>.md        code for one stack; html.md is the fallback for any stack
+ * `guides/_client/<stack>.md` is the request-signing client, appended when `client: true`.
+ */
+export declare const STACKS: readonly ["node", "nextjs", "python", "php"];
+export type Stack = (typeof STACKS)[number];
+export declare const STACK_LABELS: Record<Stack, string>;
+export interface GuideMeta {
+    goal: string;
+    title: string;
+    summary: string;
+    docs: string[];
+    client: boolean;
+}
+export declare const GUIDES_DIR: string;
+export declare function listGuides(dir?: string): GuideMeta[];
+export declare function buildGuide(goal: string, stack: Stack, docsBaseUrl: string, dir?: string): string;

package/dist/guides.js

@@ -0,0 +1,66 @@
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Integration recipes live as Markdown under `guides/<goal>/`:
+ *   overview.md       frontmatter (title, summary, docs, client) + stack-neutral steps
+ *   <stack>.md        code for one stack; html.md is the fallback for any stack
+ * `guides/_client/<stack>.md` is the request-signing client, appended when `client: true`.
+ */
+export const STACKS = ["node", "nextjs", "python", "php"];
+export const STACK_LABELS = {
+    node: "Node.js (Express)",
+    nextjs: "Next.js (App Router)",
+    python: "Python (FastAPI)",
+    php: "PHP",
+};
+export const GUIDES_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "guides");
+export function listGuides(dir = GUIDES_DIR) {
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && !d.name.startsWith("_") && existsSync(join(dir, d.name, "overview.md")))
+        .map((d) => readMeta(dir, d.name))
+        .sort((a, b) => a.goal.localeCompare(b.goal));
+}
+export function buildGuide(goal, stack, docsBaseUrl, dir = GUIDES_DIR) {
+    const known = listGuides(dir).map((g) => g.goal);
+    if (!known.includes(goal)) {
+        throw new Error(`Unknown goal "${goal}". Available goals: ${known.join(", ")}`);
+    }
+    const meta = readMeta(dir, goal);
+    const { body } = splitFrontmatter(readFileSync(join(dir, goal, "overview.md"), "utf8"));
+    const parts = [`# ${meta.title}`, `_Stack: ${STACK_LABELS[stack]}_`, body.trim()];
+    if (meta.client && goal !== "authentication") {
+        parts.push("## Prerequisite: authenticated API client", "Every call below goes through this helper. See the `authentication` guide for creating the API user and key pair.", readFileSync(join(dir, "_client", `${stack}.md`), "utf8").trim());
+    }
+    else if (goal === "authentication") {
+        parts.push("## Code", readFileSync(join(dir, "_client", `${stack}.md`), "utf8").trim());
+    }
+    const stackFile = [join(dir, goal, `${stack}.md`), join(dir, goal, "html.md")].find((p) => existsSync(p));
+    if (stackFile)
+        parts.push("## Code", readFileSync(stackFile, "utf8").trim());
+    const base = docsBaseUrl.replace(/\/+$/, "");
+    parts.push("## Source documentation", "Read these with the `read_doc` tool when you need exact field lists or response shapes:", meta.docs.map((d) => `- ${base}/${d}`).join("\n"));
+    return parts.join("\n\n") + "\n";
+}
+function readMeta(dir, goal) {
+    const { attrs } = splitFrontmatter(readFileSync(join(dir, goal, "overview.md"), "utf8"));
+    return {
+        goal,
+        title: attrs.title ?? goal,
+        summary: attrs.summary ?? "",
+        docs: (attrs.docs ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+        client: attrs.client === "true",
+    };
+}
+function splitFrontmatter(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+    if (!m)
+        return { attrs: {}, body: text };
+    const attrs = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const i = line.indexOf(":");
+        if (i > 0)
+            attrs[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    }
+    return { attrs, body: text.slice(m[0].length) };
+}

package/dist/http.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { DocsClient } from "./docs.js";
+/** Hostnames accepted in the Host header when MCP_ALLOWED_HOSTS is unset. */
+export declare const DEFAULT_ALLOWED_HOSTS: string[];
+/** Parses MCP_ALLOWED_HOSTS: comma-separated hostnames (no ports), or "*" to accept any Host. */
+export declare function parseAllowedHosts(value: string | undefined): string[] | undefined;
+/**
+ * @param opts.allowedHosts Host header allowlist (DNS rebinding protection); undefined accepts any Host.
+ */
+export declare function createHttpApp(opts?: {
+    docs?: DocsClient;
+    allowedHosts?: string[];
+}): import("express-serve-static-core").Express;