Document async loading sub-parameters (--async-min-servers, --async-timeout, --async-batch-notifications)

[RCrushMe]

Summary

The async loading sub-parameters are accepted by the CLI and listed in 1mcp serve --help, but none of them appear in any of the 78 documentation pages under docs/en/ (or docs/zh/). Only the parent flag --enable-async-loading is documented (in fast-startup.md, configuration.md, and serve.md).

Undocumented parameters

Parameter	In --help?	In docs?	Recommended value documented?
--async-min-servers <n>	Yes	No	No
--async-timeout <ms>	Yes	No	No
--async-batch-notifications	Yes	No	No
--async-batch-delay <ms>	Yes	No	No
--async-notify-on-ready	Yes	No	No

Why it matters

• fast-startup.md promotes async loading as a key feature but only shows --enable-async-loading with no tuning guidance.
• configuration.md lists --enable-config-reload and --config-reload-debounce with example values (1000, 2000), but the async family gets no equivalent treatment.
• Users running 20+ upstream servers need --async-min-servers and --async-timeout to control the readiness gate, but there is no documentation explaining what these values do or how to choose them.
• --async-batch-notifications is critical for preventing notification spam when many servers come online concurrently, yet its behavior is only discoverable by reading source code.

Suggested fix

Add a section to docs/en/guide/advanced/fast-startup.md (and the zh equivalent) covering:

1. What each sub-parameter controls
2. Recommended values for small (1-5 servers) vs large (20+ servers) deployments
3. How --async-min-servers interacts with the readiness gate and /health/ready
4. How --async-batch-notifications and --async-batch-delay reduce listChanged notification volume
5. A production example combining the full async family

Environment

• @1mcp/agent v0.34.4
• Verified against 1mcp serve --help output and full-text search of all 78 files in docs/en/

[xizhibei]

Thanks for catching this. Some readiness options are exposed but not currently enforced, so we need to correct that behavior before documenting recommended values.

[xizhibei]

This was generated by AI during triage.

Confirmed problem

This is a runtime-contract bug as well as a documentation gap. --async-min-servers and --async-timeout are parsed and stored but have no runtime consumers. They do not delay request acceptance, affect /health/ready, or gate capability publication. The same ineffective settings are accepted through ONE_MCP_* environment variables and asyncLoading.minServers / asyncLoading.timeout in config.toml.

The notification controls are functional, but --async-notify-on-ready no longer describes current behavior. Capability publication is atomic: the loading cycle waits for all configured backends to reach a terminal state, publishes one changed snapshot, then emits listChanged notifications.

Accepted contract

• Preserve immediate HTTP listener availability during async backend loading.
• Preserve atomic capability publication after all configured backends reach a terminal state.
• Deprecate --async-min-servers, --async-timeout, their ONE_MCP_* equivalents, and asyncLoading.minServers / asyncLoading.timeout as compatibility no-ops. Warn when explicitly supplied, then remove them in the next breaking release.
• Keep --async-batch-notifications and --async-batch-delay. Document them as coalescing capability-change events within the delay window; they do not create a readiness gate.
• Add --async-notify-on-snapshot for the existing async-specific notification gate. It sends notifications only when a completed loading cycle publishes a changed capability snapshot and global --enable-client-notifications remains enabled.
• Keep --async-notify-on-ready as a deprecated compatibility alias for one window, with a warning. If both names are explicitly supplied, the canonical --async-notify-on-snapshot value wins.

Acceptance criteria

• Explicit use of every deprecated CLI, environment, or TOML input emits a clear startup warning without changing startup timing.
• Default startup emits no deprecation warning.
• The new notification flag, deprecated alias, global notification gate, and explicit conflict precedence have focused tests.
• English and Chinese docs describe immediate listener availability, atomic snapshot publication, notification batching, and the deprecation path.
• Docs state that /health/ready represents configuration readiness; backend loading progress belongs to /health/mcp.
• Docs do not recommend server-count thresholds or claim that the retired settings enforce readiness.
• CLI help and config schema descriptions match the accepted contract.
• pnpm lint, pnpm typecheck, focused unit tests, and pnpm docs:build pass.

The current draft PR #398 cannot merge as written because it documents the two no-op readiness settings as functional. It needs implementation and documentation revisions matching this contract.