@wonderwhy-er/desktop-commander 0.2.13 → 0.2.15

package/README.md

@@ -86,6 +86,11 @@ For debugging mode (allows Node.js inspector connection):
 ```
 npx @wonderwhy-er/desktop-commander@latest setup --debug
 ```
+
+**Command line options during setup:**
+- `--debug`: Enable debugging mode for Node.js inspector
+- `--no-onboarding`: Disable onboarding prompts for new users
+
 Restart Claude if running.
 
 **✅ Auto-Updates:** Yes - automatically updates when you restart Claude  
@@ -652,6 +657,44 @@ set_config_value({ "key": "fileWriteLineLimit", "value": 25 })
 
 4. **Always verify configuration after changes**: Use `get_config({})` to confirm your changes were applied correctly.
 
+## Command Line Options
+
+Desktop Commander supports several command line options for customizing behavior:
+
+### Disable Onboarding
+
+By default, Desktop Commander shows helpful onboarding prompts to new users (those with fewer than 10 tool calls). You can disable this behavior:
+
+```bash
+# Disable onboarding for this session
+node dist/index.js --no-onboarding
+
+# Or if using npm scripts
+npm run start:no-onboarding
+
+# For npx installations, modify your claude_desktop_config.json:
+{
+  "mcpServers": {
+    "desktop-commander": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@wonderwhy-er/desktop-commander@latest",
+        "--no-onboarding"
+      ]
+    }
+  }
+}
+```
+
+**When onboarding is automatically disabled:**
+- When the MCP client name is set to "desktop-commander"
+- When using the `--no-onboarding` flag
+- After users have used onboarding prompts or made 10+ tool calls
+
+**Debug information:**
+The server will log when onboarding is disabled: `"Onboarding disabled via --no-onboarding flag"`
+
 ## Using Different Shells
 
 You can specify which shell to use for command execution:

package/dist/custom-stdio.js

@@ -22,14 +22,16 @@ export class FilteredStdioServerTransport extends StdioServerTransport {
         this.setupConsoleRedirection();
         // Setup stdout filtering for any other output
         this.setupStdoutFiltering();
-        // Send initialization notification
-        this.sendLogNotification('info', ['Enhanced FilteredStdioServerTransport initialized']);
+        // Note: We defer the initialization notification until enableNotifications() is called
+        // to ensure MCP protocol compliance - notifications must not be sent before initialization
     }
     /**
      * Call this method after MCP initialization is complete to enable JSON-RPC notifications
      */
     enableNotifications() {
         this.isInitialized = true;
+        // Send the deferred initialization notification first
+        this.sendLogNotification('info', ['Enhanced FilteredStdioServerTransport initialized']);
         // Replay all buffered messages in chronological order
         if (this.messageBuffer.length > 0) {
             this.sendLogNotification('info', [`Replaying ${this.messageBuffer.length} buffered initialization messages`]);

package/dist/handlers/search-handlers.js

@@ -24,6 +24,7 @@ export async function handleStartSearch(args) {
             contextLines: parsed.data.contextLines,
             timeout: parsed.data.timeout_ms,
             earlyTermination: parsed.data.earlyTermination,
+            literalSearch: parsed.data.literalSearch,
         });
         const searchTypeText = parsed.data.searchType === 'content' ? 'content search' : 'file search';
         let output = `Started ${searchTypeText} session: ${result.sessionId}\n`;

package/dist/index-oauth.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index-oauth.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { FilteredStdioServerTransport } from './custom-stdio.js';
+import { server } from './server.js';
+import { configManager } from './config-manager.js';
+import { runSetup } from './npm-scripts/setup.js';
+import { runUninstall } from './npm-scripts/uninstall.js';
+import { capture } from './utils/capture.js';
+import { logToStderr, logger } from './utils/logger.js';
+import { OAuthHttpServer } from './oauth/server.js';
+async function runServer() {
+    try {
+        // Check if first argument is "setup"
+        if (process.argv[2] === 'setup') {
+            await runSetup();
+            return;
+        }
+        // Check if first argument is "remove"
+        if (process.argv[2] === 'remove') {
+            await runUninstall();
+            return;
+        }
+        // Check for HTTP mode with OAuth
+        const httpMode = process.argv.includes('--http') || process.argv.includes('--oauth');
+        const port = getPortFromArgs() || 8000;
+        if (httpMode) {
+            await runHttpServer(port);
+        }
+        else {
+            await runStdioServer();
+        }
+    }
+    catch (error) {
+        logger.error('Failed to start server:', error);
+        process.exit(1);
+    }
+}
+async function runStdioServer() {
+    logger.info('Loading server.ts');
+    logger.info('Setting up request handlers...');
+    try {
+        logger.info('Loading configuration...');
+        await configManager.loadConfig();
+        logger.info('Configuration loaded successfully');
+        const transport = new FilteredStdioServerTransport();
+        logger.info('Enhanced FilteredStdioServerTransport initialized');
+        logger.info('Connecting server...');
+        await server.connect(transport);
+        logger.info('Server connected successfully');
+    }
+    catch (error) {
+        await capture('error_start_stdio_server', { error });
+        logToStderr('error', `Failed to start stdio server: ${error}`);
+        throw error;
+    }
+}
+async function runHttpServer(port) {
+    logger.info(`Starting HTTP server with OAuth on port ${port}`);
+    try {
+        logger.info('Loading configuration...');
+        await configManager.loadConfig();
+        logger.info('Configuration loaded successfully');
+        // OAuth configuration
+        const baseUrl = `http://localhost:${port}`;
+        const oauthConfig = {
+            enabled: true,
+            clientId: 'desktop-commander-mcp',
+            clientSecret: 'dc-secret-' + Math.random().toString(36).substring(7),
+            redirectUri: `${baseUrl}/callback`,
+            authorizationUrl: `${baseUrl}/authorize`,
+            tokenUrl: `${baseUrl}/token`,
+            scope: 'mcp:access mcp:tools mcp:resources',
+            issuer: baseUrl
+        };
+        // Create MCP handler for HTTP requests
+        const mcpHandler = createMcpHttpHandler();
+        // Create OAuth HTTP server
+        const oauthServer = new OAuthHttpServer(oauthConfig, mcpHandler);
+        oauthServer.listen(port, () => {
+            logger.info(`HTTP server running on port ${port}`);
+            logger.info(`Authorization Server Metadata: ${baseUrl}/.well-known/oauth-authorization-server`);
+            logger.info(`MCP Endpoint: ${baseUrl}/mcp`);
+            logger.info(`SSE Endpoint: ${baseUrl}/sse`);
+            console.log(`\n🚀 DesktopCommanderMCP HTTP Server Started!`);
+            console.log(`📍 Server URL: ${baseUrl}`);
+            console.log(`🔐 OAuth Metadata: ${baseUrl}/.well-known/oauth-authorization-server`);
+            console.log(`🔧 MCP Endpoint: ${baseUrl}/mcp`);
+            console.log(`⚡ SSE Endpoint: ${baseUrl}/sse`);
+            console.log(`\n📝 For Claude Custom Connectors:`);
+            console.log(`   URL: ${baseUrl}/sse`);
+            console.log(`   Authentication: OAuth`);
+        });
+        // Graceful shutdown
+        process.on('SIGINT', () => {
+            logger.info('Received SIGINT, shutting down gracefully...');
+            oauthServer.close(() => {
+                process.exit(0);
+            });
+        });
+    }
+    catch (error) {
+        await capture('error_start_http_server', { error });
+        logToStderr('error', `Failed to start HTTP server: ${error}`);
+        throw error;
+    }
+}
+function createMcpHttpHandler() {
+    return (req, res) => {
+        const url = new URL(req.url, `http://${req.headers.host}`);
+        // Handle SSE endpoint for MCP clients
+        if (url.pathname === '/sse') {
+            handleSSE(req, res);
+            return;
+        }
+        // Handle Streamable HTTP endpoint  
+        if (url.pathname === '/mcp') {
+            handleStreamableHttp(req, res);
+            return;
+        }
+        // Health check
+        if (url.pathname === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', service: 'DesktopCommanderMCP' }));
+            return;
+        }
+        // 404 for other paths
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+    };
+}
+function handleSSE(req, res) {
+    // Set SSE headers
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Headers': 'Cache-Control'
+    });
+    // SSE implementation would go here
+    // For now, just indicate that SSE is available
+    res.write('event: connected\n');
+    res.write('data: {"type":"connected","message":"DesktopCommanderMCP SSE endpoint"}\n\n');
+    // Keep connection alive
+    const heartbeat = setInterval(() => {
+        res.write('event: heartbeat\n');
+        res.write('data: {"type":"heartbeat","timestamp":' + Date.now() + '}\n\n');
+    }, 30000);
+    req.on('close', () => {
+        clearInterval(heartbeat);
+    });
+}
+function handleStreamableHttp(req, res) {
+    // Handle Streamable HTTP for MCP
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    if (req.method === 'GET') {
+        // Return server info
+        res.end(JSON.stringify({
+            name: 'DesktopCommanderMCP',
+            version: '0.2.13',
+            transport: 'streamable-http',
+            authenticated: !!req.user
+        }));
+        return;
+    }
+    // Handle MCP protocol messages
+    if (req.method === 'POST') {
+        let body = '';
+        req.on('data', chunk => body += chunk.toString());
+        req.on('end', () => {
+            try {
+                const message = JSON.parse(body);
+                // Process MCP message through the server
+                // This would need to be integrated with the existing MCP server
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: message.id,
+                    result: { message: 'MCP message received' }
+                }));
+            }
+            catch (error) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            }
+        });
+        return;
+    }
+    res.writeHead(405, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Method not allowed' }));
+}
+function getPortFromArgs() {
+    const portIndex = process.argv.findIndex(arg => arg === '--port');
+    if (portIndex !== -1 && process.argv[portIndex + 1]) {
+        return parseInt(process.argv[portIndex + 1], 10);
+    }
+    return null;
+}
+// Run the server
+runServer().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/index.js

@@ -1,11 +1,16 @@
 #!/usr/bin/env node
 import { FilteredStdioServerTransport } from './custom-stdio.js';
-import { server } from './server.js';
+import { server, flushDeferredMessages } from './server.js';
 import { configManager } from './config-manager.js';
 import { runSetup } from './npm-scripts/setup.js';
 import { runUninstall } from './npm-scripts/uninstall.js';
 import { capture } from './utils/capture.js';
 import { logToStderr, logger } from './utils/logger.js';
+// Store messages to defer until after initialization
+const deferredMessages = [];
+function deferLog(level, message) {
+    deferredMessages.push({ level, message });
+}
 async function runServer() {
     try {
         // Check if first argument is "setup"
@@ -18,17 +23,24 @@ async function runServer() {
             await runUninstall();
             return;
         }
+        // Parse command line arguments for onboarding control
+        const DISABLE_ONBOARDING = process.argv.includes('--no-onboarding');
+        if (DISABLE_ONBOARDING) {
+            logToStderr('info', 'Onboarding disabled via --no-onboarding flag');
+        }
+        // Set global flag for onboarding control
+        global.disableOnboarding = DISABLE_ONBOARDING;
         try {
-            logToStderr('info', 'Loading configuration...');
+            deferLog('info', 'Loading configuration...');
             await configManager.loadConfig();
-            logToStderr('info', 'Configuration loaded successfully');
+            deferLog('info', 'Configuration loaded successfully');
         }
         catch (configError) {
-            logToStderr('error', `Failed to load configuration: ${configError instanceof Error ? configError.message : String(configError)}`);
+            deferLog('error', `Failed to load configuration: ${configError instanceof Error ? configError.message : String(configError)}`);
             if (configError instanceof Error && configError.stack) {
-                logToStderr('debug', `Stack trace: ${configError.stack}`);
+                deferLog('debug', `Stack trace: ${configError.stack}`);
             }
-            logToStderr('warning', 'Continuing with in-memory configuration only');
+            deferLog('warning', 'Continuing with in-memory configuration only');
             // Continue anyway - we'll use an in-memory config
         }
         const transport = new FilteredStdioServerTransport();
@@ -63,17 +75,23 @@ async function runServer() {
             process.exit(1);
         });
         capture('run_server_start');
-        logToStderr('info', 'Connecting server...');
+        deferLog('info', 'Connecting server...');
         // Set up event-driven initialization completion handler
         server.oninitialized = () => {
             // This callback is triggered after the client sends the "initialized" notification
             // At this point, the MCP protocol handshake is fully complete
             transport.enableNotifications();
-            // Use the transport to send a proper JSON-RPC notification
-            transport.sendLog('info', 'MCP fully initialized, notifications enabled');
+            // Flush all deferred messages from both index.ts and server.ts
+            while (deferredMessages.length > 0) {
+                const msg = deferredMessages.shift();
+                transport.sendLog('info', msg.message);
+            }
+            flushDeferredMessages();
+            // Now we can send regular logging messages
+            transport.sendLog('info', 'Server connected successfully');
+            transport.sendLog('info', 'MCP fully initialized, all startup messages sent');
         };
         await server.connect(transport);
-        logToStderr('info', 'Server connected successfully');
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/oauth/provider.d.ts

@@ -0,0 +1,22 @@
+import type { OAuthConfig, AuthorizationServerMetadata, TokenResponse, AccessToken, AuthorizationRequest, TokenRequest } from './types.js';
+export declare class OAuthProvider {
+    private config;
+    private users;
+    private authCodes;
+    private accessTokens;
+    constructor(config: OAuthConfig);
+    static generatePKCE(): {
+        codeVerifier: string;
+        codeChallenge: string;
+    };
+    getAuthorizationServerMetadata(): AuthorizationServerMetadata;
+    handleAuthorizationRequest(params: AuthorizationRequest): {
+        authUrl: string;
+        authCode?: string;
+        error?: string;
+    };
+    handleTokenRequest(params: TokenRequest): Promise<TokenResponse | {
+        error: string;
+    }>;
+    validateAccessToken(token: string): AccessToken | null;
+}

package/dist/oauth/provider.js

@@ -0,0 +1,124 @@
+import crypto from 'crypto';
+export class OAuthProvider {
+    constructor(config) {
+        this.users = new Map();
+        this.authCodes = new Map();
+        this.accessTokens = new Map();
+        this.config = config;
+        // Add a default user for testing
+        this.users.set('admin', {
+            email: 'admin@localhost',
+            password: 'admin123' // In production, hash this!
+        });
+    }
+    // Generate PKCE code verifier and challenge
+    static generatePKCE() {
+        const codeVerifier = crypto.randomBytes(32).toString('base64url');
+        const codeChallenge = crypto
+            .createHash('sha256')
+            .update(codeVerifier)
+            .digest('base64url');
+        return { codeVerifier, codeChallenge };
+    }
+    // Get Authorization Server Metadata (required by MCP spec)
+    getAuthorizationServerMetadata() {
+        const baseUrl = this.config.issuer;
+        return {
+            issuer: baseUrl,
+            authorization_endpoint: `${baseUrl}/authorize`,
+            token_endpoint: `${baseUrl}/token`,
+            registration_endpoint: `${baseUrl}/register`,
+            revocation_endpoint: `${baseUrl}/revoke`,
+            jwks_uri: `${baseUrl}/.well-known/jwks.json`,
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            token_endpoint_auth_methods_supported: ['none', 'client_secret_basic'],
+            code_challenge_methods_supported: ['S256'],
+            scopes_supported: ['mcp:access', 'mcp:tools', 'mcp:resources']
+        };
+    }
+    // Handle authorization request
+    handleAuthorizationRequest(params) {
+        if (!params.client_id || !params.redirect_uri || !params.code_challenge) {
+            return { authUrl: '', error: 'Missing required parameters' };
+        }
+        if (params.code_challenge_method !== 'S256') {
+            return { authUrl: '', error: 'Unsupported code_challenge_method' };
+        }
+        // Generate authorization code
+        const authCode = crypto.randomBytes(32).toString('hex');
+        const expiresAt = Date.now() + 10 * 60 * 1000; // 10 minutes
+        // Store authorization code
+        this.authCodes.set(authCode, {
+            userId: 'admin', // For simplicity, auto-approve for admin user
+            clientId: params.client_id,
+            redirectUri: params.redirect_uri,
+            scope: params.scope || 'mcp:access',
+            codeChallenge: params.code_challenge,
+            codeChallengeMethod: params.code_challenge_method,
+            expiresAt
+        });
+        // Build redirect URL with auth code
+        const redirectUrl = new URL(params.redirect_uri);
+        redirectUrl.searchParams.set('code', authCode);
+        if (params.state) {
+            redirectUrl.searchParams.set('state', params.state);
+        }
+        return { authUrl: redirectUrl.toString(), authCode };
+    }
+    // Exchange authorization code for access token
+    async handleTokenRequest(params) {
+        const authCodeData = this.authCodes.get(params.code);
+        if (!authCodeData) {
+            return { error: 'Invalid authorization code' };
+        }
+        if (Date.now() > authCodeData.expiresAt) {
+            this.authCodes.delete(params.code);
+            return { error: 'Authorization code expired' };
+        }
+        // Verify PKCE
+        const computedChallenge = crypto
+            .createHash('sha256')
+            .update(params.code_verifier)
+            .digest('base64url');
+        if (computedChallenge !== authCodeData.codeChallenge) {
+            return { error: 'Invalid code_verifier' };
+        }
+        // Verify client and redirect URI
+        if (params.client_id !== authCodeData.clientId ||
+            params.redirect_uri !== authCodeData.redirectUri) {
+            return { error: 'Invalid client_id or redirect_uri' };
+        }
+        // Generate access token
+        const accessToken = crypto.randomBytes(32).toString('hex');
+        const expiresIn = 3600; // 1 hour
+        const tokenData = {
+            sub: authCodeData.userId,
+            aud: params.client_id,
+            iss: this.config.issuer,
+            exp: Math.floor(Date.now() / 1000) + expiresIn,
+            iat: Math.floor(Date.now() / 1000),
+            scope: authCodeData.scope
+        };
+        this.accessTokens.set(accessToken, tokenData);
+        this.authCodes.delete(params.code);
+        return {
+            access_token: accessToken,
+            token_type: 'Bearer',
+            expires_in: expiresIn,
+            scope: authCodeData.scope
+        };
+    }
+    // Validate access token
+    validateAccessToken(token) {
+        const tokenData = this.accessTokens.get(token);
+        if (!tokenData) {
+            return null;
+        }
+        if (Date.now() / 1000 > tokenData.exp) {
+            this.accessTokens.delete(token);
+            return null;
+        }
+        return tokenData;
+    }
+}

package/dist/oauth/server.d.ts

@@ -0,0 +1,18 @@
+import http from 'http';
+import type { OAuthConfig } from './types.js';
+export declare class OAuthHttpServer {
+    private server;
+    private oauthProvider;
+    private mcpHandler;
+    constructor(config: OAuthConfig, mcpHandler: (req: http.IncomingMessage, res: http.ServerResponse) => void);
+    private handleRequest;
+    private setCorsHeaders;
+    private handleAuthServerMetadata;
+    private handleAuthorize;
+    private handleToken;
+    private handleCallback;
+    private sendUnauthorized;
+    private getRequestBody;
+    listen(port: number, callback?: () => void): void;
+    close(callback?: () => void): void;
+}

package/dist/oauth/server.js

@@ -0,0 +1,160 @@
+import http from 'http';
+import { URL } from 'url';
+import { OAuthProvider } from './provider.js';
+export class OAuthHttpServer {
+    constructor(config, mcpHandler) {
+        this.oauthProvider = new OAuthProvider(config);
+        this.mcpHandler = mcpHandler;
+        this.server = http.createServer(this.handleRequest.bind(this));
+    }
+    async handleRequest(req, res) {
+        const url = new URL(req.url, `http://${req.headers.host}`);
+        // Enable CORS
+        this.setCorsHeaders(res);
+        if (req.method === 'OPTIONS') {
+            res.writeHead(200);
+            res.end();
+            return;
+        }
+        try {
+            // OAuth endpoints
+            if (url.pathname === '/.well-known/oauth-authorization-server') {
+                return this.handleAuthServerMetadata(res);
+            }
+            if (url.pathname === '/authorize') {
+                return this.handleAuthorize(url, res);
+            }
+            if (url.pathname === '/token' && req.method === 'POST') {
+                return this.handleToken(req, res);
+            }
+            if (url.pathname === '/callback') {
+                return this.handleCallback(url, res);
+            }
+            // Protected MCP endpoints - require authentication
+            if (url.pathname.startsWith('/mcp') || url.pathname === '/sse') {
+                const authHeader = req.headers.authorization;
+                if (!authHeader || !authHeader.startsWith('Bearer ')) {
+                    return this.sendUnauthorized(res);
+                }
+                const token = authHeader.substring(7);
+                const tokenData = this.oauthProvider.validateAccessToken(token);
+                if (!tokenData) {
+                    return this.sendUnauthorized(res);
+                }
+                // Add user info to request for MCP handler
+                req.user = tokenData;
+            }
+            // Forward to MCP handler
+            this.mcpHandler(req, res);
+        }
+        catch (error) {
+            console.error('OAuth server error:', error);
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Internal server error' }));
+        }
+    }
+    setCorsHeaders(res) {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        res.setHeader('Access-Control-Expose-Headers', 'WWW-Authenticate');
+    }
+    handleAuthServerMetadata(res) {
+        const metadata = this.oauthProvider.getAuthorizationServerMetadata();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(metadata, null, 2));
+    }
+    handleAuthorize(url, res) {
+        const params = {
+            response_type: url.searchParams.get('response_type'),
+            client_id: url.searchParams.get('client_id'),
+            redirect_uri: url.searchParams.get('redirect_uri'),
+            scope: url.searchParams.get('scope') || undefined,
+            state: url.searchParams.get('state') || undefined,
+            code_challenge: url.searchParams.get('code_challenge'),
+            code_challenge_method: url.searchParams.get('code_challenge_method')
+        };
+        const result = this.oauthProvider.handleAuthorizationRequest(params);
+        if (result.error) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: result.error }));
+            return;
+        }
+        // Redirect to the callback URL with auth code
+        res.writeHead(302, { 'Location': result.authUrl });
+        res.end();
+    }
+    async handleToken(req, res) {
+        const body = await this.getRequestBody(req);
+        const params = new URLSearchParams(body);
+        const tokenRequest = {
+            grant_type: params.get('grant_type'),
+            code: params.get('code'),
+            redirect_uri: params.get('redirect_uri'),
+            client_id: params.get('client_id'),
+            code_verifier: params.get('code_verifier')
+        };
+        const result = await this.oauthProvider.handleTokenRequest(tokenRequest);
+        if ('error' in result) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(result));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+    }
+    handleCallback(url, res) {
+        const code = url.searchParams.get('code');
+        const state = url.searchParams.get('state');
+        // Simple success page
+        const html = `
+      <!DOCTYPE html>
+      <html>
+        <head><title>Authorization Successful</title></head>
+        <body>
+          <h1>Authorization Successful!</h1>
+          <p>You can now close this window.</p>
+          <script>
+            // Try to close the window (works if opened by script)
+            try { window.close(); } catch(e) {}
+            
+            // Post message to parent if in iframe
+            if (window.opener) {
+              window.opener.postMessage({
+                type: 'oauth_success',
+                code: '${code}',
+                state: '${state}'
+              }, '*');
+            }
+          </script>
+        </body>
+      </html>
+    `;
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(html);
+    }
+    sendUnauthorized(res) {
+        res.writeHead(401, {
+            'Content-Type': 'application/json',
+            'WWW-Authenticate': 'Bearer realm="mcp", error="invalid_token"'
+        });
+        res.end(JSON.stringify({
+            error: 'unauthorized',
+            message: 'Valid access token required'
+        }));
+    }
+    async getRequestBody(req) {
+        return new Promise((resolve, reject) => {
+            let body = '';
+            req.on('data', chunk => body += chunk.toString());
+            req.on('end', () => resolve(body));
+            req.on('error', reject);
+        });
+    }
+    listen(port, callback) {
+        this.server.listen(port, callback);
+    }
+    close(callback) {
+        this.server.close(callback);
+    }
+}

package/dist/oauth/types.d.ts

@@ -0,0 +1,54 @@
+export interface OAuthConfig {
+    enabled: boolean;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    scope: string;
+    issuer: string;
+}
+export interface AuthorizationServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+    revocation_endpoint?: string;
+    jwks_uri?: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    code_challenge_methods_supported: string[];
+    scopes_supported?: string[];
+}
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+}
+export interface AccessToken {
+    sub: string;
+    aud: string | string[];
+    iss: string;
+    exp: number;
+    iat: number;
+    scope?: string;
+}
+export interface AuthorizationRequest {
+    response_type: 'code';
+    client_id: string;
+    redirect_uri: string;
+    scope?: string;
+    state?: string;
+    code_challenge: string;
+    code_challenge_method: 'S256';
+}
+export interface TokenRequest {
+    grant_type: 'authorization_code';
+    code: string;
+    redirect_uri: string;
+    client_id: string;
+    code_verifier: string;
+}

package/dist/oauth/types.js

@@ -0,0 +1,2 @@
+// OAuth 2.1 types for MCP authorization
+export {};

package/dist/search-manager.d.ts

@@ -30,6 +30,7 @@ export interface SearchSessionOptions {
     contextLines?: number;
     timeout?: number;
     earlyTermination?: boolean;
+    literalSearch?: boolean;
 }
 /**
  * Search Session Manager - handles ripgrep processes like terminal sessions

package/dist/search-manager.js

@@ -212,6 +212,10 @@ import { capture } from './utils/capture.js';
         if (options.searchType === 'content') {
             // Content search mode
             args.push('--json', '--line-number');
+            // Add literal search support for content searches
+            if (options.literalSearch) {
+                args.push('-F'); // Fixed string matching (literal)
+            }
             if (options.contextLines && options.contextLines > 0) {
                 args.push('-C', options.contextLines.toString());
             }

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function flushDeferredMessages(): void;
 export declare const server: Server<{
     method: string;
     params?: {

package/dist/server.js

@@ -1,5 +1,5 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListPromptsRequestSchema, InitializeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, InitializeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { getSystemInfo, getOSSpecificGuidance, getPathGuidance, getDevelopmentToolGuidance } from './utils/system-info.js';
 // Get system information once at startup
@@ -18,8 +18,20 @@ import { usageTracker } from './utils/usageTracker.js';
 import { processDockerPrompt } from './utils/dockerPrompt.js';
 import { VERSION } from './version.js';
 import { capture, capture_call_tool } from "./utils/capture.js";
-import { logToStderr } from './utils/logger.js';
-logToStderr('info', 'Loading server.ts');
+import { logToStderr, logger } from './utils/logger.js';
+// Store startup messages to send after initialization
+const deferredMessages = [];
+function deferLog(level, message) {
+    deferredMessages.push({ level, message });
+}
+// Function to flush deferred messages after initialization
+export function flushDeferredMessages() {
+    while (deferredMessages.length > 0) {
+        const msg = deferredMessages.shift();
+        logger.info(msg.message);
+    }
+}
+deferLog('info', 'Loading server.ts');
 export const server = new Server({
     name: "desktop-commander",
     version: VERSION,
@@ -57,8 +69,8 @@ server.setRequestHandler(InitializeRequestSchema, async (request) => {
                 name: clientInfo.name || 'unknown',
                 version: clientInfo.version || 'unknown'
             };
-            // Send JSON-RPC notification about client connection
-            logToStderr('info', `Client connected: ${currentClient.name} v${currentClient.version}`);
+            // Defer client connection message until after initialization
+            deferLog('info', `Client connected: ${currentClient.name} v${currentClient.version}`);
         }
         // Return standard initialization response
         return {
@@ -82,7 +94,7 @@ server.setRequestHandler(InitializeRequestSchema, async (request) => {
 });
 // Export current client info for access by other modules
 export { currentClient };
-logToStderr('info', 'Setting up request handlers...');
+deferLog('info', 'Setting up request handlers...');
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     try {
         logToStderr('debug', 'Generating tools list...');
@@ -257,24 +269,72 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     description: `
                         Start a streaming search that can return results progressively.
                         
+                        SEARCH STRATEGY GUIDE:
+                        Choose the right search type based on what the user is looking for:
+                        
+                        USE searchType="files" WHEN:
+                        - User asks for specific files: "find package.json", "locate config files"
+                        - Pattern looks like a filename: "*.js", "README.md", "test-*.tsx" 
+                        - User wants to find files by name/extension: "all TypeScript files", "Python scripts"
+                        - Looking for configuration/setup files: ".env", "dockerfile", "tsconfig.json"
+                        
+                        USE searchType="content" WHEN:
+                        - User asks about code/logic: "authentication logic", "error handling", "API calls"
+                        - Looking for functions/variables: "getUserData function", "useState hook"
+                        - Searching for text/comments: "TODO items", "FIXME comments", "documentation"
+                        - Finding patterns in code: "console.log statements", "import statements"
+                        - User describes functionality: "components that handle login", "files with database queries"
+                        
+                        WHEN UNSURE OR USER REQUEST IS AMBIGUOUS:
+                        Run TWO searches in parallel - one for files and one for content:
+                        
+                        Example approach for ambiguous queries like "find authentication stuff":
+                        1. Start file search: searchType="files", pattern="auth"
+                        2. Simultaneously start content search: searchType="content", pattern="authentication"  
+                        3. Present combined results: "Found 3 auth-related files and 8 files containing authentication code"
+                        
                         SEARCH TYPES:
                         - searchType="files": Find files by name (pattern matches file names)
                         - searchType="content": Search inside files for text patterns
                         
+                        PATTERN MATCHING MODES:
+                        - Default (literalSearch=false): Patterns are treated as regular expressions
+                        - Literal (literalSearch=true): Patterns are treated as exact strings
+                        
+                        WHEN TO USE literalSearch=true:
+                        Use literal search when searching for code patterns with special characters:
+                        - Function calls with parentheses and quotes
+                        - Array access with brackets
+                        - Object methods with dots and parentheses
+                        - File paths with backslashes
+                        - Any pattern containing: . * + ? ^ $ { } [ ] | \\ ( )
+                        
                         IMPORTANT PARAMETERS:
                         - pattern: What to search for (file names OR content text)
+                        - literalSearch: Use exact string matching instead of regex (default: false)
                         - filePattern: Optional filter to limit search to specific file types (e.g., "*.js", "package.json")
                         - ignoreCase: Case-insensitive search (default: true). Works for both file names and content.
                         - earlyTermination: Stop search early when exact filename match is found (optional: defaults to true for file searches, false for content searches)
                         
-                        EXAMPLES:
-                        - Find package.json files: searchType="files", pattern="package.json", filePattern="package.json"
-                        - Find all JS files: searchType="files", pattern="*.js" (or use filePattern="*.js")
-                        - Search for "TODO" in code: searchType="content", pattern="TODO", filePattern="*.js|*.ts"
-                        - Case-sensitive file search: searchType="files", pattern="README", ignoreCase=false
-                        - Case-insensitive file search: searchType="files", pattern="readme", ignoreCase=true
-                        - Find exact file, stop after first match: searchType="files", pattern="config.json", earlyTermination=true
-                        - Find all matching files: searchType="files", pattern="test.js", earlyTermination=false
+                        DECISION EXAMPLES:
+                        - "find package.json" → searchType="files", pattern="package.json" (specific file)
+                        - "find authentication components" → searchType="content", pattern="authentication" (looking for functionality)
+                        - "locate all React components" → searchType="files", pattern="*.tsx" or "*.jsx" (file pattern)
+                        - "find TODO comments" → searchType="content", pattern="TODO" (text in files)
+                        - "show me login files" → AMBIGUOUS → run both: files with "login" AND content with "login"
+                        - "find config" → AMBIGUOUS → run both: config files AND files containing config code
+                        
+                        COMPREHENSIVE SEARCH EXAMPLES:
+                        - Find package.json files: searchType="files", pattern="package.json"
+                        - Find all JS files: searchType="files", pattern="*.js"
+                        - Search for TODO in code: searchType="content", pattern="TODO", filePattern="*.js|*.ts"
+                        - Search for exact code: searchType="content", pattern="toast.error('test')", literalSearch=true
+                        - Ambiguous request "find auth stuff": Run two searches:
+                          1. searchType="files", pattern="auth"
+                          2. searchType="content", pattern="authentication"
+                        
+                        PRO TIP: When user requests are ambiguous about whether they want files or content,
+                        run both searches concurrently and combine results for comprehensive coverage.
                         
                         Unlike regular search tools, this starts a background search process and returns
                         immediately with a session ID. Use get_more_search_results to get results as they
@@ -982,3 +1042,5 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
 });
+// Add no-op handlers so Visual Studio initialization succeeds
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({ resourceTemplates: [] }));

package/dist/tools/schemas.d.ts

@@ -161,6 +161,7 @@ export declare const StartSearchArgsSchema: z.ZodObject<{
     contextLines: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     timeout_ms: z.ZodOptional<z.ZodNumber>;
     earlyTermination: z.ZodOptional<z.ZodBoolean>;
+    literalSearch: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     path: string;
     pattern: string;
@@ -168,6 +169,7 @@ export declare const StartSearchArgsSchema: z.ZodObject<{
     ignoreCase: boolean;
     includeHidden: boolean;
     contextLines: number;
+    literalSearch: boolean;
     timeout_ms?: number | undefined;
     filePattern?: string | undefined;
     maxResults?: number | undefined;
@@ -183,6 +185,7 @@ export declare const StartSearchArgsSchema: z.ZodObject<{
     includeHidden?: boolean | undefined;
     contextLines?: number | undefined;
     earlyTermination?: boolean | undefined;
+    literalSearch?: boolean | undefined;
 }>;
 export declare const GetMoreSearchResultsArgsSchema: z.ZodObject<{
     sessionId: z.ZodString;

package/dist/tools/schemas.js

@@ -95,6 +95,7 @@ export const StartSearchArgsSchema = z.object({
     contextLines: z.number().optional().default(5),
     timeout_ms: z.number().optional(), // Match process naming convention
     earlyTermination: z.boolean().optional(), // Stop search early when exact filename match is found (default: true for files, false for content)
+    literalSearch: z.boolean().optional().default(false), // Force literal string matching (-F flag) instead of regex
 });
 export const GetMoreSearchResultsArgsSchema = z.object({
     sessionId: z.string(),

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { ChildProcess } from 'child_process';
 import { FilteredStdioServerTransport } from './custom-stdio.js';
 declare global {
     var mcpTransport: FilteredStdioServerTransport | undefined;
+    var disableOnboarding: boolean | undefined;
 }
 export interface ProcessInfo {
     pid: number;

package/dist/utils/usageTracker.js

@@ -299,6 +299,21 @@ class UsageTracker {
      * Check if user should see onboarding invitation - SIMPLE VERSION
      */
     async shouldShowOnboarding() {
+        // Check if onboarding is disabled via command line argument
+        if (global.disableOnboarding) {
+            return false;
+        }
+        // Check if client is desktop-commander (disable for this client)
+        try {
+            const { currentClient } = await import('../server.js');
+            if (currentClient?.name === 'desktop-commander') {
+                return false;
+            }
+        }
+        catch (error) {
+            // If we can't import server, continue with other checks
+            console.log('[ONBOARDING DEBUG] Could not check client name, continuing...');
+        }
         const stats = await this.getStats();
         const onboardingState = await this.getOnboardingState();
         const now = Date.now();

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.2.13";
+export declare const VERSION = "0.2.15";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.2.13';
+export const VERSION = '0.2.15';

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@wonderwhy-er/desktop-commander",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "MCP server for terminal operations and file editing",
+  "mcpName": "io.github.wonderwhy-er/desktop-commander",
   "license": "MIT",
   "author": "Eduards Ruzga",
   "homepage": "https://github.com/wonderwhy-er/DesktopCommanderMCP",
@@ -69,7 +70,7 @@
     "file-operations"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.8.0",
+    "@modelcontextprotocol/sdk": "^1.9.0",
     "@vscode/ripgrep": "^1.15.9",
     "cross-fetch": "^4.1.0",
     "fastest-levenshtein": "^1.0.16",