@wootsup/yt-builder-mcp 1.2.0 → 1.4.0

package/dist/index.js

@@ -14,6 +14,11 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { isTestMode, loadRegistry } from './auth.js';
 import { ConfigError } from './errors.js';
+import { installGlobalProxyDispatcher } from './net/proxy-dispatcher.js';
+import { SERVER_VERSION } from './server.js';
+import { checkForUpdate, formatUpdateNotice } from './update/update-check.js';
+/** npm package name — used by the startup update-notice + the diagnose tool. */
+const MCP_PACKAGE_NAME = '@wootsup/yt-builder-mcp';
 import { bootstrapActiveSite } from './sites/bootstrap.js';
 import { ClientPool } from './sites/client-pool.js';
 import { SiteRegistry } from './sites/registry.js';
@@ -36,6 +41,46 @@ export { CapturingServer, } from './gateway/capturing-server.js';
 export { registerAdvancedTool } from './gateway/advanced-tool.js';
 export { collectAllRegisteredTools, findTool, } from './gateway/test-support.js';
 async function main() {
+    // Honor an enterprise HTTP(S)_PROXY / NO_PROXY before any outbound call —
+    // BOTH proxy mode (below) and fat mode use Node's global fetch, which reads
+    // this global dispatcher. Unconditional + passthrough-safe (no proxy env =
+    // direct). Also auto-derives NO_PROXY for an internal site host (gap #9).
+    // See net/proxy-dispatcher.ts.
+    installGlobalProxyDispatcher();
+    // Gap #14 — surface any YTB_MCP_EXTRA_HEADERS parse warnings ONCE at startup
+    // (dropped lines / a forbidden Authorization key) so a misconfigured corp
+    // header isn't silently ignored. stderr only — stdout is the JSON-RPC channel.
+    if (!isTestMode()) {
+        const { parseExtraHeaders } = await import('./net/extra-headers.js');
+        for (const w of parseExtraHeaders().warnings) {
+            process.stderr.write(`[yt-builder-mcp] ${w}\n`);
+        }
+    }
+    // Update notice (non-blocking, cached 24h, fail-silent) — surfaces a newer
+    // npm version to stderr without ever delaying serving or breaking behind a
+    // corporate proxy. Skipped in test-mode (the smoke probe must not hit the
+    // network). stderr only — stdout is the JSON-RPC channel.
+    if (!isTestMode()) {
+        void checkForUpdate({ currentVersion: SERVER_VERSION, packageName: MCP_PACKAGE_NAME })
+            .then((status) => {
+            const notice = formatUpdateNotice(status);
+            if (notice !== null)
+                console.error(notice);
+        })
+            .catch(() => {
+            /* fail-silent — the notifier is a courtesy, never a dependency */
+        });
+    }
+    // Proxy mode: forward stdio 1:1 to the plugin-served PHP MCP endpoint and
+    // stop here — the fat catalog below is bypassed entirely. Default (fat) is
+    // unchanged. The dynamic import is gated on the env so the fat path never
+    // loads the proxy module (and the SDK client transport it pulls in) — keeps
+    // fat-mode startup lean and avoids loading proxy code when it can't apply.
+    if (process.env.YTB_MCP_MODE === 'proxy') {
+        const { maybeRunProxy } = await import('./proxy/bridge.js');
+        if (await maybeRunProxy(process.env))
+            return;
+    }
     const testMode = isTestMode();
     // W10 — multi-site bootstrap is now centralised in
     // `auth.loadRegistry()`. The canonical resolution order is:

package/dist/index.js.map

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

package/dist/install-skill.d.ts

@@ -8,7 +8,7 @@
  * Idempotent: re-running overwrites existing skill files and skips the
  * AGENTS.md append when the marker is already present.
  *
- * Mirrors the pattern from `@wootsup/mcp install-skill` so users on both
+ * Mirrors the pattern from `@wootsup/apimapper-mcp install-skill` so users on both
  * products get the same workflow.
  *
  * @license MIT

package/dist/install-skill.js

@@ -8,7 +8,7 @@
  * Idempotent: re-running overwrites existing skill files and skips the
  * AGENTS.md append when the marker is already present.
  *
- * Mirrors the pattern from `@wootsup/mcp install-skill` so users on both
+ * Mirrors the pattern from `@wootsup/apimapper-mcp install-skill` so users on both
  * products get the same workflow.
  *
  * @license MIT
@@ -27,7 +27,7 @@ The YT Builder MCP skill is installed at \`~/.claude/skills/yt-builder-mcp/\`
 — the universal-marker path recognised by Claude Desktop and other AI
 clients that follow the \`~/AGENTS.md\` discovery protocol.
 
-It documents the 30 MCP tools (29 domain + 1 gateway, 23 entries in
+It documents the 30 MCP tools (29 domain + 1 gateway, 26 entries in
 \`tools/list\`), the 5 canonical workflows (build hero, bind dynamic
 source, clone section, diagnose 401, add custom element), and the
 gateway routing model. Source: https://github.com/wootsup/yt-builder-mcp.

package/dist/net/extra-headers.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` into a header map that is merged into EVERY
+ * outbound request on BOTH transports (fat-mode {@link RestClient} and
+ * proxy-mode `StreamableHTTPClientTransport`).
+ *
+ * Why this exists (Glöckle gap #14): a WordPress/Joomla site fronted by HTTP
+ * Basic-Auth, a WAF cookie, or a custom required header (e.g. a corporate
+ * gateway secret) cannot be reached — the only header we ever send is
+ * `Authorization: Bearer …`. This env var lets the operator attach the extra
+ * header(s) the gateway demands WITHOUT us inventing per-provider knobs.
+ *
+ * ── Accepted formats (auto-detected) ───────────────────────────────────────
+ * The value is read as ONE of two shapes, in this precedence:
+ *
+ *   1. **JSON object** — `{"X-WAF-Token":"abc","Cookie":"sid=42"}`.
+ *      Used when the trimmed value starts with `{` AND parses as a non-array
+ *      object. Non-string values are coerced via String(); null/array values
+ *      are dropped (with a warning).
+ *
+ *   2. **`Name: value` lines** — one header per line, first `:` splits:
+ *
+ *          X-WAF-Token: abc
+ *          Cookie: sid=42
+ *
+ *      Blank lines and lines starting with `#` (comments) are ignored. A line
+ *      with no `:` is dropped with a warning.
+ *
+ * ── Hard invariants ─────────────────────────────────────────────────────────
+ *   - **`Authorization` can NEVER be set here.** Any `Authorization` key (case-
+ *     insensitive) in the parsed map is dropped with a warning — the Bearer is
+ *     owned by the auth layer and an extra header must never overwrite it. This
+ *     is the parse-side half of "Bearer always wins"; the merge-side half lives
+ *     in {@link mergeExtraHeaders}.
+ *   - Empty header NAMES are dropped. Empty VALUES are kept (a deliberately
+ *     blank header is a legitimate, if rare, gateway requirement).
+ *
+ * Pure + deterministic. `warn` collects non-fatal issues; the caller decides
+ * whether to surface them (the server logs them once to stderr at startup).
+ *
+ * @license MIT
+ */
+/** Canonical env-var name for the extra-headers feature. */
+export declare const ENV_EXTRA_HEADERS = "YTB_MCP_EXTRA_HEADERS";
+export interface ParsedExtraHeaders {
+    /** The accepted header map (never contains `Authorization`). */
+    readonly headers: Record<string, string>;
+    /** Non-fatal issues (dropped lines, forbidden keys, bad JSON shape). */
+    readonly warnings: readonly string[];
+}
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` from `env` (default `process.env`). Returns an
+ * empty map (no warnings) when the var is unset/blank.
+ */
+export declare function parseExtraHeaders(env?: NodeJS.ProcessEnv): ParsedExtraHeaders;
+/**
+ * Merge extra headers UNDER an existing header set so the caller's headers
+ * (which always include `Authorization: Bearer …`) win on collision. Extra
+ * headers fill gaps; they never overwrite. Case-insensitive collision check so
+ * a `authorization` extra can never shadow a real `Authorization`.
+ *
+ * @param base   Authoritative headers (Bearer, Accept, Content-Type, If-Match…).
+ * @param extra  Parsed extra headers to merge underneath `base`.
+ * @returns A fresh record; inputs are not mutated.
+ */
+export declare function mergeExtraHeaders(base: Record<string, string>, extra: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=extra-headers.d.ts.map

package/dist/net/extra-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extra-headers.d.ts","sourceRoot":"","sources":["../../src/net/extra-headers.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,0BAA0B,CAAC;AAKzD,MAAM,WAAW,kBAAkB;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAwED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAiB1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxB"}

package/dist/net/extra-headers.js

@@ -0,0 +1,164 @@
+// packages/mcp/src/net/extra-headers.ts
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` into a header map that is merged into EVERY
+ * outbound request on BOTH transports (fat-mode {@link RestClient} and
+ * proxy-mode `StreamableHTTPClientTransport`).
+ *
+ * Why this exists (Glöckle gap #14): a WordPress/Joomla site fronted by HTTP
+ * Basic-Auth, a WAF cookie, or a custom required header (e.g. a corporate
+ * gateway secret) cannot be reached — the only header we ever send is
+ * `Authorization: Bearer …`. This env var lets the operator attach the extra
+ * header(s) the gateway demands WITHOUT us inventing per-provider knobs.
+ *
+ * ── Accepted formats (auto-detected) ───────────────────────────────────────
+ * The value is read as ONE of two shapes, in this precedence:
+ *
+ *   1. **JSON object** — `{"X-WAF-Token":"abc","Cookie":"sid=42"}`.
+ *      Used when the trimmed value starts with `{` AND parses as a non-array
+ *      object. Non-string values are coerced via String(); null/array values
+ *      are dropped (with a warning).
+ *
+ *   2. **`Name: value` lines** — one header per line, first `:` splits:
+ *
+ *          X-WAF-Token: abc
+ *          Cookie: sid=42
+ *
+ *      Blank lines and lines starting with `#` (comments) are ignored. A line
+ *      with no `:` is dropped with a warning.
+ *
+ * ── Hard invariants ─────────────────────────────────────────────────────────
+ *   - **`Authorization` can NEVER be set here.** Any `Authorization` key (case-
+ *     insensitive) in the parsed map is dropped with a warning — the Bearer is
+ *     owned by the auth layer and an extra header must never overwrite it. This
+ *     is the parse-side half of "Bearer always wins"; the merge-side half lives
+ *     in {@link mergeExtraHeaders}.
+ *   - Empty header NAMES are dropped. Empty VALUES are kept (a deliberately
+ *     blank header is a legitimate, if rare, gateway requirement).
+ *
+ * Pure + deterministic. `warn` collects non-fatal issues; the caller decides
+ * whether to surface them (the server logs them once to stderr at startup).
+ *
+ * @license MIT
+ */
+/** Canonical env-var name for the extra-headers feature. */
+export const ENV_EXTRA_HEADERS = 'YTB_MCP_EXTRA_HEADERS';
+/** Header names that may never be supplied via the extra-headers env var. */
+const FORBIDDEN_HEADER_NAMES = new Set(['authorization']);
+/** Is `name` a header we refuse to let the env var set? Case-insensitive. */
+function isForbidden(name) {
+    return FORBIDDEN_HEADER_NAMES.has(name.trim().toLowerCase());
+}
+/** Coerce a JSON value to a string, or null when it cannot sanely become one. */
+function coerceValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return null;
+}
+/** Parse the JSON-object form. Returns null when `raw` is not a JSON object. */
+function parseJsonObject(raw, warnings) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return null;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        const name = key.trim();
+        if (name === '') {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped an entry with an empty header name.`);
+            continue;
+        }
+        if (isForbidden(name)) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: "${name}" is ignored — the Bearer token is set automatically and can never be overridden here.`);
+            continue;
+        }
+        const coerced = coerceValue(value);
+        if (coerced === null) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped header "${name}" — its value is not a string/number/boolean.`);
+            continue;
+        }
+        out[name] = coerced;
+    }
+    return out;
+}
+/** Parse the `Name: value` line form. */
+function parseLines(raw, warnings) {
+    const out = {};
+    for (const lineRaw of raw.split(/\r?\n/)) {
+        const line = lineRaw.trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const idx = line.indexOf(':');
+        if (idx < 0) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped line with no ":" separator — "${line}".`);
+            continue;
+        }
+        const name = line.slice(0, idx).trim();
+        const value = line.slice(idx + 1).trim();
+        if (name === '') {
+            warnings.push(`${ENV_EXTRA_HEADERS}: dropped a line with an empty header name.`);
+            continue;
+        }
+        if (isForbidden(name)) {
+            warnings.push(`${ENV_EXTRA_HEADERS}: "${name}" is ignored — the Bearer token is set automatically and can never be overridden here.`);
+            continue;
+        }
+        out[name] = value;
+    }
+    return out;
+}
+/**
+ * Parse `YTB_MCP_EXTRA_HEADERS` from `env` (default `process.env`). Returns an
+ * empty map (no warnings) when the var is unset/blank.
+ */
+export function parseExtraHeaders(env = process.env) {
+    const raw = (env[ENV_EXTRA_HEADERS] ?? '').trim();
+    if (raw === '') {
+        return { headers: {}, warnings: [] };
+    }
+    const warnings = [];
+    // JSON-object form wins when the value looks like an object literal.
+    if (raw.startsWith('{')) {
+        const obj = parseJsonObject(raw, warnings);
+        if (obj !== null) {
+            return { headers: obj, warnings };
+        }
+        // Looked like JSON but didn't parse — fall back to line-parsing rather
+        // than silently dropping everything, and say so.
+        warnings.push(`${ENV_EXTRA_HEADERS}: value started with "{" but is not valid JSON — falling back to "Name: value" line parsing.`);
+    }
+    return { headers: parseLines(raw, warnings), warnings };
+}
+/**
+ * Merge extra headers UNDER an existing header set so the caller's headers
+ * (which always include `Authorization: Bearer …`) win on collision. Extra
+ * headers fill gaps; they never overwrite. Case-insensitive collision check so
+ * a `authorization` extra can never shadow a real `Authorization`.
+ *
+ * @param base   Authoritative headers (Bearer, Accept, Content-Type, If-Match…).
+ * @param extra  Parsed extra headers to merge underneath `base`.
+ * @returns A fresh record; inputs are not mutated.
+ */
+export function mergeExtraHeaders(base, extra) {
+    const lowerBaseKeys = new Set(Object.keys(base).map((k) => k.toLowerCase()));
+    const merged = {};
+    // Extra first, so a same-name base key overwrites it below.
+    for (const [name, value] of Object.entries(extra)) {
+        // Never let an extra header shadow a base header (esp. Authorization).
+        if (lowerBaseKeys.has(name.toLowerCase()))
+            continue;
+        merged[name] = value;
+    }
+    for (const [name, value] of Object.entries(base)) {
+        merged[name] = value;
+    }
+    return merged;
+}
+//# sourceMappingURL=extra-headers.js.map

package/dist/net/extra-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extra-headers.js","sourceRoot":"","sources":["../../src/net/extra-headers.ts"],"names":[],"mappings":"AAAA,wCAAwC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;AAS/E,6EAA6E;AAC7E,SAAS,WAAW,CAAC,IAAY;IAC7B,OAAO,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACjE,CAAC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAClF,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,gFAAgF;AAChF,SAAS,eAAe,CAAC,GAAW,EAAE,QAAkB;IACpD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACzE,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAiC,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,+CAA+C,CAAC,CAAC;YACnF,SAAS;QACb,CAAC;QACD,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,MAAM,IAAI,wFAAwF,CAAC,CAAC;YACtI,SAAS;QACb,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACnC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,qBAAqB,IAAI,+CAA+C,CAAC,CAAC;YAC5G,SAAS;QACb,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED,yCAAyC;AACzC,SAAS,UAAU,CAAC,GAAW,EAAE,QAAkB;IAC/C,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAClD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACV,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,2CAA2C,IAAI,IAAI,CAAC,CAAC;YACvF,SAAS;QACb,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,6CAA6C,CAAC,CAAC;YACjF,SAAS;QACb,CAAC;QACD,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,MAAM,IAAI,wFAAwF,CAAC,CAAC;YACtI,SAAS;QACb,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACzC,CAAC;IACD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,qEAAqE;IACrE,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC3C,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACf,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;QACtC,CAAC;QACD,uEAAuE;QACvE,iDAAiD;QACjD,QAAQ,CAAC,IAAI,CAAC,GAAG,iBAAiB,8FAA8F,CAAC,CAAC;IACtI,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC7B,IAA4B,EAC5B,KAA6B;IAE7B,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC7E,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,4DAA4D;IAC5D,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAChD,uEAAuE;QACvE,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAAE,SAAS;QACpD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/net/internal-host.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Classify a host as internal. A host is internal when ANY of:
+ *   - it is `localhost`,
+ *   - it is a private/loopback/link-local IPv4 or IPv6 literal,
+ *   - it ends in an internal DNS suffix (`.local`, `.internal`, …),
+ *   - it is a bare single-label hostname (no dot — an intranet short name).
+ *
+ * A normal public FQDN (`example.com`, `acme.co.uk`) is NOT internal.
+ */
+export declare function isInternalHost(rawHost: string): boolean;
+/** Extract a lowercased, bracket-stripped host from a URL string, or null. */
+export declare function hostFromUrl(rawUrl: string): string | null;
+export interface NoProxyDerivation {
+    /** True when this call would change NO_PROXY (host added). */
+    readonly changed: boolean;
+    /**
+     * The effective NO_PROXY value to use. When `changed` is false this is the
+     * input value verbatim (or undefined when it was unset and stays unset).
+     */
+    readonly noProxy: string | undefined;
+    /** The internal host that was added, or null when nothing was added. */
+    readonly addedHost: string | null;
+    /** Non-fatal reason when nothing was added (for an optional debug log). */
+    readonly reason?: string;
+}
+export interface DeriveNoProxyInput {
+    /** Source of env vars. */
+    readonly env: NodeJS.ProcessEnv;
+    /** The configured site URL (typically `YTB_MCP_SITE_URL`). */
+    readonly siteUrl: string | undefined;
+}
+/**
+ * Compute the NO_PROXY value to apply so an internal site host bypasses a
+ * configured corporate proxy. Idempotent + non-clobbering:
+ *
+ *   - No proxy configured → no change (the agent isn't installed anyway).
+ *   - `siteUrl` missing / unparseable / clearly public → no change.
+ *   - Host already present in NO_PROXY (case-insensitive) → no change.
+ *   - Otherwise → append the host to the existing operator NO_PROXY (preserved
+ *     verbatim, comma-joined), or seed NO_PROXY with just the host when unset.
+ *
+ * Pure: returns the value to write; the caller mutates `process.env`.
+ */
+export declare function deriveNoProxyForInternalSite(input: DeriveNoProxyInput): NoProxyDerivation;
+//# sourceMappingURL=internal-host.d.ts.map

package/dist/net/internal-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-host.d.ts","sourceRoot":"","sources":["../../src/net/internal-host.ts"],"names":[],"mappings":"AAmEA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAWvD;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASzD;AAeD,MAAM,WAAW,iBAAiB;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IAC/B,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,CAwBzF"}

package/dist/net/internal-host.js

@@ -0,0 +1,164 @@
+// packages/mcp/src/net/internal-host.ts
+/**
+ * Classify a site host as internal vs public, and derive a NO_PROXY addition
+ * for an internal host when a forward proxy is configured (Glöckle gap #9).
+ *
+ * Why this exists: when a corporate `HTTP(S)_PROXY` is set, undici's
+ * `EnvHttpProxyAgent` routes EVERYTHING through it — including traffic to an
+ * intranet WordPress/Joomla that the proxy can't (or shouldn't) reach. The
+ * `NO_PROXY` exception list fixes that, but only if the operator pre-set it.
+ * A common Glöckle-class failure: the proxy reaches the public internet fine,
+ * but the internal CMS is direct-only (or vice-versa), and outbound MCP traffic
+ * silently dies.
+ *
+ * We therefore classify the configured `YTB_MCP_SITE_URL` host and, when a
+ * proxy is set AND the host is clearly internal, add it to the effective
+ * NO_PROXY the agent reads. **Conservative by construction:** only RFC1918 /
+ * loopback / link-local IPs, `.local` / `.internal` / `.intranet` suffixes, and
+ * bare single-label hostnames (no dot) are treated as internal. A normal
+ * public FQDN is NEVER routed to NO_PROXY.
+ *
+ * Pure + env-injectable so it is unit-testable offline. Never mutates input.
+ *
+ * @license MIT
+ */
+/** Internal-by-convention DNS suffixes (RFC 6762 + common intranet TLDs). */
+const INTERNAL_SUFFIXES = ['.local', '.internal', '.intranet', '.lan', '.home.arpa'];
+/** Strip an `[…]` IPv6 bracket wrapper and a trailing `.` if present. */
+function normalizeHost(host) {
+    let h = host.trim().toLowerCase();
+    if (h.startsWith('[') && h.endsWith(']'))
+        h = h.slice(1, -1);
+    if (h.endsWith('.'))
+        h = h.slice(0, -1);
+    return h;
+}
+/** Is `host` an IPv4 literal in a private/loopback/link-local range? */
+function isPrivateIpv4(host) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (m === null)
+        return false;
+    const octets = [m[1], m[2], m[3], m[4]].map((o) => Number.parseInt(o, 10));
+    if (octets.some((o) => o > 255))
+        return false;
+    const [a, b] = octets;
+    if (a === 10)
+        return true; // 10.0.0.0/8
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local
+    return false;
+}
+/** Is `host` an IPv6 loopback / unique-local (fc00::/7) / link-local (fe80::/10)? */
+function isPrivateIpv6(host) {
+    if (!host.includes(':'))
+        return false;
+    if (host === '::1')
+        return true; // loopback
+    const first = host.split(':')[0] ?? '';
+    if (first === '')
+        return false; // e.g. "::" unspecified — not a real site host
+    const prefix = Number.parseInt(first, 16);
+    if (Number.isNaN(prefix))
+        return false;
+    // fc00::/7 (unique-local) → first hextet 0xfc00–0xfdff.
+    if (prefix >= 0xfc00 && prefix <= 0xfdff)
+        return true;
+    // fe80::/10 (link-local) → first hextet 0xfe80–0xfebf.
+    if (prefix >= 0xfe80 && prefix <= 0xfebf)
+        return true;
+    return false;
+}
+/**
+ * Classify a host as internal. A host is internal when ANY of:
+ *   - it is `localhost`,
+ *   - it is a private/loopback/link-local IPv4 or IPv6 literal,
+ *   - it ends in an internal DNS suffix (`.local`, `.internal`, …),
+ *   - it is a bare single-label hostname (no dot — an intranet short name).
+ *
+ * A normal public FQDN (`example.com`, `acme.co.uk`) is NOT internal.
+ */
+export function isInternalHost(rawHost) {
+    const host = normalizeHost(rawHost);
+    if (host === '')
+        return false;
+    if (host === 'localhost')
+        return true;
+    if (isPrivateIpv4(host))
+        return true;
+    if (isPrivateIpv6(host))
+        return true;
+    if (INTERNAL_SUFFIXES.some((s) => host.endsWith(s)))
+        return true;
+    // A bare hostname with no dot is an intranet short name (e.g. "wpserver").
+    // IPv6 literals contain ":" and are handled above; guard against them here.
+    if (!host.includes('.') && !host.includes(':'))
+        return true;
+    return false;
+}
+/** Extract a lowercased, bracket-stripped host from a URL string, or null. */
+export function hostFromUrl(rawUrl) {
+    const url = rawUrl.trim();
+    if (url === '')
+        return null;
+    try {
+        const parsed = new URL(url);
+        return normalizeHost(parsed.hostname);
+    }
+    catch {
+        return null;
+    }
+}
+/** Is any forward-proxy configured in `env`? */
+function hasProxyConfigured(env) {
+    return Boolean(env.HTTPS_PROXY ?? env.https_proxy ?? env.HTTP_PROXY ?? env.http_proxy);
+}
+/** Split a NO_PROXY string into trimmed, lowercased, non-empty entries. */
+function splitNoProxy(value) {
+    return value
+        .split(',')
+        .map((e) => e.trim().toLowerCase())
+        .filter((e) => e !== '');
+}
+/**
+ * Compute the NO_PROXY value to apply so an internal site host bypasses a
+ * configured corporate proxy. Idempotent + non-clobbering:
+ *
+ *   - No proxy configured → no change (the agent isn't installed anyway).
+ *   - `siteUrl` missing / unparseable / clearly public → no change.
+ *   - Host already present in NO_PROXY (case-insensitive) → no change.
+ *   - Otherwise → append the host to the existing operator NO_PROXY (preserved
+ *     verbatim, comma-joined), or seed NO_PROXY with just the host when unset.
+ *
+ * Pure: returns the value to write; the caller mutates `process.env`.
+ */
+export function deriveNoProxyForInternalSite(input) {
+    const { env, siteUrl } = input;
+    const current = env.NO_PROXY ?? env.no_proxy;
+    if (!hasProxyConfigured(env)) {
+        return { changed: false, noProxy: current, addedHost: null, reason: 'no proxy configured' };
+    }
+    const host = siteUrl !== undefined ? hostFromUrl(siteUrl) : null;
+    if (host === null) {
+        return { changed: false, noProxy: current, addedHost: null, reason: 'no parseable site URL' };
+    }
+    if (!isInternalHost(host)) {
+        return { changed: false, noProxy: current, addedHost: null, reason: 'site host is public' };
+    }
+    const existing = current !== undefined ? splitNoProxy(current) : [];
+    if (existing.includes(host)) {
+        return { changed: false, noProxy: current, addedHost: null, reason: 'host already in NO_PROXY' };
+    }
+    // Append, preserving the operator's existing entries verbatim (original
+    // casing/order) — we only add the host at the end.
+    const next = current !== undefined && current.trim() !== ''
+        ? `${current},${host}`
+        : host;
+    return { changed: true, noProxy: next, addedHost: host };
+}
+//# sourceMappingURL=internal-host.js.map

package/dist/net/internal-host.js.map

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

package/dist/net/proxy-dispatcher.d.ts

@@ -0,0 +1,40 @@
+import { type Dispatcher } from 'undici';
+/**
+ * Injection seam for tests — production uses the real undici functions + env.
+ */
+export interface ProxyDispatcherDeps {
+    /** Defaults to `process.env`. Read for HTTP(S)_PROXY presence. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to undici's {@link undiciSetGlobalDispatcher}. */
+    setGlobalDispatcher?: (dispatcher: Dispatcher) => void;
+    /** Defaults to `() => new EnvHttpProxyAgent()`. */
+    makeEnvHttpProxyAgent?: () => Dispatcher;
+    /** Defaults to `console.error`. */
+    stderr?: (message: string) => void;
+}
+/**
+ * Install a process-global undici dispatcher that honors the enterprise
+ * `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` environment variables at request
+ * time (undici's {@link EnvHttpProxyAgent}).
+ *
+ * Why this exists: Node's global `fetch` only auto-honors proxy env vars from
+ * **Node 24** (`NODE_USE_ENV_PROXY`). On the Node 18–23 floor this package
+ * supports, an enterprise forward/auth proxy is otherwise ignored and outbound
+ * MCP traffic silently fails. Node's global `fetch` reads the global dispatcher,
+ * and so does the MCP SDK's `StreamableHTTPClientTransport` (proxy mode) and the
+ * fat-mode `RestClient` — so one global dispatcher covers every outbound call.
+ *
+ * Installed ONLY when a forward proxy is actually configured
+ * (`HTTP_PROXY`/`HTTPS_PROXY`). With no proxy env, the default dispatcher (a
+ * direct connection) is already correct, so we skip — this also avoids undici's
+ * `EnvHttpProxyAgent is experimental` startup warning for the common, direct
+ * case. Corporate TLS-inspection root CAs are handled separately by Node's
+ * native `NODE_EXTRA_CA_CERTS` (undici's default connector honors it).
+ *
+ * Never throws: a failure to install (exotic runtime, frozen global) degrades
+ * to a stderr warning and a direct connection, returning `false`.
+ *
+ * @returns `true` if the dispatcher was installed, `false` if skipped/degraded.
+ */
+export declare function installGlobalProxyDispatcher(deps?: ProxyDispatcherDeps): boolean;
+//# sourceMappingURL=proxy-dispatcher.d.ts.map

package/dist/net/proxy-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-dispatcher.d.ts","sourceRoot":"","sources":["../../src/net/proxy-dispatcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAuE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAI9G;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8DAA8D;IAC9D,mBAAmB,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IACvD,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,MAAM,UAAU,CAAC;IACzC,mCAAmC;IACnC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAkCpF"}