feat(devtool-mcp-server): fix failed to connect client

[colinaaa]

Summary by CodeRabbit

Release Notes

• New Features

  • Exported new public APIs for tool registration and tool definitions
  • Added Schema namespace for configuration

• Bug Fixes

  • Fixed client connection failures
  • Improved USB client handling during connection timeouts
  • Enhanced device client lifecycle management to trigger connections on device connection events

Checklist

• Tests updated (or not required).
• Documentation updated (or not required).
• Changeset added, and when a BREAKING CHANGE occurs, it needs to be clearly marked (or not required).

[changeset-bot]

🦋 Changeset detected

Latest commit: 394d85a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@lynx-js/devtool-mcp-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces patch-level changes to the @lynx-js/devtool-mcp-server package, including new public exports (registerTool, defineTool, Schema), a build configuration adjustment for bundle handling, timeout logic modifications in ListClients, and removal of auto-start logic from ensureLynxConnected in favor of device-connected event triggering.

Changes

Cohort / File(s)	Change Summary
Changeset entries .changeset/olive-dodos-dress.md, .changeset/quiet-poems-turn.md	Added patch release changesets for @lynx-js/devtool-mcp-server documenting new public exports and client connection fixes
Build configuration packages/mcp-servers/devtool-mcp-server/rslib.config.ts	Modified dts bundle configuration from { bundle: true } to { bundle: { bundledPackages: [] } }
Public API exports packages/mcp-servers/devtool-mcp-server/src/index.ts	Exported registerTool function and added public exports for defineTool, ToolDefinition, and Schema namespace
Device connection logic packages/mcp-servers/devtool-mcp-server/src/connector.ts	Removed automatic startWatchClient() calls from ensureLynxConnected(), now only triggered by device-connected event
ListClients timeout handling packages/mcp-servers/devtool-mcp-server/src/tools/Device/ListClients.ts	Modified timeout branch to resolve if USB clients exist, otherwise reject with timeout error

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Timeout logic change in ListClients: Verify the conditional resolution on timeout doesn't introduce timing race conditions or unexpected state transitions
• Removal of auto-start logic: Confirm that the device-connected event reliably triggers watch client startup in all code paths previously covered by ensureLynxConnected()
• Build configuration change: Validate that bundledPackages: [] produces the intended bundling behavior and doesn't break downstream dependencies
• Public API surface expansion: Review the newly exposed utilities to ensure they're intended for public consumption and properly documented

Suggested reviewers

• upupming

Poem

🐰 New exports hop out to play,
Bundle configs find their way,
Connectors dance to events' call,
Timeouts resolve—clients rise tall! 🎪

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title describes fixing a connection issue and adding utilities, which aligns with the main changes: exporting registerTool and defineTool, fixing connection logic in connector.ts and ListClients.ts, and adding a patch for connection issues.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 0% with 10 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...devtool-mcp-server/src/tools/Device/ListClients.ts	0.00%	9 Missing ⚠️
...ckages/mcp-servers/devtool-mcp-server/src/index.ts	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codspeed-hq]

CodSpeed Performance Report

Merging #1931 will not alter performance

_{Comparing colinaaa:colin/1111/docs-mcp-server (394d85a) with main (a1e4e19)}

Summary

✅ 63 untouched
⏩ 3 skipped¹

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[relativeci]

Web Explorer

#6197 Bundle Size — 366.74KiB (0%).

394d85a(current) vs a1e4e19 main#6193(baseline)

Bundle metrics   1 change

	Current #6197	Baseline #6193
Initial JS	146.2KiB	146.2KiB
Initial CSS	32.22KiB	32.22KiB
Cache Invalidation	0%	0%
Chunks	8	8
Assets	8	8
Modules	219(-0.45%)	220
Duplicate Modules	16	16
Duplicate Code	3.21%	3.21%
Packages	4	4
Duplicate Packages	0	0

Bundle size by type  no changes

	Current #6197	Baseline #6193
JS	240.72KiB	240.72KiB
Other	93.8KiB	93.8KiB
CSS	32.22KiB	32.22KiB

Bundle analysis report Branch colinaaa:colin/1111/docs-mcp-ser... Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[relativeci]

React Example

#6167 Bundle Size — 234.35KiB (0%).

394d85a(current) vs 835e083 main#6154(baseline)

Bundle metrics  no changes

	Current #6167	Baseline #6154
Initial JS	0B	0B
Initial CSS	0B	0B
Cache Invalidation	0%	0%
Chunks	0	0
Assets	4	4
Modules	164	164
Duplicate Modules	66	66
Duplicate Code	46.71%	46.71%
Packages	2	2
Duplicate Packages	0	0

Bundle size by type  no changes

	Current #6167	Baseline #6154
IMG	145.76KiB	145.76KiB
Other	88.59KiB	88.59KiB

Bundle analysis report Branch colinaaa:colin/1111/docs-mcp-ser... Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

.changeset/quiet-poems-turn.md (1)

5-5: Polish the changeset description grammar.

The description has a minor grammar issue: "client" should be pluralized or the phrasing should be rephrased for clarity. Consider alternatives like "Fix client connection failures" or "Fix failed connections to clients."

Apply this diff to improve the description:

-Fix failed to connect to client.
+Fix client connection failures.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a1e4e19 and 394d85a.

📒 Files selected for processing (6)

• .changeset/olive-dodos-dress.md (1 hunks)
• .changeset/quiet-poems-turn.md (1 hunks)
• packages/mcp-servers/devtool-mcp-server/rslib.config.ts (1 hunks)
• packages/mcp-servers/devtool-mcp-server/src/connector.ts (0 hunks)
• packages/mcp-servers/devtool-mcp-server/src/index.ts (2 hunks)
• packages/mcp-servers/devtool-mcp-server/src/tools/Device/ListClients.ts (1 hunks)

💤 Files with no reviewable changes (1)

• packages/mcp-servers/devtool-mcp-server/src/connector.ts

🧰 Additional context used

📓 Path-based instructions (1)

.changeset/*.md

📄 CodeRabbit inference engine (AGENTS.md)

For contributions, generate and commit a Changeset describing your changes

Files:

• .changeset/olive-dodos-dress.md
• .changeset/quiet-poems-turn.md

🧠 Learnings (8)

📓 Common learnings

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1917
File: packages/mcp-servers/devtool-mcp-server/tsconfig.json:8-8
Timestamp: 2025-11-06T01:19:23.670Z
Learning: The lynx-js/devtool-mcp-server package in lynx-family/lynx-stack targets Node.js >=18.19 (specified in its package.json engines), which is different from the root project's requirement of Node.js ^22 || ^24. The package uses "lib": ["ES2024.Promise"] in its tsconfig.json because it manually includes polyfills for Promise.withResolvers while maintaining compatibility with Node.js v18.

Learnt from: gaoachao
Repo: lynx-family/lynx-stack PR: 1736
File: .changeset/spotty-experts-smoke.md:1-3
Timestamp: 2025-09-12T09:43:04.847Z
Learning: In the lynx-family/lynx-stack repository, private packages (marked with "private": true in package.json) like lynx-js/react-transform don't require meaningful changeset entries even when their public APIs change, since they are not published externally and only affect internal development.

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1917
File: packages/mcp-servers/devtool-mcp-server/src/connector.ts:347-368
Timestamp: 2025-11-06T01:17:11.892Z
Learning: In the lynx-family/lynx-stack repository, for the devtool-mcp-server package, the getSource and getConsole methods intentionally throw errors when collectors don't exist (rather than returning empty arrays) to provide clear feedback to code agents and automation tools that something is wrong (e.g., debugger not enabled, collectors not initialized), enabling them to take corrective action.

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1454
File: pnpm-workspace.yaml:46-46
Timestamp: 2025-08-07T04:00:59.645Z
Learning: In the lynx-family/lynx-stack repository, the webpack patch (patches/webpack5.101.0.patch) was created to fix issues with webpack5.99.9 but only takes effect on webpack5.100.0 and later versions. The patchedDependencies entry should use "webpack@^5.100.0" to ensure the patch applies to the correct version range.

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1558
File: .changeset/solid-squids-fall.md:2-2
Timestamp: 2025-08-19T11:25:36.127Z
Learning: In the lynx-family/lynx-stack repository, changesets should use the exact package name from package.json#name, not generic or unscoped names. Each package has its own specific scoped name (e.g., "lynx-js/react-transform" for packages/react/transform).

📚 Learning: 2025-09-12T09:43:04.847Z

Learnt from: gaoachao
Repo: lynx-family/lynx-stack PR: 1736
File: .changeset/spotty-experts-smoke.md:1-3
Timestamp: 2025-09-12T09:43:04.847Z
Learning: In the lynx-family/lynx-stack repository, private packages (marked with "private": true in package.json) like lynx-js/react-transform don't require meaningful changeset entries even when their public APIs change, since they are not published externally and only affect internal development.

Applied to files:

• .changeset/olive-dodos-dress.md
• .changeset/quiet-poems-turn.md

📚 Learning: 2025-11-06T01:19:23.670Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1917
File: packages/mcp-servers/devtool-mcp-server/tsconfig.json:8-8
Timestamp: 2025-11-06T01:19:23.670Z
Learning: The lynx-js/devtool-mcp-server package in lynx-family/lynx-stack targets Node.js >=18.19 (specified in its package.json engines), which is different from the root project's requirement of Node.js ^22 || ^24. The package uses "lib": ["ES2024.Promise"] in its tsconfig.json because it manually includes polyfills for Promise.withResolvers while maintaining compatibility with Node.js v18.

Applied to files:

• .changeset/olive-dodos-dress.md
• .changeset/quiet-poems-turn.md
• packages/mcp-servers/devtool-mcp-server/rslib.config.ts

📚 Learning: 2025-09-12T09:43:04.847Z

Learnt from: gaoachao
Repo: lynx-family/lynx-stack PR: 1736
File: .changeset/spotty-experts-smoke.md:1-3
Timestamp: 2025-09-12T09:43:04.847Z
Learning: In the lynx-family/lynx-stack repository, empty changeset files (containing only `---\n\n---`) are used for internal changes that modify src/** files but don't require meaningful release notes, such as private package changes or testing-only modifications. This satisfies CI requirements without generating user-facing release notes.

Applied to files:

• .changeset/olive-dodos-dress.md
• .changeset/quiet-poems-turn.md

📚 Learning: 2025-07-22T09:23:07.797Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1330
File: .changeset/olive-animals-attend.md:1-3
Timestamp: 2025-07-22T09:23:07.797Z
Learning: In the lynx-family/lynx-stack repository, changesets are only required for meaningful changes to end-users such as bugfixes and features. Internal/development changes like chores, refactoring, or removing debug info do not need changeset entries.

Applied to files:

• .changeset/olive-dodos-dress.md
• .changeset/quiet-poems-turn.md

📚 Learning: 2025-07-22T09:26:16.722Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1330
File: .changeset/olive-animals-attend.md:1-3
Timestamp: 2025-07-22T09:26:16.722Z
Learning: In the lynx-family/lynx-stack repository, CI checks require changesets when files matching the pattern "src/**" are modified (as configured in .changeset/config.json). For internal changes that don't need meaningful changesets, an empty changeset file is used to satisfy the CI requirement while not generating any release notes.

Applied to files:

• .changeset/olive-dodos-dress.md
• .changeset/quiet-poems-turn.md

📚 Learning: 2025-11-06T01:17:11.892Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1917
File: packages/mcp-servers/devtool-mcp-server/src/connector.ts:347-368
Timestamp: 2025-11-06T01:17:11.892Z
Learning: In the lynx-family/lynx-stack repository, for the devtool-mcp-server package, the getSource and getConsole methods intentionally throw errors when collectors don't exist (rather than returning empty arrays) to provide clear feedback to code agents and automation tools that something is wrong (e.g., debugger not enabled, collectors not initialized), enabling them to take corrective action.

Applied to files:

• .changeset/quiet-poems-turn.md

📚 Learning: 2025-08-07T04:00:59.645Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1454
File: pnpm-workspace.yaml:46-46
Timestamp: 2025-08-07T04:00:59.645Z
Learning: In the lynx-family/lynx-stack repository, the webpack patch (patches/webpack5.101.0.patch) was created to fix issues with webpack5.99.9 but only takes effect on webpack5.100.0 and later versions. The patchedDependencies entry should use "webpack@^5.100.0" to ensure the patch applies to the correct version range.

Applied to files:

• .changeset/quiet-poems-turn.md

🧬 Code graph analysis (2)

packages/mcp-servers/devtool-mcp-server/src/index.ts (1)

packages/mcp-servers/devtool-mcp-server/src/tools/defineTool.ts (1)

• ToolDefinition (28-44)

packages/mcp-servers/devtool-mcp-server/src/tools/Device/ListClients.ts (1)

packages/mcp-servers/devtool-mcp-server/src/McpContext.ts (1)

• connector (20-22)

🪛 LanguageTool

.changeset/quiet-poems-turn.md

[grammar] ~5-~5: The word ‘client’ is not correct in this context. Use one of the suggestions or replace it with an appropriate verb.
Context: ...rver": patch --- Fix failed to connect to client.

(VB_TO_NN_DT)

🔇 Additional comments (4)

packages/mcp-servers/devtool-mcp-server/src/tools/Device/ListClients.ts (1)

28-40: Good fix for timeout handling when clients connect during wait period.

The updated logic correctly handles the case where USB clients connect during the timeout window. Previously, the timeout would unconditionally reject. Now it checks connector.usbClients.size and resolves if clients are present, addressing the "failed to connect client" issue mentioned in the PR title.

The Promise.withResolvers pattern ensures only the first resolution (either from the event handler at lines 41-44 or this timeout handler) takes effect, preventing double-resolution issues.

packages/mcp-servers/devtool-mcp-server/rslib.config.ts (1)

12-21: LGTM! Correctly prevents bundling Zod types in declarations.

The change from dts: { bundle: true } to dts: { bundle: { bundledPackages: [] } } appropriately avoids inlining Zod types in the generated .d.ts files. This is necessary because the new public exports (ToolDefinition and Schema namespace) expose Zod types (z.ZodRawShape) in the public API, and consumers should use their own Zod version rather than having types bundled.

packages/mcp-servers/devtool-mcp-server/src/index.ts (2)

88-88: Exporting registerTool enables custom tool registration.

Making registerTool public is a significant API expansion that allows external consumers to register custom tools. The function signature and implementation are correct and consistent with the internal usage pattern at lines 122-124.

---

129-130: New public exports provide tool definition capabilities.

Exporting defineTool, ToolDefinition, and the Schema namespace expands the public API to enable consumers to create and register custom tools. This is consistent with the changeset description and aligns with the rslib.config.ts change that prevents bundling Zod types (since these exports expose Zod-based schemas).

Ensure these new exports are documented in the package README or API documentation, as they now form part of the public API contract.