@mcpc-tech/plugin-markdown-loader 0.0.4 → 0.0.6

package/index.cjs

@@ -32,7 +32,9 @@ var mod_exports = {};
 __export(mod_exports, {
   createPlugin: () => createPlugin,
   default: () => mod_default,
+  isDirectory: () => isDirectory,
   isMarkdownAgentFile: () => isMarkdownFile,
+  loadMarkdownAgentDirectory: () => loadMarkdownAgentDirectory,
   loadMarkdownAgentFile: () => loadMarkdownAgentFile,
   markdownAgentToComposeDefinition: () => markdownAgentToComposeDefinition,
   markdownLoaderPlugin: () => markdownLoaderPlugin,
@@ -467,6 +469,23 @@ Execute a tool:
   "args": { /* tool parameters */ }
 }
 \`\`\`
+</format>`,
+  /**
+   * Compact system prompt for autonomous MCP execution (when manual is provided)
+   *
+   * Uses simplified description with progressive disclosure:
+   * - Short description shown by default
+   * - Use `man` command with args `{ manual: true }` to get full manual
+   */
+  AUTONOMOUS_EXECUTION_COMPACT: `Agentic tool \`{toolName}\`: {description}
+
+Use \`man\` command with args \`{ tools: [], manual: true }\` to get the full manual, or \`{ tools: ["tool1"] }\` to get tool schemas.
+
+<format>
+Get full manual: \`{ "tool": "man", "args": { "tools": [], "manual": true } }\`
+Get tool schemas: \`{ "tool": "man", "args": { "tools": ["tool1", "tool2"] } }\`
+Get both: \`{ "tool": "man", "args": { "tools": ["tool1"], "manual": true } }\`
+Execute a tool: \`{ "tool": "tool_name", "args": { /* parameters */ } }\`
 </format>`,
   /**
    * Tool description for sampling tools (shown in MCP tools list)
@@ -544,6 +563,7 @@ Adjust parameters and retry.`,
 };
 var CompiledPrompts = {
   autonomousExecution: p(SystemPrompts.AUTONOMOUS_EXECUTION),
+  autonomousExecutionCompact: p(SystemPrompts.AUTONOMOUS_EXECUTION_COMPACT),
   samplingToolDescription: p(SystemPrompts.SAMPLING_TOOL_DESCRIPTION),
   aiLoopSystem: p(SystemPrompts.AI_LOOP_SYSTEM),
   actionSuccess: p(ResponseTemplates.ACTION_SUCCESS),
@@ -610,7 +630,7 @@ function createArgsDefFactory(_name, _allToolNames, _depGroups, _predefinedSteps
           },
           args: {
             type: "object",
-            description: `For "man": { tools: ["tool1", "tool2"] }. For other tools: tool parameters that strictly adhere to the tool's JSON schema.`
+            description: `For "man": { tools: ["tool1", "tool2"], manual?: true }. For other tools: tool parameters that strictly adhere to the tool's JSON schema.`
           }
         },
         required: [
@@ -621,7 +641,10 @@ function createArgsDefFactory(_name, _allToolNames, _depGroups, _predefinedSteps
     },
     /**
      * Schema for "man" command args validation
-     * Expected format: { tools: ["tool1", "tool2"] }
+     * Expected format: { tools: ["tool1", "tool2"], manual?: true }
+     *
+     * - Always require `tools`
+     * - Allow empty tools only when `manual: true`
      */
     forMan: function(allToolNames) {
       return {
@@ -635,16 +658,50 @@ function createArgsDefFactory(_name, _allToolNames, _depGroups, _predefinedSteps
               errorMessage: {
                 enum: `Invalid tool name. Available: ${allToolNames.join(", ")}`
               }
-            },
-            minItems: 1,
-            errorMessage: {
-              minItems: "At least one tool name is required"
             }
+          },
+          manual: {
+            type: "boolean",
+            description: "Set to true to get the full manual for this agent (progressive disclosure)."
           }
         },
         required: [
           "tools"
         ],
+        additionalProperties: false,
+        anyOf: [
+          // manual-only (tools can be empty)
+          {
+            properties: {
+              manual: {
+                enum: [
+                  true
+                ]
+              },
+              tools: {
+                minItems: 0
+              }
+            },
+            required: [
+              "tools",
+              "manual"
+            ]
+          },
+          // tool schemas (require at least one tool)
+          {
+            properties: {
+              tools: {
+                minItems: 1,
+                errorMessage: {
+                  minItems: "At least one tool name is required"
+                }
+              }
+            },
+            required: [
+              "tools"
+            ]
+          }
+        ],
         errorMessage: {
           required: {
             tools: 'Missing "tools" field. Expected: { tools: ["tool1", "tool2"] }'
@@ -766,14 +823,16 @@ var AgenticExecutor = class {
   allToolNames;
   toolNameToDetailList;
   server;
+  manual;
   logger;
   tracingEnabled;
   toolSchemaMap;
-  constructor(name, allToolNames, toolNameToDetailList, server) {
+  constructor(name, allToolNames, toolNameToDetailList, server, manual) {
     this.name = name;
     this.allToolNames = allToolNames;
     this.toolNameToDetailList = toolNameToDetailList;
     this.server = server;
+    this.manual = manual;
     this.tracingEnabled = false;
     this.logger = createLogger(`mcpc.agentic.${name}`, server);
     this.toolSchemaMap = new Map(toolNameToDetailList);
@@ -841,7 +900,34 @@ var AgenticExecutor = class {
           };
         }
         const argsObj = args.args;
-        return this.handleManCommand(argsObj.tools, executeSpan);
+        const tools = argsObj.tools ?? [];
+        const wantManual = argsObj.manual === true;
+        const wantTools = tools.length > 0;
+        if (wantTools && wantManual) {
+          const toolSchemas = this.handleManCommand(tools, null);
+          const manualResult = this.handleManualRequest(null);
+          if (executeSpan) {
+            executeSpan.setAttributes({
+              toolType: "man",
+              requestType: "tools+manual"
+            });
+            endSpan(executeSpan);
+          }
+          return {
+            content: [
+              ...toolSchemas.content,
+              {
+                type: "text",
+                text: "\n---\n"
+              },
+              ...manualResult.content
+            ]
+          };
+        }
+        if (wantManual) {
+          return this.handleManualRequest(executeSpan);
+        }
+        return this.handleManCommand(tools, executeSpan);
       }
       const toolArgs = args.args || {};
       return await this.executeTool(tool2, toolArgs, executeSpan);
@@ -864,6 +950,44 @@ var AgenticExecutor = class {
       };
     }
   }
+  /**
+   * Handle `man { manual: true }` - return full manual for progressive disclosure
+   */
+  handleManualRequest(executeSpan) {
+    if (executeSpan) {
+      executeSpan.setAttributes({
+        toolType: "man",
+        requestType: "manual"
+      });
+    }
+    if (!this.manual) {
+      if (executeSpan) {
+        endSpan(executeSpan);
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: "No manual available for this agent."
+          }
+        ]
+      };
+    }
+    if (executeSpan) {
+      executeSpan.setAttributes({
+        success: true
+      });
+      endSpan(executeSpan);
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: this.manual
+        }
+      ]
+    };
+  }
   /**
    * Handle `man` command - return schemas for requested tools
    * @param requestedTools - Array of tool names (already validated via JSON Schema)
@@ -905,15 +1029,29 @@ ${JSON.stringify(cleanedSchema, null, 2)}
    * Execute a tool with runtime validation
    */
   async executeTool(tool2, toolArgs, executeSpan) {
-    const externalTool = this.toolNameToDetailList.find(([name]) => name === tool2);
-    if (externalTool) {
-      const [, toolDetail] = externalTool;
+    const isExternalTool = this.toolNameToDetailList.some(([name]) => name === tool2);
+    const isInternalTool = this.allToolNames.includes(tool2);
+    if (!isExternalTool && !isInternalTool) {
       if (executeSpan) {
         executeSpan.setAttributes({
-          toolType: "external",
-          selectedTool: tool2
+          toolType: "not_found",
+          tool: tool2
         });
+        endSpan(executeSpan);
       }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Tool "${tool2}" not found. Available tools: ${this.allToolNames.join(", ")}`
+          }
+        ],
+        isError: true
+      };
+    }
+    if (isExternalTool) {
+      const externalTool = this.toolNameToDetailList.find(([name]) => name === tool2);
+      const [, toolDetail] = externalTool;
       if (toolDetail.inputSchema) {
         const rawSchema = extractJsonSchema(toolDetail.inputSchema);
         const validation = validateSchema(toolArgs, rawSchema);
@@ -936,84 +1074,53 @@ ${JSON.stringify(cleanedSchema, null, 2)}
           };
         }
       }
-      this.logger.debug({
-        message: "Executing external tool",
-        tool: tool2
+    }
+    const toolType = isExternalTool ? "external" : "internal";
+    if (executeSpan) {
+      executeSpan.setAttributes({
+        toolType,
+        selectedTool: tool2
+      });
+    }
+    this.logger.debug({
+      message: `Executing ${toolType} tool`,
+      tool: tool2
+    });
+    try {
+      const result = await this.server.callTool(tool2, toolArgs, {
+        agentName: this.name
       });
-      const result = await toolDetail.execute(toolArgs);
+      const callToolResult = result ?? {
+        content: []
+      };
       if (executeSpan) {
         executeSpan.setAttributes({
           success: true,
-          isError: !!result.isError,
-          resultContentLength: result.content?.length || 0
+          isError: !!callToolResult.isError,
+          resultContentLength: callToolResult.content?.length || 0
         });
         endSpan(executeSpan);
       }
-      return result;
-    }
-    if (this.allToolNames.includes(tool2)) {
+      return callToolResult;
+    } catch (error) {
       if (executeSpan) {
-        executeSpan.setAttributes({
-          toolType: "internal",
-          selectedTool: tool2
-        });
-      }
-      this.logger.debug({
-        message: "Executing internal tool",
-        tool: tool2
-      });
-      try {
-        const result = await this.server.callTool(tool2, toolArgs, {
-          agentName: this.name
-        });
-        const callToolResult = result ?? {
-          content: []
-        };
-        if (executeSpan) {
-          executeSpan.setAttributes({
-            success: true,
-            isError: !!callToolResult.isError,
-            resultContentLength: callToolResult.content?.length || 0
-          });
-          endSpan(executeSpan);
-        }
-        return callToolResult;
-      } catch (error) {
-        if (executeSpan) {
-          endSpan(executeSpan, error);
-        }
-        this.logger.error({
-          message: "Error executing internal tool",
-          tool: tool2,
-          error: String(error)
-        });
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error executing tool "${tool2}": ${error instanceof Error ? error.message : String(error)}`
-            }
-          ],
-          isError: true
-        };
+        endSpan(executeSpan, error);
       }
-    }
-    if (executeSpan) {
-      executeSpan.setAttributes({
-        toolType: "not_found",
-        tool: tool2
+      this.logger.error({
+        message: `Error executing ${toolType} tool`,
+        tool: tool2,
+        error: String(error)
       });
-      endSpan(executeSpan);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error executing tool "${tool2}": ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
     }
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Tool "${tool2}" not found. Available tools: ${this.allToolNames.join(", ")}`
-        }
-      ],
-      isError: true
-    };
   }
   validate(args, schema) {
     return validateSchema(args, schema);
@@ -1021,19 +1128,18 @@ ${JSON.stringify(cleanedSchema, null, 2)}
 };
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@jsr/mcpc__core/src/executors/agentic/agentic-tool-registrar.js
-function registerAgenticTool(server, { description, name, allToolNames, depGroups, toolNameToDetailList }) {
+function registerAgenticTool(server, { description, name, allToolNames, depGroups, toolNameToDetailList, manual }) {
   const createArgsDef = createArgsDefFactory(name, allToolNames, depGroups, void 0, void 0);
-  const agenticExecutor = new AgenticExecutor(name, allToolNames, toolNameToDetailList, server);
-  description = CompiledPrompts.autonomousExecution({
+  const agenticExecutor = new AgenticExecutor(name, allToolNames, toolNameToDetailList, server, manual);
+  description = manual ? CompiledPrompts.autonomousExecutionCompact({
+    toolName: name,
+    description
+  }) : CompiledPrompts.autonomousExecution({
     toolName: name,
     description
   });
   const agenticArgsDef = createArgsDef.forAgentic(allToolNames);
-  const argsDef = agenticArgsDef;
-  const schema = allToolNames.length > 0 ? argsDef : {
-    type: "object",
-    properties: {}
-  };
+  const schema = agenticArgsDef;
   server.tool(name, description, jsonSchema(createModelCompatibleJSONSchema(schema)), async (args) => {
     return await agenticExecutor.execute(args, schema);
   });
@@ -1052,7 +1158,8 @@ var createAgenticModePlugin = () => ({
       name: context2.name,
       allToolNames: context2.allToolNames,
       depGroups: context2.depGroups,
-      toolNameToDetailList: context2.toolNameToDetailList
+      toolNameToDetailList: context2.toolNameToDetailList,
+      manual: context2.manual
     });
   }
 });
@@ -1454,7 +1561,7 @@ IMPORTANT: You MUST respond with valid JSON only. Do not include any text before
     let enhanced = systemPrompt || "";
     const toolsPrompt = `
 
-AVAILABLE TOOLS:
+<available_tools>
 You have access to the following tools. To use a tool, respond with this XML format:
 <use_tool tool="tool_name">
 {"param1": "value1", "param2": "value2"}
@@ -1463,23 +1570,34 @@ You have access to the following tools. To use a tool, respond with this XML for
 Follow the JSON schema definition for each tool's parameters.
 You can use multiple tools in one response. DO NOT include text before or after tool calls - wait for the tool results first.
 
-Tools:`;
+<tools>`;
     const toolDescriptions = tools.map((tool2) => {
       if (tool2.type === "function") {
         const toolAny = tool2;
         const description = toolAny.description || "No description provided";
         const schema = toolAny.inputSchema || toolAny.parameters;
-        const params = schema ? `
-  JSON Schema: ${JSON.stringify(schema, null, 2)}` : "";
+        const schemaStr = schema ? `
+<schema>
+${JSON.stringify(schema, null, 2)}
+</schema>` : "";
         return `
-- ${tool2.name}: ${description}${params}`;
+<tool name="${tool2.name}">
+<description>
+${description}
+</description>${schemaStr}
+</tool>`;
       } else if (tool2.type === "provider-defined") {
         return `
-- ${tool2.name}: ${tool2.id || "No description provided"}`;
+<tool name="${tool2.name}">
+<description>${tool2.id || "No description provided"}</description>
+</tool>`;
       }
       return "";
     }).filter(Boolean).join("");
-    enhanced = enhanced ? `${enhanced}${toolsPrompt}${toolDescriptions}` : `${toolsPrompt}${toolDescriptions}`.trim();
+    const toolsEnd = `
+</tools>
+</available_tools>`;
+    enhanced = enhanced ? `${enhanced}${toolsPrompt}${toolDescriptions}${toolsEnd}` : `${toolsPrompt}${toolDescriptions}${toolsEnd}`.trim();
     return enhanced || void 0;
   }
   /**
@@ -3897,6 +4015,7 @@ function parse(content, options = {}) {
 }
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@mcpc/plugin-markdown-loader/src/markdown-loader.js
+var import_node_path = require("node:path");
 var import_node_process5 = __toESM(require("node:process"), 1);
 function replaceEnvVars(str2) {
   return str2.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, varName) => {
@@ -3937,7 +4056,7 @@ function parseMarkdownAgent(content) {
   }
   return {
     frontMatter,
-    description: markdownContent.trim()
+    body: markdownContent.trim()
   };
 }
 var OPTION_KEYS = [
@@ -3952,16 +4071,20 @@ var OPTION_KEYS = [
 ];
 function markdownAgentToComposeDefinition(parsed) {
   const frontMatter = replaceEnvVarsInObject(parsed.frontMatter);
-  const description = replaceEnvVars(parsed.description);
+  const body = replaceEnvVars(parsed.body);
   const options = {};
   for (const key of OPTION_KEYS) {
     if (frontMatter[key] !== void 0) {
       options[key] = frontMatter[key];
     }
   }
+  const hasDescription = frontMatter.description !== void 0 && frontMatter.description !== "";
   return {
     name: frontMatter.name,
-    description,
+    description: hasDescription ? frontMatter.description : body,
+    ...hasDescription && body ? {
+      manual: body
+    } : {},
     deps: frontMatter.deps,
     plugins: frontMatter.plugins,
     ...Object.keys(options).length > 0 ? {
@@ -3974,6 +4097,45 @@ async function loadMarkdownAgentFile(filePath) {
   const parsed = parseMarkdownAgent(content);
   return markdownAgentToComposeDefinition(parsed);
 }
+async function loadMarkdownAgentDirectory(dirPath, options = {}) {
+  const { recursive = false } = options;
+  const definitions = [];
+  const errors = [];
+  async function processDirectory(dir) {
+    const entries = await (0, import_promises.readdir)(dir, {
+      withFileTypes: true
+    });
+    for (const entry of entries) {
+      const fullPath = (0, import_node_path.join)(dir, entry.name);
+      if (entry.isDirectory() && recursive) {
+        await processDirectory(fullPath);
+      } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+        try {
+          const definition = await loadMarkdownAgentFile(fullPath);
+          definitions.push(definition);
+        } catch (error) {
+          errors.push({
+            path: fullPath,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    }
+  }
+  await processDirectory(dirPath);
+  return {
+    definitions,
+    errors
+  };
+}
+async function isDirectory(path) {
+  try {
+    const stats = await (0, import_promises.stat)(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@mcpc/plugin-markdown-loader/mod.ts
 function markdownLoaderPlugin() {
@@ -3993,7 +4155,9 @@ var mod_default = defaultPlugin;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createPlugin,
+  isDirectory,
   isMarkdownAgentFile,
+  loadMarkdownAgentDirectory,
   loadMarkdownAgentFile,
   markdownAgentToComposeDefinition,
   markdownLoaderPlugin,

package/index.mjs

@@ -428,6 +428,23 @@ Execute a tool:
   "args": { /* tool parameters */ }
 }
 \`\`\`
+</format>`,
+  /**
+   * Compact system prompt for autonomous MCP execution (when manual is provided)
+   *
+   * Uses simplified description with progressive disclosure:
+   * - Short description shown by default
+   * - Use `man` command with args `{ manual: true }` to get full manual
+   */
+  AUTONOMOUS_EXECUTION_COMPACT: `Agentic tool \`{toolName}\`: {description}
+
+Use \`man\` command with args \`{ tools: [], manual: true }\` to get the full manual, or \`{ tools: ["tool1"] }\` to get tool schemas.
+
+<format>
+Get full manual: \`{ "tool": "man", "args": { "tools": [], "manual": true } }\`
+Get tool schemas: \`{ "tool": "man", "args": { "tools": ["tool1", "tool2"] } }\`
+Get both: \`{ "tool": "man", "args": { "tools": ["tool1"], "manual": true } }\`
+Execute a tool: \`{ "tool": "tool_name", "args": { /* parameters */ } }\`
 </format>`,
   /**
    * Tool description for sampling tools (shown in MCP tools list)
@@ -505,6 +522,7 @@ Adjust parameters and retry.`,
 };
 var CompiledPrompts = {
   autonomousExecution: p(SystemPrompts.AUTONOMOUS_EXECUTION),
+  autonomousExecutionCompact: p(SystemPrompts.AUTONOMOUS_EXECUTION_COMPACT),
   samplingToolDescription: p(SystemPrompts.SAMPLING_TOOL_DESCRIPTION),
   aiLoopSystem: p(SystemPrompts.AI_LOOP_SYSTEM),
   actionSuccess: p(ResponseTemplates.ACTION_SUCCESS),
@@ -571,7 +589,7 @@ function createArgsDefFactory(_name, _allToolNames, _depGroups, _predefinedSteps
           },
           args: {
             type: "object",
-            description: `For "man": { tools: ["tool1", "tool2"] }. For other tools: tool parameters that strictly adhere to the tool's JSON schema.`
+            description: `For "man": { tools: ["tool1", "tool2"], manual?: true }. For other tools: tool parameters that strictly adhere to the tool's JSON schema.`
           }
         },
         required: [
@@ -582,7 +600,10 @@ function createArgsDefFactory(_name, _allToolNames, _depGroups, _predefinedSteps
     },
     /**
      * Schema for "man" command args validation
-     * Expected format: { tools: ["tool1", "tool2"] }
+     * Expected format: { tools: ["tool1", "tool2"], manual?: true }
+     *
+     * - Always require `tools`
+     * - Allow empty tools only when `manual: true`
      */
     forMan: function(allToolNames) {
       return {
@@ -596,16 +617,50 @@ function createArgsDefFactory(_name, _allToolNames, _depGroups, _predefinedSteps
               errorMessage: {
                 enum: `Invalid tool name. Available: ${allToolNames.join(", ")}`
               }
-            },
-            minItems: 1,
-            errorMessage: {
-              minItems: "At least one tool name is required"
             }
+          },
+          manual: {
+            type: "boolean",
+            description: "Set to true to get the full manual for this agent (progressive disclosure)."
           }
         },
         required: [
           "tools"
         ],
+        additionalProperties: false,
+        anyOf: [
+          // manual-only (tools can be empty)
+          {
+            properties: {
+              manual: {
+                enum: [
+                  true
+                ]
+              },
+              tools: {
+                minItems: 0
+              }
+            },
+            required: [
+              "tools",
+              "manual"
+            ]
+          },
+          // tool schemas (require at least one tool)
+          {
+            properties: {
+              tools: {
+                minItems: 1,
+                errorMessage: {
+                  minItems: "At least one tool name is required"
+                }
+              }
+            },
+            required: [
+              "tools"
+            ]
+          }
+        ],
         errorMessage: {
           required: {
             tools: 'Missing "tools" field. Expected: { tools: ["tool1", "tool2"] }'
@@ -727,14 +782,16 @@ var AgenticExecutor = class {
   allToolNames;
   toolNameToDetailList;
   server;
+  manual;
   logger;
   tracingEnabled;
   toolSchemaMap;
-  constructor(name, allToolNames, toolNameToDetailList, server) {
+  constructor(name, allToolNames, toolNameToDetailList, server, manual) {
     this.name = name;
     this.allToolNames = allToolNames;
     this.toolNameToDetailList = toolNameToDetailList;
     this.server = server;
+    this.manual = manual;
     this.tracingEnabled = false;
     this.logger = createLogger(`mcpc.agentic.${name}`, server);
     this.toolSchemaMap = new Map(toolNameToDetailList);
@@ -802,7 +859,34 @@ var AgenticExecutor = class {
           };
         }
         const argsObj = args.args;
-        return this.handleManCommand(argsObj.tools, executeSpan);
+        const tools = argsObj.tools ?? [];
+        const wantManual = argsObj.manual === true;
+        const wantTools = tools.length > 0;
+        if (wantTools && wantManual) {
+          const toolSchemas = this.handleManCommand(tools, null);
+          const manualResult = this.handleManualRequest(null);
+          if (executeSpan) {
+            executeSpan.setAttributes({
+              toolType: "man",
+              requestType: "tools+manual"
+            });
+            endSpan(executeSpan);
+          }
+          return {
+            content: [
+              ...toolSchemas.content,
+              {
+                type: "text",
+                text: "\n---\n"
+              },
+              ...manualResult.content
+            ]
+          };
+        }
+        if (wantManual) {
+          return this.handleManualRequest(executeSpan);
+        }
+        return this.handleManCommand(tools, executeSpan);
       }
       const toolArgs = args.args || {};
       return await this.executeTool(tool2, toolArgs, executeSpan);
@@ -825,6 +909,44 @@ var AgenticExecutor = class {
       };
     }
   }
+  /**
+   * Handle `man { manual: true }` - return full manual for progressive disclosure
+   */
+  handleManualRequest(executeSpan) {
+    if (executeSpan) {
+      executeSpan.setAttributes({
+        toolType: "man",
+        requestType: "manual"
+      });
+    }
+    if (!this.manual) {
+      if (executeSpan) {
+        endSpan(executeSpan);
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: "No manual available for this agent."
+          }
+        ]
+      };
+    }
+    if (executeSpan) {
+      executeSpan.setAttributes({
+        success: true
+      });
+      endSpan(executeSpan);
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: this.manual
+        }
+      ]
+    };
+  }
   /**
    * Handle `man` command - return schemas for requested tools
    * @param requestedTools - Array of tool names (already validated via JSON Schema)
@@ -866,15 +988,29 @@ ${JSON.stringify(cleanedSchema, null, 2)}
    * Execute a tool with runtime validation
    */
   async executeTool(tool2, toolArgs, executeSpan) {
-    const externalTool = this.toolNameToDetailList.find(([name]) => name === tool2);
-    if (externalTool) {
-      const [, toolDetail] = externalTool;
+    const isExternalTool = this.toolNameToDetailList.some(([name]) => name === tool2);
+    const isInternalTool = this.allToolNames.includes(tool2);
+    if (!isExternalTool && !isInternalTool) {
       if (executeSpan) {
         executeSpan.setAttributes({
-          toolType: "external",
-          selectedTool: tool2
+          toolType: "not_found",
+          tool: tool2
         });
+        endSpan(executeSpan);
       }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Tool "${tool2}" not found. Available tools: ${this.allToolNames.join(", ")}`
+          }
+        ],
+        isError: true
+      };
+    }
+    if (isExternalTool) {
+      const externalTool = this.toolNameToDetailList.find(([name]) => name === tool2);
+      const [, toolDetail] = externalTool;
       if (toolDetail.inputSchema) {
         const rawSchema = extractJsonSchema(toolDetail.inputSchema);
         const validation = validateSchema(toolArgs, rawSchema);
@@ -897,84 +1033,53 @@ ${JSON.stringify(cleanedSchema, null, 2)}
           };
         }
       }
-      this.logger.debug({
-        message: "Executing external tool",
-        tool: tool2
+    }
+    const toolType = isExternalTool ? "external" : "internal";
+    if (executeSpan) {
+      executeSpan.setAttributes({
+        toolType,
+        selectedTool: tool2
+      });
+    }
+    this.logger.debug({
+      message: `Executing ${toolType} tool`,
+      tool: tool2
+    });
+    try {
+      const result = await this.server.callTool(tool2, toolArgs, {
+        agentName: this.name
       });
-      const result = await toolDetail.execute(toolArgs);
+      const callToolResult = result ?? {
+        content: []
+      };
       if (executeSpan) {
         executeSpan.setAttributes({
           success: true,
-          isError: !!result.isError,
-          resultContentLength: result.content?.length || 0
+          isError: !!callToolResult.isError,
+          resultContentLength: callToolResult.content?.length || 0
         });
         endSpan(executeSpan);
       }
-      return result;
-    }
-    if (this.allToolNames.includes(tool2)) {
+      return callToolResult;
+    } catch (error) {
       if (executeSpan) {
-        executeSpan.setAttributes({
-          toolType: "internal",
-          selectedTool: tool2
-        });
-      }
-      this.logger.debug({
-        message: "Executing internal tool",
-        tool: tool2
-      });
-      try {
-        const result = await this.server.callTool(tool2, toolArgs, {
-          agentName: this.name
-        });
-        const callToolResult = result ?? {
-          content: []
-        };
-        if (executeSpan) {
-          executeSpan.setAttributes({
-            success: true,
-            isError: !!callToolResult.isError,
-            resultContentLength: callToolResult.content?.length || 0
-          });
-          endSpan(executeSpan);
-        }
-        return callToolResult;
-      } catch (error) {
-        if (executeSpan) {
-          endSpan(executeSpan, error);
-        }
-        this.logger.error({
-          message: "Error executing internal tool",
-          tool: tool2,
-          error: String(error)
-        });
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error executing tool "${tool2}": ${error instanceof Error ? error.message : String(error)}`
-            }
-          ],
-          isError: true
-        };
+        endSpan(executeSpan, error);
       }
-    }
-    if (executeSpan) {
-      executeSpan.setAttributes({
-        toolType: "not_found",
-        tool: tool2
+      this.logger.error({
+        message: `Error executing ${toolType} tool`,
+        tool: tool2,
+        error: String(error)
       });
-      endSpan(executeSpan);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error executing tool "${tool2}": ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
     }
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Tool "${tool2}" not found. Available tools: ${this.allToolNames.join(", ")}`
-        }
-      ],
-      isError: true
-    };
   }
   validate(args, schema) {
     return validateSchema(args, schema);
@@ -982,19 +1087,18 @@ ${JSON.stringify(cleanedSchema, null, 2)}
 };
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@jsr/mcpc__core/src/executors/agentic/agentic-tool-registrar.js
-function registerAgenticTool(server, { description, name, allToolNames, depGroups, toolNameToDetailList }) {
+function registerAgenticTool(server, { description, name, allToolNames, depGroups, toolNameToDetailList, manual }) {
   const createArgsDef = createArgsDefFactory(name, allToolNames, depGroups, void 0, void 0);
-  const agenticExecutor = new AgenticExecutor(name, allToolNames, toolNameToDetailList, server);
-  description = CompiledPrompts.autonomousExecution({
+  const agenticExecutor = new AgenticExecutor(name, allToolNames, toolNameToDetailList, server, manual);
+  description = manual ? CompiledPrompts.autonomousExecutionCompact({
+    toolName: name,
+    description
+  }) : CompiledPrompts.autonomousExecution({
     toolName: name,
     description
   });
   const agenticArgsDef = createArgsDef.forAgentic(allToolNames);
-  const argsDef = agenticArgsDef;
-  const schema = allToolNames.length > 0 ? argsDef : {
-    type: "object",
-    properties: {}
-  };
+  const schema = agenticArgsDef;
   server.tool(name, description, jsonSchema(createModelCompatibleJSONSchema(schema)), async (args) => {
     return await agenticExecutor.execute(args, schema);
   });
@@ -1013,7 +1117,8 @@ var createAgenticModePlugin = () => ({
       name: context2.name,
       allToolNames: context2.allToolNames,
       depGroups: context2.depGroups,
-      toolNameToDetailList: context2.toolNameToDetailList
+      toolNameToDetailList: context2.toolNameToDetailList,
+      manual: context2.manual
     });
   }
 });
@@ -1415,7 +1520,7 @@ IMPORTANT: You MUST respond with valid JSON only. Do not include any text before
     let enhanced = systemPrompt || "";
     const toolsPrompt = `
 
-AVAILABLE TOOLS:
+<available_tools>
 You have access to the following tools. To use a tool, respond with this XML format:
 <use_tool tool="tool_name">
 {"param1": "value1", "param2": "value2"}
@@ -1424,23 +1529,34 @@ You have access to the following tools. To use a tool, respond with this XML for
 Follow the JSON schema definition for each tool's parameters.
 You can use multiple tools in one response. DO NOT include text before or after tool calls - wait for the tool results first.
 
-Tools:`;
+<tools>`;
     const toolDescriptions = tools.map((tool2) => {
       if (tool2.type === "function") {
         const toolAny = tool2;
         const description = toolAny.description || "No description provided";
         const schema = toolAny.inputSchema || toolAny.parameters;
-        const params = schema ? `
-  JSON Schema: ${JSON.stringify(schema, null, 2)}` : "";
+        const schemaStr = schema ? `
+<schema>
+${JSON.stringify(schema, null, 2)}
+</schema>` : "";
         return `
-- ${tool2.name}: ${description}${params}`;
+<tool name="${tool2.name}">
+<description>
+${description}
+</description>${schemaStr}
+</tool>`;
       } else if (tool2.type === "provider-defined") {
         return `
-- ${tool2.name}: ${tool2.id || "No description provided"}`;
+<tool name="${tool2.name}">
+<description>${tool2.id || "No description provided"}</description>
+</tool>`;
       }
       return "";
     }).filter(Boolean).join("");
-    enhanced = enhanced ? `${enhanced}${toolsPrompt}${toolDescriptions}` : `${toolsPrompt}${toolDescriptions}`.trim();
+    const toolsEnd = `
+</tools>
+</available_tools>`;
+    enhanced = enhanced ? `${enhanced}${toolsPrompt}${toolDescriptions}${toolsEnd}` : `${toolsPrompt}${toolDescriptions}${toolsEnd}`.trim();
     return enhanced || void 0;
   }
   /**
@@ -1919,7 +2035,7 @@ function isMarkdownFile(path) {
 }
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@mcpc/plugin-markdown-loader/src/markdown-loader.js
-import { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@jsr/std__yaml/_chars.js
 var TAB = 9;
@@ -3858,6 +3974,7 @@ function parse(content, options = {}) {
 }
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@mcpc/plugin-markdown-loader/src/markdown-loader.js
+import { join } from "node:path";
 import process5 from "node:process";
 function replaceEnvVars(str2) {
   return str2.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, varName) => {
@@ -3898,7 +4015,7 @@ function parseMarkdownAgent(content) {
   }
   return {
     frontMatter,
-    description: markdownContent.trim()
+    body: markdownContent.trim()
   };
 }
 var OPTION_KEYS = [
@@ -3913,16 +4030,20 @@ var OPTION_KEYS = [
 ];
 function markdownAgentToComposeDefinition(parsed) {
   const frontMatter = replaceEnvVarsInObject(parsed.frontMatter);
-  const description = replaceEnvVars(parsed.description);
+  const body = replaceEnvVars(parsed.body);
   const options = {};
   for (const key of OPTION_KEYS) {
     if (frontMatter[key] !== void 0) {
       options[key] = frontMatter[key];
     }
   }
+  const hasDescription = frontMatter.description !== void 0 && frontMatter.description !== "";
   return {
     name: frontMatter.name,
-    description,
+    description: hasDescription ? frontMatter.description : body,
+    ...hasDescription && body ? {
+      manual: body
+    } : {},
     deps: frontMatter.deps,
     plugins: frontMatter.plugins,
     ...Object.keys(options).length > 0 ? {
@@ -3935,6 +4056,45 @@ async function loadMarkdownAgentFile(filePath) {
   const parsed = parseMarkdownAgent(content);
   return markdownAgentToComposeDefinition(parsed);
 }
+async function loadMarkdownAgentDirectory(dirPath, options = {}) {
+  const { recursive = false } = options;
+  const definitions = [];
+  const errors = [];
+  async function processDirectory(dir) {
+    const entries = await readdir(dir, {
+      withFileTypes: true
+    });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory() && recursive) {
+        await processDirectory(fullPath);
+      } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+        try {
+          const definition = await loadMarkdownAgentFile(fullPath);
+          definitions.push(definition);
+        } catch (error) {
+          errors.push({
+            path: fullPath,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    }
+  }
+  await processDirectory(dirPath);
+  return {
+    definitions,
+    errors
+  };
+}
+async function isDirectory(path) {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
 
 // __mcpc__plugin-markdown-loader_latest/node_modules/@mcpc/plugin-markdown-loader/mod.ts
 function markdownLoaderPlugin() {
@@ -3954,7 +4114,9 @@ var mod_default = defaultPlugin;
 export {
   createPlugin,
   mod_default as default,
+  isDirectory,
   isMarkdownFile as isMarkdownAgentFile,
+  loadMarkdownAgentDirectory,
   loadMarkdownAgentFile,
   markdownAgentToComposeDefinition,
   markdownLoaderPlugin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpc-tech/plugin-markdown-loader",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "homepage": "https://jsr.io/@mcpc/plugin-markdown-loader",
   "dependencies": {
     "@ai-sdk/provider": "^2.0.0",

package/types/mod.d.ts

@@ -25,7 +25,7 @@
  * @module
  */ import { type ToolPlugin } from "@jsr/mcpc__core";
 export { setMarkdownAgentLoader } from "@jsr/mcpc__core";
-export { isMarkdownAgentFile, loadMarkdownAgentFile, type MarkdownAgentFrontMatter, markdownAgentToComposeDefinition, type ParsedMarkdownAgent, parseMarkdownAgent } from "./src/markdown-loader.js";
+export { isDirectory, isMarkdownAgentFile, type LoadDirectoryResult, loadMarkdownAgentDirectory, loadMarkdownAgentFile, type MarkdownAgentFrontMatter, markdownAgentToComposeDefinition, type ParsedMarkdownAgent, parseMarkdownAgent } from "./src/markdown-loader.js";
 /**
  * Create a Markdown loader plugin for mcpc().
  *

package/types/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GAED,SAAiC,KAAK,UAAU,0BAAiC;AAIjF,SAAS,sBAAsB,0BAAiC;AAEhE,SACE,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,gCAAgC,EAChC,KAAK,mBAAmB,EACxB,kBAAkB,mCACc;AAElC;;;;;CAKC,GACD,OAAO,iBAAS,wBAAwB;AAWxC,qDAAqD,GACrD,OAAO,cAAM,kBAAoC;AAEjD,4DAA4D,GAC5D,cAAM,eAAe;AACrB,eAAe,cAAc"}
+{"version":3,"file":"mod.d.ts","sources":["../mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GAED,SAAiC,KAAK,UAAU,0BAAiC;AAIjF,SAAS,sBAAsB,0BAAiC;AAEhE,SACE,WAAW,EACX,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,0BAA0B,EAC1B,qBAAqB,EACrB,KAAK,wBAAwB,EAC7B,gCAAgC,EAChC,KAAK,mBAAmB,EACxB,kBAAkB,mCACc;AAElC;;;;;CAKC,GACD,OAAO,iBAAS,wBAAwB;AAWxC,qDAAqD,GACrD,OAAO,cAAM,kBAAoC;AAEjD,4DAA4D,GAC5D,cAAM,eAAe;AACrB,eAAe,cAAc"}

package/types/src/markdown-loader.d.ts

@@ -31,6 +31,11 @@ export { isMarkdownFile as isMarkdownAgentFile };
  * Front matter configuration for Markdown agent definitions
  */ export interface MarkdownAgentFrontMatter {
   /** Agent name (required) */ name: string;
+  /**
+   * Short description for progressive disclosure.
+   * If provided, the Markdown body becomes the `manual` field.
+   * If not provided, the Markdown body becomes the `description` field.
+   */ description?: string;
   /** Execution mode */ mode?: "agentic" | "ai_sampling" | "ai_acp" | "code_execution";
   /** Maximum execution steps */ maxSteps?: number;
   /** Maximum tokens for sampling */ maxTokens?: number;
@@ -71,7 +76,7 @@ export { isMarkdownFile as isMarkdownAgentFile };
  * Result of parsing a Markdown agent file
  */ export interface ParsedMarkdownAgent {
   frontMatter: MarkdownAgentFrontMatter;
-  description: string;
+  /** The Markdown body content */ body: string;
 }
 /**
  * Parse YAML front matter and Markdown content from a string
@@ -82,4 +87,27 @@ export { isMarkdownFile as isMarkdownAgentFile };
 /**
  * Load a Markdown agent definition from a file path
  */ export declare function loadMarkdownAgentFile(filePath: string): Promise<ComposeDefinition>;
+/**
+ * Result of loading agents from a directory
+ */ export interface LoadDirectoryResult {
+  /** Successfully loaded agent definitions */ definitions: ComposeDefinition[];
+  /** Errors encountered during loading (file path and error message) */ errors: Array<{
+    path: string;
+    error: string;
+  }>;
+}
+/**
+ * Load all Markdown agent definitions from a directory.
+ * Only loads .md files in the directory (non-recursive by default).
+ *
+ * @param dirPath - Path to the directory containing Markdown agent files
+ * @param options - Options for loading
+ * @param options.recursive - If true, recursively search subdirectories (default: false)
+ * @returns Object containing definitions and any errors encountered
+ */ export declare function loadMarkdownAgentDirectory(dirPath: string, options?: {
+  recursive?: boolean;
+}): Promise<LoadDirectoryResult>;
+/**
+ * Check if a path is a directory
+ */ export declare function isDirectory(path: string): Promise<boolean>;
 //# sourceMappingURL=markdown-loader.d.ts.map

package/types/src/markdown-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown-loader.d.ts","sources":["../../src/markdown-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BC,GAED,SACE,KAAK,iBAAiB,EACtB,cAAc,EACd,KAAK,eAAe,EAEpB,KAAK,cAAc,0BACW;AAMhC,SAAyB,kBAAkB,mBAAmB,GAAG;AAgCjE;;CAEC,GACD,iBAAiB;EACf,0BAA0B,GAC1B,MAAM,MAAM;EACZ,mBAAmB,GACnB,OAAO,YAAY,gBAAgB,WAAW;EAC9C,4BAA4B,GAC5B,WAAW,MAAM;EACjB,gCAAgC,GAChC,YAAY,MAAM;EAClB,mBAAmB,GACnB,iBAAiB,OAAO;EACxB,4BAA4B,GAC5B;IACE,YAAY,OAAO,MAAM,EAAE;;EAE7B,sBAAsB,GACtB,UAAU,MAAM;EAChB,oBAAoB,GACpB,OAAO,MAAM;EACb,2BAA2B,GAC3B,iBAAiB;EACjB,8CAA8C,GAC9C;IACE;MACE,QAAQ;QAAQ,OAAO,MAAM;;MAC7B,eAAe,MAAM;MACrB,gBAAgB,MAAM;MACtB,uBAAuB,MAAM;;;EAGjC,qCAAqC,GACrC;IACE,SAAS,MAAM;IACf,OAAO,MAAM;IACb,MAAM,OAAO,MAAM,EAAE,MAAM;IAC3B;MACE,MAAM,MAAM;MACZ,aAAa;QACX,MAAM,MAAM;QACZ,SAAS,MAAM;QACf,OAAO,MAAM;QACb,MAAM,OAAO,MAAM,EAAE,MAAM;;;IAG/B,iBAAiB,OAAO;;;AAI5B;;CAEC,GACD,iBAAiB;EACf,aAAa;EACb,aAAa,MAAM;;AAGrB;;CAEC,GACD,OAAO,iBAAS,mBAAmB,SAAS,MAAM,GAAG;AA8CrD;;CAEC,GACD,OAAO,iBAAS,iCACd,QAAQ,mBAAmB,GAC1B;AAsBH;;CAEC,GACD,OAAO,iBAAe,sBACpB,UAAU,MAAM,GACf,QAAQ"}
+{"version":3,"file":"markdown-loader.d.ts","sources":["../../src/markdown-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BC,GAED,SACE,KAAK,iBAAiB,EACtB,cAAc,EACd,KAAK,eAAe,EAEpB,KAAK,cAAc,0BACW;AAOhC,SAAyB,kBAAkB,mBAAmB,GAAG;AAgCjE;;CAEC,GACD,iBAAiB;EACf,0BAA0B,GAC1B,MAAM,MAAM;EACZ;;;;GAIC,GACD,cAAc,MAAM;EACpB,mBAAmB,GACnB,OAAO,YAAY,gBAAgB,WAAW;EAC9C,4BAA4B,GAC5B,WAAW,MAAM;EACjB,gCAAgC,GAChC,YAAY,MAAM;EAClB,mBAAmB,GACnB,iBAAiB,OAAO;EACxB,4BAA4B,GAC5B;IACE,YAAY,OAAO,MAAM,EAAE;;EAE7B,sBAAsB,GACtB,UAAU,MAAM;EAChB,oBAAoB,GACpB,OAAO,MAAM;EACb,2BAA2B,GAC3B,iBAAiB;EACjB,8CAA8C,GAC9C;IACE;MACE,QAAQ;QAAQ,OAAO,MAAM;;MAC7B,eAAe,MAAM;MACrB,gBAAgB,MAAM;MACtB,uBAAuB,MAAM;;;EAGjC,qCAAqC,GACrC;IACE,SAAS,MAAM;IACf,OAAO,MAAM;IACb,MAAM,OAAO,MAAM,EAAE,MAAM;IAC3B;MACE,MAAM,MAAM;MACZ,aAAa;QACX,MAAM,MAAM;QACZ,SAAS,MAAM;QACf,OAAO,MAAM;QACb,MAAM,OAAO,MAAM,EAAE,MAAM;;;IAG/B,iBAAiB,OAAO;;;AAI5B;;CAEC,GACD,iBAAiB;EACf,aAAa;EACb,8BAA8B,GAC9B,MAAM,MAAM;;AAGd;;CAEC,GACD,OAAO,iBAAS,mBAAmB,SAAS,MAAM,GAAG;AA8CrD;;CAEC,GACD,OAAO,iBAAS,iCACd,QAAQ,mBAAmB,GAC1B;AA6BH;;CAEC,GACD,OAAO,iBAAe,sBACpB,UAAU,MAAM,GACf,QAAQ;AAMX;;CAEC,GACD,iBAAiB;EACf,0CAA0C,GAC1C,aAAa;EACb,oEAAoE,GACpE,QAAQ;IAAQ,MAAM,MAAM;IAAE,OAAO,MAAM;;;AAG7C;;;;;;;;CAQC,GACD,OAAO,iBAAe,2BACpB,SAAS,MAAM,EACf;EAAW,YAAY,OAAO;CAAO,GACpC,QAAQ;AAgCX;;CAEC,GACD,OAAO,iBAAe,YAAY,MAAM,MAAM,GAAG,QAAQ,OAAO"}