@alcyone-labs/arg-parser 1.2.0 → 2.1.0

package/README.md

@@ -1,1499 +1,1021 @@
 # ArgParser - Type-Safe Command Line Argument Parser
 
-ArgParser is a powerful and flexible library for building command-line interfaces (CLIs) in TypeScript and JavaScript. It helps you define, parse, validate, and handle command-line arguments and sub-commands in a structured, type-safe way.
+A modern, type-safe command line argument parser with built-in MCP (Model Context Protocol) integration and automatic Claude Desktop Extension (DXT) generation.
+
+## Table of Contents
+
+- [Features Overview](#features-overview)
+- [Installation](#installation)
+- [Quick Start: The Unified `addTool` API](#quick-start-the-unified-addtool-api)
+- [How to Run It](#how-to-run-it)
+  - [Setting Up System-Wide CLI Access](#setting-up-system-wide-cli-access)
+- [Parsing Command-Line Arguments](#parsing-command-line-arguments)
+  - [Cannonical Usage Pattern](#cannonical-usage-pattern)
+  - [Top-level await](#top-level-await)
+  - [Promise-based parsing](#promise-based-parsing)
+- [Migrating from v1.x to the v2.0 `addTool` API](#migrating-from-v1x-to-the-v20-addtool-api)
+  - [Before v2.0: Separate Definitions](#before-v20-separate-definitions)
+  - [After v2.0: The Unified `addTool()` Method](#after-v20-the-unified-addtool-method)
+- [Core Concepts](#core-concepts)
+  - [Defining Flags](#defining-flags)
+  - [Type Handling and Validation](#type-handling-and-validation)
+  - [Hierarchical CLIs (Sub-Commands)](#hierarchical-clis-sub-commands)
+    - [MCP Exposure Control](#mcp-exposure-control)
+  - [Flag Inheritance (`inheritParentFlags`)](#flag-inheritance-inheritparentflags)
+- [MCP & Claude Desktop Integration](#mcp--claude-desktop-integration)
+  - [Output Schema Support](#output-schema-support)
+    - [Basic Usage](#basic-usage)
+    - [Predefined Schema Patterns](#predefined-schema-patterns)
+    - [Custom Zod Schemas](#custom-zod-schemas)
+    - [MCP Version Compatibility](#mcp-version-compatibility)
+    - [Automatic Error Handling](#automatic-error-handling)
+  - [Writing Effective MCP Tool Descriptions](#writing-effective-mcp-tool-descriptions)
+    - [Best Practices for Tool Descriptions](#best-practices-for-tool-descriptions)
+    - [Complete Example: Well-Documented Tool](#complete-example-well-documented-tool)
+    - [Parameter Description Guidelines](#parameter-description-guidelines)
+    - [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
+  - [Automatic MCP Server Mode (`--s-mcp-serve`)](#automatic-mcp-server-mode---s-mcp-serve)
+  - [MCP Transports](#mcp-transports)
+  - [Automatic Console Safety](#automatic-console-safety)
+  - [Generating DXT Packages (`--s-build-dxt`)](#generating-dxt-packages---s-build-dxt)
+  - [Logo Configuration](#logo-configuration)
+    - [Supported Logo Sources](#supported-logo-sources)
+  - [How DXT Generation Works](#how-dxt-generation-works)
+- [System Flags & Configuration](#system-flags--configuration)
+- [Changelog](#changelog)
+  - [v2.0.0](#v200)
+  - [v1.3.0](#v130)
+  - [v1.2.0](#v120)
+  - [v1.1.0](#v110)
+- [Backlog](#backlog)
+  - [(known) Bugs / DX improvement points](#known-bugs--dx-improvement-points)
+
+## Features Overview
+
+- **Unified Tool Architecture**: Define tools once with `addTool()` and they automatically function as both CLI subcommands and MCP tools.
+- **Type-safe flag definitions** with full TypeScript support and autocompletion.
+- **Automatic MCP Integration**: Transform any CLI into a compliant MCP server with a single command (`--s-mcp-serve`).
+- **Console Safe**: `console.log` and other methods
+  are automatically handled in MCP mode to prevent protocol contamination, requiring no changes to your code.
+- **DXT Package Generation**: Generate complete, ready-to-install Claude Desktop Extension (`.dxt`) packages with the `--s-build-dxt` command.
+- **Hierarchical Sub-commands**: Create complex, nested sub-command structures (e.g., `git commit`, `docker container ls`) with flag inheritance.
+- **Configuration Management**: Easily load (`--s-with-env`) and save (`--s-save-to-env`) configurations from/to `.env`, `.json`, `.yaml`, and `.toml` files.
+- **Automatic Help & Error Handling**: Context-aware help text and user-friendly error messages are generated automatically.
+- **Debugging Tools**: Built-in system flags like `--s-debug` and `--s-debug-print` for easy troubleshooting.
 
-Whether you're building a simple script, a complex nested CLI application, or an MCP (Model Context Protocol) server, ArgParser provides the tools to create robust and user-friendly interfaces with minimal boilerplate.
-
-## What's New in v1.2.0
-
-### **Critical MCP Fixes & Improvements**
-
-- **Fixed MCP Output Schema Support**: Resolved the critical issue where MCP tools with output schemas failed with `"Tool has an output schema but no structured content was provided"` error
-- **Enhanced Handler Context**: Added `isMcp` flag to handler context, enabling proper MCP mode detection in handlers
-- **Improved Response Format**: MCP tools now correctly return both `content` and `structuredContent` fields as required by the JSON-RPC 2.0 specification
-- **Better Integration**: Handlers can now reliably detect when they're being called from MCP mode vs CLI mode
+---
 
-### **What Was Fixed**
+## Installation
 
-**Before v1.2.0**: MCP servers would fail when tools had output schemas defined:
-```
-MCP error -32602: Tool canny-search has an output schema but no structured content was provided
+```bash
+# Using PNPM (recommended)
+pnpm add @alcyone-labs/arg-parser
 ```
 
-**After v1.2.0**: MCP tools with output schemas work correctly, returning proper JSON-RPC 2.0 responses:
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 3,
-  "result": {
-    "content": [{"type": "text", "text": "..."}],
-    "structuredContent": { /* validated against output schema */ }
-  }
-}
-```
+---
 
-### **Handler Context Enhancement**
+## Quick Start: The Unified `addTool` API
 
-Handlers now receive an `isMcp` flag to detect execution context:
+The modern way to build with ArgParser is using the `.addTool()` method. It creates a single, self-contained unit that works as both a CLI subcommand and an MCP tool.
 
 ```typescript
+import { z } from "zod";
+import { ArgParser } from "@alcyone-labs/arg-parser";
+
+// Use ArgParser.withMcp to enable MCP and DXT features
 const cli = ArgParser.withMcp({
-  handler: async (ctx) => {
-    if (ctx.isMcp) {
-      // Running in MCP mode - return structured data
-      return { success: true, data: processedData };
-    } else {
-      // Running in CLI mode - can use console output
-      console.log("Processing complete!");
-      return processedData;
-    }
+  appName: "My Awesome CLI",
+  appCommandName: "mycli",
+  description: "A tool that works in both CLI and MCP mode",
+  mcp: {
+    serverInfo: { name: "my-awesome-mcp-server", version: "1.0.0" },
+  },
+})
+  // Define a tool that works everywhere
+  .addTool({
+    name: "greet",
+    description: "A tool to greet someone",
+    flags: [
+      {
+        name: "name",
+        type: "string",
+        mandatory: true,
+        options: ["--name"],
+        description: "Name to greet",
+      },
+      {
+        name: "style",
+        type: "string",
+        enum: ["formal", "casual"],
+        defaultValue: "casual",
+        description: "Greeting style",
+      },
+    ],
+    // Optional: Define output schema for MCP clients (Claude Desktop, etc.)
+    // This only affects MCP mode - CLI mode works the same regardless
+    outputSchema: {
+      success: z.boolean().describe("Whether the greeting was successful"),
+      greeting: z.string().describe("The formatted greeting message"),
+      name: z.string().describe("The name that was greeted"),
+    },
+    handler: async (ctx) => {
+      // Use console.log freely - it's automatically safe in MCP mode!
+      console.log(`Greeting ${ctx.args.name} in a ${ctx.args.style} style...`);
+
+      const greeting =
+        ctx.args.style === "formal"
+          ? `Good day, ${ctx.args.name}.`
+          : `Hey ${ctx.args.name}!`;
+
+      console.log(greeting);
+      return { success: true, greeting, name: ctx.args.name };
+    },
+  });
+
+// parse() is async and works with both sync and async handlers
+async function main() {
+  try {
+    await cli.parse(process.argv.slice(2));
+  } catch (error) {
+    console.error("Error:", error.message);
+    process.exit(1);
   }
-});
-```
+}
 
-## What's New in v1.1.0
+main();
 
-### **Major Features**
+// Export if you want to test, use the CLI programmatically
+// or use the --s-enable-fuzzing system flag to run fuzzy tests on your CLI
+export default cli;
+```
 
-- **MCP (Model Context Protocol) Integration**: Transform any CLI into an MCP server with multiple transport support. Run MCP servers with stdio, SSE, and HTTP transports simultaneously, including streamable HTTP.
-- **System Flags**: Built-in `--s-debug-print`, `--s-with-env`, `--s-save-to-env`, `--s-enable-fuzzy`, and `--s-save-DXT` for enhanced debugging, configuration, testing, and MCP distribution
-- **Environment Loading**: Load configuration from `.env`, `.yaml`, `.json`, and `.toml` files
-- **Enhanced Debugging**: Comprehensive runtime debugging and configuration export tools
+## How to Run It
 
-### **Quick Start with MCP**
+```bash
+# This assumes `mycli` is your CLI's entry point
 
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+# 1. As a standard CLI subcommand
+mycli greet --name Jane --style formal
 
-const cli = ArgParser.withMcp({
-  appName: "My CLI Tool",
-  appCommandName: "my-tool",
-  description: "A powerful CLI that can also run as an MCP server",
-  handler: async (ctx) => ({ result: "success", args: ctx.args }),
-})
-.addFlags([
-  { name: "input", options: ["--input", "-i"], type: "string", mandatory: true },
-  { name: "verbose", options: ["--verbose", "-v"], type: "boolean", flagOnly: true },
-])
-.addMcpSubCommand("serve", {
-  name: "my-mcp-server",
-  version: "1.1.0",
-  description: "Expose this CLI as an MCP server",
-}, {
-  // Optional: Configure default transports (CLI flags take precedence)
-  defaultTransports: [
-    { type: "stdio" },
-    { type: "sse", port: 3001, host: "0.0.0.0" }
-  ]
-});
+# 2. As an MCP server, exposing the 'greet' tool
+mycli --s-mcp-serve
 
-// Use as CLI: my-tool --input data.txt --verbose
-// Use as MCP server with defaults: my-tool serve
-// Use as MCP server with CLI override: my-tool serve --transport sse --port 3002
-// Use with multiple transports: my-tool serve --transports '[{"type":"stdio"},{"type":"sse","port":3001}]'
+# 3. Generate a DXT package for Claude Desktop (2-steps)
+mycli --s-build-dxt ./my-dxt-package
 ```
 
-## Features
-
-### **Core CLI Features**
-- **Type Safety:** Define expected argument types (string, number, boolean, array, custom functions) and get type-safe parsed results
-- **Declarative API:** Configure your CLI structure, flags, and sub-commands using a clear, declarative syntax
-- **Automatic Help Generation:** Generate comprehensive and contextual help text based on your parser configuration
-- **Hierarchical Commands:** Easily define nested sub-commands to create complex command structures (e.g., `git commit`, `docker container ls`)
-- **Handler Execution:** Associate handler functions with commands and have them executed automatically upon successful parsing
-- **Validation:** Define custom validation rules for flag values with enum support and custom validators
-- **Conditional Requirements:** Make flags mandatory based on the presence or values of other arguments
-- **Default Values:** Specify default values for flags if they are not provided on the command line
-- **Flag Inheritance:** Share common flags between parent and child commands with an intuitive inheritance mechanism
-- **Error Handling:** Built-in, user-friendly error reporting for common parsing issues, with an option to handle errors manually
-
-### **MCP Integration (v1.1.0+)**
-- **Automatic MCP Server Creation:** Transform any CLI into an MCP server with a single method call
-- **Multiple Transport Support:** Run stdio, SSE, and HTTP transports simultaneously on different ports
-- **Type-Safe Tool Generation:** Automatically generate MCP tools with Zod schema validation from CLI definitions
-- **Flexible Configuration:** Support for single transport or complex multi-transport JSON configurations
-
-### **System & Configuration Features (v1.1.0+)**
-- **Environment Loading:** Load configuration from `.env`, `.yaml`, `.json`, and `.toml` files with `--s-with-env`
-- **Configuration Export:** Save current configuration to various formats with `--s-save-to-env`
-- **Advanced Debugging:** Runtime debugging with `--s-debug` and configuration inspection with `--s-debug-print`
-- **CLI Precedence:** Command line arguments always override file configuration
+Read more on generating the DXT package here: [Generating DXT Packages](#generating-dxt-packages---s-build-dxt)
 
-## Installation
+### Setting Up System-Wide CLI Access
 
-You can install ArgParser using your preferred package manager:
+To make your CLI available system-wide as a binary command, you need to configure the `bin` field in your `package.json` and use package linking:
 
-```bash
-pnpm add @alcyone-labs/arg-parser
-# or
-npm install @alcyone-labs/arg-parser
-# or
-yarn add @alcyone-labs/arg-parser
-# or
-bun add @alcyone-labs/arg-parser
-# or
-deno install npm:@alcyone-labs/arg-parser
-```
+**1. Configure your package.json:**
 
-### **For MCP Integration (Optional)**
+```json
+{
+  "name": "my-cli-app",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "mycli": "./cli.js"
+  }
+}
+```
 
-If you plan to use MCP server features, install the additional dependencies:
+**2. Make your CLI file executable:**
 
 ```bash
-pnpm add @modelcontextprotocol/sdk express
-# or
-npm install @modelcontextprotocol/sdk express
+chmod +x cli.js
 ```
 
-**Note:** MCP dependencies are optional and only required if you use `ArgParser` with MCP features or MCP-related functionality.
+**3. Add a shebang to your CLI file:**
 
-## Runtime Compatibility
+```javascript
+#!/usr/bin/env node
+# or #!/usr/bin/env bun for native typescript runtime
 
-ArgParser is fully compatible with multiple JavaScript runtimes:
+import { ArgParser } from '@alcyone-labs/arg-parser';
 
-### **BunJS**
-```bash
-# Run TypeScript directly
-bun your-cli.ts --flag value
+const cli = ArgParser.withMcp({
+  appName: "My CLI",
+  appCommandName: "mycli",
+  // ... your configuration
+});
 
-# Or compile and run
-bun build your-cli.ts --outdir ./dist
-bun ./dist/your-cli.js --flag value
+// Parse command line arguments
+await cli.parse(process.argv.slice(2));
 ```
 
-### **Node.js**
-```bash
-# Using tsx for TypeScript
-npx tsx your-cli.ts --flag value
+**4. Link the package globally:**
 
-# Using ts-node
-npx ts-node your-cli.ts --flag value
+```bash
+# Using npm
+npm link
 
-# Or compile and run
-npx tsc your-cli.ts
-node your-cli.js --flag value
-```
+# Using pnpm
+pnpm link --global
 
-### **Deno**
-```bash
-# Run with required permissions
-deno run --unstable-sloppy-imports --allow-read --allow-write --allow-env your-cli.ts --flag value
+# Using bun
+bun link
 
-# Or use the provided deno.json configuration for easier task management
-deno task example:simple-cli --env production --port 8080
+# Using yarn
+yarn link
 ```
 
-### **Using the Library in Your Projects**
-
-Install the library and use it in your projects:
+**5. Use your CLI from anywhere:**
 
 ```bash
-# Install the library
-pnpm add @alcyone-labs/arg-parser
+# Now you can run your CLI from any directory
+mycli --help
+mycli greet --name "World"
 
-# Use in your project
-import { ArgParser } from '@alcyone-labs/arg-parser';
-// or
-const { ArgParser } = require('@alcyone-labs/arg-parser');
+# Or use with npx/pnpx if you prefer
+npx mycli --help
+pnpx mycli greet --name "World"
 ```
 
-### **Running Examples**
-
-Examples are provided as TypeScript source files for educational purposes. Run them directly with your preferred runtime:
+**To unlink later:**
 
 ```bash
-# BunJS (recommended)
-bun examples/simple-cli.ts --env production --port 8080
+# Using npm
+npm unlink --global my-cli-app
+
+# Using pnpm
+pnpm unlink --global
 
-# Node.js with tsx
-npx tsx examples/simple-cli.ts --env production --port 8080
+# Using bun
+bun unlink
 
-# Deno (use predefined tasks)
-deno task example:simple-cli --env production --port 8080
+# Using yarn
+yarn unlink
 ```
 
-All examples work seamlessly across all three runtimes, ensuring maximum compatibility for your CLI applications.
+---
 
-## Basic Usage
+## Parsing Command-Line Arguments
 
-### **Standard CLI Usage**
+ArgParser's `parse()` method is async and automatically handles both synchronous and asynchronous handlers:
 
-Here's a simple example demonstrating how to define flags and parse arguments:
+### Cannonical Usage Pattern
 
 ```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
-
-const parser = new ArgParser({
-  appName: "Data Processor",
-  appCommandName: "data-proc", // Used in help text and error messages
-  description: "A tool for processing data phases",
+const cli = ArgParser.withMcp({
+  appName: "My CLI",
   handler: async (ctx) => {
-    console.log("Processing data with phase:", ctx.args.phase);
-    return { success: true, phase: ctx.args.phase };
-  },
-}).addFlags([
-  {
-    name: "phase",
-    options: ["--phase"],
-    type: "string", // Use "string", "number", "boolean", or native types
-    mandatory: true,
-    enum: ["chunking", "pairing", "analysis"],
-    description: "Processing phase to execute",
+    // Works with both sync and async operations
+    const result = await someAsyncOperation(ctx.args.input);
+    return { success: true, result };
   },
-  {
-    name: "batch",
-    options: ["-b", "--batch-number"],
-    type: "number",
-    mandatory: (args) => args.phase !== "analysis", // Conditional requirement
-    defaultValue: 0,
-    description: "Batch number (required except for analysis phase)",
-  },
-  {
-    name: "verbose",
-    options: ["-v", "--verbose"],
-    flagOnly: true, // This flag does not expect a value
-    description: "Enable verbose logging",
-  },
-]);
+});
 
-// Parse and execute
-const result = parser.parse(process.argv.slice(2));
-console.log("Result:", result);
+// parse() is async and works with both sync and async handlers
+async function main() {
+  try {
+    const result = await cli.parse(process.argv.slice(2));
+    // Handler results are automatically awaited and merged
+    console.log(result.success); // true
+  } catch (error) {
+    console.error("Error:", error.message);
+    process.exit(1);
+  }
+}
 ```
 
-### **MCP Server Usage (v1.1.0+)**
-
-Transform your CLI into an MCP server with minimal changes:
-
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+### Top-level await
 
-const cli = ArgParser.withMcp({
-  appName: "Data Processor",
-  appCommandName: "data-proc",
-  description: "A tool for processing data phases (CLI + MCP server)",
-  handler: async (ctx) => {
-    console.log("Processing data with phase:", ctx.args.phase);
-    return { success: true, phase: ctx.args.phase, batch: ctx.args.batch };
-  },
-})
-.addFlags([
-  {
-    name: "phase",
-    options: ["--phase"],
-    type: "string",
-    mandatory: true,
-    enum: ["chunking", "pairing", "analysis"],
-    description: "Processing phase to execute",
-  },
-  {
-    name: "batch",
-    options: ["-b", "--batch-number"],
-    type: "number",
-    defaultValue: 0,
-    description: "Batch number for processing",
-  },
-])
-.addMcpSubCommand("serve", {
-  name: "data-processor-mcp",
-  version: "1.1.0",
-  description: "Data Processor MCP Server",
-});
+Works in ES modules or Node.js >=18 with top-level await
 
-// Use as CLI: data-proc --phase chunking --batch 5
-// Use as MCP server: data-proc serve
-// Use with custom transport: data-proc serve --transport sse --port 3001
+```javascript
+try {
+  const result = await cli.parse(process.argv.slice(2));
+  console.log("Success:", result);
+} catch (error) {
+  console.error("Error:", error.message);
+  process.exit(1);
+}
 ```
 
-## MCP Integration (v1.1.0+)
+### Promise-based parsing
 
-ArgParser v1.1.0 introduces powerful Model Context Protocol (MCP) integration, allowing you to expose any CLI as an MCP server with minimal code changes.
+If you need synchronous contexts, you can simply rely on promise-based APIs
 
-### **Quick MCP Setup**
+```javascript
+cli
+  .parse(process.argv.slice(2))
+  .then((result) => {
+    console.log("Success:", result);
+  })
+  .catch((error) => {
+    console.error("Error:", error.message);
+    process.exit(1);
+  });
+```
 
-1. **Import the MCP-enabled class:**
-   ```typescript
-   import { ArgParser } from "@alcyone-labs/arg-parser";
-   ```
+---
 
-2. **Create your CLI with MCP support:**
-   ```typescript
-   const cli = ArgParser.withMcp({
-     appName: "My Tool",
-     appCommandName: "my-tool",
-     handler: async (ctx) => ({ result: "success", args: ctx.args }),
-   })
-   .addFlags([/* your flags */])
-   .addMcpSubCommand("serve", {
-     name: "my-mcp-server",
-     version: "1.0.0",
-   });
-   ```
+## Migrating from v1.x to the v2.0 `addTool` API
 
-3. **Use as CLI or MCP server:**
-   ```bash
-   # CLI usage
-   my-tool --input data.txt --verbose
+Version 2.0 introduces the `addTool()` method to unify CLI subcommand and MCP tool creation. This simplifies development by removing boilerplate and conditional logic.
 
-   # MCP server (stdio)
-   my-tool serve
+### Before v2.0: Separate Definitions
 
-   # MCP server (HTTP)
-   my-tool serve --transport sse --port 3001
+Previously, you had to define CLI handlers and MCP tools separately, often with conditional logic inside the handler to manage different output formats.
 
-   # Multiple transports
-   my-tool serve --transports '[{"type":"stdio"},{"type":"sse","port":3001}]'
-   ```
+```javascript
+const cli = ArgParser.withMcp({
+  appName: "My Awesome CLI",
+  appCommandName: "mycli",
+  description: "A tool that works in both CLI and MCP mode",
+  mcp: {
+    serverInfo: { name: "my-awesome-mcp-server", version: "1.0.0" },
+  },
+});
 
-### **MCP Transport Options**
+// Old way: Separate CLI subcommands and MCP tools
+cli
+  .addSubCommand({
+    name: "search",
+    handler: async (ctx) => {
+      // Manual MCP detection was required
+      if (ctx.isMcp) {
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } else {
+        console.log("Search results...");
+        return result;
+      }
+    },
+  })
+  // And a separate command to start the server
+  .addMcpSubCommand("serve", {
+    /* MCP config */
+  });
+```
 
-- **`stdio`** (default): Standard input/output for CLI tools
-- **`sse`**: Server-Sent Events over HTTP for web applications
-- **`streamable-http`**: HTTP with streaming support for advanced integrations
+### After v2.0: The Unified `addTool()` Method
 
-### **Multiple Transports Simultaneously**
+Now, a single `addTool()` definition creates both the CLI subcommand and the MCP tool. Console output is automatically managed, flags are converted to MCP schemas, and the server is started with a universal system flag.
 
-Run multiple transport types at once for maximum flexibility:
+```javascript
+const cli = ArgParser.withMcp({
+  appName: "My Awesome CLI",
+  appCommandName: "mycli",
+  description: "A tool that works in both CLI and MCP mode",
+  mcp: {
+    serverInfo: { name: "my-awesome-mcp-server", version: "1.0.0" },
+  },
+});
 
-```bash
-my-tool serve --transports '[
-  {"type":"stdio"},
-  {"type":"sse","port":3001,"path":"/sse"},
-  {"type":"streamable-http","port":3002,"path":"/mcp","host":"0.0.0.0"}
-]'
+// New way: A single tool definition for both CLI and MCP
+cli.addTool({
+  name: "search",
+  description: "Search for items",
+  flags: [
+    { name: "query", type: "string", mandatory: true },
+    { name: "apiKey", type: "string", env: "API_KEY" }, // For DXT integration
+  ],
+  handler: async (ctx) => {
+    // No more MCP detection! Use console.log freely.
+    console.log(`Searching for: ${ctx.args.query}`);
+    const results = await performSearch(ctx.args.query, ctx.args.apiKey);
+    console.log(`Found ${results.length} results`);
+    return { success: true, results };
+  },
+});
+
+// CLI usage: mycli search --query "test"
+// MCP usage: mycli --s-mcp-serve
 ```
 
-### **Automatic Tool Generation**
+**Benefits of Migrating:**
+
+- **Less Code**: A single definition replaces two or more complex ones.
+- **Simpler Logic**: No more manual MCP mode detection or response formatting.
+- **Automatic Schemas**: Flags are automatically converted into the `input_schema` for MCP tools.
+- **Automatic Console Safety**: `console.log` is automatically redirected in MCP mode.
+- **Optional Output Schemas**: Add `outputSchema` only if you want structured responses for MCP clients - CLI mode works perfectly without them.
 
-Your CLI flags are automatically converted to MCP tools with:
-- **Type-safe schemas** using Zod validation
-- **Automatic documentation** from flag descriptions
-- **Enum validation** for restricted values
-- **Error handling** with detailed messages
+---
 
 ## Core Concepts
 
 ### Defining Flags
 
-Flags are defined using the `.addFlag(flag)` method or by passing an array of flags as the second argument to the `ArgParser` constructor. Each flag is an object conforming to the `IFlag` interface:
+Flags are defined using the `IFlag` interface within the `flags` array of a tool or command.
 
 ```typescript
 interface IFlag {
-  name: string; // Internal name for accessing the value in parsed args
-  options: string[]; // Array of command-line options (e.g., ["-v", "--verbose"])
-  type:
-    | "string"
-    | "boolean"
-    | "number"
-    | "array"
-    | "object"
-    | ((value: string) => any)
-    | Constructor; // Expected type or a parsing function
-  description: string | string[]; // Text description for help output
-  mandatory?: boolean | ((args: TParsedArgs) => boolean); // Whether the flag is required, or a function that determines this
-  defaultValue?: any; // Default value if the flag is not provided
-  default?: any; // Alias for defaultValue
-  flagOnly?: boolean; // If true, the flag does not consume the next argument as its value (e.g., `--verbose`)
-  allowMultiple?: boolean; // If true, the flag can be provided multiple times (values are collected in an array)
-  enum?: any[]; // Array of allowed values. Parser validates input against this list.
-  validate?: (value: any) => boolean | string | void; // Custom validation function
-  required?: boolean | ((args: any) => boolean); // Alias for mandatory
+  name: string; // Internal name (e.g., 'verbose')
+  options: string[]; // Command-line options (e.g., ['--verbose', '-v'])
+  type: "string" | "number" | "boolean" | "array" | "object" | Function;
+  description?: string; // Help text
+  mandatory?: boolean | ((args: any) => boolean); // Whether the flag is required
+  defaultValue?: any; // Default value if not provided
+  flagOnly?: boolean; // A flag that doesn't consume a value (like --help)
+  enum?: any[]; // An array of allowed values
+  validate?: (value: any, parsedArgs?: any) => boolean | string | void; // Custom validation function
+  allowMultiple?: boolean; // Allow the flag to be provided multiple times
+  env?: string; // Links the flag to an environment variable for DXT packages, will automatically generate user_config entries in the DXT manifest and fill the flag value to the ENV value if found (process.env)
 }
 ```
 
 ### Type Handling and Validation
 
-ArgParser handles type conversion automatically based on the `type` property. You can use standard string types (`"string"`, `"number"`, `"boolean"`, `"array"`, `"object`), native constructors (`String`, `Number`, `Boolean`, `Array`, `Object`), or provide a custom function:
+ArgParser provides **strong typing** for flag definitions with comprehensive validation at both compile-time and runtime. The `type` property accepts multiple formats and ensures type safety throughout your application.
 
-```typescript
-.addFlag({
-  name: "count",
-  options: ["--count"],
-  type: Number, // Automatically converts value to a number
-})
-.addFlag({
-  name: "data",
-  options: ["--data"],
-  type: JSON.parse, // Use a function to parse complex types like JSON strings
-  description: "JSON data to process"
-})
-.addFlag({
-  name: "environment",
-  options: ["--env"],
-  type: "string",
-  enum: ["dev", "staging", "prod"], // Validate value against this list
-  description: "Deployment environment",
-})
-.addFlag({
-  name: "id",
-  options: ["--id"],
-  type: "string",
-  validate: (value) => /^[a-f0-9]+$/.test(value), // Custom validation function
-  description: "Hexadecimal ID",
-})
-.addFlag({
-  name: "config",
-  options: ["-c"],
-  allowMultiple: true,
-  type: path => require(path), // Load config from path (example)
-  description: "Load multiple configuration files"
-})
-```
-
-### Mandatory Flags
+#### Supported Type Formats
 
-Flags can be made mandatory using the `mandatory` property, or its alias "required". This can be a boolean or a function that receives the currently parsed arguments and returns a boolean.
+You can define flag types using either **constructor functions** or **string literals**:
 
 ```typescript
-.addFlag({
-  name: "input",
-  options: ["--in"],
-  type: String,
-  mandatory: true, // Always mandatory
-  description: "Input file path",
-})
-.addFlag({
-  name: "output",
-  options: ["--out"],
-  type: String,
-  mandatory: (args) => args.format === "json", // Mandatory only if --format is "json"
-  description: "Output file path (required for JSON output)",
-})
+const parser = new ArgParser({ /* ... */ }).addFlags([
+  // Constructor functions (recommended for TypeScript)
+  { name: "count", options: ["--count"], type: Number },
+  { name: "enabled", options: ["--enabled"], type: Boolean, flagOnly: true },
+  { name: "files", options: ["--files"], type: Array, allowMultiple: true },
+
+  // String literals (case-insensitive)
+  { name: "name", options: ["--name"], type: "string" },
+  { name: "port", options: ["--port"], type: "number" },
+  { name: "verbose", options: ["-v"], type: "boolean", flagOnly: true },
+  { name: "tags", options: ["--tags"], type: "array", allowMultiple: true },
+  { name: "config", options: ["--config"], type: "object" },
+
+  // Custom parser functions
+  {
+    name: "date",
+    options: ["--date"],
+    type: (value: string) => new Date(value)
+  }
+]);
 ```
 
-If a mandatory flag is missing and default error handling is enabled (`handleErrors: true`), the parser will print an error and exit.
-
-### Default Values
+#### Runtime Type Validation
 
-Set a `defaultValue` (or its alias `default`) for flags to provide a fallback value if the flag is not present in the arguments.
+The type system validates flag definitions at runtime and throws descriptive errors for invalid configurations:
 
 ```typescript
-.addFlag({
-  name: "port",
-  options: ["-p", "--port"],
-  type: Number,
-  defaultValue: 3000, // Default port is 3000 if -p or --port is not used
-  description: "Server port",
-})
+// ✅ Valid - these work
+{ name: "count", options: ["--count"], type: Number }
+{ name: "count", options: ["--count"], type: "number" }
+{ name: "count", options: ["--count"], type: "NUMBER" } // case-insensitive
+
+// ❌ Invalid - these throw ZodError
+{ name: "count", options: ["--count"], type: "invalid-type" }
+{ name: "count", options: ["--count"], type: 42 } // primitive instead of constructor
+{ name: "count", options: ["--count"], type: null }
 ```
 
-### Flag-Only Flags
+#### Automatic Type Processing
 
-Flags that do not expect a value (like `--verbose` or `--force`) should have `flagOnly: true`. When `flagOnly` is false (the default), the parser expects the next argument to be the flag's value.
+- **String literals** are automatically converted to constructor functions internally
+- **Constructor functions** are preserved as-is
+- **Custom parser functions** allow complex transformations
+- **undefined** falls back to the default `"string"` type
 
-```typescript
-.addFlag({
-  name: "verbose",
-  options: ["-v"],
-  type: Boolean, // Typically boolean for flag-only flags
-  flagOnly: true,
-  description: "Enable verbose output",
-})
-```
+#### Type Conversion Examples
 
-### Alias Properties
+```typescript
+// String flags
+--name value          → "value"
+--name="quoted value" → "quoted value"
 
-For convenience, `ArgParser` supports aliases for some flag properties:
+// Number flags
+--count 42           → 42
+--port=8080          → 8080
 
-- `default` is an alias for `defaultValue`.
-- `required` is an alias for `mandatory`.
-  If both the original property and its alias are provided, the original property (`defaultValue`, `mandatory`) takes precedence.
+// Boolean flags (flagOnly: true)
+--verbose            → true
+(no flag)            → false
 
-## Hierarchical CLIs (Sub-Commands)
+// Array flags (allowMultiple: true)
+--tags tag1,tag2,tag3           → ["tag1", "tag2", "tag3"]
+--file file1.txt --file file2.txt → ["file1.txt", "file2.txt"]
 
-ArgParser excels at building CLIs with nested commands, like `git clone` or `docker build`.
+// Custom parser functions
+--date "2023-01-01"  → Date object
+--json '{"key":"val"}' → parsed JSON object
+```
 
-### Defining Sub-Commands
+### Hierarchical CLIs (Sub-Commands)
 
-Define sub-commands using the `subCommands` option in the `ArgParser` constructor or the `.addSubCommand(subCommand)` method. Each sub-command requires a `name`, `description`, and a dedicated `ArgParser` instance for its own flags and nested sub-commands.
+While `addTool()` is the recommended way to create subcommands that are also MCP-compatible, you can use `.addSubCommand()` for traditional CLI hierarchies.
 
-Note that each flag name set is debounced to make sure there are no duplicates, but the flags are sandboxed within their respective sub-commands. So it's ok to use the same flag on different sub-commands.
+> **Note**: By default, subcommands created with `.addSubCommand()` are exposed to MCP as tools. If you want to create CLI-only subcommands, set `includeSubCommands: false` when adding tools.
 
 ```typescript
-import {
-  ArgParser,
-  HandlerContext,
-  ISubCommand,
-} from "@alcyone-labs/arg-parser";
-
-const deployParser = new ArgParser().addFlags([
-  { name: "target", options: ["-t"], type: String, mandatory: true },
-]);
-
-const monitorLogsParser = new ArgParser().addFlags([
-  { name: "follow", options: ["-f"], flagOnly: true, type: Boolean },
+// Create a parser for a nested command
+const logsParser = new ArgParser().addFlags([
+  { name: "follow", options: ["-f"], type: "boolean", flagOnly: true },
 ]);
 
+// This creates a command group: `my-cli monitor`
 const monitorParser = new ArgParser().addSubCommand({
   name: "logs",
-  description: "Show logs",
-  parser: monitorLogsParser,
-  handler: ({ args }) => {
-    console.log(`Showing logs... Follow: ${args.follow}`);
-  },
+  description: "Show application logs",
+  parser: logsParser,
+  handler: ({ args }) => console.log(`Following logs: ${args.follow}`),
 });
 
-const cli = new ArgParser({
-  appName: "My CLI",
-  appCommandName: "my-cli",
-  description: "Manage application resources",
-  subCommands: [
-    {
-      name: "deploy",
-      description: "Deploy resources",
-      parser: deployParser,
-      handler: ({ args }) => {
-        console.log(`Deploying to ${args.target}`);
-      },
-    },
-    {
-      name: "monitor",
-      description: "Monitoring commands",
-      parser: monitorParser,
-    },
-  ],
+// Attach the command group to the main CLI
+const cli = new ArgParser().addSubCommand({
+  name: "monitor",
+  description: "Monitoring commands",
+  parser: monitorParser,
 });
 
-// Example usage:
-// my-cli deploy -t production
-// my-cli monitor logs -f
+// Usage: my-cli monitor logs -f
 ```
 
-### Handler Execution
-
-A core feature is associating handler functions with commands. Handlers are functions (`(ctx: HandlerContext) => void`) that contain the logic to be executed when a specific command (root or sub-command) is successfully parsed and matched.
-
-Handlers can be defined in the `ISubCommand` object or set/updated later using the `.setHandler()` method on the command's parser instance.
-
-**By default, after successful parsing, ArgParser will execute the handler associated with the _final command_ matched in the argument chain.** For example, running `my-cli service start` will execute the handler for the `start` command, not `my-cli` or `service`.
-
-If you need to parse arguments but _prevent_ handler execution, you can pass the `skipHandlers: true` option to the `parse()` method:
+#### MCP Exposure Control
 
 ```typescript
-const args = parser.parse(process.argv.slice(2), { skipHandlers: true });
-// Handlers will NOT be executed, you can inspect 'args' and decide what to do
-```
+// By default, subcommands are exposed to MCP
+const mcpTools = parser.toMcpTools(); // Includes all subcommands
 
-### Handler Context
+// To exclude subcommands from MCP (CLI-only)
+const mcpToolsOnly = parser.toMcpTools({ includeSubCommands: false });
 
-Handler functions receive a single argument, a `HandlerContext` object, containing information about the parsing result and the command chain:
-
-```typescript
-type HandlerContext = {
-  args: TParsedArgs<any>; // Arguments parsed by and defined for the FINAL command's parser
-  parentArgs?: TParsedArgs<any>; // Combined arguments from PARENT parsers (less relevant with inheritParentFlags)
-  commandChain: string[]; // Array of command names from root to final command
-};
-```
-
-The `args` property is the most commonly used, containing flags and their values relevant to the handler's specific command. If `inheritParentFlags` is used, inherited flags appear directly in `args`.
-
-### Setting Handlers with `.setHandler()`
-
-You can define or override a parser instance's handler after its creation:
-
-```typescript
-const myCommandParser = new ArgParser().addFlags(/* ... */);
-
-myCommandParser.setHandler((ctx) => {
-  console.log(`Executing handler for ${ctx.commandChain.join(" -> ")}`);
-  // ... command logic ...
-});
-
-// You can also retrieve a sub-parser and set its handler:
-const subParser = cli.getSubCommand("deploy")?.parser;
-if (subParser) {
-  subParser.setHandler((ctx) => {
-    console.log("Overridden deploy handler!");
-    // ... new deploy logic ...
-  });
-}
-```
-
-### Accessing Sub-Parsers with `.getSubCommand()`
-
-Use the `.getSubCommand(name)` method on a parser instance to retrieve the `ISubCommand` definition for a specific sub-command by name. This allows you to access its parser instance to set handlers, add flags dynamically, or inspect its configuration.
-
-```typescript
-const deploySubCommand = cli.getSubCommand("deploy");
-if (deploySubCommand) {
-  console.log(`Description of deploy command: ${deploySubCommand.description}`);
-  // Access the parser instance:
-  const deployParserInstance = deploySubCommand.parser;
-  // Add a flag specifically to the deploy command after initial setup:
-  deployParserInstance.addFlag({
-    name: "force",
-    options: ["--force"],
-    flagOnly: true,
-    type: Boolean,
-  });
-}
+// Name conflicts: You cannot have both addSubCommand("name") and addTool({ name: "name" })
+// This will throw an error:
+parser.addSubCommand({ name: "process", parser: subParser });
+parser.addTool({ name: "process", handler: async () => {} }); // ❌ Error: Sub-command 'process' already exists
 ```
 
 ### Flag Inheritance (`inheritParentFlags`)
 
-Enable `inheritParentFlags: true` in a child parser's constructor options to automatically copy flags from its direct parent when added as a sub-command. This is useful for sharing common flags like `--verbose` across your CLI.
-
-If a flag with the same name exists in both the parent and the child, the child's definition takes precedence. The built-in `--help` flag is never inherited.
+To share common flags (like `--verbose` or `--config`) across sub-commands, set `inheritParentFlags: true` in the sub-command's parser.
 
 ```typescript
 const parentParser = new ArgParser().addFlags([
-  { name: "verbose", options: ["-v"], type: Boolean, flagOnly: true },
-  { name: "config", options: ["-c"], type: String }, // Common config flag
+  { name: "verbose", options: ["-v"], type: "boolean" },
 ]);
 
+// This child parser will automatically have the --verbose flag
 const childParser = new ArgParser({ inheritParentFlags: true }).addFlags([
-  { name: "local", options: ["-l"], type: String }, // Child-specific flag
-  { name: "config", options: ["--child-config"], type: Number }, // Override config flag
+  { name: "target", options: ["-t"], type: "string" },
 ]);
 
-parentParser.addSubCommand({
-  name: "child",
-  description: "A child command",
-  parser: childParser,
-});
-
-// The 'child' parser now effectively has flags: --help, -v, -l, --child-config
-// Running `parent child -v -l value --child-config 123` will parse all these flags.
+parentParser.addSubCommand({ name: "deploy", parser: childParser });
 ```
 
-## Automatic Help
-
-ArgParser provides robust automatic help generation.
+---
 
-### Global Help Flag (`--help`, `-h`)
+## MCP & Claude Desktop Integration
 
-A `--help` (and `-h`) flag is automatically added to every parser instance (root and sub-commands). When this flag is encountered during parsing:
+### Output Schema Support
 
-1.  ArgParser stops processing arguments.
-2.  Generates and prints the help text relevant to the current command/sub-command context.
-3.  Exits the process with code 0.
+Output schemas are **completely optional** and **only affect MCP mode** (Claude Desktop, MCP clients). They have **zero impact** on CLI usage - your CLI will work exactly the same with or without them.
 
-This behavior is triggered automatically unless `skipHelpHandling: true` is passed to the `parse()` method.
+**When do I need output schemas?**
 
-```bash
-# Shows help for the root command
-my-cli --help
+- ❌ **CLI-only usage**: Never needed - skip this section entirely
+- ✅ **MCP integration**: Optional but recommended for better structured responses
+- ✅ **Claude Desktop**: Helpful for Claude to understand your tool's output format
 
-# Shows help for the 'deploy' sub-command
-my-cli deploy --help
-```
+**Key Points:**
 
-### `helpText()` Method
+- ✅ **CLI works perfectly without them**: Your command-line interface is unaffected
+- ✅ **MCP-only feature**: Only used when running with `--s-mcp-serve`
+- ✅ **Version-aware**: Automatically included only for compatible MCP clients (v2025-06-18+)
+- ✅ **Flexible**: Use predefined patterns or custom Zod schemas
 
-You can manually generate the help text for any parser instance at any time using the `helpText()` method. This returns a string containing the formatted help output.
+#### Basic Usage
 
 ```typescript
-console.log(parser.helpText());
-```
+import { z } from "zod";
 
-### Auto-Help on Empty Invocation
+.addTool({
+  name: "process-file",
+  description: "Process a file",
+  flags: [
+    { name: "path", options: ["--path"], type: "string", mandatory: true }
+  ],
+  // Optional: Only needed if you want structured MCP responses
+  // CLI mode works exactly the same whether this is present or not
+  outputSchema: {
+    success: z.boolean().describe("Whether processing succeeded"),
+    filePath: z.string().describe("Path to the processed file"),
+    size: z.number().describe("File size in bytes"),
+    lastModified: z.string().describe("Last modification timestamp")
+  },
+  handler: async (ctx) => {
+    // Your logic here - same code for both CLI and MCP
+    // The outputSchema doesn't change how this function works
+    return {
+      success: true,
+      filePath: ctx.args.path,
+      size: 1024,
+      lastModified: new Date().toISOString()
+    };
+  }
+})
 
-For the root command, if you invoke the script **without any arguments** and the root parser **does not have a handler defined**, ArgParser will automatically display the root help text and exit cleanly (code 0). This provides immediate guidance for users who just type the script name.
+// CLI usage (outputSchema ignored): mycli process-file --path /my/file.txt
+// MCP usage (outputSchema provides structure): mycli --s-mcp-serve
+```
 
-If the root parser _does_ have a handler, it's assumed that the handler will manage the empty invocation case, and auto-help will not trigger.
+#### Predefined Schema Patterns
 
-## Error Handling
+For common use cases, use predefined patterns:
 
-ArgParser includes built-in error handling for common parsing errors like missing mandatory flags, invalid types, or unknown commands.
+```typescript
+// For simple success/error responses
+outputSchema: "successError";
 
-By default (`handleErrors: true`):
+// For operations that return data
+outputSchema: "successWithData";
 
-1.  A descriptive, colored error message is printed to `stderr`.
-2.  A suggestion to use `--help` is included, showing the correct command path.
-3.  The process exits with status code 1.
+// For file operations
+outputSchema: "fileOperation";
 
-```typescript
-// Example (assuming 'data-proc' is appCommandName and 'phase' is mandatory)
-// Running `data-proc` would output:
+// For process execution
+outputSchema: "processExecution";
 
-// Error: Missing mandatory flags: phase
-//
-// Try 'data-proc --help' for usage details.
+// For list operations
+outputSchema: "list";
 ```
 
-You can disable this behavior by setting `handleErrors: false` in the `ArgParser` constructor options. When disabled, ArgParser will throw an `ArgParserError` exception on parsing errors, allowing you to catch and handle them programmatically.
+#### Custom Zod Schemas
 
-```typescript
-import { ArgParser, ArgParserError } from "@alcyone-labs/arg-parser";
+For complex data structures:
 
-const parser = new ArgParser({
-  appCommandName: "my-app",
-  handleErrors: false, // Disable default handling
+```typescript
+outputSchema: z.object({
+  analysis: z.object({
+    summary: z.string(),
+    wordCount: z.number(),
+    sentiment: z.enum(["positive", "negative", "neutral"]),
+  }),
+  metadata: z.object({
+    timestamp: z.string(),
+    processingTime: z.number(),
+  }),
 });
-
-try {
-  const args = parser.parse(process.argv.slice(2));
-  // Process args if parsing succeeded
-} catch (error) {
-  if (error instanceof ArgParserError) {
-    console.error(`\nCustom Parse Error: ${error.message}`);
-    // Implement custom logic (e.g., logging, different exit codes)
-    process.exit(1);
-  } else {
-    // Handle unexpected errors
-    console.error("An unexpected error occurred:", error);
-    process.exit(1);
-  }
-}
 ```
 
-## Environment Configuration Export
+#### MCP Version Compatibility
 
-ArgParser includes a built-in system flag `--s-save-to-env` that allows you to export the current parser's configuration and parsed arguments to various file formats. This is useful for creating configuration templates, documenting CLI usage, or generating environment files for deployment.
+Output schemas are automatically handled based on MCP client version:
 
-### Usage
+- **MCP v2025-06-18+**: Full output schema support with `structuredContent`
+- **Earlier versions**: Schemas ignored, standard JSON text response only
 
-```bash
-# Export to .env format (default for no extension)
-your-cli --flag1 value1 --flag2 --s-save-to-env config.env
+To explicitly set the MCP version for testing:
 
-# Export to YAML format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.yaml
-
-# Export to JSON format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.json
-
-# Export to TOML format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.toml
+```typescript
+const cli = ArgParser.withMcp({
+  // ... your config
+}).setMcpProtocolVersion("2025-06-18"); // Enable output schema support
 ```
 
-### Supported Formats
-
-The format is automatically detected based on the file extension:
-
-- **`.env`** (or no extension): Bash environment variable format
-- **`.yaml` / `.yml`**: YAML format
-- **`.json` / `.jsonc`**: JSON format with metadata
-- **`.toml` / `.tml`**: TOML format
+**Important**:
 
-### Behavior
+- **CLI users**: You can ignore MCP versions entirely - they don't affect command-line usage
+- **MCP users**: ArgParser handles version detection automatically based on client capabilities
 
-- **Works at any parser level**: Can be used with root commands or sub-commands
-- **Includes inherited flags**: Shows flags from the current parser and all parent parsers in the chain
-- **Comments optional flags**: Flags that are optional and not set are commented out but still documented
-- **Preserves values**: Set flags show their actual values, unset flags show default values or are commented out
-- **Rich documentation**: Each flag includes its description, options, type, and constraints
+#### Automatic Error Handling
 
-### Example Output
+ArgParser automatically handles errors differently based on execution context, so your handlers can simply throw errors without worrying about CLI vs MCP mode:
 
-For a CLI with flags `--verbose`, `--output file.txt`, and `--count 5`:
-
-**`.env` format:**
-```bash
-# Environment configuration generated by ArgParser
-# Format: Bash .env style
-
-# verbose: Enable verbose output
-# Options: -v, --verbose
-# Type: Boolean
-# Default: false
-VERBOSE="true"
-
-# output: Output file path
-# Options: -o, --output
-# Type: String
-OUTPUT="file.txt"
-
-# count: Number of items to process
-# Options: -c, --count
-# Type: Number
-# Default: 10
-COUNT="5"
-```
-
-**`.yaml` format:**
-```yaml
-# Environment configuration generated by ArgParser
-# Format: YAML
-
-# verbose: Enable verbose output
-# Options: -v, --verbose
-# Type: Boolean
-# Default: false
+```typescript
+const cli = ArgParser.withMcp({
+  // ... config
+}).addTool({
+  name: "process-data",
+  handler: async (ctx) => {
+    // Simply throw errors - ArgParser handles the rest automatically
+    if (!ctx.args.apiKey) {
+      throw new Error("API key is required");
+    }
 
-verbose: true
-output: "file.txt"
-count: 5
+    // Do your work and return results
+    return { success: true, data: processedData };
+  },
+});
 ```
 
-## System Flags (v1.1.0+)
-
-ArgParser includes several built-in system flags that provide debugging, configuration management, and introspection capabilities. These flags are processed before normal argument parsing and will cause the program to exit after execution.
+**How it works:**
 
-### **Overview**
+- **CLI mode**: Thrown errors cause the process to exit with error code 1
+- **MCP mode**: Thrown errors are automatically converted to structured MCP error responses
+- **No manual checks needed**: Handlers don't need to check `ctx.isMcp` or handle different response formats
 
-System flags use the `--s-*` pattern and provide powerful development and deployment tools:
+### Writing Effective MCP Tool Descriptions
 
-- **`--s-debug`**: Runtime debugging with step-by-step parsing analysis
-- **`--s-with-env <file>`**: Load configuration from files (`.env`, `.yaml`, `.json`, `.toml`)
-- **`--s-save-to-env <file>`**: Export current configuration to various formats
-- **`--s-debug-print`**: Export complete parser configuration for inspection
-- **`--s-enable-fuzzy`**: Enable fuzzy testing mode (dry-run with no side effects)
-- **`--s-save-DXT [dir]`**: Generate DXT packages for MCP servers (Desktop Extensions)
+**Why descriptions matter**: When your tools are exposed to Claude Desktop or other MCP clients, the `description` field is the primary way LLMs understand what your tool does and when to use it. A well-written description significantly improves tool selection accuracy and user experience.
 
-### `--s-save-to-env <file>`
-
-Exports the current parser's configuration and parsed arguments to various file formats.
-
-```bash
-# Export to .env format (default for no extension)
-your-cli --flag1 value1 --flag2 --s-save-to-env config.env
+#### Best Practices for Tool Descriptions
 
-# Export to YAML format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.yaml
+**1. Start with the action** - Begin with a clear verb describing what the tool does:
 
-# Export to JSON format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.json
+```typescript
+// ✅ Good: Action-first, specific
+description: "Analyzes text files and returns detailed statistics including word count, character count, and sentiment analysis";
 
-# Export to TOML format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.toml
+// ❌ Avoid: Vague or noun-heavy
+description: "File analysis tool";
 ```
 
-**Features:**
-- Works at any parser level (root command or sub-commands)
-- Includes inherited flags from parent parsers in the chain
-- Comments out optional flags that are not set
-- Rich documentation for each flag (description, options, type, constraints)
-- Automatic format detection based on file extension
-
-### `--s-with-env <file>`
-
-Loads configuration from a file and merges it with command line arguments. CLI arguments take precedence over file configuration.
-
-```bash
-# Load from .env format (default for no extension)
-your-cli --s-with-env config.env
-
-# Load from YAML format
-your-cli --s-with-env config.yaml
+**2. Include context and use cases** - Explain when and why to use the tool:
 
-# Load from JSON format
-your-cli --s-with-env config.json
-
-# Load from TOML format
-your-cli --s-with-env config.toml
+```typescript
+// ✅ Good: Provides context
+description: "Converts image files between formats (PNG, JPEG, WebP). Use this when you need to change image format, resize images, or optimize file sizes. Supports batch processing of multiple files.";
 
-# Combine with CLI arguments (CLI args override file config)
-your-cli --s-with-env config.yaml --verbose --output override.txt
+// ❌ Avoid: No context
+description: "Converts images";
 ```
 
-**Supported Formats:**
-
-The format is automatically detected based on the file extension:
-
-- **`.env`** (or no extension): Dotenv format with `KEY=value` pairs
-- **`.yaml` / `.yml`**: YAML format
-- **`.json` / `.jsonc`**: JSON format (metadata is ignored if present)
-- **`.toml` / `.tml`**: TOML format
-
-**Behavior:**
-
-- **File validation**: Checks if the file exists and can be parsed
-- **Type conversion**: Automatically converts values to match flag types (boolean, number, string, array)
-- **Enum validation**: Validates values against allowed enum options
-- **CLI precedence**: Command line arguments override file configuration
-- **Error handling**: Exits with error code 1 if file cannot be loaded or parsed
-- **Flag matching**: Only loads values for flags that exist in the current parser chain
+**3. Mention key parameters and constraints** - Reference important inputs and limitations:
 
-**Example Configuration Files:**
-
-**.env format:**
-```bash
-VERBOSE=true
-OUTPUT=file.txt
-COUNT=5
-TAGS=tag1,tag2,tag3
-```
-
-**YAML format:**
-```yaml
-verbose: true
-output: file.txt
-count: 5
-tags:
-  - tag1
-  - tag2
-  - tag3
-```
+```typescript
+// ✅ Good: Mentions key parameters and constraints
+description: "Searches through project files using regex patterns. Specify the search pattern and optionally filter by file type. Supports JavaScript, TypeScript, Python, and text files up to 10MB.";
 
-**JSON format:**
-```json
-{
-  "verbose": true,
-  "output": "file.txt",
-  "count": 5,
-  "tags": ["tag1", "tag2", "tag3"]
-}
+// ❌ Avoid: No parameter guidance
+description: "Searches files";
 ```
 
-### `--s-debug-print`
+**4. Be specific about outputs** - Describe what the tool returns:
 
-Prints the complete parser configuration to a JSON file and console for debugging complex parser setups.
+```typescript
+// ✅ Good: Clear output description
+description: "Analyzes code complexity and returns metrics including cyclomatic complexity, lines of code, and maintainability index. Results include detailed breakdown by function and overall file scores.";
 
-```bash
-your-cli --s-debug-print
+// ❌ Avoid: Unclear output
+description: "Analyzes code";
 ```
 
-**Output:**
-- Creates `ArgParser.full.json` with the complete parser structure
-- Shows all flags, sub-commands, handlers, and configuration
-- Useful for debugging complex parser hierarchies
-- Human-readable console output with syntax highlighting
-
-### `--s-debug`
+#### Complete Example: Well-Documented Tool
 
-Provides detailed runtime debugging information showing how arguments are parsed step-by-step.
-
-```bash
-your-cli --flag1 value1 sub-command --flag2 value2 --s-debug
+```typescript
+.addTool({
+  name: "analyze-repository",
+  description: "Analyzes a Git repository and generates comprehensive statistics including commit history, contributor activity, code quality metrics, and dependency analysis. Use this to understand project health, identify bottlenecks, or prepare reports. Supports Git repositories up to 1GB with history up to 5 years.",
+  flags: [
+    {
+      name: "path",
+      description: "Path to the Git repository root directory",
+      options: ["--path", "-p"],
+      type: "string",
+      mandatory: true,
+    },
+    {
+      name: "include-dependencies",
+      description: "Include analysis of package.json dependencies and security vulnerabilities",
+      options: ["--include-dependencies", "-d"],
+      type: "boolean",
+      flagOnly: true,
+    },
+    {
+      name: "output-format",
+      description: "Output format for the analysis report",
+      options: ["--output-format", "-f"],
+      type: "string",
+      choices: ["json", "markdown", "html"],
+      defaultValue: "json",
+    }
+  ],
+  handler: async (ctx) => {
+    // Implementation here
+  }
+})
 ```
 
-**Output:**
-- Shows command chain identification process
-- Step-by-step argument parsing simulation
-- Final parser identification
-- Accumulated arguments at each level
-- Remaining arguments after parsing
-- Complete static configuration of the final parser
+#### Parameter Description Guidelines
 
-**Useful for:**
-- Understanding complex command chains
-- Debugging argument parsing issues
-- Seeing how flags are inherited between parsers
-- Troubleshooting sub-command resolution
-
-### Usage Notes
-
-- System flags are processed before normal argument parsing
-- They cause the program to exit after execution (exit code 0 for success)
-- Can be used with any combination of regular flags and sub-commands
-- Particularly useful during development and debugging
-
-## Debugging
-
-### Programmatic Debugging
-
-The `printAll(filePath?: string)` method is useful for debugging complex parser configurations programmatically. It recursively outputs the structure, options, flags, and handlers of a parser instance and its sub-commands.
-
-- `parser.printAll()`: Prints a colored, human-readable output to the console.
-- `parser.printAll('./config.json')`: Writes the configuration as a pretty-printed JSON file.
-- `parser.printAll('./config.log')`: Writes a plain text version to a file.
+Each flag should have a clear, concise description:
 
 ```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+// ✅ Good parameter descriptions
+{
+  name: "timeout",
+  description: "Maximum execution time in seconds (default: 30, max: 300)",
+  options: ["--timeout", "-t"],
+  type: "number",
+}
 
-const parser = new ArgParser({ appName: "Debug App" })
-  .addFlags([
-    /* ... */
-  ])
-  .addSubCommand(/* ... */);
+{
+  name: "verbose",
+  description: "Enable detailed logging output including debug information",
+  options: ["--verbose", "-v"],
+  type: "boolean",
+  flagOnly: true,
+}
 
-parser.printAll(); // Output to console
+{
+  name: "format",
+  description: "Output format for results (json: structured data, csv: spreadsheet-friendly, pretty: human-readable)",
+  options: ["--format"],
+  type: "string",
+  choices: ["json", "csv", "pretty"],
+}
 ```
 
-### Runtime Debugging
+#### Common Pitfalls to Avoid
 
-For runtime debugging, use the system flags documented above:
+- **Don't be overly technical**: Avoid jargon that doesn't help with tool selection
+- **Don't repeat the tool name**: The name is already visible, focus on functionality
+- **Don't use generic terms**: "Process data" or "handle files" are too vague
+- **Don't forget constraints**: Mention important limitations or requirements
+- **Don't ignore parameter descriptions**: Each flag should have a helpful description
 
-- `--s-debug-print`: Export complete parser configuration
-- `--s-debug`: Show step-by-step argument parsing process
-- `--s-save-to-env <file>`: Export current configuration to various formats
-- `--s-with-env <file>`: Load configuration from file and merge with CLI arguments
+**Remember**: A good description helps the LLM choose the right tool for the task and use it correctly. Invest time in writing clear, comprehensive descriptions - it directly impacts the user experience in Claude Desktop and other MCP clients.
 
-### `--s-enable-fuzzy`
+### Automatic MCP Server Mode (`--s-mcp-serve`)
 
-Enables fuzzy testing mode, which acts as a dry-run mode for safe testing without side effects. **No boilerplate code required** - the system automatically prevents CLI execution during fuzzy testing.
+You don't need to write any server logic. Run your application with the `--s-mcp-serve` flag, and ArgParser will automatically start a compliant MCP server, exposing all tools defined with `.addTool()` and subcommands created with `.addSubCommand()` (unless `includeSubCommands: false` is set).
 
 ```bash
-# Enable fuzzy mode for testing
-your-cli --s-enable-fuzzy --input test.txt --format json
-```
-
-**Features:**
-- **Automatic execution prevention**: No need for complex conditional logic in your CLI code
-- **Zero boilerplate**: Simply export your CLI with `export default cli` and call `cli.parse()`
-- Disables error handling to allow error collection
-- Skips mandatory flag validation for comprehensive testing
-- **Prevents handler function execution** (no side effects)
-- **Logs what each handler would receive** for testing visibility
-- Recursively applies to all subcommand parsers
-- Safe for testing production CLIs with database operations, file modifications, or API calls
-
-**Example Output:**
-```
-[--s-enable-fuzzy] handler() skipped for command chain: (root)
-  Input args: [--s-enable-fuzzy --input test.txt --format json]
-  Parsed args: {"input":"test.txt","format":"json"}
-```
-
-**Use Cases:**
-- Fuzzy testing CLI argument parsing
-- Validating CLI configuration without executing business logic
-- Testing complex command hierarchies safely
-- Automated testing of CLI interfaces
-
-These system flags are particularly useful when you need to debug a CLI application without modifying the source code.
-
-## Fuzzy Testing
-
-ArgParser includes comprehensive fuzzy testing capabilities to automatically test CLI configurations and catch edge cases that manual testing might miss. The fuzzy testing utility systematically explores command paths and generates various flag combinations to ensure robustness.
+# This single command starts a fully compliant MCP server
+my-cli-app --s-mcp-serve
 
-### **Quick Start**
-
-Test any ArgParser configuration using the built-in fuzzy testing CLI:
-
-```bash
-# Test an ArgParser file
-bun src/fuzzy-test-cli.ts --file examples/getting-started.ts
-
-# Test with custom options and save results
-bun src/fuzzy-test-cli.ts \
-  --file examples/getting-started.ts \
-  --output test-results.json \
-  --format json \
-  --max-depth 3 \
-  --random-tests 20 \
-  --verbose
+# You can also override transports and ports using system flags
+my-cli-app --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3001
 ```
 
-**Important Note**: Make sure that the `examples/getting-started.ts` file exports the parser instance using `export default` for the fuzzy testing CLI to work correctly.
+### MCP Transports
 
-### **System Flag Integration**
-
-The `--s-enable-fuzzy` system flag makes any CLI fuzzy-test compatible **without any code modifications or boilerplate**:
+You can define the transports directly in the .withMcp() settings, or override them via the `--s-mcp-transport(s)` flags.
 
 ```bash
-# Enable fuzzy mode for safe testing (dry-run with no side effects)
-your-cli --s-enable-fuzzy --input test.txt --format json
-
-# The fuzzy testing CLI automatically uses this flag
-bun src/fuzzy-test-cli.ts --file your-cli.ts
-```
-
-**Fuzzy mode features:**
-- **Zero boilerplate**: No conditional logic needed - just `export default cli` and `cli.parse()`
-- **Automatic prevention**: System automatically prevents CLI execution during fuzzy testing
-- **Dry-run execution**: Prevents handler function execution (no side effects)
-- **Error collection**: Disables error handling to collect all parsing errors
-- **Argument logging**: Shows what each handler would receive for testing visibility
-- **Safe testing**: Test production CLIs with database operations, file modifications, or API calls
-
-### **Testing Capabilities**
-
-The fuzzy tester automatically tests:
+# Single transport
+my-tool --s-mcp-serve --s-mcp-transport stdio
 
-- **Valid combinations**: Proper flag usage with correct types and values
-- **Invalid combinations**: Wrong inputs to verify error handling
-- **Random combinations**: Pseudo-random flag combinations for edge cases
-- **Command paths**: All subcommand combinations up to configurable depth
-- **Performance**: Execution timing for different input complexities
+# Multiple transports via JSON
+my-tool --s-mcp-serve --s-mcp-transports '[{"type":"stdio"},{"type":"sse","port":3001}]'
 
-### **Programmatic Usage**
+# Single transport with custom options
+my-tool --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3000 --s-mcp-host 0.0.0.0
 
-```typescript
-import { ArgParserFuzzyTester } from "@alcyone-labs/arg-parser/fuzzy-tester";
-import { myArgParser } from "./my-cli";
-
-const tester = new ArgParserFuzzyTester(myArgParser, {
-  maxDepth: 5,
-  randomTestCases: 10,
-  includePerformance: true,
-  testErrorCases: true,
-  verbose: false,
+# Multiple transports (configured via --s-mcp-serve system flag)
+const cli = ArgParser.withMcp({
+  appName: 'multi-tool',
+  appCommandName: 'multi-tool',
+  mcp: {
+    serverInfo: {
+      name: 'multi-tool-mcp',
+      version: '1.0.0'
+    },
+    transports: [
+      // Can be a single string...
+      "stdio",
+      // or one of the other transport types supported by @modelcontextprotocol/sdk
+      { type: "sse", port: 3000, host: "0.0.0.0" },
+      { type: "websocket", port: 3001, path: "/ws" }
+    ]
+  }
 });
-
-const report = await tester.runFuzzyTest();
-console.log(`Success rate: ${(report.successfulTests / report.totalTests * 100).toFixed(1)}%`);
 ```
 
-### **Output Formats**
+### Automatic Console Safety
 
-Generate reports in multiple formats:
+A major challenge in MCP is preventing `console.log` from corrupting the JSON-RPC communication over `STDOUT`. ArgParser solves this automatically.
 
-```bash
-# Human-readable console output
-bun src/fuzzy-test-cli.ts --file my-cli.ts --format text
-
-# Machine-readable JSON
-bun src/fuzzy-test-cli.ts --file my-cli.ts --format json --output results.json
-
-# Documentation-friendly Markdown
-bun src/fuzzy-test-cli.ts --file my-cli.ts --format markdown --output report.md
-```
+- **How it works**: When `--s-mcp-serve` is active, ArgParser hijacks the global `console` object.
+- **What it does**: It redirects `console.log`, `.info`, `.warn`, and `.debug` to `STDERR` with a prefix, making them visible for debugging without interfering with the protocol. `console.error` is preserved on `STDERR` as expected.
+- **Your benefit**: You can write `console.log` statements freely in your handlers. They will work as expected in CLI mode and be safely handled in MCP mode with **zero code changes**.
 
-For complete documentation, examples, and advanced usage patterns, see the [Fuzzy Testing Documentation](docs/fuzzy-testing.md).
+### Generating DXT Packages (`--s-build-dxt`)
 
-### `--s-save-DXT [directory]`
-
-Generates Desktop Extension (DXT) packages for all MCP servers defined in your ArgParser instance. DXT files are zip archives containing a manifest.json and server files, enabling single-click installation of MCP servers in compatible applications like Claude Desktop.
+A Desktop Extension (`.dxt`) is a standardized package for installing your tools into Claude Desktop. ArgParser automates this process.
 
 ```bash
-# Generate DXT packages in current directory
-your-cli --s-save-DXT
-
-# Generate DXT packages in specific directory
-your-cli --s-save-DXT ./dxt-packages
+# 1. Generate the DXT package contents into a directory
+my-cli-app --s-build-dxt ./my-dxt-package
 
-# Example with multiple MCP servers
-my-tool --s-save-DXT ./extensions
-```
+# The output folder contains everything needed: manifest.json, entry point, etc.
+# A default logo will be applied if you don't provide one.
 
-**Features:**
-- **Automatic detection**: Finds all MCP servers added via `addMcpSubCommand()`
-- **Multiple servers**: Generates separate DXT files for each MCP server
-- **Complete tool listing**: Includes all MCP tools in the manifest
-- **Proper metadata**: Uses actual server names, versions, and descriptions
-- **Ready to install**: Generated DXT files work with DXT-compatible applications
+# 2. (Optional) Pack the folder into a .dxt file for distribution
+npx @anthropic-ai/dxt pack ./my-dxt-package
 
-**Generated Structure:**
-```
-your-server.dxt (ZIP file)
-├── manifest.json         # Server metadata and tool definitions
-└── server/
-    └── index.js          # Server entry point
-```
+# 3. (Optional) Sign the DXT package
+npx @anthropic-ai/dxt sign ./my-dxt-package.dxt
 
-**Example Output:**
-```
-🔧 Generating DXT packages for 2 MCP server(s)...
-  ✓ Generated: primary-server.dxt
-    Server: primary-server v1.0.0
-    Tools: 3 tool(s)
-  ✓ Generated: analytics-server.dxt
-    Server: analytics-server v2.1.0
-    Tools: 5 tool(s)
-
-✅ DXT package generation completed!
-Output directory: /path/to/dxt-packages
+# Then drag & drop the .dxt file into Claude Desktop to install it, in the Settings > Extensions screen.
 ```
 
-**Use Cases:**
-- **Distribution**: Package MCP servers for easy sharing and installation
-- **Development**: Create test packages during MCP server development
-- **Deployment**: Generate production-ready DXT files for distribution
-- **Integration**: Prepare MCP servers for Claude Desktop or other DXT-compatible applications
-
-## Changelog
-
-### v1.2.0 (2025-01-02)
-
-**🔧 Critical MCP Fixes & Improvements**
-
-- **Fixed MCP Output Schema Support**: Resolved the critical issue where MCP tools with output schemas failed with `"Tool has an output schema but no structured content was provided"` error
-- **Enhanced Handler Context**: Added `isMcp` flag to handler context for proper MCP mode detection
-- **Improved Response Format**: MCP tools now correctly return both `content` and `structuredContent` fields as required by JSON-RPC 2.0
-- **Better Integration**: Handlers can reliably detect when they're being called from MCP mode vs CLI mode
-
-**What was broken before v1.2.0:**
-- MCP servers would fail when tools had output schemas defined
-- Handlers couldn't reliably detect MCP execution context
-- Response format didn't comply with MCP specification for structured content
-
-**What works now:**
-- ✅ MCP tools with output schemas work correctly
-- ✅ Proper JSON-RPC 2.0 response format with both `content` and `structuredContent`
-- ✅ Handler context includes `isMcp` flag for mode detection
-- ✅ Full compatibility with MCP clients and the Model Context Protocol specification
-
-### v1.1.0 (2024-12-XX)
-
-**Major Features**
-- MCP (Model Context Protocol) Integration with multiple transport support
-- System Flags: `--s-debug-print`, `--s-with-env`, `--s-save-to-env`, `--s-enable-fuzzy`, `--s-save-DXT`
-- Environment Loading from `.env`, `.yaml`, `.json`, and `.toml` files
-- Enhanced Debugging and configuration export tools
-
-## API Reference
-
-This section provides a quick overview of the main components. See the sections above for detailed explanations and examples.
-
-### **Core Classes**
+### Logo Configuration
 
-#### `ArgParserBase`
+The logo will appear in Claude Desktop's Extensions settings and when users interact with your MCP tools. Note that neither ArgParser nor Anthropic packer will modify the logo, so make sure to use a reasonable size, such as 256x256 pixels or 512x512 pixels maximum. Any image type that can display in a browser is supported.
 
-Base class providing core CLI parsing functionality without MCP features. Use this for lightweight CLIs that don't need MCP server capabilities.
+You can customize the logo/icon that appears in Claude Desktop for your DXT package by configuring the `logo` property in your `serverInfo`:
 
-**Constructor:**
-- `new ArgParserBase(options?, initialFlags?)`: Create basic parser instance
-
-#### `ArgParser` (v1.1.0+)
-
-Main class with built-in MCP server capabilities. Extends `ArgParserBase` with MCP integration.
-
-**Constructors:**
-- `new ArgParser(options?, initialFlags?)`: Create parser with MCP capabilities
-- `ArgParser.withMcp(options?, initialFlags?)`: Factory method for MCP-enabled parser (same as constructor)
-- `ArgParser.fromArgParser(parser)`: Convert existing ArgParserBase to MCP-enabled
-
-**MCP Methods:**
-- `toMcpTools(options?)`: Generate MCP tool structures from CLI definition
-- `createMcpServer(serverInfo, toolOptions?)`: Create MCP server instance
-- `startMcpServer(serverInfo, toolOptions?)`: Start MCP server with stdio transport
-- `startMcpServerWithTransport(serverInfo, transportType, transportOptions?, toolOptions?)`: Start with specific transport
-- `startMcpServerWithMultipleTransports(serverInfo, transports, toolOptions?)`: Start with multiple transports (manual approach)
-- `addMcpSubCommand(name, serverInfo, options?)`: Add MCP server sub-command with optional preset transports (recommended approach)
-- `parse(args, options?)`: Async version supporting async handlers
-
-**MCP Types:**
-- `McpTransportConfig`: Configuration for a single transport (`{ type, port?, host?, path?, sessionIdGenerator? }`)
-- `McpSubCommandOptions`: Options for MCP sub-command (`{ defaultTransport?, defaultTransports?, toolOptions? }`)
-
-**Transport Types:**
-- `"stdio"`: Standard input/output
-- `"sse"`: Server-Sent Events over HTTP
-- `"streamable-http"`: HTTP with streaming support
-
-**Example:**
 ```typescript
 const cli = ArgParser.withMcp({
   appName: "My CLI",
-  handler: async (ctx) => ({ result: ctx.args }),
-})
-.addFlags([/* flags */])
-.addMcpSubCommand("serve", {
-  name: "my-mcp-server",
-  version: "1.0.0",
-});
-
-// Elegant approach: Configure default transports in addMcpSubCommand
-const cli = ArgParser.withMcp({
-  appName: "My Tool",
-  handler: async (ctx) => ({ result: ctx.args }),
-})
-.addFlags([/* your flags */])
-.addMcpSubCommand("serve", {
-  name: "my-server",
-  version: "1.0.0",
-}, {
-  // Default multiple transports - used when no CLI flags provided
-  defaultTransports: [
-    { type: "stdio" },
-    { type: "sse", port: 3001 },
-    { type: "streamable-http", port: 3002 }
-  ]
+  appCommandName: "mycli",
+  mcp: {
+    // This will appear in Claude Desktop's Extensions settings
+    serverInfo: {
+      name: "my-mcp-server",
+      version: "1.0.0",
+      description: "My CLI as an MCP server",
+      logo: "./assets/my-logo.png", // Local file path
+    },
+  },
 });
-
-// Usage: my-tool serve (uses all default transports)
-// Usage: my-tool serve --transports '[{"type":"sse","port":4000}]' (overrides defaults)
 ```
 
-### Constructors
-
-#### `new ArgParserBase(options?, initialFlags?)`
-
-Constructor for creating a basic parser instance without MCP capabilities.
-
-#### `new ArgParser(options?, initialFlags?)`
-
-Constructor for creating a parser instance with MCP capabilities.
-
-- `options`: An object (`IArgParserParams`) configuring the parser.
-  - `appName?: string`: Display name.
-  - `appCommandName?: string`: Command name for help/errors.
-  - `description?: string`: Parser description.
-  - `handler?: (ctx: HandlerContext) => void`: Handler function for this parser.
-  - `subCommands?: ISubCommand[]`: Array of sub-command definitions.
-  - `handleErrors?: boolean`: Enable/disable default error handling (default: `true`).
-  - `throwForDuplicateFlags?: boolean`: Throw error for duplicate flags (default: `false`).
-  - `inheritParentFlags?: boolean`: Enable flag inheritance when this parser is a sub-command (default: `false`).
-- `initialFlags`: Optional array of `IFlag` objects to add during initialization.
-
-### `parse(args, options?)`
-
-Parses an array of command-line arguments.
-
-- `args`: `string[]` - Array of arguments (usually `process.argv.slice(2)`).
-- `options`: Optional object (`IParseOptions`).
-  - `skipHelpHandling?: boolean`: Prevents automatic help display/exit on `--help` (default: `false`).
-  - `skipHandlers?: boolean`: Prevents execution of any matched command handlers (default: `false`).
-- Returns: `TParsedArgs & { $commandChain?: string[] }` - An object containing the parsed arguments and optionally the `$commandChain`. Throws `ArgParserError` if `handleErrors` is `false`.
-
-### `.addFlag(flag)`
+If no custom logo is provided or loading fails, a default ArgParser logo is included
 
-Adds a single flag definition.
+#### Supported Logo Sources
 
-- `flag`: `IFlag` - The flag object.
-- Returns: `this` for chaining.
+**Local File Path:**
 
-### `.addFlags(flags)`
-
-Adds multiple flag definitions.
-
-- `flags`: `IFlag[]` - Array of flag objects.
-- Returns: `this` for chaining.
-
-### `.addSubCommand(subCommand)`
-
-Adds a sub-command definition.
-
-- `subCommand`: `ISubCommand` - The sub-command object.
-- Returns: `this` for chaining.
-
-### `.setHandler(handler)`
-
-Sets or overrides the handler function for this parser instance.
-
-- `handler`: `(ctx: HandlerContext) => void` - The handler function.
-- Returns: `this` for chaining.
-
-### `.getSubCommand(name)`
-
-Retrieves a defined sub-command by name.
-
-- `name`: `string` - The name of the sub-command.
-- Returns: `ISubCommand | undefined` - The sub-command definition or `undefined` if not found.
-
-### `.hasFlag(name)`
-
-Checks if a flag with the given name exists on this parser instance.
-
-- `name`: `string` - The name of the flag.
-- Returns: `boolean`.
-
-### `helpText()`
-
-Generates the formatted help text for this parser instance.
+```typescript
+logo: "./assets/my-logo.png"; // Relative to your project
+logo: "/absolute/path/to/logo.jpg"; // Absolute path
+```
 
-- Returns: `string` - The generated help text.
+**HTTP/HTTPS URL:**
 
-### `printAll(filePath?)`
+```typescript
+logo: "https://example.com/logo.png"; // Downloaded automatically
+logo: "https://cdn.example.com/icon.svg";
+```
 
-Recursively prints the parser configuration.
+### How DXT Generation Works
 
-- `filePath`: `string?` - Optional path to write output to file. `.json` extension saves as JSON.
+When you run `--s-build-dxt`, ArgParser performs several steps to create a self-contained, autonomous package:
 
-### Interfaces
+1.  **Introspection**: It analyzes all tools defined with `.addTool()`.
+2.  **Manifest Generation**: It creates a `manifest.json` file.
+    - Tool flags are converted into a JSON Schema for the `input_schema`.
+    - Flags with an `env` property (e.g., `{ name: 'apiKey', env: 'API_KEY' }`) are automatically added to the `user_config` section, prompting the user for the value upon installation and making it available as an environment variable to your tool.
+3.  **Autonomous Build**: It bundles your CLI's source code and its dependencies into a single entry point (e.g., `server.js`) that can run without `node_modules`. This ensures the DXT is portable and reliable.
+4.  **Packaging**: It assembles all necessary files (manifest, server bundle, logo, etc.) into the specified output directory, ready to be used by Claude Desktop or packed with `npx @anthropic-ai/dxt`.
 
-- `IFlag`: Defines the structure of a command-line flag.
-- `ISubCommand`: Defines the structure of a sub-command.
-- `HandlerContext`: The object passed to handler functions.
-- `IParseOptions`: Options for the `parse()` method.
-- `IArgParserParams`: Options for the `ArgParser` constructor.
-- `ArgParserError`: Custom error class thrown on parsing failures when `handleErrors` is `false`.
+---
 
-## Quick Reference
+## System Flags & Configuration
+
+ArgParser includes built-in `--s-*` flags for development, debugging, and configuration. They are processed before normal arguments and will cause the program to exit after their task is complete.
+
+| Flag                        | Description                                                                                    |
+| --------------------------- | ---------------------------------------------------------------------------------------------- |
+| **MCP & DXT**               |                                                                                                |
+| `--s-mcp-serve`             | Starts the application in MCP server mode, exposing all tools.                                 |
+| `--s-build-dxt [dir]`       | Generates a complete, autonomous DXT package for Claude Desktop.                               |
+| `--s-mcp-transport <type>`  | Overrides the MCP transport (`stdio`, `sse`, `streamable-http`).                               |
+| `--s-mcp-transports <json>` | Overrides transports with a JSON array for multi-transport setups.                             |
+| `--s-mcp-port <number>`     | Sets the port for HTTP-based transports (`sse`, `streamable-http`).                            |
+| `--s-mcp-host <string>`     | Sets the host address for HTTP-based transports.                                               |
+| **Configuration**           |                                                                                                |
+| `--s-with-env <file>`       | Loads configuration from a file (`.env`, `.json`, `.yaml`, `.toml`). CLI args take precedence. |
+| `--s-save-to-env <file>`    | Saves the current arguments to a configuration file, perfect for templates.                    |
+| **Debugging**               |                                                                                                |
+| `--s-debug`                 | Prints a detailed, step-by-step log of the argument parsing process.                           |
+| `--s-debug-print`           | Exports the entire parser configuration to a JSON file for inspection.                         |
+| `--s-enable-fuzzy`          | Enables fuzzy testing mode—a dry run that parses args but skips handler execution.             |
 
-### **Basic CLI Setup**
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+---
 
-const cli = new ArgParser({
-  appName: "My Tool",
-  appCommandName: "my-tool",
-  handler: async (ctx) => ({ result: ctx.args }),
-})
-.addFlags([
-  { name: "input", options: ["--input", "-i"], type: "string", mandatory: true },
-  { name: "verbose", options: ["--verbose", "-v"], type: "boolean", flagOnly: true },
-])
-.addSubCommand({
-  name: "process",
-  description: "Process data",
-  handler: async (ctx) => ({ processed: true }),
-  parser: new ArgParser({}, [
-    { name: "format", options: ["--format"], type: "string", enum: ["json", "xml"] },
-  ]),
-});
-```
+## Changelog
 
-### **MCP Integration**
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+### v2.1.0
 
-const mcpCli = ArgParser.withMcp({ /* same options */ })
-  .addFlags([/* same flags */])
-  .addMcpSubCommand("serve", {
-    name: "my-mcp-server",
-    version: "1.0.0",
-  });
+**Feat**
 
-// CLI: my-tool --input data.txt process --format json
-// MCP: my-tool serve --transport sse --port 3001
-```
+- IFlag function-based `type` handling must now define the type it returns, this unlocks nice features such as providing nicer Intellisense, `output schemas` support and makes it easier to upgrade to Zod V4
+- Add support for MCP output_schema field for clients that support it, CLI isn't impacted by it, this helps a lot the interactivity, self-documentation, and improves the API guarantees
 
-### **MCP Preset Transport Configuration**
-Configure default transports that will be used when no CLI transport flags are provided:
+**Fixes and changes**
+- Fix missing missing types
+- Improved MCP version compliance 
 
-```typescript
-import { ArgParser, McpTransportConfig } from "@alcyone-labs/arg-parser";
+### v2.0.0
 
-// Single preset transport
-const cliWithPreset = ArgParser.withMcp({
-  appName: "My Tool",
-  handler: async (ctx) => ({ result: ctx.args }),
-})
-.addMcpSubCommand("serve", {
-  name: "my-server",
-  version: "1.0.0",
-}, {
-  defaultTransport: {
-    type: "sse",
-    port: 3001,
-    host: "0.0.0.0"
-  }
-});
+- **Unified Tool Architecture**: Introduced `.addTool()` to define CLI subcommands and MCP tools in a single declaration.
+- **Environment Variables Support**: The `env` property on any IFlag now automatically pull value from the `process.env[${ENV}]` key and generates `user_config` entries in the DXT manifest and fills the flag value to the ENV value if found (process.env).
+- **Enhanced DXT Generation**: The `env` property on flags now automatically generates `user_config` entries in the DXT manifest.
+- **Automatic Console Safety**: Console output is automatically and safely redirected in MCP mode to prevent protocol contamination.
+- **Breaking Changes**: The `addMcpSubCommand()` and separate `addSubCommand()` for MCP tools are deprecated in favor of `addTool()` and `--s-mcp-serve`.
 
-// Multiple preset transports
-const cliWithMultiplePresets = ArgParser.withMcp({
-  appName: "Multi-Transport Tool",
-  handler: async (ctx) => ({ result: ctx.args }),
-})
-.addMcpSubCommand("serve", {
-  name: "multi-server",
-  version: "1.0.0",
-}, {
-  defaultTransports: [
-    { type: "stdio" },
-    { type: "sse", port: 3001 },
-    { type: "streamable-http", port: 3002, path: "/api/mcp" }
-  ],
-  toolOptions: {
-    includeSubCommands: true
-  }
-});
+### v1.3.0
 
-// CLI flags always take precedence over presets
-// my-tool serve                    -> Uses preset transports
-// my-tool serve --transport sse    -> Overrides preset with CLI flags
-```
+- **Plugin System & Architecture**: Refactored to a dependency-injection model, making the core library dependency-free. Optional plugins for TOML/YAML.
+- **Global Console Replacement**: Implemented the first version of automatic console suppression for MCP compliance.
+- **Autonomous Build Improvements**: Significantly reduced DXT bundle size and removed dynamic `require` issues.
 
-### **System Flags**
-```bash
-# Debug parsing
-my-tool --s-debug --input data.txt process
+### v1.2.0
 
-# Load configuration
-my-tool --s-with-env config.yaml --input override.txt
+- **Critical MCP Fixes**: Resolved issues where MCP tools with output schemas would fail. Ensured correct JSON-RPC 2.0 response formatting.
+- **Enhanced Handler Context**: Added `isMcp` flag to the handler context for more reliable mode detection.
 
-# Save configuration
-my-tool --input data.txt --s-save-to-env template.yaml
-```
+### v1.1.0
 
-### **Multiple MCP Transports**
-```bash
-# Single transport
-my-tool serve --transport sse --port 3001
-
-# Multiple transports
-my-tool serve --transports '[
-  {"type":"stdio"},
-  {"type":"sse","port":3001},
-  {"type":"streamable-http","port":3002}
-]'
-```
+- **Major Features**: First release with MCP Integration, System Flags (`--s-debug`, `--s-with-env`, etc.), and environment loading from files.
 
 ---
 
-**📖 For complete examples and tutorials, see the [`examples/`](./examples/) directory.**
-
---- 
-
 ## Backlog
 
 - [x] Publish as an open-source library
 - [x] Make ArgParser compatible with MCP out-of-the-box
-- [x] Rename --LIB-* flags to --s-*
+- [x] Rename --LIB-\* flags to --s-\*
 - [x] Make it possible to pass a `--s-save-to-env /path/to/file` parameter that saves all the parameters to a file (works with Bash-style .env, JSON, YAML, TOML)
 - [x] Make it possible to pass a `--s-with-env /path/to/file` parameter that loads all the parameters from a file (works with Bash-style .env, JSON, YAML, TOML)
 - [ ] Add System flags to args.systemArgs
@@ -1506,4 +1028,3 @@ my-tool serve --transports '[
 ### (known) Bugs / DX improvement points
 
 - [ ] When a flag with `flagOnly: false` is going to consume a value that appears like a valid flag from the set, raise the appropriate warning
-- [ ] When a flag with `allowMultiple: false` and `flagOnly: true` is passed multiple times (regardless of the options, for example "-1" and later "--one", both being valid), raise the correct error