@alcyone-labs/arg-parser 1.1.0 → 2.0.0

package/README.md

@@ -1,1373 +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.
+---
+
+## Installation
 
-## What's New in v1.1.0
+```bash
+# Using PNPM (recommended)
+pnpm add @alcyone-labs/arg-parser
+```
 
-### **Major Features**
+---
 
-- **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`, and `--s-enable-fuzzy` for enhanced debugging, configuration, and testing
-- **Environment Loading**: Load configuration from `.env`, `.yaml`, `.json`, and `.toml` files
-- **Enhanced Debugging**: Comprehensive runtime debugging and configuration export tools
+## Quick Start: The Unified `addTool` API
 
-### **Quick Start with MCP**
+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({
-  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 }),
+  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" },
+  },
 })
-.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" }
-  ]
-});
-
-// 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}]'
-```
-
-## 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
+  // 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 };
+    },
+  });
 
-## Installation
+// 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);
+  }
+}
 
-You can install ArgParser using your preferred package manager:
+main();
 
-```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
+// 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;
 ```
 
-### **For MCP Integration (Optional)**
-
-If you plan to use MCP server features, install the additional dependencies:
+## How to Run It
 
 ```bash
-pnpm add @modelcontextprotocol/sdk express
-# or
-npm install @modelcontextprotocol/sdk express
-```
+# This assumes `mycli` is your CLI's entry point
 
-**Note:** MCP dependencies are optional and only required if you use `ArgParser` with MCP features or MCP-related functionality.
+# 1. As a standard CLI subcommand
+mycli greet --name Jane --style formal
 
-## Runtime Compatibility
+# 2. As an MCP server, exposing the 'greet' tool
+mycli --s-mcp-serve
 
-ArgParser is fully compatible with multiple JavaScript runtimes:
-
-### **BunJS**
-```bash
-# Run TypeScript directly
-bun your-cli.ts --flag value
-
-# Or compile and run
-bun build your-cli.ts --outdir ./dist
-bun ./dist/your-cli.js --flag value
+# 3. Generate a DXT package for Claude Desktop (2-steps)
+mycli --s-build-dxt ./my-dxt-package
 ```
 
-### **Node.js**
-```bash
-# Using tsx for TypeScript
-npx tsx your-cli.ts --flag value
+Read more on generating the DXT package here: [Generating DXT Packages](#generating-dxt-packages---s-build-dxt)
 
-# Using ts-node
-npx ts-node your-cli.ts --flag value
+### Setting Up System-Wide CLI Access
 
-# Or compile and run
-npx tsc your-cli.ts
-node your-cli.js --flag value
-```
+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:
 
-### **Deno**
-```bash
-# Run with required permissions
-deno run --unstable-sloppy-imports --allow-read --allow-write --allow-env your-cli.ts --flag value
+**1. Configure your package.json:**
 
-# Or use the provided deno.json configuration for easier task management
-deno task example:simple-cli --env production --port 8080
+```json
+{
+  "name": "my-cli-app",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "mycli": "./cli.js"
+  }
+}
 ```
 
-### **Using Built Artifacts**
-
-After building your project with `pnpm build` (or your preferred build tool), you can use the compiled JavaScript files directly:
+**2. Make your CLI file executable:**
 
 ```bash
-# CommonJS (Node.js)
-node dist/index.cjs
-
-# ES Modules (Node.js with "type": "module" in package.json)
-node dist/index.mjs
-
-# Minified ES Modules (production)
-node dist/index.min.mjs
-
-# Import in your own projects
-const { ArgParser } = require('./dist/index.cjs');  // CommonJS
-import { ArgParser } from './dist/index.mjs';       // ES Modules
-
-# Example: Using built artifacts in production
-node -e "
-const { ArgParser } = require('./dist/index.cjs');
-const cli = new ArgParser({
-  appName: 'Production CLI',
-  handler: (ctx) => console.log('Production ready!', ctx.args)
-}).addFlags([
-  { name: 'env', options: ['--env'], type: 'string', mandatory: true, description: 'Environment' }
-]);
-cli.parse(['--env', 'production']);
-"
-```
-
-All examples in this repository work seamlessly across all three runtimes, ensuring maximum compatibility for your CLI applications.
-
-## Basic Usage
-
-### **Standard CLI Usage**
-
-Here's a simple example demonstrating how to define flags and parse arguments:
-
-```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",
-  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)",
-  },
-  {
-    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);
+chmod +x cli.js
 ```
 
-### **MCP Server Usage (v1.1.0+)**
+**3. Add a shebang to your CLI file:**
 
-Transform your CLI into an MCP server with minimal changes:
+```javascript
+#!/usr/bin/env node
+# or #!/usr/bin/env bun for native typescript runtime
 
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+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",
+  appName: "My CLI",
+  appCommandName: "mycli",
+  // ... your configuration
 });
 
-// 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
+// Parse command line arguments
+await cli.parse(process.argv.slice(2));
 ```
 
-## MCP Integration (v1.1.0+)
-
-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.
-
-### **Quick MCP Setup**
-
-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",
-   });
-   ```
-
-3. **Use as CLI or MCP server:**
-   ```bash
-   # CLI usage
-   my-tool --input data.txt --verbose
-
-   # MCP server (stdio)
-   my-tool serve
-
-   # MCP server (HTTP)
-   my-tool serve --transport sse --port 3001
-
-   # Multiple transports
-   my-tool serve --transports '[{"type":"stdio"},{"type":"sse","port":3001}]'
-   ```
-
-### **MCP Transport Options**
-
-- **`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
-
-### **Multiple Transports Simultaneously**
-
-Run multiple transport types at once for maximum flexibility:
+**4. Link the package globally:**
 
 ```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"}
-]'
-```
-
-### **Automatic Tool Generation**
-
-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
+# Using npm
+npm link
 
-### Defining Flags
+# Using pnpm
+pnpm link --global
 
-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:
+# Using bun
+bun link
 
-```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
-}
+# Using yarn
+yarn link
 ```
 
-### 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:
+**5. Use your CLI from anywhere:**
 
-```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.
+```bash
+# Now you can run your CLI from any directory
+mycli --help
+mycli greet --name "World"
 
-```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)",
-})
+# Or use with npx/pnpx if you prefer
+npx mycli --help
+pnpx mycli greet --name "World"
 ```
 
-If a mandatory flag is missing and default error handling is enabled (`handleErrors: true`), the parser will print an error and exit.
-
-### Default Values
+**To unlink later:**
 
-Set a `defaultValue` (or its alias `default`) for flags to provide a fallback value if the flag is not present in the arguments.
-
-```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",
-})
-```
+```bash
+# Using npm
+npm unlink --global my-cli-app
 
-### Flag-Only Flags
+# Using pnpm
+pnpm unlink --global
 
-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.
+# Using bun
+bun unlink
 
-```typescript
-.addFlag({
-  name: "verbose",
-  options: ["-v"],
-  type: Boolean, // Typically boolean for flag-only flags
-  flagOnly: true,
-  description: "Enable verbose output",
-})
+# Using yarn
+yarn unlink
 ```
 
-### 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
+## Parsing Command-Line Arguments
 
-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.
+ArgParser's `parse()` method is async and automatically handles both synchronous and asynchronous handlers:
 
-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.
+### Cannonical Usage Pattern
 
 ```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 },
-]);
-
-const monitorParser = new ArgParser().addSubCommand({
-  name: "logs",
-  description: "Show logs",
-  parser: monitorLogsParser,
-  handler: ({ args }) => {
-    console.log(`Showing logs... Follow: ${args.follow}`);
-  },
-});
-
-const cli = new ArgParser({
+const cli = ArgParser.withMcp({
   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,
-    },
-  ],
+  handler: async (ctx) => {
+    // Works with both sync and async operations
+    const result = await someAsyncOperation(ctx.args.input);
+    return { success: true, result };
+  },
 });
 
-// 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
-};
+// 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);
+  }
+}
 ```
 
-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`.
+### Top-level await
 
-### Setting Handlers with `.setHandler()`
+Works in ES modules or Node.js >=18 with top-level await
 
-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 ...
-  });
+```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);
 }
 ```
 
-### Accessing Sub-Parsers with `.getSubCommand()`
+### Promise-based parsing
 
-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.
+If you need synchronous contexts, you can simply rely on promise-based APIs
 
-```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,
+```javascript
+cli
+  .parse(process.argv.slice(2))
+  .then((result) => {
+    console.log("Success:", result);
+  })
+  .catch((error) => {
+    console.error("Error:", error.message);
+    process.exit(1);
   });
-}
 ```
 
-### 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.
+## Migrating from v1.x to the v2.0 `addTool` API
 
-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.
+Version 2.0 introduces the `addTool()` method to unify CLI subcommand and MCP tool creation. This simplifies development by removing boilerplate and conditional logic.
 
-```typescript
-const parentParser = new ArgParser().addFlags([
-  { name: "verbose", options: ["-v"], type: Boolean, flagOnly: true },
-  { name: "config", options: ["-c"], type: String }, // Common config flag
-]);
+### Before v2.0: Separate Definitions
 
-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
-]);
+Previously, you had to define CLI handlers and MCP tools separately, often with conditional logic inside the handler to manage different output formats.
 
-parentParser.addSubCommand({
-  name: "child",
-  description: "A child command",
-  parser: childParser,
+```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" },
+  },
 });
 
-// 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.
+// 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 */
+  });
 ```
 
-## Automatic Help
-
-ArgParser provides robust automatic help generation.
+### After v2.0: The Unified `addTool()` Method
 
-### Global Help Flag (`--help`, `-h`)
+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.
 
-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
+```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" },
+  },
+});
 
-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.
+// 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 };
+  },
+});
 
-```typescript
-console.log(parser.helpText());
+// CLI usage: mycli search --query "test"
+// MCP usage: mycli --s-mcp-serve
 ```
 
-### 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
+**Benefits of Migrating:**
 
-ArgParser includes built-in error handling for common parsing errors like missing mandatory flags, invalid types, or unknown commands.
+- **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.
 
-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:
+## Core Concepts
 
-// Error: Missing mandatory flags: phase
-//
-// Try 'data-proc --help' for usage details.
-```
+### Defining Flags
 
-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.
+Flags are defined using the `IFlag` interface within the `flags` array of a tool or command.
 
 ```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);
-  }
+interface IFlag {
+  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)
 }
 ```
 
-## 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:
+### Type Handling and Validation
 
-- **`.env`** (or no extension): Bash environment variable format
-- **`.yaml` / `.yml`**: YAML format
-- **`.json` / `.jsonc`**: JSON format with metadata
-- **`.toml` / `.tml`**: TOML format
+ArgParser automatically handles type conversion and validation:
 
-### Behavior
+- **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`)
 
-- **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
+### Hierarchical CLIs (Sub-Commands)
 
-### Example Output
+While `addTool()` is the recommended way to create subcommands that are also MCP-compatible, you can use `.addSubCommand()` for traditional CLI hierarchies.
 
-For a CLI with flags `--verbose`, `--output file.txt`, and `--count 5`:
+> **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.
 
-**`.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"
-```
+```typescript
+// Create a parser for a nested command
+const logsParser = new ArgParser().addFlags([
+  { name: "follow", options: ["-f"], type: "boolean", flagOnly: true },
+]);
 
-**`.yaml` format:**
-```yaml
-# Environment configuration generated by ArgParser
-# Format: YAML
+// This creates a command group: `my-cli monitor`
+const monitorParser = new ArgParser().addSubCommand({
+  name: "logs",
+  description: "Show application logs",
+  parser: logsParser,
+  handler: ({ args }) => console.log(`Following logs: ${args.follow}`),
+});
 
-# verbose: Enable verbose output
-# Options: -v, --verbose
-# Type: Boolean
-# Default: false
+// Attach the command group to the main CLI
+const cli = new ArgParser().addSubCommand({
+  name: "monitor",
+  description: "Monitoring commands",
+  parser: monitorParser,
+});
 
-verbose: true
-output: "file.txt"
-count: 5
+// Usage: my-cli monitor logs -f
 ```
 
-## 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.
+#### MCP Exposure Control
 
-### **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-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
+```typescript
+// By default, subcommands are exposed to MCP
+const mcpTools = parser.toMcpTools(); // Includes all subcommands
 
-# Export to JSON format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.json
+// To exclude subcommands from MCP (CLI-only)
+const mcpToolsOnly = parser.toMcpTools({ includeSubCommands: false });
 
-# Export to TOML format
-your-cli --flag1 value1 --flag2 --s-save-to-env config.toml
+// 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
 ```
 
-**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
+### Flag Inheritance (`inheritParentFlags`)
 
-# Load from YAML format
-your-cli --s-with-env config.yaml
+To share common flags (like `--verbose` or `--config`) across sub-commands, set `inheritParentFlags: true` in the sub-command's parser.
 
-# Load from JSON format
-your-cli --s-with-env config.json
+```typescript
+const parentParser = new ArgParser().addFlags([
+  { name: "verbose", options: ["-v"], type: "boolean" },
+]);
 
-# Load from TOML format
-your-cli --s-with-env config.toml
+// This child parser will automatically have the --verbose flag
+const childParser = new ArgParser({ inheritParentFlags: true }).addFlags([
+  { name: "target", options: ["-t"], type: "string" },
+]);
 
-# Combine with CLI arguments (CLI args override file config)
-your-cli --s-with-env config.yaml --verbose --output override.txt
+parentParser.addSubCommand({ name: "deploy", parser: childParser });
 ```
 
-**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:**
+## MCP & Claude Desktop Integration
 
-- **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
+### Automatic MCP Server Mode (`--s-mcp-serve`)
 
-**Example Configuration Files:**
+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).
 
-**.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"]
-}
-```
+# This single command starts a fully compliant MCP server
+my-cli-app --s-mcp-serve
 
-### `--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
+# You can also override transports and ports using system flags
+my-cli-app --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3001
 ```
 
-**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
+### MCP Transports
 
-### `--s-debug`
-
-Provides detailed runtime debugging information showing how arguments are parsed step-by-step.
+You can define the transports directly in the .withMcp() settings, or override them via the `--s-mcp-transport(s)` flags.
 
 ```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
+# Single transport
+my-tool --s-mcp-serve --s-mcp-transport stdio
 
-### `--s-enable-fuzzy`
+# Multiple transports via JSON
+my-tool --s-mcp-serve --s-mcp-transports '[{"type":"stdio"},{"type":"sse","port":3001}]'
 
-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.
+# 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
 
-```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"}
+# 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" }
+    ]
+  }
+});
 ```
 
-**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.
+### Automatic Console Safety
 
-## Fuzzy Testing
+A major challenge in MCP is preventing `console.log` from corrupting the JSON-RPC communication over `STDOUT`. ArgParser solves this automatically.
 
-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.
+- **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**.
 
-### **Quick Start**
+### Generating DXT Packages (`--s-build-dxt`)
 
-Test any ArgParser configuration using the built-in fuzzy testing CLI:
+A Desktop Extension (`.dxt`) is a standardized package for installing your tools into Claude Desktop. ArgParser automates this process.
 
 ```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
-```
+# 1. Generate the DXT package contents into a directory
+my-cli-app --s-build-dxt ./my-dxt-package
 
-**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.
+# The output folder contains everything needed: manifest.json, entry point, etc.
+# A default logo will be applied if you don't provide one.
 
-### **System Flag Integration**
+# 2. (Optional) Pack the folder into a .dxt file for distribution
+npx @anthropic-ai/dxt pack ./my-dxt-package
 
-The `--s-enable-fuzzy` system flag makes any CLI fuzzy-test compatible **without any code modifications or boilerplate**:
-
-```bash
-# Enable fuzzy mode for safe testing (dry-run with no side effects)
-your-cli --s-enable-fuzzy --input test.txt --format json
+# 3. (Optional) Sign the DXT package
+npx @anthropic-ai/dxt sign ./my-dxt-package.dxt
 
-# The fuzzy testing CLI automatically uses this flag
-bun src/fuzzy-test-cli.ts --file your-cli.ts
+# Then drag & drop the .dxt file into Claude Desktop to install it, in the Settings > Extensions screen.
 ```
 
-**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
+### Logo Configuration
 
-### **Testing Capabilities**
+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.
 
-The fuzzy tester automatically tests:
-
-- **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
-
-### **Programmatic Usage**
+You can customize the logo/icon that appears in Claude Desktop for your DXT package by configuring the `logo` property in your `serverInfo`:
 
 ```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,
+const cli = ArgParser.withMcp({
+  appName: "My CLI",
+  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
+    },
+  },
 });
-
-const report = await tester.runFuzzyTest();
-console.log(`Success rate: ${(report.successfulTests / report.totalTests * 100).toFixed(1)}%`);
 ```
 
-### **Output Formats**
-
-Generate reports in multiple formats:
+If no custom logo is provided or loading fails, a default ArgParser logo is included
 
-```bash
-# Human-readable console output
-bun src/fuzzy-test-cli.ts --file my-cli.ts --format text
+#### Supported Logo Sources
 
-# Machine-readable JSON
-bun src/fuzzy-test-cli.ts --file my-cli.ts --format json --output results.json
+**Local File Path:**
 
-# Documentation-friendly Markdown
-bun src/fuzzy-test-cli.ts --file my-cli.ts --format markdown --output report.md
+```typescript
+logo: "./assets/my-logo.png"; // Relative to your project
+logo: "/absolute/path/to/logo.jpg"; // Absolute path
 ```
 
-For complete documentation, examples, and advanced usage patterns, see the [Fuzzy Testing Documentation](docs/fuzzy-testing.md).
-
-## API Reference
-
-This section provides a quick overview of the main components. See the sections above for detailed explanations and examples.
+**HTTP/HTTPS URL:**
 
-### **Core Classes**
-
-#### `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 }
-  ]
-});
-
-// Usage: my-tool serve (uses all default transports)
-// Usage: my-tool serve --transports '[{"type":"sse","port":4000}]' (overrides defaults)
+logo: "https://example.com/logo.png"; // Downloaded automatically
+logo: "https://cdn.example.com/icon.svg";
 ```
 
-### 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)`
-
-Adds a single flag definition.
-
-- `flag`: `IFlag` - The flag object.
-- Returns: `this` for chaining.
-
-### `.addFlags(flags)`
-
-Adds multiple flag definitions.
-
-- `flags`: `IFlag[]` - Array of flag objects.
-- Returns: `this` for chaining.
-
-### `.addSubCommand(subCommand)`
-
-Adds a sub-command definition.
+### How DXT Generation Works
 
-- `subCommand`: `ISubCommand` - The sub-command object.
-- Returns: `this` for chaining.
+When you run `--s-build-dxt`, ArgParser performs several steps to create a self-contained, autonomous package:
 
-### `.setHandler(handler)`
+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`.
 
-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`.
-
-## Quick Reference
-
-### **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"] },
-  ]),
-});
-```
-
-### **MCP Integration**
-```typescript
-import { ArgParser } from "@alcyone-labs/arg-parser";
+---
 
-const mcpCli = ArgParser.withMcp({ /* same options */ })
-  .addFlags([/* same flags */])
-  .addMcpSubCommand("serve", {
-    name: "my-mcp-server",
-    version: "1.0.0",
-  });
+## 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.             |
 
-// CLI: my-tool --input data.txt process --format json
-// MCP: my-tool serve --transport sse --port 3001
-```
+---
 
-### **MCP Preset Transport Configuration**
-Configure default transports that will be used when no CLI transport flags are provided:
+## Changelog
 
-```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
@@ -1380,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