[akash-aman]

Stacked on #1 (it reuses editors/conformance). Retarget to main once #1 is merged.

Summary

A Blackbox window side for every IntelliJ-based IDE (2024.3+), built on the IDE's debugger platform (XDebugger). It speaks the same protocol as the VS Code extension and blackbox.nvim, so one MCP server lists JetBrains projects next to VS Code, Cursor, Antigravity and Neovim windows.

• One window per open project. The id is <pid>-<hash>. AI tools started in the IDE terminal get BLACKBOX_WINDOW for their project.

• All 33 tools. Run configurations start by name in the debugger. Steps, threads, frames, variables, evaluate, set variable, watches and output all work.

  • Hit conditions and logpoints are applied by the plugin: the breakpoint pauses, the plugin counts the hit or logs the message, and resumes.

• Java: method breakpoints (App.add) and caught/uncaught exception filters.

• PHP (PhpStorm):

  • method breakpoints (Class::method);
  • Xdebug exception filters, the same ones VS Code's PHP Debug offers;
  • Listen for PHP Debug Connections offered as a launch configuration.

  This uses PhpStorm's classes by name, since PhpStorm 2026 targets Java 25.

• Ships the MCP server: an esbuild bundle from editors/vscode. The plugin installs ~/.blackbox/blackbox-mcp.js with the same rules as the VS Code extension: newer versions only, one record per install. Users get Tools | Blackbox: Copy MCP Config.

• Windows: Node can't reach Java's Unix sockets there, so the plugin listens on TCP loopback with a token (tcp://127.0.0.1:<port>/<token>).

MCP server changes (editors/vscode)

• callExtension connects to tcp:// windows and sends their token. TCP entries aren't dropped as stale.
• An editor process that serves several windows (a JetBrains IDE) now identifies only the editor, not an arbitrary one of its windows.
• New bundle:mcp script (esbuild). release-notes.js takes CHANGELOG=<file>.

Testing

• Conformance (npm run test:jetbrains): the same suite as Neovim, through the real MCP server, against IntelliJ IDEA Community with a Java fixture. 7 passing, run 3 times locally. The stalled-start check is skipped, since run configurations can't stall like a debug adapter.
  • A new check starts the server through the launcher the plugin installed.
• Kotlin unit tests: 11, covering the bridge server (framing, TCP token, registry entry, private folder), hit conditions and launcher version rules.
• Plugin verifier: compatible with IntelliJ IDEA 2024.3.6 and PhpStorm 2026.2.3, with no internal API used.
• Unchanged and still passing: VS Code unit tests (107, 3 new), Neovim conformance (7), Lua unit tests (31).
• Not yet tested live: PhpStorm on a real Xdebug site. PhpStorm isn't installed here; it needs a licence.

Notes

• .github/workflows/jetbrains.yml runs:

  • unit tests and build on Linux, macOS and Windows;
  • the verifier and the conformance suite (under xvfb) on Linux.

  Releases are started by jetbrains-v* tags and need the JETBRAINS_* secrets (see CONTRIBUTING). The first Marketplace upload must be done by hand.

• LocalTerminalCustomizer is deprecated in 2026.2 but still works. A follow-up can move to the new terminal API.