fix(docs-mcp-server): resolve package path on Windows startup by JohnieXu · Pull Request #2474 · lynx-family/lynx-stack

JohnieXu · 2026-04-17T14:19:19Z

Summary

Replace file URL pathname usage with fileURLToPath(import.meta.url) + dirname(...) before package discovery
Add a guard that throws a clear error when findPackage.up(...) cannot resolve package.json
Prevent startup crashes caused by readFile(undefined, 'utf-8') on Windows

Test plan

Verified code change is minimal and scoped to packages/mcp-servers/docs-mcp-server/main.ts
Build/test in CI (local install blocked by repo engine requirement: Node ^22 || ^24, current env is Node v20.19.0)

Summary by CodeRabbit

Bug Fixes
- Improved startup reliability with clearer error messages when initialization cannot find required configuration, preventing silent failures.
- Resolved a Windows startup issue that could prevent the service from launching.
Chores
- Added release metadata for a patch update to deploy the fix.

Resolve package.json lookup from file URL using fileURLToPath/dirname and add an explicit guard when package discovery fails, preventing startup crashes from readFile(undefined). Made-with: Cursor

changeset-bot · 2026-04-17T14:19:32Z

🦋 Changeset detected

Latest commit: 97de09a

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/docs-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 · 2026-04-17T14:19:54Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 58e641d3-4f4f-4d29-a9ad-34089986643d

📥 Commits

Reviewing files that changed from the base of the PR and between 4a5a06d and 97de09a.

📒 Files selected for processing (1)

.changeset/pink-items-deliver.md

✅ Files skipped from review due to trivial changes (1)

.changeset/pink-items-deliver.md

📝 Walkthrough

Walkthrough

The change updates package.json discovery in docs-mcp-server to compute the directory with dirname(fileURLToPath(import.meta.url)) and uses it as the cwd for findPackage.up(...); it also adds a runtime guard that throws if findPackage.up(...) fails to locate package.json.

Changes

Cohort / File(s)	Summary
Package.json discovery & runtime guard `packages/mcp-servers/docs-mcp-server/main.ts`	Replaced `new URL('.', import.meta.url).pathname` with `dirname(fileURLToPath(import.meta.url))` for directory resolution and added an explicit error throw when `findPackage.up(...)` returns undefined.
Release metadata `.changeset/pink-items-deliver.md`	Added a changeset for `@lynx-js/docs-mcp-server` marking a patch release referencing a Windows startup error fix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

docs-mcp-server crashes on Windows: readFile receives undefined path at startup #2473: Implements the same cross-platform path resolution fix and runtime guard for findPackage.up(...).

Possibly related PRs

feat: introduce @lynx-js/docs-mcp-server #1925: Modifies packages/mcp-servers/docs-mcp-server/main.ts to change directory derivation and package.json lookup logic (strong code-level overlap).

Poem

🐰 I hopped from URL to file with care,

dirname and fileURL led me there,
If package.json hides, I loudly cry,
"Find it or fail!" — beneath the sky,
A tiny rabbit, error-safe and spry.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly matches the main change: fixing a package path resolution issue on Windows startup in the docs-mcp-server.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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

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

cla-assistant · 2026-04-17T14:24:52Z

All committers have signed the CLA.

Signed-off-by: Qingyu Wang <40660121+colinaaa@users.noreply.github.com>

colinaaa

Thank you!

codecov · 2026-04-20T08:58:46Z

Codecov Report

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

Files with missing lines	Patch %	Lines
packages/mcp-servers/docs-mcp-server/main.ts	0.00%	7 Missing ⚠️

📢 Thoughts on this report? Let us know!

codspeed-hq · 2026-04-20T09:17:15Z

Merging this PR will improve performance by 16.77%

⚡ 1 improved benchmark
✅ 80 untouched benchmarks
⏩ 26 skipped benchmarks¹

Performance Changes

	Benchmark	`BASE`	`HEAD`	Efficiency
⚡	`transform 1000 view elements`	47.7 ms	40.8 ms	+16.77%

_{Comparing JohnieXu:fix/docs-mcp-windows-pkgpath (97de09a) with main (fb7bc84)}

26 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 · 2026-04-20T09:19:20Z

React External

#529 Bundle Size — 580.35KiB (0%).

97de09a(current) vs 3118b10 main#524(baseline)

Bundle metrics no changes

	Current #529	Baseline #524
Initial JS	`0B`	`0B`
Initial CSS	`0B`	`0B`
Cache Invalidation	`0%`	`0%`
Chunks	`0`	`0`
Assets	`3`	`3`
Modules	`17`	`17`
Duplicate Modules	`5`	`5`
Duplicate Code	`8.59%`	`8.59%`
Packages	`0`	`0`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #529	Baseline #524
Other	`580.35KiB`	`580.35KiB`

Bundle analysis report Branch JohnieXu:fix/docs-mcp-windows-pk... Project dashboard

^{Generated by RelativeCI Documentation Report issue}

relativeci · 2026-04-20T09:19:21Z

React MTF Example

#545 Bundle Size — 193.94KiB (0%).

97de09a(current) vs 3118b10 main#540(baseline)

Bundle metrics no changes

	Current #545	Baseline #540
Initial JS	`0B`	`0B`
Initial CSS	`0B`	`0B`
Cache Invalidation	`0%`	`0%`
Chunks	`0`	`0`
Assets	`3`	`3`
Modules	`173`	`173`
Duplicate Modules	`66`	`66`
Duplicate Code	`43.94%`	`43.94%`
Packages	`2`	`2`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #545	Baseline #540
IMG	`111.23KiB`	`111.23KiB`
Other	`82.71KiB`	`82.71KiB`

Bundle analysis report Branch JohnieXu:fix/docs-mcp-windows-pk... Project dashboard

^{Generated by RelativeCI Documentation Report issue}

relativeci · 2026-04-20T09:19:24Z

Web Explorer

#8986 Bundle Size — 898.09KiB (-0.03%).

97de09a(current) vs 3118b10 main#8981(baseline)

Bundle metrics

3 changes

	Current #8986	Baseline #8981
Initial JS	`44.47KiB`	`44.47KiB`
Initial CSS	`2.16KiB`	`2.16KiB`
Cache Invalidation	`13.64%`	`0%`
Chunks	`9`	`9`
Assets	`11`	`11`
Modules	`230`(`-0.43%`)	`231`
Duplicate Modules	`11`	`11`
Duplicate Code	`27.21%`(`+0.04%`)	`27.2%`
Packages	`10`	`10`
Duplicate Packages	`0`	`0`

Bundle size by type

1 change

1 improvement

	Current #8986	Baseline #8981
JS	`494.3KiB` (`-0.05%`)	`494.55KiB`
Other	`401.63KiB`	`401.63KiB`
CSS	`2.16KiB`	`2.16KiB`

Bundle analysis report Branch JohnieXu:fix/docs-mcp-windows-pk... Project dashboard

^{Generated by RelativeCI Documentation Report issue}

relativeci · 2026-04-20T09:19:26Z

React Example

#7412 Bundle Size — 223.33KiB (0%).

97de09a(current) vs 3118b10 main#7407(baseline)

Bundle metrics no changes

	Current #7412	Baseline #7407
Initial JS	`0B`	`0B`
Initial CSS	`0B`	`0B`
Cache Invalidation	`0%`	`0%`
Chunks	`0`	`0`
Assets	`4`	`4`
Modules	`179`	`179`
Duplicate Modules	`69`	`69`
Duplicate Code	`44.48%`	`44.48%`
Packages	`2`	`2`
Duplicate Packages	`0`	`0`

Bundle size by type no changes

	Current #7412	Baseline #7407
IMG	`145.76KiB`	`145.76KiB`
Other	`77.58KiB`	`77.58KiB`

Bundle analysis report Branch JohnieXu:fix/docs-mcp-windows-pk... Project dashboard

^{Generated by RelativeCI Documentation Report issue}

fix(docs-mcp-server): handle package path resolution on Windows

4a5a06d

Resolve package.json lookup from file URL using fileURLToPath/dirname and add an explicit guard when package discovery fails, preventing startup crashes from readFile(undefined). Made-with: Cursor

Create pink-items-deliver.md

97de09a

Signed-off-by: Qingyu Wang <40660121+colinaaa@users.noreply.github.com>

colinaaa approved these changes Apr 20, 2026

View reviewed changes

colinaaa linked an issue Apr 20, 2026 that may be closed by this pull request

docs-mcp-server crashes on Windows: readFile receives undefined path at startup #2473

Closed

colinaaa merged commit 99172f1 into lynx-family:main Apr 20, 2026
100 of 107 checks passed

github-actions Bot mentioned this pull request Apr 20, 2026

chore: Release 2026-04-24 14:53:52 #2477

Open

Conversation

JohnieXu commented Apr 17, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Poem

Uh oh!

cla-assistant Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

colinaaa left a comment

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codspeed-hq Bot commented Apr 20, 2026

Merging this PR will improve performance by 16.77%

Performance Changes

Footnotes

Uh oh!

relativeci Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React External

#529 Bundle Size — 580.35KiB (0%).

Uh oh!

relativeci Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React MTF Example

#545 Bundle Size — 193.94KiB (0%).

Uh oh!

relativeci Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Web Explorer

#8986 Bundle Size — 898.09KiB (-0.03%).

Uh oh!

relativeci Bot commented Apr 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

React Example

#7412 Bundle Size — 223.33KiB (0%).

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JohnieXu commented Apr 17, 2026 •

edited by coderabbitai Bot

Loading

changeset-bot Bot commented Apr 17, 2026 •

edited

Loading

coderabbitai Bot commented Apr 17, 2026 •

edited

Loading

cla-assistant Bot commented Apr 17, 2026 •

edited

Loading

codecov Bot commented Apr 20, 2026 •

edited

Loading

relativeci Bot commented Apr 20, 2026 •

edited

Loading

relativeci Bot commented Apr 20, 2026 •

edited

Loading

relativeci Bot commented Apr 20, 2026 •

edited

Loading

relativeci Bot commented Apr 20, 2026 •

edited

Loading