Use Puma::Server instead of Puma::Launcher to fix Ctrl+C handling

[kx7m2qd]

Puma::Launcher installs process-wide SIGINT/SIGTERM signal traps as part of its startup, intended for when Puma owns the entire process (e.g. run standalone via the puma CLI). Since the MCP server runs on a background thread inside msfconsole (spawned via framework.threads.spawn), these traps are process-global and silently override msfconsole's own Ctrl+C handling, which relies on Ruby's default Interrupt behavior.

This swaps Puma::Launcher for Puma::Server, the lower-level, embeddable API. Puma::Server does not install any signal traps, making it safe to run inside a host process like msfconsole. Also updated shutdown to call .stop(true) directly on the server for graceful shutdown.

Related Issue:

Fixes #21650

Verification Steps:

1. • Load the mcp plugin, run mcp start, then press Ctrl+C. Expected: console prints Interrupt: use the 'exit' command to quit (matching normal msfconsole behavior), rather than doing nothing.
2. • With the server running, run mcp stop. Expected: prints MCP server stopped cleanly with no hang or error.
3. • Run mcp start followed by mcp restart. Expected: server restarts cleanly without error.

Test Evidence:

msf > load mcp
[] MCP plugin loaded. Use mcp start to start the server.
[] Successfully loaded plugin: mcp
msf > mcp start
[] Auto-started msgrpc - User: msf, Pass: [redacted]
[] MCP server started on localhost:3000 (transport: http)
msf > Interrupt: use the 'exit' command to quit
msf > mcp stop
[] MCP server stopped
msf > mcp start
[] MCP server started on localhost:3000 (transport: http)
msf > mcp restart
[*] MCP server started on localhost:3000 (transport: http)

Environment:

| Operating System | Ubuntu 24.04 |
| Target Software/Hardware | N/A |

AI Usage Disclosure:

Used AI to help identify the root cause and draft the fix. All testing and verification was done manually by me.

Pre-Submission Checklist:

• No sensitive information (IP addresses, credentials, API keys, hashes) in code or documentation
• Tested on the target environment specified in the Environment section above
• Read the CONTRIBUTING.md and module acceptance guidelines

Reviewer Notes

Wasn't able to get the full local RSpec suite passing due to an unrelated local Postgres/msfdb environment setup issue on my machine verified manually instead (see Test Evidence). Happy to dig further if CI surfaces anything.

[dwelch-r7]

Tested and seems to work well, one minor comment but once that's addressed I think this is good to go

[dwelch-r7]

Does Puma::Launcher not have support for workers? if it does let's add it in, otherwise we should remove all references to workers if they aren't used anymore

[kx7m2qd]

Good question turns out workers goes a bit deeper than server.rb. It's actually a supported, validated config option (MSF_MCP_WORKERS env var / mcp.workers in the config file, validated in config/validator.rb, loaded in config/loader.rb) that's wired through to the standalone msfmcpd binary via application.rb.
Since Puma::Server doesn't support clustering (that's Puma::Cluster, which Puma::Launcher used internally), workers is currently a no-op wherever it flows through start_http. Given the plugin path always uses the default (PUMA_WORKERS = 0), this PR's fix doesn't change plugin behavior either way but I don't want to silently strip a documented option that might affect the standalone msfmcpd binary without testing that path too.

Given the scope, I'd propose: keep workers in this PR as-is (still a no-op, same as before my change — not a regression I'm introducing), and I'll follow up with a separate PR/issue to properly deprecate or reintroduce cluster support for workers, after testing the msfmcpd binary path specifically. Let me know if you'd rather I just strip it now instead happy to do either, just flagging the wider surface first.

[dwelch-r7]

The plugin only uses 0 sure but there are other ways of starting up the MCP server using msfmcpd where if you set MSF_MCP_WORKERS=4 it would work yes?

[kx7m2qd]

You're right, confirmed MSF_MCP_WORKERS=4 via msfmcpd would genuinely lose clustering with this change, that's a real regression I missed since I only tested the plugin path (always workers: 0).

Digging into why: Puma::Launcher 's signal trapping is largely there to support clustering coordinating worker processes needs the parent to own SIGTERM/SIGINT. That's actually fine for msfmcpd (it's a standalone process, same as any CLI daemon), it's only a problem for the plugin case where we're embedded inside msfconsole.

Proposing a conditional: use Puma::Server when workers == 0 (the plugin's case, fixes the Ctrl+C bug), and keep Puma::Launcher when workers > 0 (preserves clustering for msfmcpd, and signal ownership there isn't an issue). Will push an update and test both paths (plugin + msfmcpd with MSF_MCP_WORKERS set) before pinging you again.

[kx7m2qd]

Pushed the fix verified both paths:

Plugin (mcp start, workers=0): Ctrl+C still shows the normal Interrupt: use the 'exit' command to quit, and mcp stop/mcp restart work cleanly.
Standalone (MSF_MCP_WORKERS=2 ./msfmcpd): confirmed clustering is genuinely preserved —ps -ef --forestshows the parent Puma process with 2 real cluster worker child processes underneath it, same as before this change.

Confirmed with your exact example MSF_MCP_WORKERS=4 ./msfmcpd now spawns 4 real cluster workers:

puma 6.6.0 (tcp://localhost:3000) [metasploit-framework]
  \_ msfrpcd
  \_ puma: cluster worker 0: 151501
  \_ puma: cluster worker 1: 151501
  \_ puma: cluster worker 2: 151501
  \_ puma: cluster worker 3: 151501

And the plugin path (workers=0) still fixes the original Ctrl+C issue
mcp start/Ctrl+C/mcp stop/mcp restart all confirmed working cleanly.