toolception 0.3.0 → 0.5.0

package/dist/index.js

@@ -1,16 +1,16 @@
-var w = (r) => {
+var P = (r) => {
   throw TypeError(r);
 };
-var B = (r, e, t) => e.has(r) || w("Cannot " + t);
-var v = (r, e, t) => e.has(r) ? w("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(r) : e.set(r, t);
-var u = (r, e, t) => (B(r, e, "access private method"), t);
-import { z as T } from "zod";
-import S from "fastify";
-import M from "@fastify/cors";
-import { randomUUID as p } from "node:crypto";
-import { StreamableHTTPServerTransport as C } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { isInitializeRequest as x } from "@modelcontextprotocol/sdk/types.js";
-const b = {
+var ee = (r, e, s) => e.has(r) || P("Cannot " + s);
+var T = (r, e, s) => e.has(r) ? P("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(r) : e.set(r, s);
+var f = (r, e, s) => (ee(r, e, "access private method"), s);
+import { z as b } from "zod";
+import N from "fastify";
+import j from "@fastify/cors";
+import { randomUUID as y } from "node:crypto";
+import { StreamableHTTPServerTransport as k } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest as D } from "@modelcontextprotocol/sdk/types.js";
+const L = {
   dynamic: [
     "dynamic-tool-discovery",
     "dynamicToolDiscovery",
@@ -18,89 +18,98 @@ const b = {
   ],
   toolsets: ["tool-sets", "toolSets", "FMP_TOOL_SETS"]
 };
-class Y {
+class se {
   constructor(e = {}) {
     this.keys = {
-      dynamic: e.keys?.dynamic ?? b.dynamic,
-      toolsets: e.keys?.toolsets ?? b.toolsets
+      dynamic: e.keys?.dynamic ?? L.dynamic,
+      toolsets: e.keys?.toolsets ?? L.toolsets
     };
   }
-  resolveMode(e, t) {
-    return this.isDynamicEnabled(t) ? "DYNAMIC" : this.getToolsetsString(t) ? "STATIC" : this.isDynamicEnabled(e) ? "DYNAMIC" : this.getToolsetsString(e) ? "STATIC" : null;
+  resolveMode(e, s) {
+    return this.isDynamicEnabled(s) ? "DYNAMIC" : this.getToolsetsString(s) ? "STATIC" : this.isDynamicEnabled(e) ? "DYNAMIC" : this.getToolsetsString(e) ? "STATIC" : null;
   }
-  parseCommaSeparatedToolSets(e, t) {
+  parseCommaSeparatedToolSets(e, s) {
     if (!e || typeof e != "string") return [];
-    const s = e.split(",").map((a) => a.trim()).filter((a) => a.length > 0), o = new Set(Object.keys(t)), i = [];
-    for (const a of s)
-      o.has(a) ? i.push(a) : console.warn(
-        `Invalid toolset '${a}' ignored. Available: ${Array.from(
+    const t = e.split(",").map((n) => n.trim()).filter((n) => n.length > 0), o = new Set(Object.keys(s)), i = [];
+    for (const n of t)
+      o.has(n) ? i.push(n) : console.warn(
+        `Invalid toolset '${n}' ignored. Available: ${Array.from(
           o
         ).join(", ")}`
       );
     return i;
   }
-  getModulesForToolSets(e, t) {
-    const s = /* @__PURE__ */ new Set();
+  getModulesForToolSets(e, s) {
+    const t = /* @__PURE__ */ new Set();
     for (const o of e) {
-      const i = t[o];
-      i && (i.modules || []).forEach((a) => s.add(a));
+      const i = s[o];
+      i && (i.modules || []).forEach((n) => t.add(n));
     }
-    return Array.from(s);
+    return Array.from(t);
   }
-  validateToolsetName(e, t) {
+  validateToolsetName(e, s) {
     if (!e || typeof e != "string")
       return {
         isValid: !1,
         error: `Invalid toolset name provided. Must be a non-empty string. Available toolsets: ${Object.keys(
-          t
+          s
         ).join(", ")}`
       };
-    const s = e.trim();
-    return s.length === 0 ? {
+    const t = e.trim();
+    return t.length === 0 ? {
       isValid: !1,
       error: `Empty toolset name provided. Available toolsets: ${Object.keys(
-        t
+        s
       ).join(", ")}`
-    } : t[s] ? { isValid: !0, sanitized: s } : {
+    } : s[t] ? { isValid: !0, sanitized: t } : {
       isValid: !1,
-      error: `Toolset '${s}' not found. Available toolsets: ${Object.keys(
-        t
+      error: `Toolset '${t}' not found. Available toolsets: ${Object.keys(
+        s
       ).join(", ")}`
     };
   }
-  validateToolsetModules(e, t) {
+  /**
+   * Validates and retrieves modules for a set of toolsets.
+   * Note: A toolset with only direct tools (no modules) is valid and returns an empty modules array.
+   * @param toolsetNames - Array of toolset names to validate
+   * @param catalog - The toolset catalog to validate against
+   * @returns Validation result with modules array if valid
+   */
+  validateToolsetModules(e, s) {
     try {
-      const s = this.getModulesForToolSets(e, t);
-      return !s || s.length === 0 ? {
-        isValid: !1,
-        error: `No modules found for toolsets: ${e.join(", ")}`
-      } : { isValid: !0, modules: s };
-    } catch (s) {
+      for (const o of e)
+        if (!s[o])
+          return {
+            isValid: !1,
+            error: `Toolset '${o}' not found in catalog`
+          };
+      return { isValid: !0, modules: this.getModulesForToolSets(e, s) };
+    } catch (t) {
       return {
         isValid: !1,
-        error: `Error resolving modules for ${e.join(", ")}: ${s instanceof Error ? s.message : "Unknown error"}`
+        error: `Error resolving modules for ${e.join(", ")}: ${t instanceof Error ? t.message : "Unknown error"}`
       };
     }
   }
   isDynamicEnabled(e) {
     if (!e) return !1;
-    for (const t of this.keys.dynamic) {
-      const s = e[t];
-      if (s === !0 || typeof s == "string" && s.trim().toLowerCase() === "true")
+    for (const s of this.keys.dynamic) {
+      const t = e[s];
+      if (t === !0 || typeof t == "string" && t.trim().toLowerCase() === "true")
         return !0;
     }
     return !1;
   }
   getToolsetsString(e) {
     if (e)
-      for (const t of this.keys.toolsets) {
-        const s = e[t];
-        if (typeof s == "string" && s.trim().length > 0)
-          return s;
+      for (const s of this.keys.toolsets) {
+        const t = e[s];
+        if (typeof t == "string" && t.trim().length > 0)
+          return t;
       }
   }
 }
-class U {
+class te {
   constructor(e) {
     this.catalog = e.catalog, this.moduleLoaders = e.moduleLoaders ?? {};
   }
@@ -118,80 +127,80 @@ class U {
           ", "
         )}`
       };
-    const t = e.trim();
-    return t.length === 0 ? {
+    const s = e.trim();
+    return s.length === 0 ? {
       isValid: !1,
       error: `Empty toolset name provided. Available toolsets: ${this.getAvailableToolsets().join(
         ", "
       )}`
-    } : this.catalog[t] ? { isValid: !0, sanitized: t } : {
+    } : this.catalog[s] ? { isValid: !0, sanitized: s } : {
       isValid: !1,
-      error: `Toolset '${t}' not found. Available toolsets: ${this.getAvailableToolsets().join(
+      error: `Toolset '${s}' not found. Available toolsets: ${this.getAvailableToolsets().join(
         ", "
       )}`
     };
   }
-  async resolveToolsForToolsets(e, t) {
-    const s = [];
+  async resolveToolsForToolsets(e, s) {
+    const t = [];
     for (const o of e) {
       const i = this.catalog[o];
-      if (i && (Array.isArray(i.tools) && i.tools.length > 0 && s.push(...i.tools), Array.isArray(i.modules) && i.modules.length > 0))
-        for (const a of i.modules) {
-          const l = this.moduleLoaders[a];
+      if (i && (Array.isArray(i.tools) && i.tools.length > 0 && t.push(...i.tools), Array.isArray(i.modules) && i.modules.length > 0))
+        for (const n of i.modules) {
+          const l = this.moduleLoaders[n];
           if (l)
             try {
-              const n = await l(t);
-              Array.isArray(n) && n.length > 0 && s.push(...n);
-            } catch (n) {
+              const a = await l(s);
+              Array.isArray(a) && a.length > 0 && t.push(...a);
+            } catch (a) {
               console.warn(
-                `Module loader '${a}' failed for toolset '${o}':`,
-                n
+                `Module loader '${n}' failed for toolset '${o}':`,
+                a
               );
             }
         }
     }
-    return s;
+    return t;
   }
 }
-class A extends Error {
-  constructor(e, t, s, o) {
-    super(e), this.name = "ToolingError", this.code = t, this.details = s;
+class R extends Error {
+  constructor(e, s, t, o) {
+    super(e), this.name = "ToolingError", this.code = s, this.details = t;
   }
 }
-class I {
+class z {
   constructor(e = {}) {
     this.names = /* @__PURE__ */ new Set(), this.toolsetToNames = /* @__PURE__ */ new Map(), this.options = {
       namespaceWithToolset: e.namespaceWithToolset ?? !0
     };
   }
-  getSafeName(e, t) {
-    return !this.options.namespaceWithToolset || t.startsWith(`${e}.`) ? t : `${e}.${t}`;
+  getSafeName(e, s) {
+    return !this.options.namespaceWithToolset || s.startsWith(`${e}.`) ? s : `${e}.${s}`;
   }
   has(e) {
     return this.names.has(e);
   }
   add(e) {
     if (this.names.has(e))
-      throw new A(
+      throw new R(
         `Tool name collision: '${e}' already registered`,
         "E_TOOL_NAME_CONFLICT"
       );
     this.names.add(e);
   }
-  addForToolset(e, t) {
-    this.add(t);
-    const s = this.toolsetToNames.get(e) ?? /* @__PURE__ */ new Set();
-    s.add(t), this.toolsetToNames.set(e, s);
+  addForToolset(e, s) {
+    this.add(s);
+    const t = this.toolsetToNames.get(e) ?? /* @__PURE__ */ new Set();
+    t.add(s), this.toolsetToNames.set(e, t);
   }
-  mapAndValidate(e, t) {
-    return t.map((s) => {
-      const o = this.getSafeName(e, s.name);
+  mapAndValidate(e, s) {
+    return s.map((t) => {
+      const o = this.getSafeName(e, t.name);
       if (this.has(o))
-        throw new A(
+        throw new R(
           `Tool name collision for '${o}'`,
           "E_TOOL_NAME_CONFLICT"
         );
-      return { ...s, name: o };
+      return { ...t, name: o };
     });
   }
   list() {
@@ -199,14 +208,28 @@ class I {
   }
   listByToolset() {
     const e = {};
-    for (const [t, s] of this.toolsetToNames.entries())
-      e[t] = Array.from(s);
+    for (const [s, t] of this.toolsetToNames.entries())
+      e[s] = Array.from(t);
     return e;
   }
 }
-class W {
+class oe {
   constructor(e) {
-    this.activeToolsets = /* @__PURE__ */ new Set(), this.server = e.server, this.resolver = e.resolver, this.context = e.context, this.onToolsListChanged = e.onToolsListChanged, this.exposurePolicy = e.exposurePolicy, this.toolRegistry = e.toolRegistry ?? new I({ namespaceWithToolset: !0 });
+    this.activeToolsets = /* @__PURE__ */ new Set(), this.server = e.server, this.resolver = e.resolver, this.context = e.context, this.onToolsListChanged = e.onToolsListChanged, this.exposurePolicy = e.exposurePolicy, this.toolRegistry = e.toolRegistry ?? new z({ namespaceWithToolset: !0 });
+  }
+  /**
+   * Sends a tool list change notification if configured.
+   * Logs warnings on failure instead of throwing.
+   * @returns Promise that resolves when notification is sent (or skipped)
+   * @private
+   */
+  async notifyToolsChanged() {
+    if (this.onToolsListChanged)
+      try {
+        await this.onToolsListChanged();
+      } catch (e) {
+        console.warn("Failed to send tool list change notification:", e);
+      }
   }
   getAvailableToolsets() {
     return this.resolver.getAvailableToolsets();
@@ -220,90 +243,113 @@ class W {
   isActive(e) {
     return this.activeToolsets.has(e);
   }
-  async enableToolset(e) {
+  /**
+   * Enables a single toolset by name.
+   * Validates the toolset, checks exposure policies, resolves tools, and registers them.
+   * @param toolsetName - The name of the toolset to enable
+   * @param skipNotification - If true, skips the tool list change notification (for batch operations)
+   * @returns Result object with success status and message
+   */
+  async enableToolset(e, s = !1) {
     const t = this.resolver.validateToolsetName(e);
     if (!t.isValid || !t.sanitized)
       return {
         success: !1,
         message: t.error || "Unknown validation error"
       };
-    const s = t.sanitized;
-    if (this.activeToolsets.has(s))
+    const o = t.sanitized;
+    if (this.activeToolsets.has(o))
       return {
         success: !1,
-        message: `Toolset '${s}' is already enabled.`
+        message: `Toolset '${o}' is already enabled.`
       };
+    const i = this.checkExposurePolicy(o);
+    if (!i.allowed)
+      return { success: !1, message: i.message };
+    const n = [];
     try {
-      const o = await this.resolver.resolveToolsForToolsets(
-        [s],
+      const l = await this.resolver.resolveToolsForToolsets(
+        [o],
         this.context
       );
-      if (this.exposurePolicy?.allowlist && !this.exposurePolicy.allowlist.includes(s))
-        return {
-          success: !1,
-          message: `Toolset '${s}' is not allowed by policy.`
-        };
-      if (this.exposurePolicy?.denylist && this.exposurePolicy.denylist.includes(s))
-        return {
-          success: !1,
-          message: `Toolset '${s}' is denied by policy.`
-        };
-      if (this.exposurePolicy?.maxActiveToolsets !== void 0 && this.activeToolsets.size + 1 > this.exposurePolicy.maxActiveToolsets)
-        return this.exposurePolicy.onLimitExceeded?.(
-          [s],
-          Array.from(this.activeToolsets)
-        ), {
-          success: !1,
-          message: `Activation exceeds maxActiveToolsets (${this.exposurePolicy.maxActiveToolsets}).`
-        };
-      if (o && o.length > 0) {
-        const i = this.toolRegistry.mapAndValidate(
-          s,
-          o
+      if (l && l.length > 0) {
+        const a = this.toolRegistry.mapAndValidate(
+          o,
+          l
         );
-        this.registerDirectTools(i, s);
-      }
-      this.activeToolsets.add(s);
-      try {
-        await this.onToolsListChanged?.();
-      } catch (i) {
-        console.warn("Failed to send tool list change notification:", i);
+        for (const c of a)
+          this.registerSingleTool(c, o), n.push(c.name);
       }
-      return {
+      return this.activeToolsets.add(o), s || await this.notifyToolsChanged(), {
         success: !0,
-        message: `Toolset '${s}' enabled successfully. Registered ${o?.length ?? 0} tools.`
+        message: `Toolset '${o}' enabled successfully. Registered ${l?.length ?? 0} tools.`
       };
-    } catch (o) {
-      return this.activeToolsets.delete(s), {
+    } catch (l) {
+      return n.length > 0 && console.warn(
+        `Partial failure enabling toolset '${o}'. ${n.length} tools were registered but toolset activation failed. Tools remain registered due to MCP limitations: ${n.join(", ")}`
+      ), {
         success: !1,
-        message: `Failed to enable toolset '${s}': ${o instanceof Error ? o.message : "Unknown error"}`
+        message: `Failed to enable toolset '${o}': ${l instanceof Error ? l.message : "Unknown error"}`
       };
     }
   }
+  /**
+   * Checks if a toolset is allowed by the exposure policy.
+   * @param toolsetName - The sanitized toolset name to check
+   * @returns Object indicating if allowed and reason message if not
+   * @private
+   */
+  checkExposurePolicy(e) {
+    return this.exposurePolicy?.allowlist && !this.exposurePolicy.allowlist.includes(e) ? {
+      allowed: !1,
+      message: `Toolset '${e}' is not allowed by policy.`
+    } : this.exposurePolicy?.denylist && this.exposurePolicy.denylist.includes(e) ? {
+      allowed: !1,
+      message: `Toolset '${e}' is denied by policy.`
+    } : this.exposurePolicy?.maxActiveToolsets !== void 0 && this.activeToolsets.size + 1 > this.exposurePolicy.maxActiveToolsets ? (this.exposurePolicy.onLimitExceeded?.(
+      [e],
+      Array.from(this.activeToolsets)
+    ), {
+      allowed: !1,
+      message: `Activation exceeds maxActiveToolsets (${this.exposurePolicy.maxActiveToolsets}).`
+    }) : { allowed: !0, message: "" };
+  }
+  /**
+   * Registers a single tool with the MCP server.
+   * @param tool - The tool definition to register
+   * @param toolsetKey - The toolset key for tracking
+   * @private
+   */
+  registerSingleTool(e, s) {
+    this.server.tool(
+      e.name,
+      e.description,
+      e.inputSchema,
+      async (t) => await e.handler(t)
+    ), this.toolRegistry.addForToolset(s, e.name);
+  }
+  /**
+   * Disables a toolset by name.
+   * Note: Due to MCP limitations, tools remain registered but the toolset is marked inactive.
+   * @param toolsetName - The name of the toolset to disable
+   * @returns Result object with success status and message
+   */
   async disableToolset(e) {
-    const t = this.resolver.validateToolsetName(e);
-    if (!t.isValid || !t.sanitized) {
+    const s = this.resolver.validateToolsetName(e);
+    if (!s.isValid || !s.sanitized) {
       const o = Array.from(this.activeToolsets).join(", ") || "none";
       return {
         success: !1,
-        message: `${t.error || "Unknown validation error"} Active toolsets: ${o}`
+        message: `${s.error || "Unknown validation error"} Active toolsets: ${o}`
       };
     }
-    const s = t.sanitized;
-    if (!this.activeToolsets.has(s))
-      return {
-        success: !1,
-        message: `Toolset '${s}' is not currently active. Active toolsets: ${Array.from(this.activeToolsets).join(", ") || "none"}`
-      };
-    this.activeToolsets.delete(s);
-    try {
-      await this.onToolsListChanged?.();
-    } catch (o) {
-      console.warn("Failed to send tool list change notification:", o);
-    }
-    return {
+    const t = s.sanitized;
+    return this.activeToolsets.has(t) ? (this.activeToolsets.delete(t), await this.notifyToolsChanged(), {
       success: !0,
-      message: `Toolset '${s}' disabled successfully. Individual tools remain registered due to MCP limitations.`
+      message: `Toolset '${t}' disabled successfully. Individual tools remain registered due to MCP limitations.`
+    }) : {
+      success: !1,
+      message: `Toolset '${t}' is not currently active. Active toolsets: ${Array.from(this.activeToolsets).join(", ") || "none"}`
     };
   }
   getStatus() {
@@ -317,121 +363,112 @@ class W {
       toolsetToTools: this.toolRegistry.listByToolset()
     };
   }
+  /**
+   * Enables multiple toolsets in a batch operation.
+   * Sends a single notification after all toolsets are processed.
+   * @param toolsetNames - Array of toolset names to enable
+   * @returns Result object with overall success status and individual results
+   */
   async enableToolsets(e) {
-    const t = [];
-    for (const i of e)
+    const s = [];
+    for (const n of e)
       try {
-        const a = await this.enableToolset(i);
-        t.push({ name: i, ...a });
-      } catch (a) {
-        t.push({
-          name: i,
+        const l = await this.enableToolset(n, !0);
+        s.push({ name: n, ...l });
+      } catch (l) {
+        s.push({
+          name: n,
           success: !1,
-          message: a instanceof Error ? a.message : "Unknown error",
+          message: l instanceof Error ? l.message : "Unknown error",
           code: "E_INTERNAL"
         });
       }
-    const s = t.every((i) => i.success), o = s ? "All toolsets enabled" : "Some toolsets failed to enable";
-    if (t.length > 0)
-      try {
-        await this.onToolsListChanged?.();
-      } catch {
-      }
-    return { success: s, results: t, message: o };
-  }
-  registerDirectTools(e, t) {
-    for (const s of e)
-      try {
-        this.server.tool(
-          s.name,
-          s.description,
-          s.inputSchema,
-          async (o) => await s.handler(o)
-        ), t ? this.toolRegistry.addForToolset(t, s.name) : this.toolRegistry.add(s.name);
-      } catch (o) {
-        throw console.error(`Failed to register direct tool '${s.name}':`, o), o;
-      }
+    const t = s.every((n) => n.success), o = s.some((n) => n.success), i = t ? "All toolsets enabled" : o ? "Some toolsets failed to enable" : "All toolsets failed to enable";
+    return o && await this.notifyToolsChanged(), { success: t, results: s, message: i };
   }
+  /**
+   * Enables all available toolsets in a batch operation.
+   * @returns Result object with overall success status and individual results
+   */
   async enableAllToolsets() {
     const e = this.getAvailableToolsets();
     return this.enableToolsets(e);
   }
 }
-function H(r, e, t) {
-  const s = t?.mode ?? "DYNAMIC";
-  r.tool(
+function re(r, e, s) {
+  (s?.mode ?? "DYNAMIC") === "DYNAMIC" && (r.tool(
     "enable_toolset",
     "Enable a toolset by name",
-    { name: T.string().describe("Toolset name") },
+    { name: b.string().describe("Toolset name") },
     async (o) => {
-      const { name: i } = o, a = await e.enableToolset(i);
+      const i = await e.enableToolset(o.name);
       return {
-        content: [{ type: "text", text: JSON.stringify(a) }]
+        content: [{ type: "text", text: JSON.stringify(i) }]
       };
     }
   ), r.tool(
     "disable_toolset",
     "Disable a toolset by name (state only)",
-    { name: T.string().describe("Toolset name") },
+    { name: b.string().describe("Toolset name") },
     async (o) => {
-      const { name: i } = o, a = await e.disableToolset(i);
+      const i = await e.disableToolset(o.name);
       return {
-        content: [{ type: "text", text: JSON.stringify(a) }]
+        content: [{ type: "text", text: JSON.stringify(i) }]
       };
     }
-  ), s === "DYNAMIC" && (r.tool(
+  ), r.tool(
     "list_toolsets",
     "List available toolsets with active status and definitions",
     {},
     async () => {
-      const o = e.getAvailableToolsets(), i = e.getStatus().toolsetToTools, a = o.map((l) => {
-        const n = e.getToolsetDefinition(l);
+      const o = e.getAvailableToolsets(), i = e.getStatus().toolsetToTools, n = o.map((l) => {
+        const a = e.getToolsetDefinition(l);
         return {
           key: l,
           active: e.isActive(l),
-          definition: n ? {
-            name: n.name,
-            description: n.description,
-            modules: n.modules ?? [],
-            decisionCriteria: n.decisionCriteria ?? void 0
+          definition: a ? {
+            name: a.name,
+            description: a.description,
+            modules: a.modules ?? [],
+            decisionCriteria: a.decisionCriteria ?? void 0
           } : null,
           tools: i[l] ?? []
         };
       });
       return {
         content: [
-          { type: "text", text: JSON.stringify({ toolsets: a }) }
+          { type: "text", text: JSON.stringify({ toolsets: n }) }
         ]
       };
     }
   ), r.tool(
     "describe_toolset",
     "Describe a toolset with definition, active status and tools",
-    { name: T.string().describe("Toolset name") },
+    { name: b.string().describe("Toolset name") },
     async (o) => {
-      const { name: i } = o, a = e.getToolsetDefinition(i), l = e.getStatus().toolsetToTools;
-      if (!a)
+      const i = e.getToolsetDefinition(o.name), n = e.getStatus().toolsetToTools;
+      if (!i)
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({ error: `Unknown toolset '${i}'` })
+              text: JSON.stringify({ error: `Unknown toolset '${o.name}'` })
             }
           ]
         };
-      const n = {
-        key: i,
-        active: e.isActive(i),
+      const l = {
+        key: o.name,
+        active: e.isActive(o.name),
         definition: {
-          name: a.name,
-          description: a.description,
-          modules: a.modules ?? [],
-          decisionCriteria: a.decisionCriteria ?? void 0
+          name: i.name,
+          description: i.description,
+          modules: i.modules ?? [],
+          decisionCriteria: i.decisionCriteria ?? void 0
         },
-        tools: l[i] ?? []
+        tools: n[o.name] ?? []
       };
       return {
-        content: [{ type: "text", text: JSON.stringify(n) }]
+        content: [{ type: "text", text: JSON.stringify(l) }]
       };
     }
   )), r.tool(
@@ -449,41 +486,72 @@ function H(r, e, t) {
     }
   );
 }
-class y {
+class w {
   constructor(e) {
-    this.toolsetValidator = new Y();
-    const t = e.startup ?? {}, s = this.resolveStartupConfig(t, e.catalog);
-    this.mode = s.mode, this.resolver = new U({
+    this.initError = null, this.toolsetValidator = new se();
+    const s = e.startup ?? {}, t = this.resolveStartupConfig(s, e.catalog);
+    this.mode = t.mode, this.resolver = new te({
       catalog: e.catalog,
       moduleLoaders: e.moduleLoaders
     });
-    const o = new I({
+    const o = new z({
       namespaceWithToolset: e.exposurePolicy?.namespaceToolsWithSetKey ?? !0
     });
-    this.manager = new W({
+    this.manager = new oe({
       server: e.server,
       resolver: this.resolver,
       context: e.context,
       onToolsListChanged: e.notifyToolsListChanged,
       exposurePolicy: e.exposurePolicy,
       toolRegistry: o
-    }), e.registerMetaTools !== !1 && H(e.server, this.manager, { mode: this.mode });
-    const i = s.toolsets;
-    i === "ALL" ? this.manager.enableToolsets(this.resolver.getAvailableToolsets()) : Array.isArray(i) && i.length > 0 && this.manager.enableToolsets(i);
+    }), e.registerMetaTools !== !1 && re(e.server, this.manager, { mode: this.mode });
+    const i = t.toolsets;
+    this.initPromise = this.initializeToolsets(i);
+  }
+  /**
+   * Initializes toolsets asynchronously during construction.
+   * Stores any errors for later retrieval via ensureReady().
+   * @param initial - The toolsets to initialize or "ALL"
+   * @returns Promise that resolves when initialization is complete
+   * @private
+   */
+  async initializeToolsets(e) {
+    try {
+      e === "ALL" ? await this.manager.enableToolsets(this.resolver.getAvailableToolsets()) : Array.isArray(e) && e.length > 0 && await this.manager.enableToolsets(e);
+    } catch (s) {
+      this.initError = s instanceof Error ? s : new Error(String(s)), console.error("Failed to initialize toolsets:", this.initError);
+    }
+  }
+  /**
+   * Waits for the orchestrator to be fully initialized.
+   * Call this before using the orchestrator to ensure all toolsets are loaded.
+   * @throws {Error} If initialization failed
+   */
+  async ensureReady() {
+    if (await this.initPromise, this.initError)
+      throw this.initError;
+  }
+  /**
+   * Checks if the orchestrator has finished initialization.
+   * Does not throw on error - use ensureReady() for that.
+   * @returns Promise that resolves to true if ready, false if initialization failed
+   */
+  async isReady() {
+    return await this.initPromise, this.initError === null;
   }
-  resolveStartupConfig(e, t) {
+  resolveStartupConfig(e, s) {
     if (e.mode) {
       if (e.mode === "DYNAMIC" && e.toolsets)
         return console.warn("startup.toolsets provided but ignored in DYNAMIC mode"), { mode: "DYNAMIC" };
       if (e.mode === "STATIC") {
         if (e.toolsets === "ALL")
           return { mode: "STATIC", toolsets: "ALL" };
-        const s = Array.isArray(e.toolsets) ? e.toolsets : [], o = [];
-        for (const i of s) {
-          const { isValid: a, sanitized: l, error: n } = this.toolsetValidator.validateToolsetName(i, t);
-          a && l ? o.push(l) : n && console.warn(n);
+        const t = Array.isArray(e.toolsets) ? e.toolsets : [], o = [];
+        for (const i of t) {
+          const { isValid: n, sanitized: l, error: a } = this.toolsetValidator.validateToolsetName(i, s);
+          n && l ? o.push(l) : a && console.warn(a);
         }
-        if (s.length > 0 && o.length === 0)
+        if (t.length > 0 && o.length === 0)
           throw new Error(
             "STATIC mode requires valid toolsets or 'ALL'; none were valid"
           );
@@ -493,16 +561,16 @@ class y {
     }
     if (e.toolsets === "ALL") return { mode: "STATIC", toolsets: "ALL" };
     if (Array.isArray(e.toolsets) && e.toolsets.length > 0) {
-      const s = [];
+      const t = [];
       for (const o of e.toolsets) {
-        const { isValid: i, sanitized: a, error: l } = this.toolsetValidator.validateToolsetName(o, t);
-        i && a ? s.push(a) : l && console.warn(l);
+        const { isValid: i, sanitized: n, error: l } = this.toolsetValidator.validateToolsetName(o, s);
+        i && n ? t.push(n) : l && console.warn(l);
       }
-      if (s.length === 0)
+      if (t.length === 0)
         throw new Error(
           "STATIC mode requires valid toolsets or 'ALL'; none were valid"
         );
-      return { mode: "STATIC", toolsets: s };
+      return { mode: "STATIC", toolsets: t };
     }
     return { mode: "DYNAMIC" };
   }
@@ -513,11 +581,13 @@ class y {
     return this.manager;
   }
 }
-class P {
+var v, S;
+class O {
   constructor(e = {}) {
-    this.storage = /* @__PURE__ */ new Map(), this.maxSize = e.maxSize ?? 1e3, this.ttlMs = e.ttlMs ?? 1e3 * 60 * 60;
-    const t = e.pruneIntervalMs ?? 1e3 * 60 * 10;
-    this.pruneInterval = setInterval(() => this.pruneExpired(), t);
+    T(this, v);
+    this.storage = /* @__PURE__ */ new Map(), this.maxSize = e.maxSize ?? 1e3, this.ttlMs = e.ttlMs ?? 1e3 * 60 * 60, this.onEvict = e.onEvict;
+    const s = e.pruneIntervalMs ?? 1e3 * 60 * 10;
+    this.pruneInterval = setInterval(() => this.pruneExpired(), s);
   }
   getEntryCount() {
     return this.storage.size;
@@ -529,47 +599,184 @@ class P {
     return this.ttlMs;
   }
   get(e) {
-    const t = this.storage.get(e);
-    return t ? Date.now() - t.lastAccessed > this.ttlMs ? (this.delete(e), null) : (t.lastAccessed = Date.now(), this.storage.delete(e), this.storage.set(e, t), t.resource) : null;
+    const s = this.storage.get(e);
+    return s ? Date.now() - s.lastAccessed > this.ttlMs ? (this.delete(e), null) : (s.lastAccessed = Date.now(), this.storage.delete(e), this.storage.set(e, s), s.resource) : null;
   }
-  set(e, t) {
+  set(e, s) {
     this.storage.size >= this.maxSize && this.evictLeastRecentlyUsed();
-    const s = { resource: t, lastAccessed: Date.now() };
-    this.storage.set(e, s);
+    const t = { resource: s, lastAccessed: Date.now() };
+    this.storage.set(e, t);
   }
+  /**
+   * Removes an entry from the cache.
+   * Calls the onEvict callback if configured.
+   * @param key - The key to remove
+   */
   delete(e) {
-    this.storage.delete(e);
+    const s = this.storage.get(e);
+    s && (this.storage.delete(e), f(this, v, S).call(this, e, s.resource));
   }
-  stop() {
-    this.pruneInterval && (clearInterval(this.pruneInterval), this.pruneInterval = void 0);
+  /**
+   * Stops the background pruning interval and optionally clears all entries.
+   * @param clearEntries - If true, also removes all entries and calls onEvict for each
+   */
+  stop(e = !1) {
+    this.pruneInterval && (clearInterval(this.pruneInterval), this.pruneInterval = void 0), e && this.clear();
   }
+  /**
+   * Clears all entries from the cache.
+   * Calls onEvict for each entry being removed.
+   */
+  clear() {
+    const e = Array.from(this.storage.entries());
+    this.storage.clear();
+    for (const [s, t] of e)
+      f(this, v, S).call(this, s, t.resource);
+  }
+  /**
+   * Evicts the least recently used entry from the cache.
+   * @private
+   */
   evictLeastRecentlyUsed() {
     const e = this.storage.keys().next().value;
     e && this.delete(e);
   }
+  /**
+   * Removes all expired entries from the cache.
+   * @private
+   */
   pruneExpired() {
-    const e = Date.now();
-    for (const [t, s] of this.storage.entries())
-      e - s.lastAccessed > this.ttlMs && this.delete(t);
+    const e = Date.now(), s = [];
+    for (const [t, o] of this.storage.entries())
+      e - o.lastAccessed > this.ttlMs && s.push(t);
+    for (const t of s)
+      this.delete(t);
+  }
+}
+v = new WeakSet(), /**
+ * Safely calls the evict callback, catching and logging any errors.
+ * @param key - The key being evicted
+ * @param resource - The resource being evicted
+ * @private
+ */
+S = function(e, s) {
+  if (this.onEvict)
+    try {
+      const t = this.onEvict(e, s);
+      t instanceof Promise && t.catch((o) => {
+        console.warn(`Error in cache eviction callback for key '${e}':`, o);
+      });
+    } catch (t) {
+      console.warn(`Error in cache eviction callback for key '${e}':`, t);
+    }
+};
+function V(r, e, s, t) {
+  const o = ["/mcp", "/healthz", "/tools", "/.well-known/mcp-config"];
+  for (const i of s) {
+    const n = `${e}${i.path}`;
+    if (o.some(
+      (c) => n.startsWith(`${e}${c}`)
+    )) {
+      console.warn(
+        `Custom endpoint ${i.method} ${i.path} conflicts with built-in MCP endpoint. Skipping registration.`
+      );
+      continue;
+    }
+    const a = i.method.toLowerCase();
+    r[a](n, async (c, d) => {
+      try {
+        const u = c.headers["mcp-client-id"]?.trim(), p = u && u.length > 0 ? u : `anon-${y()}`;
+        let C;
+        if (i.bodySchema) {
+          const m = i.bodySchema.safeParse(c.body);
+          if (!m.success)
+            return A(d, "body", m.error);
+          C = m.data;
+        }
+        let x = {};
+        if (i.querySchema) {
+          const m = i.querySchema.safeParse(c.query);
+          if (!m.success)
+            return A(d, "query", m.error);
+          x = m.data;
+        }
+        let I = {};
+        if (i.paramsSchema) {
+          const m = i.paramsSchema.safeParse(c.params);
+          if (!m.success)
+            return A(d, "params", m.error);
+          I = m.data;
+        }
+        const M = {
+          body: C,
+          query: x,
+          params: I,
+          headers: c.headers,
+          clientId: p
+        };
+        if (t?.contextExtractor) {
+          const m = await t.contextExtractor(c);
+          Object.assign(M, m);
+        }
+        const $ = await i.handler(M);
+        if (i.responseSchema) {
+          const m = i.responseSchema.safeParse($);
+          return m.success ? m.data : (console.error(
+            `Response validation failed for ${i.method} ${i.path}:`,
+            m.error
+          ), d.code(500), {
+            error: {
+              code: "RESPONSE_VALIDATION_ERROR",
+              message: "Internal server error: invalid response format"
+            }
+          });
+        }
+        return $;
+      } catch (u) {
+        return console.error(
+          `Error in custom endpoint ${i.method} ${i.path}:`,
+          u
+        ), d.code(500), {
+          error: {
+            code: "INTERNAL_ERROR",
+            message: u instanceof Error ? u.message : "Internal server error"
+          }
+        };
+      }
+    });
   }
 }
-class J {
-  constructor(e, t, s = {}, o) {
-    this.app = null, this.clientCache = new P(), this.defaultManager = e, this.createBundle = t, this.options = {
-      host: s.host ?? "0.0.0.0",
-      port: s.port ?? 3e3,
-      basePath: s.basePath ?? "/",
-      cors: s.cors ?? !0,
-      logger: s.logger ?? !1,
-      app: s.app
+function A(r, e, s) {
+  return r.code(400), {
+    error: {
+      code: "VALIDATION_ERROR",
+      message: `Validation failed for ${e}`,
+      details: s.errors
+    }
+  };
+}
+class ie {
+  constructor(e, s, t = {}, o) {
+    this.app = null, this.clientCache = new O({
+      onEvict: (i, n) => {
+        this.cleanupBundle(n);
+      }
+    }), this.defaultManager = e, this.createBundle = s, this.options = {
+      host: t.host ?? "0.0.0.0",
+      port: t.port ?? 3e3,
+      basePath: t.basePath ?? "/",
+      cors: t.cors ?? !0,
+      logger: t.logger ?? !1,
+      app: t.app,
+      customEndpoints: t.customEndpoints
     }, this.configSchema = o;
   }
   async start() {
     if (this.app) return;
-    const e = this.options.app ?? S({ logger: this.options.logger });
-    this.options.cors && await e.register(M, { origin: !0 });
-    const t = this.options.basePath.endsWith("/") ? this.options.basePath.slice(0, -1) : this.options.basePath;
-    e.get(`${t}/healthz`, async () => ({ ok: !0 })), e.get(`${t}/tools`, async () => this.defaultManager.getStatus()), e.get(`${t}/.well-known/mcp-config`, async (s, o) => (o.header("Content-Type", "application/schema+json; charset=utf-8"), this.configSchema ?? {
+    const e = this.options.app ?? N({ logger: this.options.logger });
+    this.options.cors && await e.register(j, { origin: !0 });
+    const s = this.options.basePath.endsWith("/") ? this.options.basePath.slice(0, -1) : this.options.basePath;
+    e.get(`${s}/healthz`, async () => ({ ok: !0 })), e.get(`${s}/tools`, async () => this.defaultManager.getStatus()), e.get(`${s}/.well-known/mcp-config`, async (t, o) => (o.header("Content-Type", "application/schema+json; charset=utf-8"), this.configSchema ?? {
       $schema: "https://json-schema.org/draft/2020-12/schema",
       title: "MCP Session Configuration",
       description: "Schema for the /mcp endpoint configuration",
@@ -579,32 +786,32 @@ class J {
       "x-mcp-version": "1.0",
       "x-query-style": "dot+bracket"
     })), e.post(
-      `${t}/mcp`,
-      async (s, o) => {
-        const i = s.headers["mcp-client-id"]?.trim(), a = i && i.length > 0 ? i : `anon-${p()}`, l = !a.startsWith("anon-");
-        let n = l ? this.clientCache.get(a) : null;
-        if (!n) {
-          const f = this.createBundle(), g = f.sessions;
-          n = {
-            server: f.server,
-            orchestrator: f.orchestrator,
-            sessions: g instanceof Map ? g : /* @__PURE__ */ new Map()
-          }, l && this.clientCache.set(a, n);
+      `${s}/mcp`,
+      async (t, o) => {
+        const i = t.headers["mcp-client-id"]?.trim(), n = i && i.length > 0 ? i : `anon-${y()}`, l = !n.startsWith("anon-");
+        let a = l ? this.clientCache.get(n) : null;
+        if (!a) {
+          const u = this.createBundle(), p = u.sessions;
+          a = {
+            server: u.server,
+            orchestrator: u.orchestrator,
+            sessions: p instanceof Map ? p : /* @__PURE__ */ new Map()
+          }, l && this.clientCache.set(n, a);
         }
-        const c = s.headers["mcp-session-id"];
-        let h;
-        if (c && n.sessions.get(c))
-          h = n.sessions.get(c);
-        else if (!c && x(s.body)) {
-          const f = p();
-          h = new C({
-            sessionIdGenerator: () => f,
-            onsessioninitialized: (g) => {
-              n.sessions.set(g, h);
+        const c = t.headers["mcp-session-id"];
+        let d;
+        if (c && a.sessions.get(c))
+          d = a.sessions.get(c);
+        else if (!c && D(t.body)) {
+          const u = y();
+          d = new k({
+            sessionIdGenerator: () => u,
+            onsessioninitialized: (p) => {
+              a.sessions.set(p, d);
             }
           });
           try {
-            await n.server.connect(h);
+            await a.server.connect(d);
           } catch {
             return o.code(500), {
               jsonrpc: "2.0",
@@ -612,8 +819,8 @@ class J {
               id: null
             };
           }
-          h.onclose = () => {
-            h?.sessionId && n.sessions.delete(h.sessionId);
+          d.onclose = () => {
+            d?.sessionId && a.sessions.delete(d.sessionId);
           };
         } else
           return o.code(400), {
@@ -621,29 +828,29 @@ class J {
             error: { code: -32e3, message: "Session not found or expired" },
             id: null
           };
-        return await h.handleRequest(
-          s.raw,
+        return await d.handleRequest(
+          t.raw,
           o.raw,
-          s.body
+          t.body
         ), o;
       }
-    ), e.get(`${t}/mcp`, async (s, o) => {
-      const i = s.headers["mcp-client-id"]?.trim(), a = i && i.length > 0 ? i : "";
-      if (!a)
+    ), e.get(`${s}/mcp`, async (t, o) => {
+      const i = t.headers["mcp-client-id"]?.trim(), n = i && i.length > 0 ? i : "";
+      if (!n)
         return o.code(400), "Missing mcp-client-id";
-      const l = this.clientCache.get(a);
+      const l = this.clientCache.get(n);
       if (!l)
         return o.code(400), "Invalid or expired client";
-      const n = s.headers["mcp-session-id"];
-      if (!n)
+      const a = t.headers["mcp-session-id"];
+      if (!a)
         return o.code(400), "Missing mcp-session-id";
-      const c = l.sessions.get(n);
-      return c ? (await c.handleRequest(s.raw, o.raw), o) : (o.code(400), "Invalid or expired session ID");
+      const c = l.sessions.get(a);
+      return c ? (await c.handleRequest(t.raw, o.raw), o) : (o.code(400), "Invalid or expired session ID");
     }), e.delete(
-      `${t}/mcp`,
-      async (s, o) => {
-        const i = s.headers["mcp-client-id"]?.trim(), a = i && i.length > 0 ? i : "", l = s.headers["mcp-session-id"];
-        if (!a || !l)
+      `${s}/mcp`,
+      async (t, o) => {
+        const i = t.headers["mcp-client-id"]?.trim(), n = i && i.length > 0 ? i : "", l = t.headers["mcp-session-id"];
+        if (!n || !l)
           return o.code(400), {
             jsonrpc: "2.0",
             error: {
@@ -652,8 +859,8 @@ class J {
             },
             id: null
           };
-        const n = this.clientCache.get(a), c = n?.sessions.get(l);
-        if (!n || !c)
+        const a = this.clientCache.get(n), c = a?.sessions.get(l);
+        if (!a || !c)
           return o.code(404), {
             jsonrpc: "2.0",
             error: { code: -32e3, message: "Session not found or expired" },
@@ -666,62 +873,86 @@ class J {
             } catch {
             }
         } finally {
-          c?.sessionId ? n.sessions.delete(c.sessionId) : n.sessions.delete(l);
+          c?.sessionId ? a.sessions.delete(c.sessionId) : a.sessions.delete(l);
         }
         return o.code(204).send(), o;
       }
-    ), this.options.app || await e.listen({ host: this.options.host, port: this.options.port }), this.app = e;
+    ), this.options.customEndpoints && this.options.customEndpoints.length > 0 && V(e, s, this.options.customEndpoints), this.options.app || await e.listen({ host: this.options.host, port: this.options.port }), this.app = e;
   }
+  /**
+   * Stops the Fastify server and cleans up all resources.
+   * Closes all client sessions and clears the cache.
+   */
   async stop() {
-    this.app && (this.options.app || await this.app.close(), this.app = null);
+    this.app && (this.clientCache.stop(!0), this.options.app || await this.app.close(), this.app = null);
+  }
+  /**
+   * Cleans up resources associated with a client bundle.
+   * Closes all sessions within the bundle.
+   * @param bundle - The client bundle to clean up
+   * @private
+   */
+  cleanupBundle(e) {
+    for (const [s, t] of e.sessions.entries())
+      try {
+        typeof t.close == "function" && t.close().catch((o) => {
+          console.warn(`Error closing session ${s}:`, o);
+        });
+      } catch (o) {
+        console.warn(`Error closing session ${s}:`, o);
+      }
+    e.sessions.clear();
   }
 }
-async function de(r) {
+async function Se(r) {
   const e = r.startup?.mode ?? "DYNAMIC";
   if (typeof r.createServer != "function")
     throw new Error("createMcpServer: `createServer` (factory) is required");
-  const t = r.createServer(), s = (n) => typeof n?.server?.notification == "function", o = (n) => typeof n?.notifyToolsListChanged == "function", i = async (n) => {
+  const s = r.createServer(), t = (a) => typeof a?.server?.notification == "function", o = (a) => typeof a?.notifyToolsListChanged == "function", i = async (a) => {
     try {
-      if (s(n)) {
-        await n.server.notification({
+      if (t(a)) {
+        await a.server.notification({
           method: "notifications/tools/list_changed"
         });
         return;
       }
-      o(n) && await n.notifyToolsListChanged();
-    } catch {
+      o(a) && await a.notifyToolsListChanged();
+    } catch (c) {
+      if ((c instanceof Error ? c.message : String(c)) === "Not connected")
+        return;
+      console.warn("Failed to send tools list changed notification:", c);
     }
-  }, a = new y({
-    server: t,
+  }, n = new w({
+    server: s,
     catalog: r.catalog,
     moduleLoaders: r.moduleLoaders,
     exposurePolicy: r.exposurePolicy,
     context: r.context,
-    notifyToolsListChanged: async () => i(t),
+    notifyToolsListChanged: async () => i(s),
     startup: r.startup,
     registerMetaTools: r.registerMetaTools !== void 0 ? r.registerMetaTools : e === "DYNAMIC"
-  }), l = new J(
-    a.getManager(),
+  }), l = new ie(
+    n.getManager(),
     () => {
       if (e === "STATIC")
-        return { server: t, orchestrator: a };
-      const n = r.createServer(), c = new y({
-        server: n,
+        return { server: s, orchestrator: n };
+      const a = r.createServer(), c = new w({
+        server: a,
         catalog: r.catalog,
         moduleLoaders: r.moduleLoaders,
         exposurePolicy: r.exposurePolicy,
         context: r.context,
-        notifyToolsListChanged: async () => i(n),
+        notifyToolsListChanged: async () => i(a),
         startup: r.startup,
         registerMetaTools: r.registerMetaTools !== void 0 ? r.registerMetaTools : e === "DYNAMIC"
       });
-      return { server: n, orchestrator: c };
+      return { server: a, orchestrator: c };
     },
     r.http,
     r.configSchema
   );
   return {
-    server: t,
+    server: s,
     start: async () => {
       await l.start();
     },
@@ -730,16 +961,16 @@ async function de(r) {
     }
   };
 }
-function q(r) {
-  G(r), K(r), Q(r), X(r);
+function ne(r) {
+  ae(r), le(r), ce(r), de(r);
 }
-function G(r) {
+function ae(r) {
   if (!r || typeof r != "object")
     throw new Error(
       "Permission configuration is required for createPermissionBasedMcpServer"
     );
 }
-function K(r) {
+function le(r) {
   if (!r.source)
     throw new Error('Permission source must be either "headers" or "config"');
   if (r.source !== "headers" && r.source !== "config")
@@ -747,19 +978,19 @@ function K(r) {
       `Invalid permission source: "${r.source}". Must be either "headers" or "config"`
     );
 }
-function Q(r) {
+function ce(r) {
   if (r.source === "config" && !r.staticMap && !r.resolver)
     throw new Error(
       "Config-based permissions require at least one of: staticMap or resolver function"
     );
 }
-function X(r) {
+function de(r) {
   if (r.staticMap !== void 0) {
     if (typeof r.staticMap != "object" || r.staticMap === null)
       throw new Error(
         "staticMap must be an object mapping client IDs to toolset arrays"
       );
-    Z(r.staticMap);
+    he(r.staticMap);
   }
   if (r.resolver !== void 0 && typeof r.resolver != "function")
     throw new Error(
@@ -770,48 +1001,61 @@ function X(r) {
   if (r.headerName !== void 0 && (typeof r.headerName != "string" || r.headerName.length === 0))
     throw new Error("headerName must be a non-empty string");
 }
-function Z(r) {
-  for (const [e, t] of Object.entries(r))
-    if (!Array.isArray(t))
+function he(r) {
+  for (const [e, s] of Object.entries(r))
+    if (!Array.isArray(s))
       throw new Error(
         `staticMap value for client "${e}" must be an array of toolset names`
       );
 }
-var m, $, E, L, N;
-class ee {
+var g, F, _, B, H, W;
+class ue {
   /**
    * Creates a new PermissionResolver instance.
    * @param config - The permission configuration defining how permissions are resolved
    */
   constructor(e) {
-    v(this, m);
-    this.config = e, this.cache = /* @__PURE__ */ new Map();
+    T(this, g);
+    this.config = e, this.cache = /* @__PURE__ */ new Map(), this.normalizedHeaderName = (e.headerName || "mcp-toolset-permissions").toLowerCase();
   }
   /**
    * Resolves permissions for a client based on the configured source.
    * Results are cached to improve performance for subsequent requests from the same client.
    * Handles all errors gracefully by returning empty permissions on failure.
+   * 
+   * Note on caching: For header-based permissions, permissions are cached by clientId.
+   * This means subsequent requests from the same client will use cached permissions,
+   * even if headers change. Use invalidateCache(clientId) to force re-resolution.
+   * 
    * @param clientId - The unique identifier for the client
    * @param headers - Optional request headers (required for header-based permissions)
    * @returns Array of toolset names the client is allowed to access
    */
-  resolvePermissions(e, t) {
+  resolvePermissions(e, s) {
     if (this.cache.has(e))
       return this.cache.get(e);
-    let s;
+    let t;
     try {
-      this.config.source === "headers" ? s = u(this, m, $).call(this, t) : s = u(this, m, E).call(this, e), Array.isArray(s) || (console.warn(
+      this.config.source === "headers" ? t = f(this, g, F).call(this, s) : t = f(this, g, B).call(this, e), Array.isArray(t) || (console.warn(
         `Permission resolution returned non-array for client ${e}, using empty permissions`
-      ), s = []), s = s.filter(
+      ), t = []), t = t.filter(
         (o) => typeof o == "string" && o.trim().length > 0
       );
     } catch (o) {
       console.error(
         `Unexpected error resolving permissions for client ${e}:`,
         o
-      ), s = [];
+      ), t = [];
     }
-    return this.cache.set(e, s), s;
+    return this.cache.set(e, t), t;
+  }
+  /**
+   * Invalidates cached permissions for a specific client.
+   * Call this when you know a client's permissions have changed.
+   * @param clientId - The client ID to invalidate
+   */
+  invalidateCache(e) {
+    this.cache.delete(e);
   }
   /**
    * Clears the permission cache.
@@ -821,26 +1065,43 @@ class ee {
     this.cache.clear();
   }
 }
-m = new WeakSet(), /**
+g = new WeakSet(), /**
  * Parses permissions from request headers.
  * Extracts comma-separated toolset names from the configured header.
  * Handles malformed headers gracefully by returning empty permissions.
+ * Uses case-insensitive header lookup per RFC 7230.
  * @param headers - Request headers containing permission data
  * @returns Array of toolset names from headers, or empty array if header is missing/malformed
  * @private
  */
-$ = function(e) {
-  const t = this.config.headerName || "mcp-toolset-permissions", s = e?.[t];
+F = function(e) {
+  if (!e)
+    return [];
+  const s = f(this, g, _).call(this, e, this.normalizedHeaderName);
   if (!s)
     return [];
   try {
-    return s.split(",").map((o) => o.trim()).filter((o) => o.length > 0);
-  } catch (o) {
+    return s.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+  } catch (t) {
     return console.warn(
-      `Failed to parse permission header '${t}':`,
-      o
+      `Failed to parse permission header '${this.normalizedHeaderName}':`,
+      t
     ), [];
   }
+}, /**
+ * Finds a header value using case-insensitive key matching.
+ * HTTP headers are case-insensitive per RFC 7230.
+ * @param headers - The headers object to search
+ * @param normalizedKey - The lowercase key to search for
+ * @returns The header value if found, undefined otherwise
+ * @private
+ */
+_ = function(e, s) {
+  if (e[s] !== void 0)
+    return e[s];
+  for (const [t, o] of Object.entries(e))
+    if (t.toLowerCase() === s)
+      return o;
 }, /**
  * Resolves permissions from server-side configuration.
  * Tries resolver function first (if provided), then falls back to static map,
@@ -849,16 +1110,16 @@ $ = function(e) {
  * @returns Array of toolset names from configuration
  * @private
  */
-E = function(e) {
+B = function(e) {
   if (this.config.resolver) {
-    const t = u(this, m, L).call(this, e);
-    if (t !== null)
-      return t;
+    const s = f(this, g, H).call(this, e);
+    if (s !== null)
+      return s;
   }
   if (this.config.staticMap) {
-    const t = u(this, m, N).call(this, e);
-    if (t !== null)
-      return t;
+    const s = f(this, g, W).call(this, e);
+    if (s !== null)
+      return s;
   }
   return this.config.defaultPermissions || [];
 }, /**
@@ -868,16 +1129,16 @@ E = function(e) {
  * @returns Array of toolset names if successful, null if resolver fails or returns invalid data
  * @private
  */
-L = function(e) {
+H = function(e) {
   try {
-    const t = this.config.resolver(e);
-    return Array.isArray(t) ? t : (console.warn(
+    const s = this.config.resolver(e);
+    return Array.isArray(s) ? s : (console.warn(
       `Permission resolver returned non-array for client ${e}, using fallback`
     ), null);
-  } catch (t) {
-    const s = t instanceof Error ? t.message : String(t);
+  } catch (s) {
+    const t = s instanceof Error ? s.message : String(s);
     return console.warn(
-      `Permission resolver declined client ${e} (${s}), trying fallback`
+      `Permission resolver declined client ${e} (${t}), trying fallback`
     ), null;
   }
 }, /**
@@ -887,25 +1148,37 @@ L = function(e) {
  * @returns Array of toolset names if found, null if client not in map
  * @private
  */
-N = function(e) {
-  const t = this.config.staticMap[e];
-  return t !== void 0 ? Array.isArray(t) ? t : [] : null;
+W = function(e) {
+  const s = this.config.staticMap[e];
+  return s !== void 0 ? Array.isArray(s) ? s : [] : null;
 };
-function se(r, e) {
-  return async (t) => {
-    const s = e.resolvePermissions(
-      t.clientId,
-      t.headers
-    ), o = r(s), i = o.orchestrator.getManager();
-    return s.length > 0 && await i.enableToolsets(s), {
+function fe(r, e) {
+  return async (s) => {
+    const t = e.resolvePermissions(
+      s.clientId,
+      s.headers
+    ), o = r(t), i = o.orchestrator.getManager(), n = [], l = [];
+    if (t.length > 0) {
+      const a = await i.enableToolsets(t);
+      for (const c of a.results)
+        c.success ? n.push(c.name) : (l.push(c.name), console.warn(
+          `Failed to enable toolset '${c.name}' for client '${s.clientId}': ${c.message}`
+        ));
+      if (n.length === 0 && l.length > 0)
+        throw new Error(
+          `All requested toolsets failed to enable for client '${s.clientId}'. Requested: [${t.join(", ")}]. Check that toolset names in permissions match the catalog.`
+        );
+    }
+    return {
       server: o.server,
       orchestrator: o.orchestrator,
-      allowedToolsets: s
+      allowedToolsets: n,
+      failedToolsets: l
     };
   };
 }
-var d, D, j, z, O, R, k, F, V, _;
-class te {
+var h, Y, U, q, J, G, K, Q, X, E, Z;
+class me {
   /**
    * Creates a new PermissionAwareFastifyTransport instance.
    * @param defaultManager - Default tool manager for status endpoints
@@ -913,15 +1186,20 @@ class te {
    * @param options - Transport configuration options
    * @param configSchema - Optional JSON schema for configuration discovery
    */
-  constructor(e, t, s = {}, o) {
-    v(this, d);
-    this.app = null, this.clientCache = new P(), this.defaultManager = e, this.createPermissionAwareBundle = t, this.options = {
-      host: s.host ?? "0.0.0.0",
-      port: s.port ?? 3e3,
-      basePath: s.basePath ?? "/",
-      cors: s.cors ?? !0,
-      logger: s.logger ?? !1,
-      app: s.app
+  constructor(e, s, t = {}, o) {
+    T(this, h);
+    this.app = null, this.clientCache = new O({
+      onEvict: (i, n) => {
+        f(this, h, Y).call(this, n);
+      }
+    }), this.defaultManager = e, this.createPermissionAwareBundle = s, this.options = {
+      host: t.host ?? "0.0.0.0",
+      port: t.port ?? 3e3,
+      basePath: t.basePath ?? "/",
+      cors: t.cors ?? !0,
+      logger: t.logger ?? !1,
+      app: t.app,
+      customEndpoints: t.customEndpoints
     }, this.configSchema = o;
   }
   /**
@@ -930,25 +1208,60 @@ class te {
    */
   async start() {
     if (this.app) return;
-    const e = this.options.app ?? S({ logger: this.options.logger });
-    this.options.cors && await e.register(M, { origin: !0 });
-    const t = u(this, d, D).call(this, this.options.basePath);
-    u(this, d, j).call(this, e, t), u(this, d, z).call(this, e, t), u(this, d, O).call(this, e, t), u(this, d, R).call(this, e, t), u(this, d, k).call(this, e, t), u(this, d, F).call(this, e, t), this.options.app || await e.listen({ host: this.options.host, port: this.options.port }), this.app = e;
+    const e = this.options.app ?? N({ logger: this.options.logger });
+    this.options.cors && await e.register(j, { origin: !0 });
+    const s = f(this, h, U).call(this, this.options.basePath);
+    f(this, h, q).call(this, e, s), f(this, h, J).call(this, e, s), f(this, h, G).call(this, e, s), f(this, h, K).call(this, e, s), f(this, h, Q).call(this, e, s), f(this, h, X).call(this, e, s), this.options.customEndpoints && this.options.customEndpoints.length > 0 && V(e, s, this.options.customEndpoints, {
+      contextExtractor: async (t) => {
+        const o = f(this, h, E).call(this, t);
+        try {
+          const i = await this.createPermissionAwareBundle(o);
+          return {
+            allowedToolsets: i.allowedToolsets,
+            failedToolsets: i.failedToolsets
+          };
+        } catch (i) {
+          return console.warn(
+            `Permission resolution failed for custom endpoint: ${i}`
+          ), {
+            allowedToolsets: [],
+            failedToolsets: []
+          };
+        }
+      }
+    }), this.options.app || await e.listen({ host: this.options.host, port: this.options.port }), this.app = e;
   }
   /**
-   * Stops the Fastify server and cleans up resources.
+   * Stops the Fastify server and cleans up all resources.
+   * Closes all client sessions and clears the cache.
    */
   async stop() {
-    this.app && (this.options.app || await this.app.close(), this.app = null);
+    this.app && (this.clientCache.stop(!0), this.options.app || await this.app.close(), this.app = null);
   }
 }
-d = new WeakSet(), /**
+h = new WeakSet(), /**
+ * Cleans up resources associated with a client bundle.
+ * Closes all sessions within the bundle.
+ * @param bundle - The client bundle to clean up
+ * @private
+ */
+Y = function(e) {
+  for (const [s, t] of e.sessions.entries())
+    try {
+      typeof t.close == "function" && t.close().catch((o) => {
+        console.warn(`Error closing session ${s}:`, o);
+      });
+    } catch (o) {
+      console.warn(`Error closing session ${s}:`, o);
+    }
+  e.sessions.clear();
+}, /**
  * Normalizes the base path by removing trailing slashes.
  * @param basePath - The base path to normalize
  * @returns Normalized base path without trailing slash
  * @private
  */
-D = function(e) {
+U = function(e) {
   return e.endsWith("/") ? e.slice(0, -1) : e;
 }, /**
  * Registers the health check endpoint.
@@ -956,24 +1269,24 @@ D = function(e) {
  * @param base - Base path for routes
  * @private
  */
-j = function(e, t) {
-  e.get(`${t}/healthz`, async () => ({ ok: !0 }));
+q = function(e, s) {
+  e.get(`${s}/healthz`, async () => ({ ok: !0 }));
 }, /**
  * Registers the tools status endpoint.
  * @param app - Fastify instance
  * @param base - Base path for routes
  * @private
  */
-z = function(e, t) {
-  e.get(`${t}/tools`, async () => this.defaultManager.getStatus());
+J = function(e, s) {
+  e.get(`${s}/tools`, async () => this.defaultManager.getStatus());
 }, /**
  * Registers the MCP configuration discovery endpoint.
  * @param app - Fastify instance
  * @param base - Base path for routes
  * @private
  */
-O = function(e, t) {
-  e.get(`${t}/.well-known/mcp-config`, async (s, o) => (o.header("Content-Type", "application/schema+json; charset=utf-8"), this.configSchema ?? {
+G = function(e, s) {
+  e.get(`${s}/.well-known/mcp-config`, async (t, o) => (o.header("Content-Type", "application/schema+json; charset=utf-8"), this.configSchema ?? {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     title: "MCP Session Configuration",
     description: "Schema for the /mcp endpoint configuration",
@@ -990,37 +1303,42 @@ O = function(e, t) {
  * @param base - Base path for routes
  * @private
  */
-R = function(e, t) {
+K = function(e, s) {
   e.post(
-    `${t}/mcp`,
-    async (s, o) => {
-      const i = u(this, d, V).call(this, s), a = !i.clientId.startsWith("anon-");
-      let l = a ? this.clientCache.get(i.clientId) : null;
+    `${s}/mcp`,
+    async (t, o) => {
+      const i = f(this, h, E).call(this, t), n = !i.clientId.startsWith("anon-");
+      let l = n ? this.clientCache.get(i.clientId) : null;
       if (!l)
         try {
-          const h = await this.createPermissionAwareBundle(i), f = h.sessions;
+          const d = await this.createPermissionAwareBundle(i);
+          d.failedToolsets.length > 0 && console.warn(
+            `Client ${i.clientId} had ${d.failedToolsets.length} toolsets fail to enable: [${d.failedToolsets.join(", ")}]. Successfully enabled: [${d.allowedToolsets.join(", ")}]`
+          );
+          const u = d.sessions;
           l = {
-            server: h.server,
-            orchestrator: h.orchestrator,
-            allowedToolsets: h.allowedToolsets,
-            sessions: f instanceof Map ? f : /* @__PURE__ */ new Map()
-          }, a && this.clientCache.set(i.clientId, l);
-        } catch (h) {
+            server: d.server,
+            orchestrator: d.orchestrator,
+            allowedToolsets: d.allowedToolsets,
+            failedToolsets: d.failedToolsets,
+            sessions: u instanceof Map ? u : /* @__PURE__ */ new Map()
+          }, n && this.clientCache.set(i.clientId, l);
+        } catch (d) {
           return console.error(
             `Failed to create permission-aware bundle for client ${i.clientId}:`,
-            h
-          ), o.code(403), u(this, d, _).call(this, "Access denied");
+            d
+          ), o.code(403), f(this, h, Z).call(this, "Access denied");
         }
-      const n = s.headers["mcp-session-id"];
+      const a = t.headers["mcp-session-id"];
       let c;
-      if (n && l.sessions.get(n))
-        c = l.sessions.get(n);
-      else if (!n && x(s.body)) {
-        const h = p();
-        c = new C({
-          sessionIdGenerator: () => h,
-          onsessioninitialized: (f) => {
-            l.sessions.set(f, c);
+      if (a && l.sessions.get(a))
+        c = l.sessions.get(a);
+      else if (!a && D(t.body)) {
+        const d = y();
+        c = new k({
+          sessionIdGenerator: () => d,
+          onsessioninitialized: (u) => {
+            l.sessions.set(u, c);
           }
         });
         try {
@@ -1042,9 +1360,9 @@ R = function(e, t) {
           id: null
         };
       return await c.handleRequest(
-        s.raw,
+        t.raw,
         o.raw,
-        s.body
+        t.body
       ), o;
     }
   );
@@ -1054,19 +1372,19 @@ R = function(e, t) {
  * @param base - Base path for routes
  * @private
  */
-k = function(e, t) {
-  e.get(`${t}/mcp`, async (s, o) => {
-    const i = s.headers["mcp-client-id"]?.trim(), a = i && i.length > 0 ? i : "";
-    if (!a)
+Q = function(e, s) {
+  e.get(`${s}/mcp`, async (t, o) => {
+    const i = t.headers["mcp-client-id"]?.trim(), n = i && i.length > 0 ? i : "";
+    if (!n)
       return o.code(400), "Missing mcp-client-id";
-    const l = this.clientCache.get(a);
+    const l = this.clientCache.get(n);
     if (!l)
       return o.code(400), "Invalid or expired client";
-    const n = s.headers["mcp-session-id"];
-    if (!n)
+    const a = t.headers["mcp-session-id"];
+    if (!a)
       return o.code(400), "Missing mcp-session-id";
-    const c = l.sessions.get(n);
-    return c ? (await c.handleRequest(s.raw, o.raw), o) : (o.code(400), "Invalid or expired session ID");
+    const c = l.sessions.get(a);
+    return c ? (await c.handleRequest(t.raw, o.raw), o) : (o.code(400), "Invalid or expired session ID");
   });
 }, /**
  * Registers the DELETE /mcp endpoint for session termination.
@@ -1074,12 +1392,12 @@ k = function(e, t) {
  * @param base - Base path for routes
  * @private
  */
-F = function(e, t) {
+X = function(e, s) {
   e.delete(
-    `${t}/mcp`,
-    async (s, o) => {
-      const i = s.headers["mcp-client-id"]?.trim(), a = i && i.length > 0 ? i : "", l = s.headers["mcp-session-id"];
-      if (!a || !l)
+    `${s}/mcp`,
+    async (t, o) => {
+      const i = t.headers["mcp-client-id"]?.trim(), n = i && i.length > 0 ? i : "", l = t.headers["mcp-session-id"];
+      if (!n || !l)
         return o.code(400), {
           jsonrpc: "2.0",
           error: {
@@ -1088,8 +1406,8 @@ F = function(e, t) {
           },
           id: null
         };
-      const n = this.clientCache.get(a), c = n?.sessions.get(l);
-      if (!n || !c)
+      const a = this.clientCache.get(n), c = a?.sessions.get(l);
+      if (!a || !c)
         return o.code(404), {
           jsonrpc: "2.0",
           error: { code: -32e3, message: "Session not found or expired" },
@@ -1102,7 +1420,7 @@ F = function(e, t) {
           } catch {
           }
       } finally {
-        c?.sessionId ? n.sessions.delete(c.sessionId) : n.sessions.delete(l);
+        c?.sessionId ? a.sessions.delete(c.sessionId) : a.sessions.delete(l);
       }
       return o.code(204).send(), o;
     }
@@ -1114,11 +1432,11 @@ F = function(e, t) {
  * @returns Client request context with ID and headers
  * @private
  */
-V = function(e) {
-  const t = e.headers["mcp-client-id"]?.trim(), s = t && t.length > 0 ? t : `anon-${p()}`, o = {};
-  for (const [i, a] of Object.entries(e.headers))
-    typeof a == "string" && (o[i] = a);
-  return { clientId: s, headers: o };
+E = function(e) {
+  const s = e.headers["mcp-client-id"]?.trim(), t = s && s.length > 0 ? s : `anon-${y()}`, o = {};
+  for (const [i, n] of Object.entries(e.headers))
+    typeof n == "string" && (o[i] = n);
+  return { clientId: t, headers: o };
 }, /**
  * Creates a safe error response that doesn't expose unauthorized toolset information.
  * Used for permission-related errors to prevent information leakage.
@@ -1127,22 +1445,37 @@ V = function(e) {
  * @returns JSON-RPC error response object
  * @private
  */
-_ = function(e = "Access denied", t = -32e3) {
+Z = function(e = "Access denied", s = -32e3) {
   return {
     jsonrpc: "2.0",
     error: {
-      code: t,
+      code: s,
       message: e
     },
     id: null
   };
 };
-async function he(r) {
+function ge(r) {
+  if (!r) return;
+  const e = {
+    namespaceToolsWithSetKey: r.namespaceToolsWithSetKey
+  };
+  return r.allowlist !== void 0 && console.warn(
+    "Permission-based servers: exposurePolicy.allowlist is ignored. Allowed toolsets are determined by client permissions."
+  ), r.denylist !== void 0 && console.warn(
+    "Permission-based servers: exposurePolicy.denylist is ignored. Use permission configuration to control toolset access."
+  ), r.maxActiveToolsets !== void 0 && console.warn(
+    "Permission-based servers: exposurePolicy.maxActiveToolsets is ignored. Toolset count is determined by client permissions."
+  ), r.onLimitExceeded !== void 0 && console.warn(
+    "Permission-based servers: exposurePolicy.onLimitExceeded is ignored. No toolset limits are enforced."
+  ), e;
+}
+async function Ee(r) {
   if (!r.permissions)
     throw new Error(
       "Permission configuration is required for createPermissionBasedMcpServer. Please provide a 'permissions' field in the options."
     );
-  if (q(r.permissions), r.startup)
+  if (ne(r.permissions), r.startup)
     throw new Error(
       "Permission-based servers determine toolsets from client permissions. The 'startup' option is not allowed. Remove it from your configuration."
     );
@@ -1150,23 +1483,25 @@ async function he(r) {
     throw new Error(
       "createPermissionBasedMcpServer: `createServer` (factory) is required"
     );
-  const e = new ee(r.permissions), t = r.createServer(), s = new y({
+  const e = ge(
+    r.exposurePolicy
+  ), s = new ue(r.permissions), t = r.createServer(), o = new w({
     server: t,
     catalog: r.catalog,
     moduleLoaders: r.moduleLoaders,
-    exposurePolicy: r.exposurePolicy,
+    exposurePolicy: e,
     context: r.context,
     notifyToolsListChanged: void 0,
     // No notifications in STATIC mode
     startup: { mode: "STATIC", toolsets: [] },
     registerMetaTools: !1
-  }), o = se(
-    (a) => {
-      const l = r.createServer(), n = new y({
-        server: l,
+  }), i = fe(
+    (l) => {
+      const a = r.createServer(), c = new w({
+        server: a,
         catalog: r.catalog,
         moduleLoaders: r.moduleLoaders,
-        exposurePolicy: r.exposurePolicy,
+        exposurePolicy: e,
         context: r.context,
         notifyToolsListChanged: void 0,
         // No notifications in STATIC mode
@@ -1175,31 +1510,39 @@ async function he(r) {
         registerMetaTools: !1
         // No meta-tools - toolsets are fixed per client
       });
-      return { server: l, orchestrator: n };
+      return { server: a, orchestrator: c };
     },
-    e
-  ), i = new te(
-    s.getManager(),
-    o,
+    s
+  ), n = new me(
+    o.getManager(),
+    i,
     r.http,
     r.configSchema
   );
   return {
     server: t,
     start: async () => {
-      await i.start();
+      await n.start();
     },
     close: async () => {
       try {
-        await i.stop();
+        await n.stop();
       } finally {
-        e.clearCache();
+        s.clearCache();
       }
     }
   };
 }
+function Ce(r) {
+  return r;
+}
+function xe(r) {
+  return r;
+}
 export {
-  de as createMcpServer,
-  he as createPermissionBasedMcpServer
+  Se as createMcpServer,
+  Ee as createPermissionBasedMcpServer,
+  Ce as defineEndpoint,
+  xe as definePermissionAwareEndpoint
 };
 //# sourceMappingURL=index.js.map