@mcpc-tech/core 0.3.23 → 0.3.25

package/index.cjs

@@ -534,6 +534,7 @@ __export(mod_exports, {
   composeMcpDepTools: () => composeMcpDepTools,
   convertToAISDKTools: () => convertToAISDKTools,
   extractJsonSchema: () => extractJsonSchema,
+  isMarkdownFile: () => isMarkdownFile,
   isProdEnv: () => isProdEnv,
   isSCF: () => isSCF,
   isWrappedSchema: () => isWrappedSchema,
@@ -542,6 +543,7 @@ __export(mod_exports, {
   optionalObject: () => optionalObject,
   parseJSON: () => parseJSON,
   parseMcpcConfigs: () => parseMcpcConfigs,
+  setMarkdownAgentLoader: () => setMarkdownAgentLoader,
   truncateJSON: () => truncateJSON
 });
 module.exports = __toCommonJS(mod_exports);
@@ -14868,7 +14870,9 @@ var Client = class extends Protocol {
           }
           return taskValidationResult.data;
         }
-        const validationResult = safeParse3(CreateMessageResultSchema, result);
+        const hasTools = params.tools || params.toolChoice;
+        const resultSchema = hasTools ? CreateMessageResultWithToolsSchema : CreateMessageResultSchema;
+        const validationResult = safeParse3(resultSchema, result);
         if (!validationResult.success) {
           const errorMessage = validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);
           throw new McpError(ErrorCode.InvalidParams, `Invalid sampling result: ${errorMessage}`);
@@ -18306,7 +18310,9 @@ ${JSON.stringify(cleanedSchema, null, 2)}
         tool: tool2
       });
       try {
-        const result = await this.server.callTool(tool2, toolArgs);
+        const result = await this.server.callTool(tool2, toolArgs, {
+          agentName: this.name
+        });
         const callToolResult = result ?? {
           content: []
         };
@@ -19341,7 +19347,7 @@ function isValidPlugin(plugin) {
   if (!p2.name || typeof p2.name !== "string" || p2.name.trim() === "") {
     return false;
   }
-  const hasHook = typeof p2.configureServer === "function" || typeof p2.composeStart === "function" || typeof p2.transformTool === "function" || typeof p2.finalizeComposition === "function" || typeof p2.registerAgentTool === "function" || typeof p2.composeEnd === "function" || typeof p2.transformInput === "function" || typeof p2.transformOutput === "function" || typeof p2.dispose === "function";
+  const hasHook = typeof p2.configureServer === "function" || typeof p2.composeStart === "function" || typeof p2.transformTool === "function" || typeof p2.finalizeComposition === "function" || typeof p2.registerAgentTool === "function" || typeof p2.composeEnd === "function" || typeof p2.transformInput === "function" || typeof p2.transformOutput === "function" || typeof p2.beforeToolExecute === "function" || typeof p2.afterToolExecute === "function" || typeof p2.dispose === "function";
   if (!hasHook) return false;
   if (p2.enforce && p2.enforce !== "pre" && p2.enforce !== "post") {
     return false;
@@ -19648,6 +19654,113 @@ var PluginManager = class {
     }
     return false;
   }
+  // === Tool Execution Lifecycle Hooks ===
+  /**
+   * Trigger beforeToolExecute hooks for all applicable plugins
+   * Returns the combined result from all plugins
+   *
+   * Hook execution order:
+   * 1. 'pre' enforced plugins first
+   * 2. Normal plugins (no enforce)
+   * 3. 'post' enforced plugins last
+   *
+   * If any plugin returns skipExecution=true, execution is skipped
+   * and the result from that plugin is used.
+   */
+  async triggerBeforeToolExecute(context2) {
+    const beforePlugins = this.plugins.filter((p2) => p2.beforeToolExecute);
+    if (beforePlugins.length === 0) {
+      return void 0;
+    }
+    const sortedPlugins = sortPluginsByOrder(beforePlugins);
+    let currentArgs = context2.args;
+    let combinedMetadata = {};
+    for (const plugin of sortedPlugins) {
+      if (plugin.beforeToolExecute) {
+        try {
+          const result = await plugin.beforeToolExecute({
+            ...context2,
+            args: currentArgs
+          });
+          if (result) {
+            if (result.metadata) {
+              combinedMetadata = {
+                ...combinedMetadata,
+                ...result.metadata
+              };
+            }
+            if (result.skipExecution) {
+              return {
+                skipExecution: true,
+                result: result.result,
+                metadata: combinedMetadata
+              };
+            }
+            if (result.modifiedArgs !== void 0) {
+              currentArgs = result.modifiedArgs;
+            }
+          }
+        } catch (error2) {
+          const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+          await this.logger.error(`Plugin "${plugin.name}" beforeToolExecute failed for "${context2.toolName}": ${errorMsg}`);
+        }
+      }
+    }
+    if (currentArgs !== context2.args) {
+      return {
+        modifiedArgs: currentArgs,
+        metadata: Object.keys(combinedMetadata).length > 0 ? combinedMetadata : void 0
+      };
+    }
+    if (Object.keys(combinedMetadata).length > 0) {
+      return {
+        metadata: combinedMetadata
+      };
+    }
+    return void 0;
+  }
+  /**
+   * Trigger afterToolExecute hooks for all applicable plugins
+   * Returns the final result after all plugins have processed it
+   */
+  async triggerAfterToolExecute(context2) {
+    const afterPlugins = this.plugins.filter((p2) => p2.afterToolExecute);
+    if (afterPlugins.length === 0) {
+      return void 0;
+    }
+    const sortedPlugins = sortPluginsByOrder(afterPlugins);
+    let currentResult = context2.result;
+    let markAsError = context2.isError;
+    for (const plugin of sortedPlugins) {
+      if (plugin.afterToolExecute) {
+        try {
+          const result = await plugin.afterToolExecute({
+            ...context2,
+            result: currentResult,
+            isError: markAsError
+          });
+          if (result) {
+            if (result.modifiedResult !== void 0) {
+              currentResult = result.modifiedResult;
+            }
+            if (result.markAsError !== void 0) {
+              markAsError = result.markAsError;
+            }
+          }
+        } catch (error2) {
+          const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+          await this.logger.error(`Plugin "${plugin.name}" afterToolExecute failed for "${context2.toolName}": ${errorMsg}`);
+        }
+      }
+    }
+    if (currentResult !== context2.result || markAsError !== context2.isError) {
+      return {
+        modifiedResult: currentResult,
+        markAsError
+      };
+    }
+    return void 0;
+  }
   /**
    * Dispose all plugins and cleanup resources
    */
@@ -19878,6 +19991,24 @@ var ToolManager = class {
     }
     return composedTools;
   }
+  /**
+   * Get a single tool as ComposedTool object by name
+   */
+  getComposedTool(name) {
+    const tool2 = this.toolRegistry.get(name);
+    if (!tool2) {
+      return void 0;
+    }
+    return {
+      name,
+      description: tool2.description,
+      inputSchema: tool2.schema ?? {
+        type: "object",
+        properties: {}
+      },
+      execute: tool2.callback
+    };
+  }
 };
 
 // __mcpc__core_latest/node_modules/@mcpc/core/src/utils/common/schema.js
@@ -20078,9 +20209,81 @@ var ComposableMCPServer = class extends Server {
       if (!handler) {
         throw new Error(`Tool ${toolName} not found`);
       }
-      const processedArgs = await this.applyPluginTransforms(toolName, args, "input");
-      const result = await handler(processedArgs, extra);
-      return await this.applyPluginTransforms(toolName, result, "output", args);
+      const toolDefinition = this.toolManager.getComposedTool(toolName);
+      const startTime = Date.now();
+      const beforeContext = {
+        toolName,
+        args,
+        server: this,
+        toolDefinition,
+        isInternalCall: false
+      };
+      const beforeResult = await this.pluginManager.triggerBeforeToolExecute(beforeContext);
+      if (beforeResult?.skipExecution) {
+        const executionTimeMs2 = Date.now() - startTime;
+        const afterContext2 = {
+          toolName,
+          args,
+          result: beforeResult.result,
+          server: this,
+          wasSkipped: true,
+          executionTimeMs: executionTimeMs2,
+          isError: false,
+          metadata: beforeResult.metadata,
+          isInternalCall: false
+        };
+        const afterResult2 = await this.pluginManager.triggerAfterToolExecute(afterContext2);
+        let finalResult = afterResult2?.modifiedResult ?? beforeResult.result;
+        if (afterResult2?.markAsError && finalResult) {
+          finalResult = {
+            ...finalResult,
+            isError: true
+          };
+        }
+        return finalResult;
+      }
+      const effectiveArgs = beforeResult?.modifiedArgs ?? args;
+      const processedArgs = await this.applyPluginTransforms(toolName, effectiveArgs, "input");
+      let result = await handler(processedArgs, extra);
+      const isError = !!result?.isError;
+      result = await this.applyPluginTransforms(toolName, result, "output", args);
+      if (isError && result && !("isError" in result)) {
+        result = {
+          ...result,
+          isError: true
+        };
+      }
+      const executionTimeMs = Date.now() - startTime;
+      const afterContext = {
+        toolName,
+        args,
+        result,
+        server: this,
+        wasSkipped: false,
+        executionTimeMs,
+        isError,
+        metadata: beforeResult?.metadata,
+        isInternalCall: false
+      };
+      const afterResult = await this.pluginManager.triggerAfterToolExecute(afterContext);
+      if (afterResult?.modifiedResult !== void 0) {
+        let finalResult = afterResult.modifiedResult;
+        const hasExplicitIsError = finalResult && "isError" in finalResult;
+        if (!hasExplicitIsError && afterResult.markAsError && finalResult) {
+          finalResult = {
+            ...finalResult,
+            isError: true
+          };
+        }
+        return finalResult;
+      }
+      if (afterResult?.markAsError && result) {
+        return {
+          ...result,
+          isError: true
+        };
+      }
+      return result;
     });
     this.setRequestHandler(SetLevelRequestSchema, (request) => {
       const { level } = request.params;
@@ -20102,8 +20305,9 @@ var ComposableMCPServer = class extends Server {
   }
   /**
    * Call any registered tool directly, whether it's public or internal
+   * Supports tool execution lifecycle hooks for dynamic context handoff
    */
-  async callTool(name, args) {
+  async callTool(name, args, options = {}) {
     const resolvedName = this.resolveToolName(name);
     if (!resolvedName) {
       throw new Error(`Tool ${name} not found`);
@@ -20112,9 +20316,99 @@ var ComposableMCPServer = class extends Server {
     if (!callback) {
       throw new Error(`Tool ${name} not found`);
     }
-    const processedArgs = await this.applyPluginTransforms(resolvedName, args, "input");
-    const result = await callback(processedArgs);
-    return await this.applyPluginTransforms(resolvedName, result, "output", args);
+    const toolDefinition = this.toolManager.getComposedTool(resolvedName);
+    const startTime = Date.now();
+    const beforeContext = {
+      toolName: resolvedName,
+      args,
+      server: this,
+      toolDefinition,
+      isInternalCall: true,
+      agentName: options.agentName,
+      executionChain: options.executionChain
+    };
+    const beforeResult = await this.pluginManager.triggerBeforeToolExecute(beforeContext);
+    if (beforeResult?.skipExecution) {
+      const executionTimeMs2 = Date.now() - startTime;
+      const afterContext2 = {
+        toolName: resolvedName,
+        args,
+        result: beforeResult.result,
+        server: this,
+        wasSkipped: true,
+        executionTimeMs: executionTimeMs2,
+        isError: false,
+        metadata: beforeResult.metadata,
+        isInternalCall: true,
+        agentName: options.agentName
+      };
+      const afterResult2 = await this.pluginManager.triggerAfterToolExecute(afterContext2);
+      let finalResult = afterResult2?.modifiedResult ?? beforeResult.result;
+      if (afterResult2?.markAsError && finalResult && typeof finalResult === "object") {
+        finalResult = {
+          ...finalResult,
+          isError: true
+        };
+      }
+      return finalResult;
+    }
+    const effectiveArgs = beforeResult?.modifiedArgs ?? args;
+    const processedArgs = await this.applyPluginTransforms(resolvedName, effectiveArgs, "input");
+    let result;
+    let isError = false;
+    try {
+      result = await callback(processedArgs);
+    } catch (error2) {
+      isError = true;
+      result = {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error2 instanceof Error ? error2.message : String(error2)}`
+          }
+        ],
+        isError: true
+      };
+    }
+    result = await this.applyPluginTransforms(resolvedName, result, "output", args);
+    if (isError && result && typeof result === "object" && !("isError" in result)) {
+      result = {
+        ...result,
+        isError: true
+      };
+    }
+    const executionTimeMs = Date.now() - startTime;
+    const afterContext = {
+      toolName: resolvedName,
+      args,
+      result,
+      server: this,
+      wasSkipped: false,
+      executionTimeMs,
+      isError,
+      metadata: beforeResult?.metadata,
+      isInternalCall: true,
+      agentName: options.agentName
+    };
+    const afterResult = await this.pluginManager.triggerAfterToolExecute(afterContext);
+    if (afterResult?.modifiedResult !== void 0) {
+      let finalResult = afterResult.modifiedResult;
+      const hasExplicitIsError = finalResult && typeof finalResult === "object" && "isError" in finalResult;
+      if (!hasExplicitIsError && afterResult.markAsError && finalResult && typeof finalResult === "object") {
+        finalResult = {
+          ...finalResult,
+          isError: true
+        };
+      }
+      return finalResult;
+    }
+    if (afterResult?.markAsError && result && typeof result === "object") {
+      return {
+        ...result,
+        isError: true
+      };
+    }
+    return result;
   }
   /**
    * Get all public tool names (exposed to MCP clients)
@@ -20406,12 +20700,44 @@ function convertToAISDKTools(server, helpers) {
 }
 
 // __mcpc__core_latest/node_modules/@mcpc/core/src/set-up-mcp-compose.js
+var markdownAgentLoader = null;
+function setMarkdownAgentLoader(loader) {
+  markdownAgentLoader = loader;
+}
+function isMarkdownFile(path) {
+  return path.endsWith(".md") || path.endsWith(".markdown");
+}
+async function resolveComposeInput(input) {
+  if (typeof input !== "string") {
+    return input;
+  }
+  if (!isMarkdownFile(input)) {
+    throw new Error(`Invalid compose input: "${input}". Expected a Markdown file path (.md) or a ComposeDefinition object.`);
+  }
+  if (!markdownAgentLoader) {
+    throw new Error(`Cannot load Markdown agent file "${input}": Markdown loader not available. Use markdownLoaderPlugin() from "@mcpc/plugin-markdown-loader", or use inline ComposeDefinition objects.`);
+  }
+  return await markdownAgentLoader(input);
+}
 function parseMcpcConfigs(conf) {
   return conf ?? [];
 }
-async function mcpc(serverConf, composeConf, setupCallback) {
+async function mcpc(serverConf, composeConf, optionsOrSetup) {
   const server = new ComposableMCPServer(...serverConf);
-  const parsed = parseMcpcConfigs(composeConf);
+  const options = typeof optionsOrSetup === "function" ? {
+    setup: optionsOrSetup
+  } : optionsOrSetup ?? {};
+  if (options.plugins) {
+    for (const plugin of options.plugins) {
+      if (typeof plugin === "string") {
+        await server.loadPluginFromPath(plugin);
+      } else {
+        await server.addPlugin(plugin);
+      }
+    }
+  }
+  const resolvedConfigs = composeConf ? await Promise.all(composeConf.map(resolveComposeInput)) : [];
+  const parsed = parseMcpcConfigs(resolvedConfigs);
   await server.initBuiltInPlugins();
   for (const mcpcConfig of parsed) {
     if (mcpcConfig.plugins) {
@@ -20424,8 +20750,8 @@ async function mcpc(serverConf, composeConf, setupCallback) {
       }
     }
   }
-  if (setupCallback) {
-    await setupCallback(server);
+  if (options.setup) {
+    await options.setup(server);
   }
   for (const mcpcConfig of parsed) {
     await server.compose(mcpcConfig.name, mcpcConfig.description ?? "", mcpcConfig.deps, mcpcConfig.options);
@@ -20438,6 +20764,7 @@ async function mcpc(serverConf, composeConf, setupCallback) {
   composeMcpDepTools,
   convertToAISDKTools,
   extractJsonSchema,
+  isMarkdownFile,
   isProdEnv,
   isSCF,
   isWrappedSchema,
@@ -20446,5 +20773,6 @@ async function mcpc(serverConf, composeConf, setupCallback) {
   optionalObject,
   parseJSON,
   parseMcpcConfigs,
+  setMarkdownAgentLoader,
   truncateJSON
 });

package/index.mjs

@@ -14856,7 +14856,9 @@ var Client = class extends Protocol {
           }
           return taskValidationResult.data;
         }
-        const validationResult = safeParse3(CreateMessageResultSchema, result);
+        const hasTools = params.tools || params.toolChoice;
+        const resultSchema = hasTools ? CreateMessageResultWithToolsSchema : CreateMessageResultSchema;
+        const validationResult = safeParse3(resultSchema, result);
         if (!validationResult.success) {
           const errorMessage = validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);
           throw new McpError(ErrorCode.InvalidParams, `Invalid sampling result: ${errorMessage}`);
@@ -18294,7 +18296,9 @@ ${JSON.stringify(cleanedSchema, null, 2)}
         tool: tool2
       });
       try {
-        const result = await this.server.callTool(tool2, toolArgs);
+        const result = await this.server.callTool(tool2, toolArgs, {
+          agentName: this.name
+        });
         const callToolResult = result ?? {
           content: []
         };
@@ -19328,7 +19332,7 @@ function isValidPlugin(plugin) {
   if (!p2.name || typeof p2.name !== "string" || p2.name.trim() === "") {
     return false;
   }
-  const hasHook = typeof p2.configureServer === "function" || typeof p2.composeStart === "function" || typeof p2.transformTool === "function" || typeof p2.finalizeComposition === "function" || typeof p2.registerAgentTool === "function" || typeof p2.composeEnd === "function" || typeof p2.transformInput === "function" || typeof p2.transformOutput === "function" || typeof p2.dispose === "function";
+  const hasHook = typeof p2.configureServer === "function" || typeof p2.composeStart === "function" || typeof p2.transformTool === "function" || typeof p2.finalizeComposition === "function" || typeof p2.registerAgentTool === "function" || typeof p2.composeEnd === "function" || typeof p2.transformInput === "function" || typeof p2.transformOutput === "function" || typeof p2.beforeToolExecute === "function" || typeof p2.afterToolExecute === "function" || typeof p2.dispose === "function";
   if (!hasHook) return false;
   if (p2.enforce && p2.enforce !== "pre" && p2.enforce !== "post") {
     return false;
@@ -19635,6 +19639,113 @@ var PluginManager = class {
     }
     return false;
   }
+  // === Tool Execution Lifecycle Hooks ===
+  /**
+   * Trigger beforeToolExecute hooks for all applicable plugins
+   * Returns the combined result from all plugins
+   *
+   * Hook execution order:
+   * 1. 'pre' enforced plugins first
+   * 2. Normal plugins (no enforce)
+   * 3. 'post' enforced plugins last
+   *
+   * If any plugin returns skipExecution=true, execution is skipped
+   * and the result from that plugin is used.
+   */
+  async triggerBeforeToolExecute(context2) {
+    const beforePlugins = this.plugins.filter((p2) => p2.beforeToolExecute);
+    if (beforePlugins.length === 0) {
+      return void 0;
+    }
+    const sortedPlugins = sortPluginsByOrder(beforePlugins);
+    let currentArgs = context2.args;
+    let combinedMetadata = {};
+    for (const plugin of sortedPlugins) {
+      if (plugin.beforeToolExecute) {
+        try {
+          const result = await plugin.beforeToolExecute({
+            ...context2,
+            args: currentArgs
+          });
+          if (result) {
+            if (result.metadata) {
+              combinedMetadata = {
+                ...combinedMetadata,
+                ...result.metadata
+              };
+            }
+            if (result.skipExecution) {
+              return {
+                skipExecution: true,
+                result: result.result,
+                metadata: combinedMetadata
+              };
+            }
+            if (result.modifiedArgs !== void 0) {
+              currentArgs = result.modifiedArgs;
+            }
+          }
+        } catch (error2) {
+          const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+          await this.logger.error(`Plugin "${plugin.name}" beforeToolExecute failed for "${context2.toolName}": ${errorMsg}`);
+        }
+      }
+    }
+    if (currentArgs !== context2.args) {
+      return {
+        modifiedArgs: currentArgs,
+        metadata: Object.keys(combinedMetadata).length > 0 ? combinedMetadata : void 0
+      };
+    }
+    if (Object.keys(combinedMetadata).length > 0) {
+      return {
+        metadata: combinedMetadata
+      };
+    }
+    return void 0;
+  }
+  /**
+   * Trigger afterToolExecute hooks for all applicable plugins
+   * Returns the final result after all plugins have processed it
+   */
+  async triggerAfterToolExecute(context2) {
+    const afterPlugins = this.plugins.filter((p2) => p2.afterToolExecute);
+    if (afterPlugins.length === 0) {
+      return void 0;
+    }
+    const sortedPlugins = sortPluginsByOrder(afterPlugins);
+    let currentResult = context2.result;
+    let markAsError = context2.isError;
+    for (const plugin of sortedPlugins) {
+      if (plugin.afterToolExecute) {
+        try {
+          const result = await plugin.afterToolExecute({
+            ...context2,
+            result: currentResult,
+            isError: markAsError
+          });
+          if (result) {
+            if (result.modifiedResult !== void 0) {
+              currentResult = result.modifiedResult;
+            }
+            if (result.markAsError !== void 0) {
+              markAsError = result.markAsError;
+            }
+          }
+        } catch (error2) {
+          const errorMsg = error2 instanceof Error ? error2.message : String(error2);
+          await this.logger.error(`Plugin "${plugin.name}" afterToolExecute failed for "${context2.toolName}": ${errorMsg}`);
+        }
+      }
+    }
+    if (currentResult !== context2.result || markAsError !== context2.isError) {
+      return {
+        modifiedResult: currentResult,
+        markAsError
+      };
+    }
+    return void 0;
+  }
   /**
    * Dispose all plugins and cleanup resources
    */
@@ -19865,6 +19976,24 @@ var ToolManager = class {
     }
     return composedTools;
   }
+  /**
+   * Get a single tool as ComposedTool object by name
+   */
+  getComposedTool(name) {
+    const tool2 = this.toolRegistry.get(name);
+    if (!tool2) {
+      return void 0;
+    }
+    return {
+      name,
+      description: tool2.description,
+      inputSchema: tool2.schema ?? {
+        type: "object",
+        properties: {}
+      },
+      execute: tool2.callback
+    };
+  }
 };
 
 // __mcpc__core_latest/node_modules/@mcpc/core/src/utils/common/schema.js
@@ -20065,9 +20194,81 @@ var ComposableMCPServer = class extends Server {
       if (!handler) {
         throw new Error(`Tool ${toolName} not found`);
       }
-      const processedArgs = await this.applyPluginTransforms(toolName, args, "input");
-      const result = await handler(processedArgs, extra);
-      return await this.applyPluginTransforms(toolName, result, "output", args);
+      const toolDefinition = this.toolManager.getComposedTool(toolName);
+      const startTime = Date.now();
+      const beforeContext = {
+        toolName,
+        args,
+        server: this,
+        toolDefinition,
+        isInternalCall: false
+      };
+      const beforeResult = await this.pluginManager.triggerBeforeToolExecute(beforeContext);
+      if (beforeResult?.skipExecution) {
+        const executionTimeMs2 = Date.now() - startTime;
+        const afterContext2 = {
+          toolName,
+          args,
+          result: beforeResult.result,
+          server: this,
+          wasSkipped: true,
+          executionTimeMs: executionTimeMs2,
+          isError: false,
+          metadata: beforeResult.metadata,
+          isInternalCall: false
+        };
+        const afterResult2 = await this.pluginManager.triggerAfterToolExecute(afterContext2);
+        let finalResult = afterResult2?.modifiedResult ?? beforeResult.result;
+        if (afterResult2?.markAsError && finalResult) {
+          finalResult = {
+            ...finalResult,
+            isError: true
+          };
+        }
+        return finalResult;
+      }
+      const effectiveArgs = beforeResult?.modifiedArgs ?? args;
+      const processedArgs = await this.applyPluginTransforms(toolName, effectiveArgs, "input");
+      let result = await handler(processedArgs, extra);
+      const isError = !!result?.isError;
+      result = await this.applyPluginTransforms(toolName, result, "output", args);
+      if (isError && result && !("isError" in result)) {
+        result = {
+          ...result,
+          isError: true
+        };
+      }
+      const executionTimeMs = Date.now() - startTime;
+      const afterContext = {
+        toolName,
+        args,
+        result,
+        server: this,
+        wasSkipped: false,
+        executionTimeMs,
+        isError,
+        metadata: beforeResult?.metadata,
+        isInternalCall: false
+      };
+      const afterResult = await this.pluginManager.triggerAfterToolExecute(afterContext);
+      if (afterResult?.modifiedResult !== void 0) {
+        let finalResult = afterResult.modifiedResult;
+        const hasExplicitIsError = finalResult && "isError" in finalResult;
+        if (!hasExplicitIsError && afterResult.markAsError && finalResult) {
+          finalResult = {
+            ...finalResult,
+            isError: true
+          };
+        }
+        return finalResult;
+      }
+      if (afterResult?.markAsError && result) {
+        return {
+          ...result,
+          isError: true
+        };
+      }
+      return result;
     });
     this.setRequestHandler(SetLevelRequestSchema, (request) => {
       const { level } = request.params;
@@ -20089,8 +20290,9 @@ var ComposableMCPServer = class extends Server {
   }
   /**
    * Call any registered tool directly, whether it's public or internal
+   * Supports tool execution lifecycle hooks for dynamic context handoff
    */
-  async callTool(name, args) {
+  async callTool(name, args, options = {}) {
     const resolvedName = this.resolveToolName(name);
     if (!resolvedName) {
       throw new Error(`Tool ${name} not found`);
@@ -20099,9 +20301,99 @@ var ComposableMCPServer = class extends Server {
     if (!callback) {
       throw new Error(`Tool ${name} not found`);
     }
-    const processedArgs = await this.applyPluginTransforms(resolvedName, args, "input");
-    const result = await callback(processedArgs);
-    return await this.applyPluginTransforms(resolvedName, result, "output", args);
+    const toolDefinition = this.toolManager.getComposedTool(resolvedName);
+    const startTime = Date.now();
+    const beforeContext = {
+      toolName: resolvedName,
+      args,
+      server: this,
+      toolDefinition,
+      isInternalCall: true,
+      agentName: options.agentName,
+      executionChain: options.executionChain
+    };
+    const beforeResult = await this.pluginManager.triggerBeforeToolExecute(beforeContext);
+    if (beforeResult?.skipExecution) {
+      const executionTimeMs2 = Date.now() - startTime;
+      const afterContext2 = {
+        toolName: resolvedName,
+        args,
+        result: beforeResult.result,
+        server: this,
+        wasSkipped: true,
+        executionTimeMs: executionTimeMs2,
+        isError: false,
+        metadata: beforeResult.metadata,
+        isInternalCall: true,
+        agentName: options.agentName
+      };
+      const afterResult2 = await this.pluginManager.triggerAfterToolExecute(afterContext2);
+      let finalResult = afterResult2?.modifiedResult ?? beforeResult.result;
+      if (afterResult2?.markAsError && finalResult && typeof finalResult === "object") {
+        finalResult = {
+          ...finalResult,
+          isError: true
+        };
+      }
+      return finalResult;
+    }
+    const effectiveArgs = beforeResult?.modifiedArgs ?? args;
+    const processedArgs = await this.applyPluginTransforms(resolvedName, effectiveArgs, "input");
+    let result;
+    let isError = false;
+    try {
+      result = await callback(processedArgs);
+    } catch (error2) {
+      isError = true;
+      result = {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error2 instanceof Error ? error2.message : String(error2)}`
+          }
+        ],
+        isError: true
+      };
+    }
+    result = await this.applyPluginTransforms(resolvedName, result, "output", args);
+    if (isError && result && typeof result === "object" && !("isError" in result)) {
+      result = {
+        ...result,
+        isError: true
+      };
+    }
+    const executionTimeMs = Date.now() - startTime;
+    const afterContext = {
+      toolName: resolvedName,
+      args,
+      result,
+      server: this,
+      wasSkipped: false,
+      executionTimeMs,
+      isError,
+      metadata: beforeResult?.metadata,
+      isInternalCall: true,
+      agentName: options.agentName
+    };
+    const afterResult = await this.pluginManager.triggerAfterToolExecute(afterContext);
+    if (afterResult?.modifiedResult !== void 0) {
+      let finalResult = afterResult.modifiedResult;
+      const hasExplicitIsError = finalResult && typeof finalResult === "object" && "isError" in finalResult;
+      if (!hasExplicitIsError && afterResult.markAsError && finalResult && typeof finalResult === "object") {
+        finalResult = {
+          ...finalResult,
+          isError: true
+        };
+      }
+      return finalResult;
+    }
+    if (afterResult?.markAsError && result && typeof result === "object") {
+      return {
+        ...result,
+        isError: true
+      };
+    }
+    return result;
   }
   /**
    * Get all public tool names (exposed to MCP clients)
@@ -20393,12 +20685,44 @@ function convertToAISDKTools(server, helpers) {
 }
 
 // __mcpc__core_latest/node_modules/@mcpc/core/src/set-up-mcp-compose.js
+var markdownAgentLoader = null;
+function setMarkdownAgentLoader(loader) {
+  markdownAgentLoader = loader;
+}
+function isMarkdownFile(path) {
+  return path.endsWith(".md") || path.endsWith(".markdown");
+}
+async function resolveComposeInput(input) {
+  if (typeof input !== "string") {
+    return input;
+  }
+  if (!isMarkdownFile(input)) {
+    throw new Error(`Invalid compose input: "${input}". Expected a Markdown file path (.md) or a ComposeDefinition object.`);
+  }
+  if (!markdownAgentLoader) {
+    throw new Error(`Cannot load Markdown agent file "${input}": Markdown loader not available. Use markdownLoaderPlugin() from "@mcpc/plugin-markdown-loader", or use inline ComposeDefinition objects.`);
+  }
+  return await markdownAgentLoader(input);
+}
 function parseMcpcConfigs(conf) {
   return conf ?? [];
 }
-async function mcpc(serverConf, composeConf, setupCallback) {
+async function mcpc(serverConf, composeConf, optionsOrSetup) {
   const server = new ComposableMCPServer(...serverConf);
-  const parsed = parseMcpcConfigs(composeConf);
+  const options = typeof optionsOrSetup === "function" ? {
+    setup: optionsOrSetup
+  } : optionsOrSetup ?? {};
+  if (options.plugins) {
+    for (const plugin of options.plugins) {
+      if (typeof plugin === "string") {
+        await server.loadPluginFromPath(plugin);
+      } else {
+        await server.addPlugin(plugin);
+      }
+    }
+  }
+  const resolvedConfigs = composeConf ? await Promise.all(composeConf.map(resolveComposeInput)) : [];
+  const parsed = parseMcpcConfigs(resolvedConfigs);
   await server.initBuiltInPlugins();
   for (const mcpcConfig of parsed) {
     if (mcpcConfig.plugins) {
@@ -20411,8 +20735,8 @@ async function mcpc(serverConf, composeConf, setupCallback) {
       }
     }
   }
-  if (setupCallback) {
-    await setupCallback(server);
+  if (options.setup) {
+    await options.setup(server);
   }
   for (const mcpcConfig of parsed) {
     await server.compose(mcpcConfig.name, mcpcConfig.description ?? "", mcpcConfig.deps, mcpcConfig.options);
@@ -20424,6 +20748,7 @@ export {
   composeMcpDepTools,
   convertToAISDKTools,
   extractJsonSchema,
+  isMarkdownFile,
   isProdEnv,
   isSCF,
   isWrappedSchema,
@@ -20432,5 +20757,6 @@ export {
   optionalObject,
   parseJSON,
   parseMcpcConfigs,
+  setMarkdownAgentLoader,
   truncateJSON
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpc-tech/core",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "homepage": "https://jsr.io/@mcpc/core",
   "dependencies": {
     "@ai-sdk/provider": "^2.0.0",

package/types/mod.d.ts

@@ -47,11 +47,13 @@
  *
  * @module
  */ export * from "./src/compose.js";
-export type { AgentToolRegistrationContext, ComposedTool, ComposeEndContext, ComposeStartContext, FinalizeContext, ToolConfig, ToolPlugin, TransformContext } from "./src/plugin-types.js";
+export type { McpServerConfig, MCPSetting, SseServerConfig, StdioServerConfig, StreamableHTTPServerConfig } from "./src/service/tools.js";
+export type { SamplingConfig, ToolRefXml } from "./src/types.js";
+export type { AfterToolExecuteContext, AfterToolExecuteResult, AgentToolRegistrationContext, BeforeToolExecuteContext, BeforeToolExecuteResult, ComposedTool, ComposeEndContext, ComposeStartContext, FinalizeContext, RuntimeTransformContext, ToolConfig, ToolPlugin, TransformContext } from "./src/plugin-types.js";
 export * from "./src/utils/common/env.js";
 export * from "./src/utils/common/json.js";
 export * from "./src/utils/common/mcp.js";
-export * from "./src/set-up-mcp-compose.js";
+export { type ComposeDefinition, type ComposeInput, type ComposibleMCPConfig, isMarkdownFile, type MarkdownAgentLoader, mcpc, type McpcOptions, parseMcpcConfigs, setMarkdownAgentLoader } from "./src/set-up-mcp-compose.js";
 export { extractJsonSchema, isWrappedSchema, jsonSchema, type Schema } from "./src/utils/schema.js";
 export { convertToAISDKTools, type JsonSchemaHelper, type ToolHelper } from "./src/ai-sdk-adapter.js";
 //# sourceMappingURL=mod.d.ts.map

package/types/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDC,GAED,iCAAiC;AAGjC,cACE,4BAA4B,EAC5B,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,UAAU,EACV,gBAAgB,gCACa;AAE/B,0CAA0C;AAC1C,2CAA2C;AAC3C,0CAA0C;AAE1C,4CAA4C;AAG5C,SACE,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,KAAK,MAAM,gCACkB;AAG/B,SACE,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,kCACgB"}
+{"version":3,"file":"mod.d.ts","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDC,GAED,iCAAiC;AAGjC,cACE,eAAe,EACf,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,0BAA0B,iCACI;AAGhC,cAAc,cAAc,EAAE,UAAU,yBAAyB;AAGjE,cACE,uBAAuB,EACvB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,EACvB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,UAAU,EACV,gBAAgB,gCACa;AAE/B,0CAA0C;AAC1C,2CAA2C;AAC3C,0CAA0C;AAE1C,SACE,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,cAAc,EACd,KAAK,mBAAmB,EACxB,IAAI,EACJ,KAAK,WAAW,EAChB,gBAAgB,EAChB,sBAAsB,sCACa;AAGrC,SACE,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,KAAK,MAAM,gCACkB;AAG/B,SACE,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,UAAU,kCACgB"}

package/types/src/compose.d.ts

@@ -29,7 +29,11 @@ export declare class ComposableMCPServer extends Server {
    */ findToolConfig(toolId: string): ToolConfig | undefined;
   /**
    * Call any registered tool directly, whether it's public or internal
-   */ callTool(name: string, args: unknown): Promise<unknown>;
+   * Supports tool execution lifecycle hooks for dynamic context handoff
+   */ callTool(name: string, args: unknown, options?: {
+    agentName?: string;
+    executionChain?: string[];
+  }): Promise<unknown>;
   /**
    * Get all public tool names (exposed to MCP clients)
    */ getPublicToolNames(): string[];

package/types/src/compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.ts","sources":["../../src/compose.ts"],"names":[],"mappings":"AAAA,SAGE,KAAK,cAAc,EAGnB,KAAK,IAAI,6CAC8C;AACzD,SAAwC,KAAK,MAAM,4BAA4B;AAC/E,cAAc,UAAU,6BAA6B;AACrD,SACE,MAAM,EACN,KAAK,aAAa,oDAC4C;AAGhE,cAAc,iBAAiB,kCAAkC;AACjE,cAAc,UAAU,EAAE,YAAY,qBAAqB;AAM3D,cAA4B,UAAU,EAAE,UAAU,4BAA4B;AAe9E,OAAO,cAAM,4BAA4B;EACvC,QAAQ,mBAA6B;EACrC,QAAQ,iBAAyB;EACjC,QAAQ,YAAsC;EAG9C,IAAI,mBAAmB,IAAI,MAAM,EAAE,MAAM;EAIzC,YAAY,aAAa,cAAc,EAAE,SAAS,aAAa;EAiB/D;;GAEC,GACD,AAAM,sBAAsB,QAAQ,IAAI;UAqB1B;UAsDN;EAIR,KAAK,GACH,MAAM,MAAM,EACZ,aAAa,MAAM,EACnB,cAAc,OAAO,KAAK,UAAU,EACpC,KAAK,MAAM,GAAG,QAAQ,OAAO,KAAK,OAAO,EACzC;IAAW,WAAW,OAAO;IAAE,SAAS,OAAO;IAAE,UAAU;GACvD;EA+DN;;GAEC,GACD,gBAAgB,MAAM,MAAM,GAAG,eAAe,SAAS;EAIvD;;GAEC,GACD,eAAe,QAAQ,MAAM,GAAG,aAAa,SAAS;EAItD;;GAEC,GACD,AAAM,SAAS,MAAM,MAAM,EAAE,MAAM,OAAO,GAAG,QAAQ,OAAO;EAyB5D;;GAEC,GACD,sBAAsB,MAAM;EAI5B;;GAEC,GACD,kBAAkB;EAIlB;;GAEC,GACD,sBAAsB,MAAM;EAI5B;;GAEC,GACD,wBAAwB,MAAM;EAM9B;;GAEC,GACD,oBACE,MAAM,MAAM;IACT,aAAa,MAAM;IAAE,QAAQ;MAAe,SAAS;EAI1D;;GAEC,GACD,aAAa,MAAM,MAAM,GAAG,OAAO;EAInC;;GAEC,GACD,WAAW,UAAU,MAAM,EAAE,QAAQ,UAAU,GAAG,IAAI;EAItD;;GAEC,GACD,cAAc,UAAU,MAAM,GAAG,aAAa,SAAS;EAIvD;;GAEC,GACD,iBAAiB,UAAU,MAAM,GAAG,OAAO;EAI3C;;GAEC,GACD,AAAM,UAAU,QAAQ,UAAU,GAAG,QAAQ,IAAI;EAIjD;;GAEC,GACD,AAAM,mBACJ,YAAY,MAAM,EAClB;IAAW,QAAQ,OAAO;GAAoB,GAC7C,QAAQ,IAAI;UAOD;EAOd;;GAEC,GACD,AAAM,kBAAkB,QAAQ,IAAI;EAIpC;;GAEC,GACD,SAAe,SAAS,QAAQ,IAAI;EAK9B,QACJ,MAAM,MAAM,GAAG,IAAI,EACnB,aAAa,MAAM,EACnB,aAAY,UAA+B,EAC3C,UAAS,kBAAkB,UAAgC;AAiR/D"}
+{"version":3,"file":"compose.d.ts","sources":["../../src/compose.ts"],"names":[],"mappings":"AAAA,SAGE,KAAK,cAAc,EAGnB,KAAK,IAAI,6CAC8C;AACzD,SAAwC,KAAK,MAAM,4BAA4B;AAC/E,cAAc,UAAU,6BAA6B;AACrD,SACE,MAAM,EACN,KAAK,aAAa,oDAC4C;AAGhE,cAAc,iBAAiB,kCAAkC;AACjE,cAAc,UAAU,EAAE,YAAY,qBAAqB;AAM3D,cAA4B,UAAU,EAAE,UAAU,4BAA4B;AAe9E,OAAO,cAAM,4BAA4B;EACvC,QAAQ,mBAA6B;EACrC,QAAQ,iBAAyB;EACjC,QAAQ,YAAsC;EAG9C,IAAI,mBAAmB,IAAI,MAAM,EAAE,MAAM;EAIzC,YAAY,aAAa,cAAc,EAAE,SAAS,aAAa;EAiB/D;;GAEC,GACD,AAAM,sBAAsB,QAAQ,IAAI;UAqB1B;UAsDN;EAIR,KAAK,GACH,MAAM,MAAM,EACZ,aAAa,MAAM,EACnB,cAAc,OAAO,KAAK,UAAU,EACpC,KAAK,MAAM,GAAG,QAAQ,OAAO,KAAK,OAAO,EACzC;IAAW,WAAW,OAAO;IAAE,SAAS,OAAO;IAAE,UAAU;GACvD;EA+JN;;GAEC,GACD,gBAAgB,MAAM,MAAM,GAAG,eAAe,SAAS;EAIvD;;GAEC,GACD,eAAe,QAAQ,MAAM,GAAG,aAAa,SAAS;EAItD;;;GAGC,GACD,AAAM,SACJ,MAAM,MAAM,EACZ,MAAM,OAAO,EACb;IAAW,YAAY,MAAM;IAAE,iBAAiB,MAAM;GAAS,GAC9D,QAAQ,OAAO;EA4JlB;;GAEC,GACD,sBAAsB,MAAM;EAI5B;;GAEC,GACD,kBAAkB;EAIlB;;GAEC,GACD,sBAAsB,MAAM;EAI5B;;GAEC,GACD,wBAAwB,MAAM;EAM9B;;GAEC,GACD,oBACE,MAAM,MAAM;IACT,aAAa,MAAM;IAAE,QAAQ;MAAe,SAAS;EAI1D;;GAEC,GACD,aAAa,MAAM,MAAM,GAAG,OAAO;EAInC;;GAEC,GACD,WAAW,UAAU,MAAM,EAAE,QAAQ,UAAU,GAAG,IAAI;EAItD;;GAEC,GACD,cAAc,UAAU,MAAM,GAAG,aAAa,SAAS;EAIvD;;GAEC,GACD,iBAAiB,UAAU,MAAM,GAAG,OAAO;EAI3C;;GAEC,GACD,AAAM,UAAU,QAAQ,UAAU,GAAG,QAAQ,IAAI;EAIjD;;GAEC,GACD,AAAM,mBACJ,YAAY,MAAM,EAClB;IAAW,QAAQ,OAAO;GAAoB,GAC7C,QAAQ,IAAI;UAOD;EAOd;;GAEC,GACD,AAAM,kBAAkB,QAAQ,IAAI;EAIpC;;GAEC,GACD,SAAe,SAAS,QAAQ,IAAI;EAK9B,QACJ,MAAM,MAAM,GAAG,IAAI,EACnB,aAAa,MAAM,EACnB,aAAY,UAA+B,EAC3C,UAAS,kBAAkB,UAAgC;AAiR/D"}

package/types/src/plugin-types.d.ts

@@ -26,6 +26,19 @@ export interface ToolPlugin {
   /** Called after composition is complete - for logging and cleanup */ composeEnd?: (result: ComposeEndContext) => void | Promise<void>;
   /** Called before tool execution - transform input arguments */ transformInput?: (args: unknown, context: RuntimeTransformContext) => unknown | Promise<unknown>;
   /** Called after tool execution - transform output result */ transformOutput?: (result: unknown, context: RuntimeTransformContext) => unknown | Promise<unknown>;
+  /**
+   * Called before a tool is executed
+   * Use this to intercept tool calls, modify arguments, or skip execution entirely.
+   * This enables dynamic tool context handoff to AI agents.
+   *
+   * @returns BeforeToolExecuteResult to modify behavior, or void/undefined to continue normally
+   */ beforeToolExecute?: (context: BeforeToolExecuteContext) => BeforeToolExecuteResult | void | Promise<BeforeToolExecuteResult | void>;
+  /**
+   * Called after a tool is executed (or skipped)
+   * Use this to modify results, log execution, or trigger follow-up actions.
+   *
+   * @returns AfterToolExecuteResult to modify the result, or void/undefined to keep original
+   */ afterToolExecute?: (context: AfterToolExecuteContext) => AfterToolExecuteResult | void | Promise<AfterToolExecuteResult | void>;
   /** Called when plugin is removed or server is disposed - for cleanup */ dispose?: () => void | Promise<void>;
 }
 /** Context for composeStart hook */ export interface ComposeStartContext {
@@ -90,6 +103,57 @@ export interface ToolPlugin {
   /** Original input arguments (available in transformOutput) */ originalArgs?: unknown;
   /** Transformation direction */ direction: "input" | "output";
 }
+/**
+ * Result of beforeToolExecute hook
+ * Allows plugins to modify execution or skip it entirely
+ */ export interface BeforeToolExecuteResult {
+  /**
+   * If true, skip the actual tool execution and use the provided result
+   * This enables dynamic handoff to AI agents
+   */ skipExecution?: boolean;
+  /**
+   * Modified arguments to pass to the tool (if not skipping)
+   */ modifiedArgs?: unknown;
+  /**
+   * Result to return if skipping execution
+   * Required when skipExecution is true
+   */ result?: unknown;
+  /**
+   * Optional metadata to pass to afterToolExecute
+   */ metadata?: Record<string, unknown>;
+}
+/** Context for beforeToolExecute hook */ export interface BeforeToolExecuteContext {
+  /** Name of the tool being executed */ toolName: string;
+  /** Arguments passed to the tool */ args: unknown;
+  /** The MCP server instance */ server: ComposableMCPServer;
+  /** Tool definition (if available) */ toolDefinition?: ComposedTool;
+  /** Whether this is an internal tool call (within agent) vs external (from MCP client) */ isInternalCall: boolean;
+  /** Parent agent name (if called from within an agent) */ agentName?: string;
+  /** Execution context chain (for nested agent calls) */ executionChain?: string[];
+}
+/** Context for afterToolExecute hook */ export interface AfterToolExecuteContext {
+  /** Name of the tool that was executed */ toolName: string;
+  /** Original arguments passed to the tool */ args: unknown;
+  /** Result from tool execution */ result: unknown;
+  /** The MCP server instance */ server: ComposableMCPServer;
+  /** Whether execution was skipped by beforeToolExecute */ wasSkipped: boolean;
+  /** Time taken for execution in milliseconds */ executionTimeMs: number;
+  /** Whether the result indicates an error */ isError: boolean;
+  /** Metadata from beforeToolExecute */ metadata?: Record<string, unknown>;
+  /** Whether this is an internal tool call */ isInternalCall: boolean;
+  /** Parent agent name (if called from within an agent) */ agentName?: string;
+}
+/**
+ * Result of afterToolExecute hook
+ * Allows plugins to modify the final result
+ */ export interface AfterToolExecuteResult {
+  /**
+   * Modified result to return
+   */ modifiedResult?: unknown;
+  /**
+   * If true, mark the result as an error
+   */ markAsError?: boolean;
+}
 export interface ToolConfig {
   /** Override the tool's description */ description?: string;
   /** Tool visibility settings - simplified to two independent flags */ visibility?: {

package/types/src/plugin-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-types.d.ts","sources":["../../src/plugin-types.ts"],"names":[],"mappings":"AAAA;;;CAGC,GAED,cAAc,IAAI,6CAA0D;AAC5E,cAAc,YAAY,qBAAqB;AAC/C,cAAc,mBAAmB,uBAAuB;AACxD,cAAc,aAAa,6BAA6B;AAExD,iBAAiB,qBAAqB;EACpC,SAAS;;AAKX,iBAAiB;EACf,oDAAoD,GACpD,MAAM,MAAM;EAEZ,0DAA0D,GAC1D,UAAU,MAAM;EAEhB,kFAAkF,GAClF,UAAU,QAAQ;EAElB,6CAA6C,GAC7C,QAAQ,kBAAkB,MAAM,MAAM,KAAK,OAAO;EAElD,qEAAqE,GACrE,eAAe,MAAM;EAIrB,8DAA8D,GAC9D,mBAAmB,QAAQ,wBAAwB,IAAI,GAAG,QAAQ,IAAI;EAEtE,iEAAiE,GACjE,gBAAgB,SAAS,wBAAwB,IAAI,GAAG,QAAQ,IAAI;EAEpE,uEAAuE,GACvE,iBACE,MAAM,cACN,SAAS,qBACN,eAAe,IAAI,GAAG,QAAQ,eAAe,IAAI;EAEtD,gEAAgE,GAChE,uBACE,OAAO,OAAO,MAAM,EAAE,eACtB,SAAS,oBACN,IAAI,GAAG,QAAQ,IAAI;EAExB;;;;GAIC,GACD,qBACE,SAAS,iCACN,IAAI,GAAG,QAAQ,IAAI;EAExB,mEAAmE,GACnE,cAAc,QAAQ,sBAAsB,IAAI,GAAG,QAAQ,IAAI;EAI/D,6DAA6D,GAC7D,kBACE,MAAM,OAAO,EACb,SAAS,4BACN,OAAO,GAAG,QAAQ,OAAO;EAE9B,0DAA0D,GAC1D,mBACE,QAAQ,OAAO,EACf,SAAS,4BACN,OAAO,GAAG,QAAQ,OAAO;EAE9B,sEAAsE,GACtE,gBAAgB,IAAI,GAAG,QAAQ,IAAI;;AAarC,kCAAkC,GAClC,iBAAiB;EACf,YAAY,MAAM;EAClB,aAAa,MAAM;EACnB,MAAM;EACN,QAAQ;EACR,gDAAgD,GAChD,gBAAgB,MAAM;;AAGxB,mCAAmC,GACnC,iBAAiB;EACf,UAAU,MAAM;EAChB,QAAQ;EACR,MAAM;EACN,wDAAwD,GACxD,cAAc;EACd,gFAAgF,GAChF,qBAAqB,MAAM;;AAG7B,yCAAyC,GACzC,iBAAiB;EACf,YAAY,MAAM;EAClB,MAAM;EACN,QAAQ;EACR,gCAAgC,GAChC,WAAW,MAAM;;AAGnB,2EAA2E,GAC3E,iBAAiB;EACf,QAAQ;EACR,MAAM,MAAM;EACZ,aAAa,MAAM;EACnB,MAAM,gBAAgB,MAAM;EAC5B,cAAc,MAAM;EACpB,uBAAuB,MAAM,EAAE;EAC/B,WAAW,OAAO,MAAM,EAAE,OAAO;EACjC,sBAAsB,IAAI,MAAM,EAAE,MAAM;EACxC,iBAAiB,MAAM;EACvB,iBAAiB,MAAM;EACvB;IACE,OAAO,MAAM;IACb;MAAmB,gBAAgB,MAAM;MAAE,YAAY,OAAO;;IAC9D,QAAQ;MAAQ,aAAa,MAAM;MAAE,SAAS,MAAM;;IACpD,oBAAoB,MAAM;KACzB,KAAK,MAAM,GAAG,OAAO;;;AAI1B,gCAAgC,GAChC,iBAAiB;EACf,UAAU,MAAM,GAAG,IAAI;EACvB,aAAa,MAAM;EACnB,MAAM;EACN,QAAQ;EACR,wCAAwC,GACxC;IACE,YAAY,MAAM;IAClB,gDAAgD,GAChD,aAAa,MAAM;IACnB,mDAAmD,GACnD,aAAa,MAAM;;;AAIvB,8EAA8E,GAC9E,iBAAiB;EACf,UAAU,MAAM;EAChB,QAAQ;EACR,4DAA4D,GAC5D,eAAe,OAAO;EACtB,6BAA6B,GAC7B,WAAW,UAAU;;AAevB,iBAAiB;EACf,oCAAoC,GACpC,cAAc,MAAM;EACpB,mEAAmE,GACnE;IACE;;;;KAIC,GACD,SAAS,OAAO;IAChB;;;;KAIC,GACD,SAAS,OAAO"}
+{"version":3,"file":"plugin-types.d.ts","sources":["../../src/plugin-types.ts"],"names":[],"mappings":"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"}

package/types/src/set-up-mcp-compose.d.ts

@@ -95,10 +95,52 @@ export interface ComposeDefinition {
      */ refs?: Array<ToolRefXml>;
   };
 }
+/**
+ * Input type for mcpc() that supports both inline definitions and file paths.
+ * - ComposeDefinition: Inline agent definition object
+ * - string: Path to a Markdown agent file (.md)
+ *
+ * @example
+ * ```typescript
+ * // Mix of inline and file-based definitions
+ * await mcpc(serverConf, [
+ *   './agents/coding-agent.md',           // Load from file
+ *   { name: 'inline-agent', description: '...' }  // Inline definition
+ * ]);
+ * ```
+ */ export type ComposeInput = ComposeDefinition | string;
 export interface ComposibleMCPConfig {
   [key: string]: ComposeDefinition[];
 }
+/**
+ * Markdown agent file loader function type.
+ * This is registered by markdownLoaderPlugin() to avoid circular dependencies.
+ */ export type MarkdownAgentLoader = (filePath: string) => Promise<ComposeDefinition>;
+/**
+ * Register the Markdown agent loader (called by markdownLoaderPlugin())
+ */ export declare function setMarkdownAgentLoader(loader: MarkdownAgentLoader): void;
+/**
+ * Check if a path is a Markdown file (.md or .markdown)
+ */ export declare function isMarkdownFile(path: string): boolean;
 export declare function parseMcpcConfigs(conf?: ComposeDefinition[]): ComposeDefinition[];
+/**
+ * Options for mcpc() function
+ */ export interface McpcOptions {
+  /**
+   * Loader plugins to load BEFORE resolving compose inputs.
+   * These plugins register file loaders (e.g., markdown-loader) that are needed
+   * to parse file paths in composeConf.
+   *
+   * Supports both plugin objects and string paths (e.g., "@mcpc/plugin-markdown-loader").
+   *
+   * Note: This is different from ComposeDefinition.plugins which are runtime plugins
+   * that transform tool descriptions and results AFTER composition.
+   */ plugins?: (ToolPlugin | string)[];
+  /**
+   * Callback to register custom tools or perform additional setup before composition.
+   * Useful for adding internal tools or custom configurations.
+   */ setup?: (server: ComposableMCPServer) => void | Promise<void>;
+}
 /**
  * Create and configure an agentic MCP server with composed tools.
  *
@@ -110,6 +152,7 @@ export declare function parseMcpcConfigs(conf?: ComposeDefinition[]): ComposeDef
  *
  * @example
  * ```typescript
+ * // Using inline definitions
  * const server = await mcpc(
  *   [
  *     { name: "coding-agent", version: "1.0.0" },
@@ -139,6 +182,16 @@ export declare function parseMcpcConfigs(conf?: ComposeDefinition[]): ComposeDef
  *     options: { mode: "ai_sampling" }
  *   }]
  * );
+ *
+ * // Using Markdown file paths with plugin
+ * import { markdownLoaderPlugin } from "@mcpc/plugin-markdown-loader";
+ *
+ * const server = await mcpc(
+ *   [{ name: "my-server", version: "1.0.0" }, { capabilities: { tools: {} } }],
+ *   ["./agents/coding-agent.md"],
+ *   { plugins: [markdownLoaderPlugin()] }
+ * );
+ *
  * await server.connect(new StdioServerTransport());
  * ```
  *
@@ -146,20 +199,17 @@ export declare function parseMcpcConfigs(conf?: ComposeDefinition[]): ComposeDef
  *   - First element: Server metadata (name, version)
  *   - Second element: Server capabilities (tools, sampling, etc.)
  *
- * @param composeConf - Array of agent composition definitions. Each definition includes:
- *   - name: Agent name (set to null for composition-only mode)
- *   - description: Agent purpose with XML-like tool references (e.g., `<tool name="server.tool"/>`)
- *   - deps: MCP server dependencies with transport configurations (stdio, sse, streamable-http)
- *   - plugins: Global plugins to transform/extend tool behavior (objects or file paths)
- *   - options: Execution mode settings (agentic, ai_sampling, ai_acp)
+ * @param composeConf - Array of agent composition definitions or Markdown file paths.
+ *   - ComposeDefinition: Inline agent definition object
+ *   - string: Path to a Markdown agent file (.md) - requires markdown-loader plugin
  *
- * @param setupCallback - Optional callback to register custom tools or perform additional setup
- *   before composition. Useful for adding internal tools or custom configurations.
+ * @param options - Optional configuration for mcpc()
+ *   - plugins: Plugins to load before resolving compose inputs (e.g., markdown-loader)
  *
  * @returns A configured MCP Server instance ready to connect to a transport
  *
  * @see {@link ComposeDefinition} for detailed composition configuration options
  * @see {@link ToolPlugin} for plugin development guide
  * @see https://github.com/mcpc-tech/mcpc/tree/main/docs for complete documentation
- */ export declare function mcpc(serverConf: ConstructorParameters<typeof ComposableMCPServer>, composeConf?: ComposeDefinition[], setupCallback?: (server: ComposableMCPServer) => void | Promise<void>): Promise<InstanceType<typeof ComposableMCPServer>>;
+ */ export declare function mcpc(serverConf: ConstructorParameters<typeof ComposableMCPServer>, composeConf?: ComposeInput[], optionsOrSetup?: McpcOptions | ((server: ComposableMCPServer) => void | Promise<void>)): Promise<InstanceType<typeof ComposableMCPServer>>;
 //# sourceMappingURL=set-up-mcp-compose.d.ts.map

package/types/src/set-up-mcp-compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-up-mcp-compose.d.ts","sources":["../../src/set-up-mcp-compose.ts"],"names":[],"mappings":"AAAA,SAAS,mBAAmB,oBAAoB;AAChD,cAAc,UAAU,6BAA6B;AACrD,cAAc,cAAc,qBAAqB;AACjD,cAAc,UAAU,4BAA4B;AACpD,cAAc,UAAU,qBAAqB;AAC7C,cAAc,aAAa,6BAA6B;AAExD,iBAAiB;EACf;;;GAGC,GACD,MAAM,MAAM,GAAG,IAAI;EACnB;;GAEC,GACD,cAAc,MAAM;EACpB,OAAO;EAEP;;;;;;;;;;;GAWC,GACD,WAAW,aAAa,MAAM;EAE9B;IACE;;;;;;KAMC,GACD,OAAO;IAEP;;KAEC,GACD,iBAAiB;IAEjB;;;;KAIC,GACD;MACE;QACE,QAAQ;UAAQ,OAAO,MAAM;;QAC7B,eAAe,MAAM;QACrB,gBAAgB,MAAM;QACtB,uBAAuB,MAAM;;;IAIjC;;;;KAIC,GACD;MACE,SAAS,MAAM;MACf,OAAO,MAAM;MACb,MAAM,OAAO,MAAM,EAAE,MAAM;MAC3B;QACE,MAAM,MAAM;QACZ,aAAa;UACX,MAAM,MAAM;UACZ,SAAS,MAAM;UACf,OAAO,MAAM;UACb,MAAM,OAAO,MAAM,EAAE,MAAM;;;MAG/B,iBAAiB,OAAO;;IAG1B;;;;KAIC,GACD,WAAW,MAAM;IAEjB;;;;KAIC,GACD,YAAY,MAAM;IAElB;;;;KAIC,GACD,iBAAiB,OAAO;IAExB;;;;;KAKC,GACD;;;KAGC,GACD,OAAO,MAAM;;;AAMjB,iBAAiB;GACd,KAAK,MAAM,GAAG;;AAGjB,OAAO,iBAAS,iBACd,OAAO,mBAAmB,GACzB;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DC,GACD,OAAO,iBAAe,KACpB,YAAY,6BAA6B,oBAAoB,EAC7D,cAAc,mBAAmB,EACjC,iBAAiB,QAAQ,wBAAwB,IAAI,GAAG,QAAQ,IAAI,CAAC,GACpE,QAAQ,oBAAoB"}
+{"version":3,"file":"set-up-mcp-compose.d.ts","sources":["../../src/set-up-mcp-compose.ts"],"names":[],"mappings":"AAAA,SAAS,mBAAmB,oBAAoB;AAChD,cAAc,UAAU,6BAA6B;AACrD,cAAc,cAAc,qBAAqB;AACjD,cAAc,UAAU,4BAA4B;AACpD,cAAc,UAAU,qBAAqB;AAC7C,cAAc,aAAa,6BAA6B;AAExD,iBAAiB;EACf;;;GAGC,GACD,MAAM,MAAM,GAAG,IAAI;EACnB;;GAEC,GACD,cAAc,MAAM;EACpB,OAAO;EAEP;;;;;;;;;;;GAWC,GACD,WAAW,aAAa,MAAM;EAE9B;IACE;;;;;;KAMC,GACD,OAAO;IAEP;;KAEC,GACD,iBAAiB;IAEjB;;;;KAIC,GACD;MACE;QACE,QAAQ;UAAQ,OAAO,MAAM;;QAC7B,eAAe,MAAM;QACrB,gBAAgB,MAAM;QACtB,uBAAuB,MAAM;;;IAIjC;;;;KAIC,GACD;MACE,SAAS,MAAM;MACf,OAAO,MAAM;MACb,MAAM,OAAO,MAAM,EAAE,MAAM;MAC3B;QACE,MAAM,MAAM;QACZ,aAAa;UACX,MAAM,MAAM;UACZ,SAAS,MAAM;UACf,OAAO,MAAM;UACb,MAAM,OAAO,MAAM,EAAE,MAAM;;;MAG/B,iBAAiB,OAAO;;IAG1B;;;;KAIC,GACD,WAAW,MAAM;IAEjB;;;;KAIC,GACD,YAAY,MAAM;IAElB;;;;KAIC,GACD,iBAAiB,OAAO;IAExB;;;;;KAKC,GACD;;;KAGC,GACD,OAAO,MAAM;;;AAIjB;;;;;;;;;;;;;CAaC,GACD,YAAY,eAAe,oBAAoB,MAAM;AAIrD,iBAAiB;GACd,KAAK,MAAM,GAAG;;AAGjB;;;CAGC,GACD,YAAY,uBACV,UAAU,MAAM,KACb,QAAQ;AAKb;;CAEC,GACD,OAAO,iBAAS,uBAAuB,QAAQ,mBAAmB,GAAG,IAAI;AAIzE;;CAEC,GACD,OAAO,iBAAS,eAAe,MAAM,MAAM,GAAG,OAAO;AAgCrD,OAAO,iBAAS,iBACd,OAAO,mBAAmB,GACzB;AAIH;;CAEC,GACD,iBAAiB;EACf;;;;;;;;;GASC,GACD,WAAW,aAAa,MAAM;EAE9B;;;GAGC,GACD,SAAS,QAAQ,wBAAwB,IAAI,GAAG,QAAQ,IAAI;;AAG9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEC,GACD,OAAO,iBAAe,KACpB,YAAY,6BAA6B,oBAAoB,EAC7D,cAAc,cAAc,EAC5B,iBACI,gBACE,QAAQ,wBAAwB,IAAI,GAAG,QAAQ,IAAI,EAAE,GAC1D,QAAQ,oBAAoB"}