Skip to content

docs: add command line and MCP server guide - #430

Merged
NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
Bruce-Yii:docs/cli-mcp-guide
Sep 29, 2026
Merged

NandhaKishorM merged 3 commits into
NandhaKishorM:mainfrom
Bruce-Yii:docs/cli-mcp-guide

Conversation

@Bruce-Yii

@Bruce-Yii Bruce-Yii commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

What

  • Add docs/cli-mcp.md, a task-oriented guide for choosing and using the local laya CLI versus the built-in MCP stdio server.
  • Link the guide from docs/index.md and remove the index's stale claim that CLI/MCP material is README-only.
  • Keep the change documentation-only; no runtime, public API, README, HTTP API, or .nav.yml changes.

Why

YU-86 covers the standalone Command line and MCP server item in #390. The README has short summaries, but readers need one page that explains the interface boundary, source-backed commands/tools, first-use model loading, MCP client configuration, environment variables, and the structured-decision/action boundary.

This intentionally does not duplicate the adjacent Routing (#416) or Questions and answers (#418) guides, and does not absorb the still-coordinated HTTP API surface.

Source verification

How it was verified

python tests/test_cli.py                         22 passed, 0 failed
python tests/test_mcp.py (temporary mcp 2.2.0)  86 passed, 0 failed
python tests/test_packaging.py                  42 passed, 0 failed
python tests/test_doc_tables.py                 54 passed, 0 failed
python -m compileall -q laya tests              passed
python -m ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120
                                                   All checks passed
zensical build --strict --clean                  No issues found
git diff --check                                  passed

Checklist

  • Focused on one change
  • Based on the latest main
  • Tests and strict documentation build pass locally
  • Documentation-only; no public API change

Refs #390

@NandhaKishorM

Copy link
Copy Markdown
Owner

Thanks, this is a well-researched page, and the preset and environment tables match the code. Three small fixes: the stock laya-mcp-server builds its Router without hooks and has no way to configure them, so please say hooks only fire if a custom launcher installs them (for example with set_default_hooks). Please describe noul as the probability of true rather than a calibrated one, since the checkpoints ship over-confident. And mention that an empty line also ends interactive mode. #480 has landed and edits the same last sentence of docs/index.md, so please rebase; the closing sentence should then list only routing, the HTTP API and confidence gating.

@aashish254

Copy link
Copy Markdown
Contributor

Heads up from the check rather than a review: #564 lands the MCP side of the line about "the two
entry points expose different preset aliases". If that one merges, laya_preset accepts the same
five presets the CLI does -- email joins guard, moderation, triage and model_router -- and
router resolves to model_router, so those two sentences in the tool table collapse into one
list with one long-form name, and the note about the CLI placing text under the preset's state
field becomes true on both surfaces.

Docs are your lane, so I have not touched a word of them. Fold it in whenever is convenient, or
say the word and I will send just those lines as a commit on your branch.

@Bruce-Yii

Bruce-Yii commented Sep 26, 2026 via email

Copy link
Copy Markdown
Contributor Author

Rebases onto current main and re-verifies the page against the code it
describes, then fixes four statements that current main no longer supports.

The rebase needed care. The previous head was a merge commit, and the
maintainer's requested corrections lived in that merge's hand-resolved
conflict resolution rather than in an ordinary commit. A plain rebase drops
merges, so replaying the branch produced a page that silently lost all three
of them. The guide is restored with those corrections intact, plus the
`laya_shortlist` and `laya eval` sections.

Corrected against the code:

* `laya_predict_batch`, `laya_route_batch` and `laya_decide` are registered by
  the MCP server but were missing from the "Available tools" table, which
  listed five of the eight tools. The 0.3.21 sweep put batching and the token
  budget on every surface; this page still described the pre-batch set.
* `LAYA_AUTO_TASK` is read by the MCP server (`auto_task_detection=`) and
  documented in its module docstring, but was absent from the environment
  table.
* The preset paragraph claimed the two entry points expose different preset
  aliases. They no longer do: `laya_preset` now carries all five presets the
  CLI has, with `router` accepted as an alias for the canonical `model_router`,
  and it performs the same state-field placement. The paragraph now states the
  shared list once and notes the alias, instead of describing a difference
  that no longer exists.

Verified still true, and left as written: the stock `laya-mcp-server` launcher
builds its Router without installing hooks (there is no hook reference anywhere
in `laya/mcp/server.py`), `laya.hooks.set_default_hooks` is the documented way
to install them, `noul` is the probability of true, an empty line ends
interactive mode, `DEFAULT_SHORTLIST_K` is 20 with mean-pooled embeddings from
the answering checkpoint's own encoder, the transport is stdio only, and the
three README anchors this page links to still exist.

`docs/index.md`'s closing sentence now lists only routing, the HTTP API and
confidence gating, as requested, with the guide's own table row carrying the
command line and MCP server.

Checks: `tests/test_doc_tables.py` 109 passed, `tests/test_packaging.py` 106
passed. All five relative links in the guide resolve. The docs workflow's
`zensical build --strict` gate was not run locally — zensical is not installed
in this environment.
@Bruce-Yii

Copy link
Copy Markdown
Contributor Author

Rebased onto current main, and the three fixes are in: hooks now say the stock launcher installs none, noul is the probability of true, and an empty line ends interactive mode. docs/index.md's closing sentence lists only routing, the HTTP API and confidence gating.

#564 has landed, so I folded in the preset lines rather than leaving them for later. The paragraph no longer claims the two entry points expose different aliases — laya_preset now carries all five the CLI has, router is accepted as an alias for the canonical model_router, and it performs the same state-field placement. I checked that against laya/mcp/tools.py and laya/cli.py rather than taking the description on trust; the placement claim holds, with the nuance that MCP needs a one-key object rather than a bare string.

Verifying the rest of the page against the code turned up three more things the 0.3.21 sweep invalidated:

  • laya_predict_batch, laya_route_batch and laya_decide are registered by the server but were missing from the tools table, which listed five of the eight.

  • LAYA_AUTO_TASK is read by the MCP server and documented in its own docstring, but was absent from the environment table.

  • A rebase note, in case it bites anyone else: the previous head was a merge commit, and the corrections above lived in that merge's conflict resolution rather than in a normal commit. A plain rebase drops merges and silently loses them, so the page came back without all three until I restored them. Worth knowing before anyone rebases a docs branch here.

Still true and left as written: the stock launcher builds its Router with no hooks anywhere in laya/mcp/server.py, laya.hooks.set_default_hooks is the way to install them, the shortlist default is k=20 off the answering checkpoint's own encoder, and the transport is stdio only. tests/test_doc_tables.py and tests/test_packaging.py pass, and all five relative links resolve. I could not run the docs workflow's zensical build --strict locally — zensical is not installed here.

One thing that is not mine: dependency CVEs fails on this PR, and it is failing on every PR built today across four different branches, including a Dependabot one. The log reports 7 known vulnerabilities in 3 declared packages, json-repair 0.25.2 among them with a fix in 0.60.1. Nothing in this diff touches a dependency — it is two documentation files. Flagging it because it will gate your merge button for everyone until those are bumped.

@NandhaKishorM
NandhaKishorM merged commit 063a125 into NandhaKishorM:main Sep 29, 2026
22 of 23 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Passed checks and merged. Thank you @Bruce-Yii! It ships in 0.3.22.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants