@alcyone-labs/arg-parser 1.2.0 → 2.0.0

package/README.md

@@ -1,1499 +1,655 @@
 # 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)
+  - [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)
+  - [How DXT Generation Works](#how-dxt-generation-works)
+- [System Flags & Configuration](#system-flags--configuration)
+- [Changelog](#changelog)
+- [Backlog](#backlog)
+
+## 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 { 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",
+      },
+    ],
+    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",
-  },
-  {
-    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)",
+    // Works with both sync and async operations
+    const result = await someAsyncOperation(ctx.args.input);
+    return { success: true, result };
   },
-  {
-    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+)**
+### Top-level await
 
-Transform your CLI into an MCP server with minimal changes:
+Works in ES modules or Node.js >=18 with top-level await
 
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
-
-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",
-});
-
-// 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";
-   ```
+---
+
+## Migrating from v1.x to the v2.0 `addTool` API
 
-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",
-   });
-   ```
+Version 2.0 introduces the `addTool()` method to unify CLI subcommand and MCP tool creation. This simplifies development by removing boilerplate and conditional logic.
 
-3. **Use as CLI or MCP server:**
-   ```bash
-   # CLI usage
-   my-tool --input data.txt --verbose
+### Before v2.0: Separate Definitions
 
-   # MCP server (stdio)
-   my-tool serve
+Previously, you had to define CLI handlers and MCP tools separately, often with conditional logic inside the handler to manage different output formats.
 
-   # MCP server (HTTP)
-   my-tool serve --transport 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" },
+  },
+});
 
-   # Multiple transports
-   my-tool serve --transports '[{"type":"stdio"},{"type":"sse","port":3001}]'
-   ```
+// 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 */
+  });
+```
 
-### **MCP Transport Options**
+### After v2.0: The Unified `addTool()` Method
 
-- **`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
+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.
 
-### **Multiple Transports Simultaneously**
+```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" },
+  },
+});
 
-Run multiple transport types at once for maximum flexibility:
+// 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 };
+  },
+});
 
-```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"}
-]'
+// 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.
 
-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 automatically handles type conversion and validation:
 
-```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
-
-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.
-
-```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)",
-})
-```
+- **String flags**: `--name value` or `--name="quoted value"`
+- **Number flags**: `--count 42` (automatically parsed)
+- **Boolean flags**: `--verbose` (presence implies `true`)
+- **Array flags**: `--tags tag1,tag2,tag3` or multiple `--tag value1 --tag value2` (requires `allowMultiple: true`)
 
-If a mandatory flag is missing and default error handling is enabled (`handleErrors: true`), the parser will print an error and exit.
+### Hierarchical CLIs (Sub-Commands)
 
-### Default Values
+While `addTool()` is the recommended way to create subcommands that are also MCP-compatible, you can use `.addSubCommand()` for traditional CLI hierarchies.
 
-Set a `defaultValue` (or its alias `default`) for flags to provide a fallback value if the flag is not present in the arguments.
+> **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
-.addFlag({
-  name: "port",
-  options: ["-p", "--port"],
-  type: Number,
-  defaultValue: 3000, // Default port is 3000 if -p or --port is not used
-  description: "Server port",
-})
-```
-
-### Flag-Only Flags
-
-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.
-
-```typescript
-.addFlag({
-  name: "verbose",
-  options: ["-v"],
-  type: Boolean, // Typically boolean for flag-only flags
-  flagOnly: true,
-  description: "Enable verbose output",
-})
-```
-
-### Alias Properties
-
-For convenience, `ArgParser` supports aliases for some flag properties:
-
-- `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.
-
-## Hierarchical CLIs (Sub-Commands)
-
-ArgParser excels at building CLIs with nested commands, like `git clone` or `docker build`.
-
-### Defining 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.
-
-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.
-
-```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
-```
-
-### 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:
-
-```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
-```
-
-### Handler Context
-
-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
-};
+// Usage: my-cli monitor logs -f
 ```
 
-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:
+#### MCP Exposure Control
 
 ```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()`
+// By default, subcommands are exposed to MCP
+const mcpTools = parser.toMcpTools(); // Includes all subcommands
 
-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.
+// To exclude subcommands from MCP (CLI-only)
+const mcpToolsOnly = parser.toMcpTools({ includeSubCommands: false });
 
-```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`)
-
-A `--help` (and `-h`) flag is automatically added to every parser instance (root and sub-commands). When this flag is encountered during parsing:
-
-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.
-
-This behavior is triggered automatically unless `skipHelpHandling: true` is passed to the `parse()` method.
-
-```bash
-# Shows help for the root command
-my-cli --help
-
-# Shows help for the 'deploy' sub-command
-my-cli deploy --help
-```
-
-### `helpText()` Method
-
-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.
-
-```typescript
-console.log(parser.helpText());
-```
-
-### Auto-Help on Empty Invocation
-
-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.
-
-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.
-
-## Error Handling
-
-ArgParser includes built-in error handling for common parsing errors like missing mandatory flags, invalid types, or unknown commands.
-
-By default (`handleErrors: true`):
-
-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.
-
-```typescript
-// Example (assuming 'data-proc' is appCommandName and 'phase' is mandatory)
-// Running `data-proc` would output:
-
-// Error: Missing mandatory flags: phase
-//
-// Try 'data-proc --help' for usage details.
-```
-
-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.
-
-```typescript
-import { ArgParser, ArgParserError } from "@alcyone-labs/arg-parser";
-
-const parser = new ArgParser({
-  appCommandName: "my-app",
-  handleErrors: false, // Disable default handling
-});
-
-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
-
-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.
-
-### Usage
-
-```bash
-# Export to .env format (default for no extension)
-your-cli --flag1 value1 --flag2 --s-save-to-env config.env
-
-# 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
-```
-
-### 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
-
-### Behavior
-
-- **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
-
-### Example Output
-
-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
-
-verbose: true
-output: "file.txt"
-count: 5
-```
-
-## 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.
-
-### **Overview**
-
-System flags use the `--s-*` pattern and provide powerful development and deployment tools:
-
-- **`--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)
-
-### `--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
-
-# 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
-```
-
-**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
-
-# Load from JSON format
-your-cli --s-with-env config.json
-
-# Load from TOML format
-your-cli --s-with-env config.toml
-
-# Combine with CLI arguments (CLI args override file config)
-your-cli --s-with-env config.yaml --verbose --output override.txt
-```
-
-**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
-
-**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
-```
-
-**JSON format:**
-```json
-{
-  "verbose": true,
-  "output": "file.txt",
-  "count": 5,
-  "tags": ["tag1", "tag2", "tag3"]
-}
-```
-
-### `--s-debug-print`
-
-Prints the complete parser configuration to a JSON file and console for debugging complex parser setups.
-
-```bash
-your-cli --s-debug-print
-```
-
-**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`
-
-Provides detailed runtime debugging information showing how arguments are parsed step-by-step.
-
-```bash
-your-cli --flag1 value1 sub-command --flag2 value2 --s-debug
-```
-
-**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
-
-**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.
-
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
-
-const parser = new ArgParser({ appName: "Debug App" })
-  .addFlags([
-    /* ... */
-  ])
-  .addSubCommand(/* ... */);
-
-parser.printAll(); // Output to console
-```
-
-### Runtime Debugging
-
-For runtime debugging, use the system flags documented above:
+---
 
-- `--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
+## MCP & Claude Desktop Integration
 
-### `--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.
-
-### **Quick Start**
-
-Test any ArgParser configuration using the built-in fuzzy testing CLI:
+# This single command starts a fully compliant MCP server
+my-cli-app --s-mcp-serve
 
-```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.
-
-### **System Flag Integration**
+### MCP Transports
 
-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
+# 1. Generate the DXT package contents into a directory
+my-cli-app --s-build-dxt ./my-dxt-package
 
-# Generate DXT packages in specific directory
-your-cli --s-save-DXT ./dxt-packages
+# The output folder contains everything needed: manifest.json, entry point, etc.
+# A default logo will be applied if you don't provide one.
 
-# Example with multiple MCP servers
-my-tool --s-save-DXT ./extensions
-```
+# 2. (Optional) Pack the folder into a .dxt file for distribution
+npx @anthropic-ai/dxt pack ./my-dxt-package
 
-**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
+# 3. (Optional) Sign the DXT package
+npx @anthropic-ai/dxt sign ./my-dxt-package.dxt
 
-**Generated Structure:**
-```
-your-server.dxt (ZIP file)
-├── manifest.json         # Server metadata and tool definitions
-└── server/
-    └── index.js          # Server entry point
+# Then drag & drop the .dxt file into Claude Desktop to install it, in the Settings > Extensions screen.
 ```
 
-**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
-```
-
-**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
+### Logo Configuration
 
-This section provides a quick overview of the main components. See the sections above for detailed explanations and examples.
+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.
 
-### **Core Classes**
+You can customize the logo/icon that appears in Claude Desktop for your DXT package by configuring the `logo` property in your `serverInfo`:
 
-#### `ArgParserBase`
-
-Base class providing core CLI parsing functionality without MCP features. Use this for lightweight CLIs that don't need MCP server capabilities.
-
-**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.
-
-- Returns: `string` - The generated help text.
-
-### `printAll(filePath?)`
-
-Recursively prints the parser configuration.
-
-- `filePath`: `string?` - Optional path to write output to file. `.json` extension saves as JSON.
-
-### Interfaces
-
-- `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`.
+```typescript
+logo: "./assets/my-logo.png"; // Relative to your project
+logo: "/absolute/path/to/logo.jpg"; // Absolute path
+```
 
-## Quick Reference
+**HTTP/HTTPS URL:**
 
-### **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"] },
-  ]),
-});
+logo: "https://example.com/logo.png"; // Downloaded automatically
+logo: "https://cdn.example.com/icon.svg";
 ```
 
-### **MCP Integration**
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+### How DXT Generation Works
 
-const mcpCli = ArgParser.withMcp({ /* same options */ })
-  .addFlags([/* same flags */])
-  .addMcpSubCommand("serve", {
-    name: "my-mcp-server",
-    version: "1.0.0",
-  });
+When you run `--s-build-dxt`, ArgParser performs several steps to create a self-contained, autonomous package:
 
-// CLI: my-tool --input data.txt process --format json
-// MCP: my-tool serve --transport sse --port 3001
-```
+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`.
 
-### **MCP Preset Transport Configuration**
-Configure default transports that will be used when no CLI transport flags are provided:
+---
 
-```typescript
-import { ArgParser, McpTransportConfig } from "@alcyone-labs/arg-parser";
+## 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.             |
 
-// 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"
-  }
-});
+---
 
-// 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
-  }
-});
+## Changelog
 
-// CLI flags always take precedence over presets
-// my-tool serve                    -> Uses preset transports
-// my-tool serve --transport sse    -> Overrides preset with CLI flags
-```
+### v2.0.0
 
-### **System Flags**
-```bash
-# Debug parsing
-my-tool --s-debug --input data.txt process
+- **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`.
 
-# Load configuration
-my-tool --s-with-env config.yaml --input override.txt
+### v1.3.0
 
-# Save configuration
-my-tool --input data.txt --s-save-to-env template.yaml
-```
+- **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.
 
-### **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}
-]'
-```
+### v1.2.0
 
----
+- **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.
+
+### v1.1.0
 
-**📖 For complete examples and tutorials, see the [`examples/`](./examples/) directory.**
+- **Major Features**: First release with MCP Integration, System Flags (`--s-debug`, `--s-with-env`, etc.), and environment loading from files.
 
---- 
+---
 
 ## 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 +662,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