Skip to content

feat(cdp): Add Chrome DevTools Protocol support for AI-assisted debugging#1002

Merged
kuishou68 merged 14 commits intoiOfficeAI:mainfrom
loonghao:feat/cdp-support
Mar 3, 2026
Merged

feat(cdp): Add Chrome DevTools Protocol support for AI-assisted debugging#1002
kuishou68 merged 14 commits intoiOfficeAI:mainfrom
loonghao:feat/cdp-support

Conversation

@loonghao
Copy link
Copy Markdown
Collaborator

@loonghao loonghao commented Feb 26, 2026 •
edited
Loading

Summary

This PR introduces Chrome DevTools Protocol (CDP) support to AionUi, enabling seamless integration with AI-powered development tools through the Model Context Protocol (MCP).

What is CDP and Why It Matters for Developers

Chrome DevTools Protocol (CDP) is a powerful debugging protocol that allows external tools to inspect, debug, and control Chrome/Electron applications. For AionUi users, this means:

  • AI-Assisted Debugging: Connect AI assistants (like Claude, Cursor AI) directly to AionUi to debug issues, inspect UI state, and automate testing
  • Automated Testing: Use browser automation tools to write end-to-end tests
  • Development Workflow Integration: Integrate with popular IDEs for a seamless debugging experience
  • Real-time Inspection: Inspect the running application state, network requests, console logs, and more

Changes

CDP Infrastructure (src/utils/configureChromium.ts)

  • Auto-discover available ports (9230-9250 range)
  • Multi-instance support with registry file (~/.aionui-cdp-registry.json)
  • Automatic cleanup of stale processes
  • Environment variable override (AIONUI_CDP_PORT)
  • Persistent configuration in user data directory

Settings UI (src/renderer/components/SettingsModal/contents/SystemModalContent.tsx)

  • Enable/disable CDP toggle (dev mode only)
  • Current port display with quick actions
  • Complete MCP configuration display - shows full JSON config ready to copy
  • MCP config file path hint - guides users where to add the config
  • One-click copy for CDP URL and MCP config
  • Open in browser button to view debuggable pages
  • Restart reminder when config changes

Bug Fix (src/channels/plugins/telegram/TelegramPlugin.ts)

  • Fixed process not exiting issue when stopping Telegram bot
  • Added proper promise tracking for bot.start() lifecycle
  • Added 5-second timeout mechanism to prevent hanging

Documentation

  • New file: docs/cdp.md - Standalone CDP documentation (bilingual EN/CN)
  • README updated with brief CDP reference

How to Use

Development Mode

CDP is enabled by default when running just dev on port 9230.

Production Mode

  1. Open Settings → System → Developer Debug (dev mode only)
  2. Enable "Enable Remote Debugging (CDP)"
  3. Restart AionUi
  4. Copy the MCP configuration
  5. Add it to your IDE's MCP settings file:
    • Cursor: ~/.cursor/mcp.json
    • Claude Desktop: ~/.claude/settings.json

MCP Configuration Example

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9230"
      ]
    }
  }
}

Documentation

Full documentation available at docs/cdp.md

Testing

  • CDP port auto-discovery works correctly
  • Multiple instances don't conflict
  • Settings UI displays correctly (dev mode)
  • MCP config copies with correct port
  • Telegram bot shutdown no longer hangs
  • All translations complete

@loonghao
Copy link
Copy Markdown
Collaborator Author

loonghao commented Feb 26, 2026

配置页面
7ad2dad84ee581eebe7875a1899e084e

使用展示
image
image

@loonghao loonghao force-pushed the feat/cdp-support branch 3 times, most recently from 420d8f7 to 09b8c68 Compare February 27, 2026 10:43
@loonghao loonghao changed the title feat(cdp): Add Chrome DevTools Protocol support for AI-assisted debugging fix(telegram): resolve process hanging on shutdown Feb 27, 2026
@loonghao loonghao changed the title fix(telegram): resolve process hanging on shutdown feat(cdp): Add Chrome DevTools Protocol support for AI-assisted debugging Feb 27, 2026
@loonghao loonghao force-pushed the feat/cdp-support branch 2 times, most recently from 404678a to 8b7593a Compare February 28, 2026 16:41
@loonghao
Copy link
Copy Markdown
Collaborator Author

loonghao commented Feb 28, 2026

@kaizhou-lab 已经rebase了，看看还有哪些需要调整

@kuishou68
Copy link
Copy Markdown
Collaborator

kuishou68 commented Mar 2, 2026

@loonghao Thanks for the CDP support! A few issues need to be resolved:

Blocking

  1. isPortAvailableSync busy-spins the main process — The while (Date.now() - start < 150) loop blocks the event loop. With 21 ports (9230–9250), that's ~3 seconds of blocked startup. The socket callbacks never fire during the spin since the event loop is frozen, so the check is effectively a no-op. Consider using net.createServer().listen() with try/catch (fails immediately on conflict), or move CDP init to after app.ready and use async port checking.
  2. Production bypass via config file — The UI hides the toggle when isDevMode === false, but if a user manually writes {"enabled": true} to cdp.config.json, CDP starts in production. shouldEnableCdp should hard-reject enabled: true when app.isPackaged === true.
  3. isPortAvailable returns Promise cast as boolean — The @deprecated function uses as unknown as boolean on a Promise. It's dead code but should be removed entirely.

Warning

  1. Unrelated Telegram fix bundled in — The TelegramPlugin.ts shutdown hang fix is a separate concern. Should be its own PR for clean rollback if needed.
  2. Tests have no real assertions — Multiple tests use expect(true).toBe(true) and re-declare constants locally instead of importing from source. The DEFAULT_CDP_PORT test asserts 9223 but the actual source uses 9230.
  3. resolveCdpPortFromEnv returns undefined but typed as number | null — Fix the return type to include undefined, or return null.

loonghao and others added 6 commits March 2, 2026 22:06
@loonghao
feat(cdp): add Chrome DevTools Protocol support with UI controls
dd82083
@loonghao
feat(cdp): enhance CDP settings UI with complete MCP config display
b474901
@loonghao
fix: resolve prettier lint errors in SystemModalContent
be57db2
@loonghao
feat(cdp): hide CDP settings in production and move docs to standalon…
bcfdddf 
…e file

- Add isDevMode field to CdpStatus/ICdpStatus interfaces, backed by
  app.isPackaged, so the renderer can gate developer-only UI
- Move CDP container (title + CdpSettings) into the CdpSettings component
  and return null when isDevMode is false, hiding the entire block in
  packaged builds
- Extract CDP documentation from both READMEs into docs/cdp.md
- Update unit tests to cover the new isDevMode property
@loonghao
fix: resolve TypeScript trigger type error in siderTooltip
a7b8d4f
@loonghao
fix: stabilize CDP init and flaky Windows ACP disconnect test
38cd9fd
@kuishou68 kuishou68 merged commit 5c8f539 into iOfficeAI:main Mar 3, 2026
12 checks passed
@kuishou68 kuishou68 mentioned this pull request Mar 4, 2026
Closed
4 tasks
@kaizhou-lab kaizhou-lab mentioned this pull request Mar 17, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kuishou68 kuishou68 kuishou68 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@loonghao @kuishou68