mirror of https://github.com/callstack/agent-device.git synced 2026-09-14 20:06:34 +08:00

Files

T

Michał Pierzchała 6a8beb653e feat(mcp): compact server instructions in both eras + MCP-only help tool (#1839 )

* feat(mcp): compact server instructions in both eras + MCP-only help tool (#1833)

MCP-only clients got no workflow guidance: server/discover carried two
sentences, legacy initialize carried nothing, and the CLI guides
(agent-device --help, help <topic>) were unreachable over MCP.

- MCP_SERVER_INSTRUCTIONS: one MCP-phrased workflow card (<2 KB, the
  Claude Code truncation limit) returned by server/discover and legacy
  initialize alike.
- help tool, router-owned (not a command descriptor): no topic -> the CLI
  decision card; topic -> agent-device help <topic|command> text, prefixed
  with the one-line CLI->tool-property mapping; unknown topic -> isError
  listing the topics. listCommandTools() stays descriptor-only for the AI
  SDK; the router composes descriptors + help.
- Move src/cli/parser/cli-help{,-overview}.ts to src/cli-schema/ so
  src/mcp (rank 3) can import the renderers without a layering back-edge
  into src/cli (rank 6).

* fix(mcp): name terminal-only commands in help guides; colocate cli-help tests with their sources

- The MCP guide preamble claimed every `agent-device <command>` line is a
  tool of that name; `help web` tells the reader to run `web setup` /
  `web doctor` and no `web` tool exists. The preamble now lists the exact
  CLI-only set (listCliCommandNames minus listMcpExposedCommandNames) —
  derived, not scanned out of prose where `device`/`web` are ordinary
  words. Regression: help web names `web` as terminal-only, and the listed
  set equals the registry difference.
- cli-help-*.test.ts move from src/cli/parser/__tests__ to src/cli-schema/
  to mirror the moved sources.

* perf(mcp): tighten the guide card, tool description, and preamble

Instructions card 1572 -> 1378 bytes (paid every session), tool
description and preamble trimmed, HELP_TOOL built once as a const.
Bundle delta vs main 3189 -> 2715 bytes; the remainder is the guide text
itself, which the bundle carried in no MCP-phrased form before.

2026-08-18 17:48:36 +02:00

3.0 KiB

Raw Permalink Blame History

Adding a CLI Flag

A new flag touches only the layers that need to understand it. Stop at the layer where it stops mattering — threading it further is the common failure, not stopping too early.

packages/contracts/src/cli-flags.ts: add to CliFlags; add the definition to the matching src/commands/cli-grammar/flag-definitions-*.ts owner and the relevant group in flag-groups.ts (for example SNAPSHOT_FLAGS). Then update the command family metadata/schema that exposes the flag; find the owner with rg -n "<command>|supportedFlags|allowedFlags" src/commands src/cli-schema src/cli/parser. For schema-only CLI commands (cdp, auth, connect, proxy, react-devtools, web) the owner is SCHEMA_ONLY_CLI_COMMAND_SCHEMAS in src/cli-schema/command-overrides.ts. New flags are operator-only by default. Add a flag to PROJECT_CONFIG_FLAG_KEYS in src/cli-schema/cli-config.ts only when repository control is safe; this positive allowlist is the completeness gate.
src/commands/cli-grammar/*: read the CLI flag into command input.
src/commands/command-projection.ts and command-family projection helpers: write the input into the daemon request only if the flag affects daemon execution.
src/commands/*-command-contracts.ts: add to the command input schema only if the option should be available through Node.js or MCP as structured input.
src/client/client-types.ts: update the public typed client option only when the Node.js interface exposes it.
src/client/client-normalizers.ts: update daemon flag normalization only when the request still needs a public-to-internal translation.
src/daemon/context.ts and src/core/dispatch-context.ts: add the field only when it flows into platform dispatch.
Handler/platform modules: thread the option only after the command surface, grammar, and projection prove it belongs there.
scripts/integration-progress-model.ts: classify the flag (device-observable vs intentionally-outside). The architecture-progress gate fails CI on unclassified public flags.
If the flag changes interaction semantics, revisit the affected cells in packages/contracts/src/interaction-guarantees.ts (scope with appliesTo when the flag exists only on some commands).

Command-only flags (like find --first) that never reach the platform layer usually stop at steps 1-3, plus step 9.

Where CLI help and schema live

Long help prose: src/cli-schema/cli-help.ts. Flag definitions: src/commands/cli-grammar/.
Command-specific usage/flag metadata lives with the command family metadata that owns the command.
Parser/help rendering stays in src/cli/parser/; command schema metadata is derived from command metadata, family declarations, and the schema-only merge path in src/cli-schema/command-overrides.ts. Keep the two separate.
Locating an owner: rg -n "helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser src/cli-schema.

3.0 KiB Raw Permalink Blame History

Adding a CLI Flag

Where CLI help and schema live

3.0 KiB

Raw Permalink Blame History