feat(cli): add async server wait workflow - #410
Open
xizhibei wants to merge 4 commits into
Open
Conversation
|
Warning Review limit reached
Next review available in: 42 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (20)
📝 WalkthroughWalkthroughThis change adds load-aware inspect status contracts, a new ChangesAsync loading workflow
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant CLI as wait CLI
participant Surface as Reusable client surface
participant Inspect as /api/v1/inspect
participant Runtime as Loading tracker
CLI->>Surface: start authenticated wait workflow
Surface->>Inspect: poll tracked server status
Inspect->>Runtime: read loading state
Runtime-->>Inspect: return status and availability
Inspect-->>CLI: return connected, terminal, or timeout result
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (2)
docs/zh/commands/inspect.md (1)
21-21: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winBring the edited public command pages into the documentation contract.
docs/zh/commands/inspect.md#L21-L21: Add frontmatter and replace./wait.mdwith the absolute/zh/commands/waitlink.docs/zh/commands/run.md#L23-L23: Add required frontmatter.As per coding guidelines, “Include frontmatter for all public documentation pages” and “Use absolute internal links in documentation.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/zh/commands/inspect.md` at line 21, Update docs/zh/commands/inspect.md at lines 21-21 by adding the required frontmatter and replacing the relative ./wait.md link with the absolute /zh/commands/wait link. Update docs/zh/commands/run.md at lines 23-23 by adding the required frontmatter, following the existing public documentation page conventions.Source: Coding guidelines
src/commands/shared/clientSurfaceAttachment.test.ts (1)
194-215: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse the shared mock factories for the new test fixtures.
src/commands/shared/clientSurfaceAttachment.test.ts#L194-L215: Create the cached-session fixture throughtest/unit-utils/MockFactories.ts, extending it if needed.src/commands/wait/wait.test.ts#L7-L39: Create the attachment context and inspect-response fixture data through the shared factories.As per coding guidelines, “Use
test/unit-utils/MockFactories.tsfor consistent mock data and mock factories.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/commands/shared/clientSurfaceAttachment.test.ts` around lines 194 - 215, Use the shared mock factories from test/unit-utils/MockFactories.ts for both affected test fixtures: in src/commands/shared/clientSurfaceAttachment.test.ts lines 194-215, create the cached-session data through the appropriate factory and extend it with required fields; in src/commands/wait/wait.test.ts lines 7-39, create the attachment context and inspect-response data through the shared factories. Preserve each test’s existing behavior and assertions.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/en/commands/index.md`:
- Line 82: Update docs/en/commands/index.md lines 82-82 to describe wait as
waiting for configured static servers to become connected and available. Update
docs/en/commands/inspect.md lines 36-36 to state that scripts wait for servers
to be connected and available, and replace the relative ./wait.md link with the
absolute internal /commands/wait link.
In `@docs/en/guide/advanced/fast-startup.md`:
- Line 65: Update the readiness descriptions for the connected state in
docs/en/guide/advanced/fast-startup.md lines 65-65 and
docs/zh/guide/advanced/fast-startup.md lines 65-65 to clarify that tool
invocation requires both connected and available, not connected alone; preserve
the respective English and Chinese wording.
In `@src/commands/run/run.ts`:
- Around line 256-334: Update the status dispatch around the existing
connected-and-available check to explicitly handle server.status === 'connected'
with server.available === false. Route this transitional state through
statusErrorResponse using server_loading semantics, with guidance to wait for
the server to become available rather than suggesting a restart; leave the
existing pending/loading, OAuth, and generic unavailable branches unchanged.
In `@src/commands/wait/wait.ts`:
- Around line 69-70: Update the status handling around the wait command’s
attachment check to handle auth_required separately, preserving its original
error code and the context-aware recovery guidance from
formatClientSurfaceAuthRequiredMessage. Only non-authentication failures should
continue throwing server_status_unavailable with 1mcp inspect.
- Around line 47-55: Update waitCommand to validate and normalize the complete
WaitCommandOptions object with the project’s Zod schema before reading timeout
or starting attachment/polling. Include timeout, filter/tag, and format fields
in the boundary validation, then use the parsed options for subsequent logic
while preserving the existing positive-timeout requirement and WaitCommandError
behavior.
In `@src/transport/http/routes/inspectRoutes.ts`:
- Around line 435-454: Apply the same target authorization or scope gate used
for tool targets before the static-server early return in the inspect route.
Ensure out-of-scope static servers return 404 before exposing status,
authorizationUrl, or error metadata, while preserving the existing payload for
authorized static servers.
---
Nitpick comments:
In `@docs/zh/commands/inspect.md`:
- Line 21: Update docs/zh/commands/inspect.md at lines 21-21 by adding the
required frontmatter and replacing the relative ./wait.md link with the absolute
/zh/commands/wait link. Update docs/zh/commands/run.md at lines 23-23 by adding
the required frontmatter, following the existing public documentation page
conventions.
In `@src/commands/shared/clientSurfaceAttachment.test.ts`:
- Around line 194-215: Use the shared mock factories from
test/unit-utils/MockFactories.ts for both affected test fixtures: in
src/commands/shared/clientSurfaceAttachment.test.ts lines 194-215, create the
cached-session data through the appropriate factory and extend it with required
fields; in src/commands/wait/wait.test.ts lines 7-39, create the attachment
context and inspect-response data through the shared factories. Preserve each
test’s existing behavior and assertions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 7566ba78-fdb3-4ec3-982b-cbde8db4b728
📒 Files selected for processing (36)
README.mddocs/.vitepress/config/en.tsdocs/.vitepress/config/zh.tsdocs/en/commands/index.mddocs/en/commands/inspect.mddocs/en/commands/run.mddocs/en/commands/wait.mddocs/en/guide/advanced/fast-startup.mddocs/zh/commands/index.mddocs/zh/commands/inspect.mddocs/zh/commands/run.mddocs/zh/commands/wait.mddocs/zh/guide/advanced/fast-startup.mdsrc/commands/inspect/inspect.tssrc/commands/inspect/inspectUtils.tssrc/commands/instructions/instructionsUtils.tssrc/commands/run/run.rest-errors.test.tssrc/commands/run/run.rest-fallback.test.tssrc/commands/run/run.rest-primary.test.tssrc/commands/run/run.tssrc/commands/shared/apiClient.tssrc/commands/shared/clientSurfaceAttachment.test.tssrc/commands/shared/clientSurfaceAttachment.tssrc/commands/shared/commandRunner.test.tssrc/commands/shared/commandRunner.tssrc/commands/shared/filterSelectionQuery.tssrc/commands/shared/inspectApiSchemas.tssrc/commands/wait/index.tssrc/commands/wait/wait.test.tssrc/commands/wait/wait.tssrc/index.tssrc/transport/http/routes/apiRoutes.test.tssrc/transport/http/routes/inspectHelpers.test.tssrc/transport/http/routes/inspectHelpers.tssrc/transport/http/routes/inspectRoutes.tssrc/types/serverStatus.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
1mcp wait [server]and status-awarerunbehavior that never falls through to an unsafe early MCP sessionValidation
pnpm lintpnpm typecheckpnpm buildpnpm docs:buildpnpm test:unit(298 files, 4,333 tests)Existing Vitest mock-hoisting, VitePress highlighting/chunk-size, and Node deprecation warnings remain unchanged.
Closes #395
Closes #405
Summary by CodeRabbit
New Features
waitCLI command to monitor configured static servers until they are connected and available.runandinspectworkflows with clearer server readiness and recovery guidance.Documentation
waitcommand.