Linux Terminal Launch Fails: PowerShell Console Closes Immediately Due to Incorrect Shell Quoting

[Fabelwesen]

🐛 Bug Description

On Linux systems (specifically tested on CachyOS/Arch Linux using KDE Plasma/konsole), the PowerShell.MCP server fails to start the persistent console. When calling start_powershell_console or any tool that triggers auto-start, a terminal window (e.g., konsole) opens for a fraction of a second and closes immediately.

The MCP client reports a Not connected or Failed to start PowerShell console error.

---

🔍 Root Cause Analysis

The issue lies in the PwshLauncherLinux.cs (or PowerShellProcessManager.cs depending on the version) within the PowerShell.MCP.Proxy project.

The current implementation attempts to launch pwsh via a login shell using the following command structure:

var pwshCommand = $"exec pwsh -NoExit -WorkingDirectory '{workingDir}' -Command ''{initCommand}''";

When this is passed to bash -l -c, the double single quotes ('') are interpreted by Bash as an empty string. This results in several critical failures:

1. Variable Expansion: Because the command is not effectively quoted, Bash attempts to expand PowerShell variables (like $global:PowerShellMCPProxyPid) as Bash variables. Since they don't exist in the Bash environment, they resolve to empty strings.
2. Syntax Errors: The resulting command string sent to pwsh is corrupted/empty, causing PowerShell to exit immediately with a syntax error, which in turn closes the terminal window.

---

💡 Proposed Solution: Base64 EncodedCommand

The most robust way to pass complex initialization commands to PowerShell across different shells (Bash, Zsh, etc.) without hitting quoting or expansion issues is using the -EncodedCommand parameter.

Recommended Change:

In PowerShellProcessManager.cs (Linux launcher section):

1. Construct the initCommand using standard single quotes.
2. Encode the command string to a Base64 UTF-16LE string.
3. Execute pwsh using -EncodedCommand.

Example Implementation (C#):

// 1. Build the command normally (no more double-single-quote escaping needed)
string initCommand = $"$global:PowerShellMCPProxyPid = {proxyPid}; $global:PowerShellMCPAgentId = '{agentId}'; {caseFix}Import-Module PowerShell.MCP -Force; Remove-Module PSReadLine -ErrorAction SilentlyContinue; {startupCommands}";

// 2. Encode to Base64 (UTF-16LE is required for -EncodedCommand)
var initBytes = System.Text.Encoding.Unicode.GetBytes(initCommand);
var encodedCommand = System.Convert.ToBase64String(initBytes);

// 3. Launch with -EncodedCommand
var pwshCommand = $"exec pwsh -NoExit -WorkingDirectory '{workingDir}' -EncodedCommand {encodedCommand}";

---

🛠️ Additional Minor Fix: Join-Path in caseFix

While debugging, I also encountered an error in the caseFix logic:
Join-Path: Cannot bind argument to parameter 'Path' because it is an empty string.

This happens if the user's $env:PSModulePath contains empty entries (e.g., trailing separators).

Fix: Add a check for null or whitespace before calling Join-Path:

var caseFix = "foreach ($p in ($env:PSModulePath -split [IO.Path]::PathSeparator)) { if ([string]::IsNullOrWhiteSpace($p)) { continue }; $lc = Join-Path $p 'powershell.mcp'; ... }";

---

✅ Verification

After applying these changes and rebuilding the Proxy, the PowerShell console now starts perfectly and remains stable on Linux (KDE/konsole).

Environment tested:

• OS: CachyOS (Arch based)
• Kernel: 6.18.x
• Desktop: KDE Plasma 6 (Wayland)
• Terminal: konsole
• PowerShell: 7.4.x
• MCP Module: 1.7.0

[yotsuda]

Thank you for the excellent report — both the root cause analysis and the -EncodedCommand solution were exactly right. We applied your proposed fix directly.

v1.7.1 is now available on PSGallery.

# Upgrade
Update-PSResource PowerShell.MCP

# Set execute permission
chmod +x (Get-MCPProxyPath)

Then update your MCP client configuration to point to the new version:

# Claude Code
claude mcp remove PowerShell
claude mcp add PowerShell -s user -- (Get-MCPProxyPath)

# Claude Desktop — update claude_desktop_config.json with the new path:
Get-MCPProxyPath

We adopted both of your suggestions:

1. -EncodedCommand — Exactly as you proposed. The init command is now encoded as Base64 UTF-16LE, completely bypassing shell quoting issues. We also moved -WorkingDirectory into the encoded command as Set-Location to avoid any remaining quoting edge cases.

2. caseFix empty path guard — Added the IsNullOrWhiteSpace check you identified, in both the terminal launcher and the headless launcher paths.

We verified the fix on Ubuntu + konsole (matching your terminal emulator). Thank you for the thorough root cause analysis and the ready-to-use solution — it made the fix straightforward.

Closing this issue with v1.7.1.