Graceful Dialog Failure Handling

Overview

When NCP's confirmation dialog system fails due to platform limitations or missing dependencies, instead of blocking operations, NCP provides clear manual installation instructions to help users complete their desired actions.

Problem Statement

NCP requires user confirmation before adding/removing MCPs for security. Confirmation is attempted through:

MCP elicitation (if client supports it)
Native OS dialogs (fallback for clients without elicitation)

However, native dialogs can fail due to:

Linux: Missing zenity or kdialog packages
Windows: PowerShell execution restrictions
macOS: AppleScript permissions denied
Other: Platform-specific issues

Previous behavior: When dialog failed, NCP blocked the operation with a generic error, leaving users unable to proceed.

Problem: This blocks legitimate user actions due to our limitation, not user choice.

Solution: Manual Installation Instructions

When the dialog system fails, NCP now provides comprehensive manual installation instructions instead of just blocking.

Example Response for Failed Installation

⚠️  Cannot show confirmation dialog: Neither zenity nor kdialog is available

For security, NCP requires user confirmation before installing MCPs.

Since the dialog system isn't working on your system, you can install manually:

1. Open your profile configuration file:
   /Users/username/.ncp/profiles/default.json

2. Add this to the "mcpServers" section:
   "github": {
     "command": "npx",
     "args": ["-y", "@modelcontextprotocol/server-github"]
   }

3. Save the file

4. Restart NCP or your MCP client

⚙️  Full command for reference: npx -y @modelcontextprotocol/server-github

💡 If this MCP requires API keys/credentials, add them to the "env" field in the config.

Example Response for Failed Removal

⚠️  Cannot show confirmation dialog: Neither zenity nor kdialog is available

For security, NCP requires user confirmation before removing MCPs.

Since the dialog system isn't working on your system, you can remove manually:

1. Open your profile configuration file:
   /Users/username/.ncp/profiles/default.json

2. Find and delete the "github" entry from the "mcpServers" section

3. Save the file

4. Restart NCP or your MCP client

💡 Make sure to preserve valid JSON format (watch for trailing commas).

Benefits

1. Security Maintained ✅

User confirmation still required (manual edit confirms intent)
No automatic installation of untrusted code
Transparent about what's being added/removed

2. User Goals Achieved ✅

Users can still get what they want
AI can guide them through manual process
Clear, actionable steps provided

3. Transparency ✅

Explains the limitation clearly
Shows exact configuration to add
Reveals the underlying command being executed

4. Better UX ✅

Doesn't dead-end the user
AI remains helpful despite our limitation
User learns about NCP configuration format

Implementation Details

Code Location

src/internal-mcps/ncp-management.ts

Add Operation (lines 272-298)

typescript

} catch (nativeError: any) {
  // Dialog system failed - provide manual installation instructions
  logger.error(`Native dialog failed: ${nativeError.message}`);

  const profilePath = await this.profileManager!.getProfilePath(profile);
  const argsStr = commandArgs.length > 0 ? commandArgs.join(' ') : '';
  const configToAdd = {
    command,
    args: commandArgs
  };

  return {
    success: false,
    error: `⚠️  Cannot show confirmation dialog: ${nativeError.message}\n\n` +
           `For security, NCP requires user confirmation before installing MCPs.\n\n` +
           `Since the dialog system isn't working on your system, you can install manually:\n\n` +
           `1. Open your profile configuration file:\n` +
           `   ${profilePath}\n\n` +
           `2. Add this to the "mcpServers" section:\n` +
           `   "${mcpName}": ${JSON.stringify(configToAdd, null, 2).split('\n').join('\n   ')}\n\n` +
           `3. Save the file\n\n` +
           `4. Restart NCP or your MCP client\n\n` +
           `⚙️  Full command for reference: ${command} ${argsStr}\n\n` +
           `💡 If this MCP requires API keys/credentials, add them to the "env" field in the config.`
  };
}

Remove Operation (lines 443-461)

typescript

} catch (nativeError: any) {
  // Dialog system failed - provide manual removal instructions
  logger.error(`Native dialog failed: ${nativeError.message}`);

  const profilePath = await this.profileManager!.getProfilePath(profile);

  return {
    success: false,
    error: `⚠️  Cannot show confirmation dialog: ${nativeError.message}\n\n` +
           `For security, NCP requires user confirmation before removing MCPs.\n\n` +
           `Since the dialog system isn't working on your system, you can remove manually:\n\n` +
           `1. Open your profile configuration file:\n` +
           `   ${profilePath}\n\n` +
           `2. Find and delete the "${mcpName}" entry from the "mcpServers" section\n\n` +
           `3. Save the file\n\n` +
           `4. Restart NCP or your MCP client\n\n` +
           `💡 Make sure to preserve valid JSON format (watch for trailing commas).`
  };
}

User Scenarios

Scenario 1: Extension User Without Global CLI

Context: User running NCP as Claude Desktop extension (.dxt), global CLI not enabled

What Happens:

AI tries to add MCP via ncp:add
Elicitation times out (5s)
Native dialog fallback fails (platform issue)
NCP detects: Extension mode + global CLI disabled

NCP Response:

⚠️  Cannot show confirmation dialog: [error message]

For security, NCP requires user confirmation before installing MCPs.

📌 EASIEST OPTION: Enable the global NCP command

1. Edit your Claude Desktop extension settings (.dxt file)
2. Set: "enableGlobalCLI": true
3. Restart Claude Desktop
4. Use command: ncp add github npx -y @modelcontextprotocol/server-github

────────────────────────────────────────

📝 OR: Install manually by editing configuration

1. Open your profile configuration file:
   /Users/username/.ncp/profiles/all.json

2. Add this to the "mcpServers" section:
   "github": {
     "command": "npx",
     "args": ["-y", "@modelcontextprotocol/server-github"]
   }

[...]

User Action: Either:

Option 1 (Easier): Enables global CLI in extension settings, then uses ncp add command
Option 2: Opens profile JSON and adds MCP config manually

Result: ✅ User gets the MCP they want via the easiest path

Scenario 2: Linux User Without Zenity

Context: User on Ubuntu without zenity installed (standalone NCP or extension with global CLI enabled)

What Happens:

AI tries to add MCP via ncp:add
Elicitation times out (5s)
Native dialog fallback attempts zenity → fails
Native dialog fallback attempts kdialog → fails
Error thrown: "Neither zenity nor kdialog is available"

NCP Response:

⚠️  Cannot show confirmation dialog: Neither zenity nor kdialog is available

[Manual installation instructions with exact JSON to add]

User Action: Opens ~/.ncp/profiles/default.json, adds the MCP config manually, saves, restarts

Result: ✅ User gets the MCP they want, security maintained

Scenario 3: Windows User with PowerShell Restrictions

Context: Corporate Windows machine with PowerShell execution policy restrictions

What Happens:

AI tries to add MCP via ncp:add
Elicitation times out (5s)
Native dialog fallback attempts PowerShell MessageBox → fails with execution policy error
Error thrown: "PowerShell dialog failed: execution policy"

NCP Response:

⚠️  Cannot show confirmation dialog: PowerShell dialog failed: execution policy

[Manual installation instructions with exact JSON to add]

User Action: Opens profile JSON, adds MCP config manually

Result: ✅ User gets the MCP they want despite PowerShell restrictions

Scenario 4: macOS User with AppleScript Denied

Context: macOS user who denied AppleScript permissions in System Preferences

What Happens:

AI tries to add MCP via ncp:add
Elicitation times out (5s)
Native dialog fallback attempts AppleScript → permission denied
Error thrown: "AppleScript permission denied"

NCP Response:

⚠️  Cannot show confirmation dialog: AppleScript permission denied

[Manual installation instructions with exact JSON to add]

User Action: Either:

Opens profile JSON and adds MCP config manually, OR
Grants AppleScript permission and retries

Result: ✅ User can proceed either way

Decision Flow

User requests: Add/Remove MCP
         ↓
Try elicitation (5s timeout)
         ↓
    Supported? ─── Yes ──→ Show elicitation UI → Get user response → Proceed
         ↓
        No
         ↓
Try native dialog (45s timeout)
         ↓
    Works? ───────── Yes ──→ Show OS dialog → Get user response → Proceed
         ↓
        No
         ↓
Dialog failed (our limitation)
         ↓
Return manual installation instructions
         ↓
AI presents instructions to user
         ↓
User manually edits config
         ↓
✅ User achieves goal, security maintained

Comparison: Before vs After

Before (Blocking)

User: "Add the time MCP"
AI: "I'll add it for you..."
NCP: "⛔ Cannot show confirmation dialog. Installation cancelled for security."
AI: "Sorry, I can't install it because the dialog system isn't working."
User: ❌ Stuck, can't get the MCP

After (Helpful)

User: "Add the time MCP"
AI: "I'll add it for you..."
NCP: "⚠️ Cannot show dialog, here are manual installation instructions..."
AI: "The automatic installer isn't working on your system, but I can help you add it manually:
     1. Open ~/.ncp/profiles/default.json
     2. Add this configuration: [shows exact JSON]
     3. Save and restart"
User: ✅ Follows steps, gets the MCP

Security Considerations

Is This Secure?

Yes. Manual installation is just as secure as automated installation with confirmation:

Intent Confirmation: User must manually edit config (confirms intent)
Transparency: User sees exact command/config being added
No Auto-Execution: User must explicitly save and restart
Same Result: Whether automated or manual, same config gets added

Key Insight: The confirmation dialog's purpose is to ensure user intent and transparency. Manual installation achieves both.

Why Not Just Auto-Install?

We could bypass the dialog and auto-install when dialog fails. We don't do this because:

Security: Users should always know what's being installed
Transparency: Clear review of command/config before installation
Control: User can modify config before saving (e.g., add custom args)
Education: User learns about NCP config format

Testing

Test Script

test-dialog-failure-handling.js

Simulates dialog failure and demonstrates manual installation instructions.

bash

node test-dialog-failure-handling.js

Expected Output

✅ Dialog fails as expected
✅ Manual installation instructions generated
✅ Instructions include profile path
✅ Instructions include exact JSON to add
✅ Clear steps for user to follow

Native Dialog Cross-Platform Support - Platform-specific dialog implementations
Native Dialog Timeout & Retry - Timeout and retry mechanisms
MCP Prompts for User Interaction - Elicitation-first strategy

Future Enhancements

Possible Improvements

One-Click Install Script: Generate a shell script user can run to add the MCP
Visual Config Editor: Launch browser-based config editor if dialogs don't work
Clipboard Copy: Automatically copy JSON to clipboard for easier pasting
Link to Troubleshooting: Provide link to fix dialog system (install zenity, enable PowerShell, etc.)

Not Planned

Auto-install without confirmation: Would compromise security
Silent fallback: User should always be informed about limitations

Summary

Problem: Dialog failure blocked user actions

Solution: Provide manual installation instructions when dialogs fail

Benefits:

✅ Security maintained (user still confirms via manual edit)
✅ User goals achieved (can still install/remove MCPs)
✅ Better UX (AI remains helpful despite our limitation)
✅ Transparency (user sees exact config)

Philosophy: When automation fails, empower users with clear manual steps rather than blocking them.

Graceful Dialog Failure Handling ​

Overview ​

Problem Statement ​

Solution: Manual Installation Instructions ​

Example Response for Failed Installation ​

Example Response for Failed Removal ​

Benefits ​

1. Security Maintained ✅ ​

2. User Goals Achieved ✅ ​

3. Transparency ✅ ​

4. Better UX ✅ ​

Implementation Details ​

Code Location ​

Add Operation (lines 272-298) ​

Remove Operation (lines 443-461) ​

User Scenarios ​

Scenario 1: Extension User Without Global CLI ​

Scenario 2: Linux User Without Zenity ​

Scenario 3: Windows User with PowerShell Restrictions ​

Scenario 4: macOS User with AppleScript Denied ​

Decision Flow ​

Comparison: Before vs After ​

Before (Blocking) ​

After (Helpful) ​

Security Considerations ​

Is This Secure? ​

Why Not Just Auto-Install? ​

Testing ​

Test Script ​

Expected Output ​

Related Documentation ​

Future Enhancements ​

Possible Improvements ​

Not Planned ​

Summary ​

Graceful Dialog Failure Handling

Overview

Problem Statement

Solution: Manual Installation Instructions

Example Response for Failed Installation

Example Response for Failed Removal

Benefits

1. Security Maintained ✅

2. User Goals Achieved ✅

3. Transparency ✅

4. Better UX ✅

Implementation Details

Code Location

Add Operation (lines 272-298)

Remove Operation (lines 443-461)

User Scenarios

Scenario 1: Extension User Without Global CLI

Scenario 2: Linux User Without Zenity

Scenario 3: Windows User with PowerShell Restrictions

Scenario 4: macOS User with AppleScript Denied

Decision Flow

Comparison: Before vs After

Before (Blocking)

After (Helpful)

Security Considerations

Is This Secure?

Why Not Just Auto-Install?

Testing

Test Script

Expected Output

Related Documentation

Future Enhancements

Possible Improvements

Not Planned

Summary