Skip to content

Add headless CLI and stdio MCP entry points (plan-only write gates) - #3

Open
xiaquwan1001 wants to merge 2 commits into
Redminote11tech:mainfrom
xiaquwan1001:feat/cli-and-mcp-entry
Open

xiaquwan1001 wants to merge 2 commits into
Redminote11tech:mainfrom
xiaquwan1001:feat/cli-and-mcp-entry

Conversation

@xiaquwan1001

Copy link
Copy Markdown

Follow-up to #1. Depends on nothing in #2 — the two branches are independent and can be merged in either order.

Why

The useful capability in this project is not the window: VcomFlasher, FastbootClient, FastbootFlasherService, OemInfoService, PartitionExtractor, Utils/UpdateApp, Utils/SuperMerger, Utils/ProcessRunner are already free of Avalonia. Reaching them currently requires a desktop session and a human clicking buttons, which makes scripted or agent-driven use impossible and makes diagnostics manual.

What

Cli/ (compiled into the main assembly):

  • exit codes 0 ok / 1 usage / 2 no device / 3 device refused / 4 gated / 5 file or environment;
  • read-only commands: info, doctor, getvar <name>, extract <UPDATE.APP> [outdir], dump <partition> -o <dir>;
  • write commands flash-ota, flash-xml, vcom-unlock, oeminfo, downgrade-enable implemented as plan-only gates: they print/return the exact partition list, sizes and image paths and exit 4. With --yes the status becomes confirmed-but-write-path-not-implemented and it still exits 4 — this build cannot write to a device;
  • --json on every command, diagnostics on stderr.

--mcp / mcp (also on the main executable, routed before Avalonia starts):

  • newline-delimited JSON-RPC 2.0 over stdio; initialize, notifications/initialized, ping, tools/list, tools/call;
  • tool schemas are generated from the same parameter metadata the CLI uses, so there is one source of truth;
  • write tools require confirm: true and still only return the plan; exit 4 is reported as a normal result (isError: false) because a gate is not a failure;
  • stdout carries protocol frames only; every log line goes to stderr.

KirinTool.Cli/ is a thin console project referencing the main project, so command implementations exist once.

Program.cs routes --mcp/mcp before StartWithClassicDesktopLifetime, so the MCP server never initializes a GUI. Kirin-Tool.csproj gains four Remove="KirinTool.Cli/**" entries to stop the root glob from compiling the sub-project's generated AssemblyInfo.cs twice (CS0579).

Verification

$ dotnet build -c Release --no-incremental
    149 个警告
    0 个错误

Same warning count as the main baseline. tools/list and tools/call were exercised through a piped stdin session (initialize → notifications/initialized → tools/list → four tools/call requests: extract exit 0, flash_ota without confirm exit 4 with a plan, getvar against a refusing device exit 3, unknown tool exit 1), with jq parsing each stdout line to confirm the frames are valid and that stderr stays separate.

Deliberate limits

  • no real write path anywhere (see above) — the gate is the feature;
  • no Content-Length framing, batching, SSE/HTTP transport, auth, or tools/list pagination;
  • Services/USBUpdate/* (bare Action progress) and DialogService → IUserInteraction are not extracted yet, so the USB Update path has no CLI equivalent;
  • vcom-unlock currently only builds a static plan; the interactive cable-swap step and ObservableCollection<ProgressItemViewModel> progress model are untouched;
  • no -s/--device selection yet.

Happy to restructure into a separate assembly, drop the MCP half, or extend the gate to a real write path behind an explicit flag — whichever direction you prefer.

The 14 service classes were already Avalonia-free, so the orchestration is
reused as-is instead of being copied:

- Cli/: command registry, arg parser, exit codes (0/1/2/3/4/5), read-only
  commands info/doctor/getvar/extract/dump, and gated write commands
  flash-ota/flash-xml/vcom-unlock/oeminfo/downgrade-enable that print their
  plan and exit 4 without ever touching a device.
- KirinTool.Cli/: thin console project referencing the main project so the
  command implementations exist only once.
- --mcp / mcp subcommand: newline-delimited JSON-RPC 2.0 over stdio with
  tools/list and tools/call; write tools require confirm:true and still only
  return the plan. All diagnostics go to stderr so stdout stays protocol-clean.
- Program.cs routes --mcp before Avalonia starts, so the MCP server never
  initializes a GUI.
Add a narrow GitHub Actions workflow that gates the headless CLI + stdio MCP
entry points: restore/build Kirin-Tool.csproj and KirinTool.Cli.csproj on
.NET 8, run hardware-free smoke tests (--help, version, doctor against a stub
fastboot, and an MCP initialize/tools-list session), then upload the CLI build
output. Firmware loaders and the bundled fastboot payload are excluded from the
artifact; only runtimes/linux-x64 is kept.

The upstream release pipeline in build.yml only runs on v* tags, so it cannot
gate a branch push.
xiaquwan1001 added a commit to xiaquwan1001/kirin-tool-linux-refresh that referenced this pull request Nov 10, 2026
把 CLI/MCP(Redminote11tech#3 的内容)与 Full OTA 真实写入路径(feat/ota-flash)合并进 fork 主线;上游 PR #2/Redminote11tech#3 的分支保持不动,等上游评审。
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.

1 participant