@alcyone-labs/arg-parser 2.2.1 → 2.4.0

package/README.md

@@ -1,15 +1,17 @@
 # ArgParser - Type-Safe Command Line Argument Parser
 
-A modern, type-safe command line argument parser with built-in MCP (Model Context Protocol) integration and automatic Claude Desktop Extension (DXT) generation.
+A modern, type-safe command line argument parser with built-in MCP (Model Context Protocol) integration, real-time MCP Resources, 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)
+  - [MCP Tool Name Constraints](#mcp-tool-name-constraints)
 - [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)
+  - [Automatic Argument Detection](#automatic-argument-detection)
   - [Cannonical Usage Pattern](#cannonical-usage-pattern)
   - [Top-level await](#top-level-await)
   - [Promise-based parsing](#promise-based-parsing)
@@ -19,6 +21,11 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
 - [Core Concepts](#core-concepts)
   - [Defining Flags](#defining-flags)
   - [Type Handling and Validation](#type-handling-and-validation)
+    - [Supported Type Formats](#supported-type-formats)
+    - [Runtime Type Validation](#runtime-type-validation)
+    - [Automatic Type Processing](#automatic-type-processing)
+    - [Async Custom Parser Support](#async-custom-parser-support)
+    - [Type Conversion Examples](#type-conversion-examples)
   - [Hierarchical CLIs (Sub-Commands)](#hierarchical-clis-sub-commands)
     - [MCP Exposure Control](#mcp-exposure-control)
   - [Flag Inheritance (`inheritParentFlags`)](#flag-inheritance-inheritparentflags)
@@ -36,13 +43,100 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
     - [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
   - [Automatic MCP Server Mode (`--s-mcp-serve`)](#automatic-mcp-server-mode---s-mcp-serve)
   - [MCP Transports](#mcp-transports)
+  - [MCP Logging Configuration](#mcp-logging-configuration)
+    - [Enhanced Logging (Recommended)](#enhanced-logging-recommended)
+    - [Simple Logging Configuration](#simple-logging-configuration)
+    - [Configuration Priority](#configuration-priority)
+    - [Configuration Merging](#configuration-merging)
+    - [Path Resolution Options](#path-resolution-options)
+  - [MCP Resources - Real-Time Data Feeds](#mcp-resources---real-time-data-feeds)
+    - [Basic Resource Setup](#basic-resource-setup)
+    - [URI Templates with Dynamic Parameters](#uri-templates-with-dynamic-parameters)
+    - [MCP Subscription Lifecycle](#mcp-subscription-lifecycle)
+    - [Usage Examples](#usage-examples)
+    - [Design Patterns](#design-patterns)
   - [Automatic Console Safety](#automatic-console-safety)
   - [Generating DXT Packages (`--s-build-dxt`)](#generating-dxt-packages---s-build-dxt)
   - [Logo Configuration](#logo-configuration)
     - [Supported Logo Sources](#supported-logo-sources)
+  - [Including Additional Files in DXT Packages](#including-additional-files-in-dxt-packages)
+    - [Include Options](#include-options)
   - [How DXT Generation Works](#how-dxt-generation-works)
+  - [DXT Bundling Strategies](#dxt-bundling-strategies)
+    - [Standard Approach (Recommended for Most Projects)](#standard-approach-recommended-for-most-projects)
+    - [Native Dependencies Approach](#native-dependencies-approach)
+  - [Typical Errors](#typical-errors)
 - [System Flags & Configuration](#system-flags--configuration)
 - [Changelog](#changelog)
+  - [v2.4.0](#v240)
+  - [v2.3.0](#v230)
+  - [v2.2.1](#v221)
+  - [v2.2.0](#v220)
+  - [v2.1.1](#v211)
+  - [v2.1.0](#v210)
+  - [v2.0.0](#v200)
+  - [v1.3.0](#v130)
+  - [v1.2.0](#v120)
+  - [v1.1.0](#v110)
+- [Backlog](#backlog)
+  - [(known) Bugs / DX improvement points](#known-bugs--dx-improvement-points)
+
+- [Features Overview](#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)
+  - [Automatic Argument Detection](#automatic-argument-detection)
+  - [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)
+    - [Supported Type Formats](#supported-type-formats)
+    - [Runtime Type Validation](#runtime-type-validation)
+    - [Automatic Type Processing](#automatic-type-processing)
+    - [Async Custom Parser Support](#async-custom-parser-support)
+    - [Type Conversion Examples](#type-conversion-examples)
+  - [Hierarchical CLIs (Sub-Commands)](#hierarchical-clis-sub-commands)
+    - [MCP Exposure Control](#mcp-exposure-control)
+  - [Flag Inheritance (`inheritParentFlags`)](#flag-inheritance-inheritparentflags)
+- [MCP & Claude Desktop Integration](#mcp--claude-desktop-integration)
+  - [Output Schema Support](#output-schema-support)
+    - [Basic Usage](#basic-usage)
+    - [Predefined Schema Patterns](#predefined-schema-patterns)
+    - [Custom Zod Schemas](#custom-zod-schemas)
+    - [MCP Version Compatibility](#mcp-version-compatibility)
+    - [Automatic Error Handling](#automatic-error-handling)
+  - [Writing Effective MCP Tool Descriptions](#writing-effective-mcp-tool-descriptions)
+    - [Best Practices for Tool Descriptions](#best-practices-for-tool-descriptions)
+    - [Complete Example: Well-Documented Tool](#complete-example-well-documented-tool)
+    - [Parameter Description Guidelines](#parameter-description-guidelines)
+    - [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
+  - [Automatic MCP Server Mode (`--s-mcp-serve`)](#automatic-mcp-server-mode---s-mcp-serve)
+  - [MCP Transports](#mcp-transports)
+  - [MCP Log Path Configuration](#mcp-log-path-configuration)
+  - [MCP Resources - Real-Time Data Feeds](#mcp-resources---real-time-data-feeds) ⭐
+  - [Automatic Console Safety](#automatic-console-safety)
+  - [Generating DXT Packages (`--s-build-dxt`)](#generating-dxt-packages---s-build-dxt)
+  - [Logo Configuration](#logo-configuration)
+    - [Supported Logo Sources](#supported-logo-sources)
+  - [How DXT Generation Works](#how-dxt-generation-works)
+  - [DXT Bundling Strategies](#dxt-bundling-strategies)
+    - [Standard Approach (Recommended for Most Projects)](#standard-approach-recommended-for-most-projects)
+    - [Native Dependencies Approach](#native-dependencies-approach)
+- [Typical Errors](#typical-errors)
+- [System Flags & Configuration](#system-flags--configuration)
+- [Changelog](#changelog)
+  - [v2.3.0](#v230)
+  - [v2.2.1](#v221)
+  - [v2.2.0](#v220)
+  - [v2.1.1](#v211)
+  - [v2.1.0](#v210)
   - [v2.0.0](#v200)
   - [v1.3.0](#v130)
   - [v1.2.0](#v120)
@@ -55,9 +149,10 @@ A modern, type-safe command line argument parser with built-in MCP (Model Contex
 - **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`).
+- **MCP Resources with Real-Time Feeds** ⭐: Create subscription-based data feeds with URI templates for live notifications to AI assistants.
 - **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.
+- **DXT Package Generation**: Generate complete, ready-to-install Claude Desktop Extension (`.dxt`) packages with the `--s-build-dxt` command and `--s-with-node-modules` for platform-dependent builds.
 - **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.
@@ -149,6 +244,35 @@ main();
 export default cli;
 ```
 
+### MCP Tool Name Constraints
+
+When using `.addTool()` or `.addMcpTool()`, tool names are automatically sanitized for MCP compatibility. MCP tool names must follow the pattern `^[a-zA-Z0-9_-]{1,64}$` (only alphanumeric characters, underscores, and hyphens, with a maximum length of 64 characters).
+
+```typescript
+// These names will be automatically sanitized:
+cli.addTool({
+  name: "test.tool", // → "test_tool"
+  // ... rest of config
+});
+
+cli.addTool({
+  name: "my@tool", // → "my_tool"
+  // ... rest of config
+});
+
+cli.addTool({
+  name: "tool with spaces", // → "tool_with_spaces"
+  // ... rest of config
+});
+
+cli.addTool({
+  name: "very-long-tool-name-that-exceeds-the-64-character-limit-for-mcp", // → truncated to 64 chars
+  // ... rest of config
+});
+```
+
+The library will warn you when tool names are sanitized, but your tools will continue to work normally. For CLI usage, the original name is preserved as the subcommand name.
+
 ## How to Run It
 
 ```bash
@@ -162,6 +286,18 @@ mycli --s-mcp-serve
 
 # 3. Generate a DXT package for Claude Desktop (2-steps)
 mycli --s-build-dxt ./my-dxt-package
+
+# If you use ML models or packages that include binaries such as Sqlite3 or sharp, etc...
+# You need to bundle the node_modules folder with your DXT package
+# In order to do this, you need to use the following flag:
+# First hard-install all the packages
+rm -rf node_moduels
+pnpm install --prod --node-linker=hoisted
+# Then bundle with node_modules
+mycli --s-build-dxt ./my-dxt-package --s-with-node-modules
+# then packages the dxt
+npx @anthropic-ai/dxt pack ./my-dxt-package
+# then upload the dxt bundle to Claude Desktop from the settings > extensions > advanced screen
 ```
 
 Read more on generating the DXT package here: [Generating DXT Packages](#generating-dxt-packages---s-build-dxt)
@@ -268,7 +404,7 @@ const cli = ArgParser.withMcp({
   handler: async (ctx) => ({ success: true, data: ctx.args }),
 });
 
-// NEW: Call parse() without arguments
+// You can call parse() without arguments
 // Automatically detects Node.js environment and uses process.argv.slice(2)
 async function main() {
   try {
@@ -961,13 +1097,19 @@ my-cli-app --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3001
 # Configure custom log file path for MCP server logs
 my-cli-app --s-mcp-serve --s-mcp-log-path ./custom-logs/mcp-server.log
 
-# Or configure log path programmatically in withMcp()
+# Or configure logging programmatically in withMcp()
 const cli = ArgParser.withMcp({
   appName: 'My CLI App',
   appCommandName: 'my-cli-app',
   mcp: {
     serverInfo: { name: 'my-server', version: '1.0.0' },
-    logPath: './my-logs/mcp-server.log'  // Programmatic log path
+    // NEW: Improved logging with level control
+    log: {
+      level: 'info',        // Captures info, warn, error
+      logToFile: './my-logs/mcp-server.log',
+      prefix: 'MyApp'
+    }
+    // LEGACY: logPath: './my-logs/mcp-server.log'  // Still works
   }
 });
 ```
@@ -989,20 +1131,30 @@ my-tool --s-mcp-serve --s-mcp-transport sse --s-mcp-port 3000 --s-mcp-host 0.0.0
 # Custom log path via CLI flag (logs to specified file instead of ./logs/mcp.log)
 my-tool --s-mcp-serve --s-mcp-log-path /var/log/my-mcp-server.log
 
-# Custom log path via programmatic configuration
+# Improved logging via programmatic configuration
 const parser = ArgParser.withMcp({
   mcp: {
     serverInfo: { name: 'my-tool', version: '1.0.0' },
-    logPath: '/var/log/my-mcp-server.log'
+    log: {
+      level: 'debug',       // Capture all log levels
+      logToFile: '/var/log/my-mcp-server.log',
+      prefix: 'MyTool'
+    }
+    // LEGACY: logPath: '/var/log/my-mcp-server.log'  // Still works
   }
 });
 
-# Multiple transports and custom log path (configured via --s-mcp-serve system flag)
+# Multiple transports and improved logging (configured via --s-mcp-serve system flag)
 const cli = ArgParser.withMcp({
   appName: 'multi-tool',
   appCommandName: 'multi-tool',
   mcp: {
-    logPath: './logs/multi-tool-mcp.log',  // Custom log path
+    // NEW: improved logging configuration
+    log: {
+      level: 'info',
+      logToFile: './logs/multi-tool-mcp.log',
+      prefix: 'MultiTool'
+    },
     serverInfo: {
       name: 'multi-tool-mcp',
       version: '1.0.0'
@@ -1018,13 +1170,91 @@ const cli = ArgParser.withMcp({
 });
 ```
 
-### MCP Log Path Configuration
+### MCP Logging Configuration
+
+MCP server logging can be configured with McpLoggerOptions options using `@alcyone-labs/simple-mcp-logger`. You can control log levels, output destinations, and more.
+
+#### Enhanced Logging (Recommended)
+
+Use the new `log` property for comprehensive logging control:
+
+```typescript
+const parser = ArgParser.withMcp({
+  appName: "My MCP Server",
+  appCommandName: "my-mcp-server",
+  mcp: {
+    serverInfo: { name: "my-server", version: "1.0.0" },
+    log: {
+      level: "debug", // Captures debug, info, warn, error
+      logToFile: "./logs/comprehensive.log",
+      prefix: "MyServer",
+      mcpMode: true, // MCP compliant (default)
+    },
+  },
+});
+```
+
+**Available log levels**: `"debug"` | `"info"` | `"warn"` | `"error"` | `"silent"`
+
+**Type Safety**: The `McpLoggerOptions` type is provided for full TypeScript support and matches the interface from `@alcyone-labs/simple-mcp-logger`.
+
+#### Simple Logging Configuration
+
+For basic use cases, you can use a simple string path:
+
+```typescript
+const parser = ArgParser.withMcp({
+  mcp: {
+    serverInfo: { name: "my-server", version: "1.0.0" },
+    log: "./logs/simple.log", // Simple string path
+  },
+});
+```
 
-MCP server logs can be configured through multiple methods with the following priority order:
+#### Configuration Priority
+
+Logging configuration follows this priority order:
 
 1. **CLI Flag (Highest Priority)**: `--s-mcp-log-path <path>`
-2. **Programmatic Configuration**: `mcp.logPath` in `withMcp()`
-3. **Default Path (Fallback)**: `./logs/mcp.log`
+2. **Merging**: When both `mcp.log` and `mcp.logPath` are present:
+   - `mcp.log` provides logger options (level, prefix, mcpMode)
+   - `mcp.logPath` provides flexible path resolution (relativeTo, basePath)
+   - Path resolution: `mcp.logPath` > `mcp.log.logToFile`
+3. **Log Config Only**: `mcp.log` object or string in `withMcp()`
+4. **Legacy Log Path Only**: `mcp.logPath` in `withMcp()`
+5. **Default Path (Fallback)**: `./logs/mcp.log`
+
+#### Configuration Merging
+
+When both `log` and `logPath` are specified:
+
+```typescript
+const parser = ArgParser.withMcp({
+  mcp: {
+    serverInfo: { name: "my-server", version: "1.0.0" },
+    // log provides logger options (level, prefix, mcpMode)
+    log: {
+      level: "debug",
+      prefix: "MyServer",
+      mcpMode: true,
+      // logToFile can be omitted when using logPath
+    },
+    // logPath provides flexible path resolution
+    logPath: {
+      path: "./logs/app.log",
+      relativeTo: "entry", // "entry" | "cwd" | "absolute"
+      basePath: "/custom/base", // Optional custom base path
+    },
+  },
+});
+```
+
+**Merging behavior:**
+
+- `log` provides logger configuration (level, prefix, mcpMode)
+- `logPath` provides flexible path resolution with `relativeTo` options
+- If both specify a file path, `logPath` takes precedence for path resolution
+- This preserves the powerful `LogPath` features while using `McpLoggerOptions` for logger settings
 
 #### Path Resolution Options
 
@@ -1043,7 +1273,7 @@ const parser = ArgParser.withMcp({
   },
 });
 
-// Object configuration for advanced use cases
+// Object configuration for more granular use cases
 const parser = ArgParser.withMcp({
   // ... other config
   mcp: {
@@ -1062,6 +1292,143 @@ const parser = ArgParser.withMcp({
 
 The CLI flag always takes precedence, allowing users to override the developer's programmatic configuration when needed. By default, relative paths resolve relative to the application's entry point, making logs predictably located near DXT packages.
 
+### MCP Resources - Real-Time Data Feeds
+
+MCP Resources enable your CLI tools to provide **real-time, subscription-based data feeds** to AI assistants. Unlike tools (which are called once), resources can be subscribed to and provide live updates when data changes.
+
+**Key Benefits:**
+
+- **Real-time notifications**: AI assistants get notified when your data changes
+- **Flexible URI templates**: Support dynamic parameters like `data://alerts/aged/gte:{threshold}`
+- **Standard MCP pattern**: Full subscription lifecycle support
+- **Zero CLI impact**: Resources only work in MCP mode, CLI usage unchanged
+
+#### Basic Resource Setup
+
+```typescript
+const parser = ArgParser.withMcp({
+  appName: "Data Monitor",
+  appCommandName: "data-monitor",
+  mcp: {
+    serverInfo: { name: "data-monitor", version: "1.0.0" },
+  },
+}).addMcpResource({
+  name: "recent-data",
+  uriTemplate: "data://recent",
+  title: "Recent Data",
+  description: "Get the most recent data entries",
+  mimeType: "application/json",
+  handler: async (uri) => {
+    const recentData = await getRecentData();
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify(recentData, null, 2),
+          mimeType: "application/json",
+        },
+      ],
+    };
+  },
+});
+```
+
+#### URI Templates with Dynamic Parameters
+
+Create flexible resources that accept parameters:
+
+```typescript
+.addMcpResource({
+  name: "aged-data-alert",
+  uriTemplate: "data://alerts/aged/gte:{threshold}",
+  title: "Aged Data Alert",
+  description: "Monitor data that has aged past a threshold (in milliseconds)",
+  handler: async (uri, { threshold }) => {
+    const thresholdMs = parseInt(threshold);
+    const agedData = await getDataOlderThan(new Date(Date.now() - thresholdMs));
+
+    return {
+      contents: [{
+        uri: uri.href,
+        text: JSON.stringify({
+          threshold_ms: thresholdMs,
+          query_time: new Date().toISOString(),
+          aged_data: agedData,
+          count: agedData.length
+        }, null, 2),
+        mimeType: "application/json"
+      }]
+    };
+  }
+});
+```
+
+#### MCP Subscription Lifecycle
+
+Resources support the full MCP subscription pattern:
+
+1. **Client subscribes**: `resources/subscribe` → `"data://alerts/aged/gte:10000"`
+2. **Server monitors**: Your application detects data changes
+3. **Server notifies**: `notifications/resources/updated` sent to subscribed clients
+4. **Client reads fresh data**: `resources/read` → `"data://alerts/aged/gte:10000"`
+5. **Client unsubscribes**: `resources/unsubscribe` when done
+
+#### Usage Examples
+
+**AI Assistant Integration:**
+
+```typescript
+// AI assistant can subscribe to real-time data
+await client.request("resources/subscribe", {
+  uri: "data://alerts/aged/gte:60000", // 1 minute threshold
+});
+
+// Handle notifications
+client.on("notifications/resources/updated", async (notification) => {
+  const response = await client.request("resources/read", {
+    uri: notification.uri,
+  });
+  console.log("Fresh data:", JSON.parse(response.contents[0].text));
+});
+```
+
+**Command Line Testing:**
+
+```bash
+# Start MCP server
+data-monitor --s-mcp-serve
+
+# Test resource (in another terminal)
+echo '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"data://alerts/aged/gte:10000"}}' | data-monitor --s-mcp-serve
+```
+
+#### Design Patterns
+
+**Static Resources**: Use simple URIs for data that changes content but not structure
+
+```typescript
+uriTemplate: "logs://recent"; // Always available, content updates
+uriTemplate: "status://system"; // System status, updates in real-time
+```
+
+**Parameterized Resources**: Use URI templates for flexible filtering
+
+```typescript
+uriTemplate: "data://type/{type}"; // Filter by type
+uriTemplate: "alerts/{severity}/gte:{age}"; // Multiple parameters
+uriTemplate: "search/{query}/limit:{count}"; // Search with limits
+```
+
+**Time-Based Resources**: Perfect for monitoring and alerting
+
+```typescript
+uriTemplate: "events/since:{timestamp}"; // Events since timestamp
+uriTemplate: "metrics/aged/gte:{threshold}"; // Metrics past threshold
+uriTemplate: "logs/errors/last:{duration}"; // Recent errors
+```
+
+> **💡 Pro Tip**: Resources are perfect for monitoring, alerting, and real-time data feeds. They complement tools (one-time actions) by providing continuous data streams that AI assistants can subscribe to.
+
 ### Automatic Console Safety
 
 A major challenge in MCP is preventing `console.log` from corrupting the JSON-RPC communication over `STDOUT`. ArgParser solves this automatically.
@@ -1082,12 +1449,26 @@ my-cli-app --s-build-dxt ./my-dxt-package
 # A default logo will be applied if you don't provide one.
 
 # 2. (Optional) Pack the folder into a .dxt file for distribution
+# (you can install the unpacked folder) directly in Claude Desktop > Settings > Extensions > Advanced
 npx @anthropic-ai/dxt pack ./my-dxt-package
 
-# 3. (Optional) Sign the DXT package
+# 3. (Optional) Sign the DXT package - this has not been well tested yet
 npx @anthropic-ai/dxt sign ./my-dxt-package.dxt
 
 # Then drag & drop the .dxt file into Claude Desktop to install it, in the Settings > Extensions screen.
+
+# **IMPORTANT**:
+# If you use ML models or packages that include binaries such as Sqlite3 or sharp, etc...
+# You need to bundle the node_modules folder with your DXT package
+# In order to do this, you need to use the following flag:
+# First hard-install all the packages
+rm -rf node_moduels
+pnpm install --prod --linker hoisted
+# Then bundle with node_modules
+mycli --s-build-dxt ./my-dxt-package --s-with-node-modules
+# then build the dxt bundle
+npx @anthropic-ai/dxt pack ./my-dxt-package
+# then upload the dxt bundle to Claude Desktop from the settings > extensions > advanced
 ```
 
 ### Logo Configuration
@@ -1130,6 +1511,62 @@ logo: "https://example.com/logo.png"; // Downloaded automatically
 logo: "https://cdn.example.com/icon.svg";
 ```
 
+### Including Additional Files in DXT Packages
+
+You can include additional files and directories in your DXT package using the `dxt.include` configuration. This is useful for bundling database migrations, configuration files, assets, or any other files your MCP server needs at runtime.
+
+```typescript
+const cli = ArgParser.withMcp({
+  appName: "My CLI",
+  appCommandName: "mycli",
+  mcp: {
+    serverInfo: {
+      name: "my-mcp-server",
+      version: "1.0.0",
+      description: "My CLI as an MCP server",
+    },
+    dxt: {
+      include: [
+        "migrations", // Copy entire migrations folder
+        "config/production.json", // Copy specific file
+        { from: "assets/logo.png", to: "logo.png" }, // Copy and rename file
+        { from: "scripts", to: "bin" }, // Copy folder with new name
+      ],
+    },
+  },
+});
+```
+
+#### Include Options
+
+**Simple string paths** - Copy files/directories to the same relative location:
+
+```typescript
+include: [
+  "migrations", // Copies ./migrations/ to dxt/migrations/
+  "config/default.json", // Copies ./config/default.json to dxt/config/default.json
+];
+```
+
+**Object mapping** - Copy with custom destination paths:
+
+```typescript
+include: [
+  { from: "config/prod.json", to: "config.json" }, // Rename during copy
+  { from: "database/schema", to: "db/schema" }, // Copy to different path
+];
+```
+
+**Path Resolution**: All paths in the `from` field are resolved relative to your project root (where `package.json` and `tsconfig.json` are located).
+
+**Example Use Cases**:
+
+- Database migration files for initialization
+- Configuration templates or defaults
+- Static assets like images or documents
+- Scripts or utilities needed at runtime
+- Documentation or help files
+
 ### How DXT Generation Works
 
 When you run `--s-build-dxt`, ArgParser performs several steps to create a self-contained, autonomous package:
@@ -1138,37 +1575,145 @@ When you run `--s-build-dxt`, ArgParser performs several steps to create a self-
 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.
+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. If you have properly setup your node_modules (via `pnpm install --prod --node-linker=hoisted`) and pass `--s-with-node-nodules` to the bundling process, the resulting DXT will include all necessary dependencies, this is useful for projects that require native dependencies or have complex dependency trees.
 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`.
 
+### DXT Bundling Strategies
+
+ArgParser offers two approaches for handling dependencies in DXT packages, depending on your project's needs.
+
+#### Standard Approach (Recommended for Most Projects)
+
+```bash
+# For pure JavaScript/TypeScript projects
+your-cli --s-build-dxt
+```
+
+- **Best for**: Pure JS/TS projects without native dependencies
+- **Bundle size**: Small (5-10MB typical)
+- **Build time**: Fast
+- **Dependencies**: Bundled automatically by TSDown
+
+#### Native Dependencies Approach
+
+```bash
+# For projects with native binaries (ONNX, Sharp, SQLite, etc.)
+rm -rf node_modules
+pnpm install --prod --node-linker=hoisted
+your-cli --s-build-dxt --s-with-node-modules
+```
+
+- **Best for**: Projects using ONNX Runtime, Sharp, Canvas, SQLite, or other packages with `.node` binaries
+- **Bundle size**: Larger (50-200MB typical)
+- **Build time**: Longer (copies entire node_modules)
+- **Dependencies**: Complete autonomy - no installation needed by Claude
+
+**When to use `--s-with-node-modules`:**
+
+- ✅ Your project uses machine learning packages (ONNX Runtime, TensorFlow bindings)
+- ✅ You need image processing (Sharp, Canvas)
+- ✅ You use database packages with native binaries (better-sqlite3, sqlite3)
+- ✅ You want guaranteed compatibility without runtime installation
+- ✅ Bundle size is acceptable for your use case
+
+**Required preparation steps:**
+
+1. `rm -rf node_modules` - Clean slate for proper structure
+2. `pnpm install --prod --node-linker=hoisted` - Creates flat, symlink-free structure
+3. Add `--s-with-node-modules` flag to your build command
+
+The system automatically validates your setup and provides guidance if issues are detected.
+
+### Typical Errors
+
+**Failed to run in Claude Desktop**:
+
+Claude Desktop is pretty finicky (as of Claude 0.12.28), and the built-in Node.js does not work with extensions built with `--s-with-node-modules` and installed via ArgParser (and I have no idea why because there's no debug info).
+To resolve this, simply go to `Claude Desktop > Settings > Extensions > Advanced Settings` and turn **OFF** `Use Built-in Node.js for MCP`.
+
+Note that there are _many_ reasons for extensions not to work, if it does not work with Built-in or System Node.js, then something in your app is wrong. Feel free to join Alcyone Labs' discord for support: [Alcyone Labs' Discord](https://discord.gg/rRHhpz5nS5)
+
+**Failed to attach to MCP when downloading external assets**
+
+Sometimes, the MCP client needs to install external files, for example an ML model from HuggingFace or some task that takes more than 10 seconds to run. While it's working, Claude Desktop will display a `Cannot attach to MCP`, simply ignore it, Claude Desktop runs a ping every X seconds, and when it is running a long-running task, the ping will fail, but the task itself will still finish correctly.
+
+**Failed to generate DXT package**:
+
+If you encounter the following error running a command such as:
+
+```bash
+rm -rf node_modules
+pnpm install --prod --node-linker=hoisted
+bun src/index.ts --s-build-dxt ./dxt --s-with-node-modules
+
+-- Error generating DXT package: TSDown DXT build failed: EEXIST: file already exists, mkdir
+```
+
+Then run:
+
+```bash
+rm -rf ./dxt
+bun src/index.ts --s-build-dxt ./dxt --s-with-node-modules
+```
+
+And it should work. TSDown is tasked to clean the outputDir first, but it won't if some files have been manually changed.
+
 ---
 
 ## 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 in the specified directory.         |
-| `--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.                                                    |
-| `--s-mcp-log-path <path>`   | Sets the file path for MCP server logs (default: `./logs/mcp.log`). Overrides programmatic setting. |
-| **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.                  |
+| 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 in the specified directory.                    |
+| `--s-with-node-modules`     | Use with `--s-build-dxt`. Includes complete node_modules in DXT package for projects with native dependencies. |
+| `--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.                                                               |
+| `--s-mcp-log-path <path>`   | Sets the file path for MCP server logs (default: `./logs/mcp.log`). Overrides programmatic setting.            |
+| **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.                             |
 
 ---
 
 ## Changelog
 
+### v2.4.0
+
+**Feat**
+
+- MCP client now supports initialization during the client 'initialize' call, which allows to do certain things such as establishing database connection or even running migrations
+- MCP client now sanitizes the method names to ensure spec-compliants MCP behavior, names that collision will be logged
+- There were some use-cases where the DXT bundling failed, this new release addresses all of them, namely:
+  1. Output structure will match that of the input so relative files (for example DB migrations) will work
+  2.
+- DXT bundling now supports including resources via options: `{dxt: {include: ['TSDown blob-like paths']}`
+- Logger was improved to support log level via `options:{ log: {} }` so you can set it to level: 'debug' and the MCP log will contain 100% of the console output, logPath setting was not impacted
+
+**Fixes and Changes**
+
+- Zod has been upgraded to V4 and no issue was identified (but @modelcontextprotocol/sdk had to be upgraded to V4 as well, which was more challenging).
+
+### v2.3.0
+
+The DXT bundling is working pretty well now, and we have had a lot of success building, bundling and running various extensions. If you see issues, feel free to open an Issue on GitHub with details, or ask about it on [Alcyone Labs' Discord](https://discord.gg/rRHhpz5nS5)
+
+Make sure to clearly identify if you need to include the node_modules or not. In doubt, include them using `--s-with-node-modules`
+
+**Feat**
+
+- **New `--s-with-node-modules` flag**: Create fully autonomous DXT packages that include complete native dependencies. Perfect for projects using ONNX Runtime, Sharp, SQLite, or other packages with `.node` binaries. Use `rm -rf ./node_modules && pnpm install --prod --node-linker=hoisted` followed by `my-cli --s-build-dxt ./dxt --s-with-node-modules` to create self-contained packages that work without Claude needing to install dependencies.
+  Note that when bundling with node_modules, it's likely that the built-in Node.js will not work with that extension, so go to `Claude Desktop > Settings > Extensions > Advanced Settings` and turn **OFF** `Use Built-in Node.js for MCP`.
+
 ### v2.2.1
 
 **Feat**
@@ -1241,11 +1786,11 @@ ArgParser includes built-in `--s-*` flags for development, debugging, and config
 - [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)
 - [x] Add support for async type function to enable more flexibility
+- [x] Upgrade to Zod/V4 (V4 does not support functions well, this will take more time, not a priority)
 - [ ] Add System flags to args.systemArgs
 - [ ] Improve flag options collision prevention
 - [ ] Add support for locales / translations
 - [ ] (potentially) add support for fully typed parsed output, this has proven very challenging
-- [ ] Upgrade to Zod/V4 (V4 does not support functions well, this will take more time, not a priority)
 
 ### (known) Bugs / DX improvement points