devserver

---
name: devserver
description: Build, test, and maintain the Uno DevServer (CLI tool, RemoteControl Host, MCP proxy, add-in discovery). Use when working under src/Uno.UI.DevServer.Cli, src/Uno.UI.RemoteControl.Host, or src/Uno.UI.RemoteControl.DevServer.Tests, or on DevServer CLI commands, the MCP proxy, IDE channel, or add-in resolution.
---

# DevServer (CLI / Host / MCP)

Maintain and extend the Uno DevServer: the CLI tool, the Host process, MCP proxy integration, and add-in discovery. The DevServer projects are **independent of the UI framework** and do **not** require `crosstargeting_override.props`.

## 1. Architecture — a 2-process chain

1. **CLI** (`Uno.UI.DevServer.Cli`) – entry point, user-facing commands, MCP STDIO proxy, start-lifecycle management.
2. **Host** (`Uno.UI.RemoteControl.Host`) – ASP.NET Core server for Hot Reload, IDE channel, processors.

The CLI `start` command handles existing-server detection (AmbientRegistry), IDE channel rebinding, port allocation, and launches the Host in **direct mode** (no `--command`), so all arguments (including `--ideChannel`) reach the Host via `IConfiguration` regardless of Host binary version. Non-start commands (`stop`, `list`, `cleanup`) use the Host's controller mode (`--command=<verb>`). The CLI can also run in **MCP mode** (`--mcp-app`) as a Model Context Protocol proxy between AI agents and the running Host.

### Packages
| NuGet Package | Contents |
|---------------|----------|
| `Uno.DevServer` | CLI tool (installed via `dotnet tool`) |
| `Uno.WinUI.DevServer` | Host binaries, processors, BuildTransitive targets |

## 2. Source map
| Directory | Purpose |
|-----------|---------|
| `src/Uno.UI.DevServer.Cli/` | CLI tool: commands, helpers, MCP proxy |
| `src/Uno.UI.DevServer.Cli/Helpers/` | Discovery, caching, process helpers |
| `src/Uno.UI.DevServer.Cli/Mcp/` | MCP server, client proxy |
| `src/Uno.UI.RemoteControl.Host/` | Host process: server, extensibility, IDE channel |
| `src/Uno.UI.RemoteControl.Host/Extensibility/` | Add-in loading and discovery |
| `src/Uno.UI.RemoteControl.DevServer.Tests/` | Unit and integration tests |
| `build/test-scripts/` | PowerShell integration test harness |
| `build/nuget/Uno.WinUI.DevServer.nuspec` | NuGet package definition |

Key files: `CliManager.cs` (command router), `UnoToolsLocator.cs` (SDK/package discovery from global.json, NuGet cache, AmbientRegistry), `TargetsAddInResolver.cs` (fast add-in discovery via `.targets` XML), `ManifestAddInResolver.cs` (manifest-first discovery from `devserver-addin.json`), `DotNetVersionCache.cs`, `McpStdioServer.cs`, `ProxyLifecycleManager.cs`, `McpUpstreamClient.cs`, `ToolListManager.cs`, `DevServerMonitor.cs` (+ `MonitorDecisions.cs`, pure decision logic for testability), `HealthService.cs`/`HealthReport.cs`, `DiscoveryIssueMapper.cs`, `ConnectionState.cs`, `SolutionFileFinder.cs`; Host: `RemoteControlServer.cs` (WebSocket server, processors), `AddIns.cs` (discovery + assembly loading).

## 3. Build & test
```bash
dotnet build src/Uno.UI.DevServer.Cli/Uno.UI.DevServer.Cli.csproj
dotnet build src/Uno.UI.RemoteControl.Host/Uno.UI.RemoteControl.Host.csproj
dotnet test  src/Uno.UI.RemoteControl.DevServer.Tests/Uno.UI.RemoteControl.DevServer.Tests.csproj
```
The test project **links source files** from CLI/Host (rather than referencing outputs) to avoid circular dependencies — when adding a new source file for testing, add a `<Compile Include>` link in the `.csproj`. Integration tests: `build/test-scripts/run-devserver-cli-tests.ps1` with `-DevServerCliDllPath`. Test conventions: MSTest + AwesomeAssertions, naming `Test_WhenCondition_ShouldExpectation`, sequential (`[assembly: Parallelize(Workers = 1)]`), temp dirs + injectable delegates for subprocess mocking.

## 4. CLI commands & flags
Commands: `start`, `stop`, `list`, `disco` (discover env/SDK/active server), `login` (open Uno settings app), `--mcp-app` (MCP STDIO proxy mode).
Flags: `-l trace`, `-fl <path>` (file logging, `{Date}` token), `--json` (disco output), `--addins-only`, `--mcp-wait-tools-list`, `--force-roots-fallback` (legacy override; auto-detected now), `--solution-dir <path>`.

## 5. Add-in discovery — three paths
1. **Manifest-first** (`devserver-addin.json`): `ManifestAddInResolver` resolves entry points directly, with `minHostVersion` gating.
2. **Fast `.targets` parse (~200ms)**: `TargetsAddInResolver` parses `packages.json` + `buildTransitive/*.targets` for `<UnoRemoteControlAddIns>` without invoking MSBuild.
3. **MSBuild fallback (10-30s)**: Host runs `dotnet build` evaluation; `--addins` (opt-in) bypasses this when the CLI pre-resolves paths.

## 6. MCP proxy
`McpStdioServer.cs` / `ProxyLifecycleManager.cs` bridge AI agents to the Host over STDIO: returns tool defs while the Host launches in the background, sends `tools/list_changed` when tools are ready, detects client `roots` support.

**MCP roots — two modes:** some clients support roots (Claude Code, VS Code Copilot, Cursor); others don't (Windsurf, JetBrains, Gemini CLI, Claude Desktop).
- **Default**: DevServer starts immediately using `--solution-dir`/cwd; requests roots if supported; auto-enables roots fallback (agent calls `uno_app_initialize`) when unresolved + no roots support.
- **`--force-roots-fallback`**: defers startup until `uno_app_initialize`. Rarely needed.
`StartOnceGuard` (`MonitorDecisions.cs`) prevents duplicate starts when roots arrive after an immediate start.

**Solution discovery** (`SolutionFileFinder`): recursive `.sln`/`.slnx` search up to **3 levels deep**, respects `.gitignore` (via `git check-ignore`), falls back to a skip list (`node_modules`, `bin`, `obj`, `.vs`, `.idea`, `packages`) when git is unavailable.

**ConnectionState lifecycle** (`Mcp/ConnectionState.cs`):
```
Initializing → Discovering → Launching → Connecting → Connected
                                                ↓ (crash)
                                          Reconnecting → Discovering (cycle)
                                                ↓ (max retries)
                                             Degraded
```
Two retry counters: DevServerMonitor (3 startup attempts) and ProxyLifecycleManager (3 crash→restart cycles).

## 7. Common maintenance tasks
- **Add a CLI command**: handle in `CliManager.cs` (follow `start`/`stop`/`disco`), add help in `Program.cs`, add an integration test in `run-devserver-cli-tests.ps1`.
- **Modify Host startup**: `Program.cs` (routing), `Startup.cs` (ASP.NET config); test via `dotnet run` from the Host dir.
- **Modify add-in discovery**: `TargetsAddInResolver.cs` (+ `TargetsAddInResolverTests.cs`); verify with `uno-devserver disco --json` in a real project.
- **Modify MCP proxy**: `McpStdioServer.cs`/`ProxyLifecycleManager.cs`/`ToolListManager.cs`; test with `--mcp-app` + an MCP client; check `--mcp-wait-tools-list` for clients without `tools/list_changed`.

## 8. IDE compatibility constraints
All launchers use **direct Host launch**; the controller path (`--command start`) is only for non-start commands. The CLI `start` (`StartCommandHandler`) manages the start lifecycle itself. Consequences:
- AmbientRegistry duplicate protection exists for CLI-launched instances, **not** IDE-launched; multiple instances per solution are possible (IDE + CLI, or IDE + MCP).
- `--addins` MUST stay opt-in: absence = MSBuild discovery unchanged.
- `disco --json` returns an `activeServer` field (null, or `processId`/`port`/`mcpEndpoint`/`parentProcessId`/`startTime`) from AmbientRegistry — the recommended way for extensions to detect a running server.

**Visual Studio** (`uno.studio`): probes `Uno.UI.RemoteControl.VS.EntryPoint` and constructor signatures v2/v3 via **reflection** — **never rename or change those constructor signatures** without coordinating with the VS extension team; `EntryPointRegressionTests.cs` guards the contract. Launch resolves `tools/rc/host/net{major}.0/Uno.UI.RemoteControl.Host.dll` and launches directly with `--httpPort/--ppid/--solution`.
**Rider** (`uno.rider`): inspects project references for `uno.winui.devserver`, derives host path from `dotnet --version`; fallback `dotnet build /t:GetRemoteControlHostPath`.
**VS Code** (`uno.vscode`): delegates to the CLI — `dotnet dnx uno.devserver start --httpPort {port} --ideChannel {guid} --solution {sln}`; supports external-host debug via `.uno.vscode.remote-control` marker.
**Host CLI contract**: args via `ConfigurationBuilder.AddCommandLine()`; `--addins` opt-in for backward compatibility.

## 9. References
- `doc/articles/dev-server.md`
- `src/Uno.UI.DevServer.Cli/health-diagnostics.md`, `src/Uno.UI.DevServer.Cli/addin-discovery.md`
- `specs/001-fast-devserver-startup/`
- `build/test-scripts/run-devserver-cli-tests.ps1`, `build/nuget/Uno.WinUI.DevServer.nuspec`

More agent context in unoplatform/uno

21 other files this repository gives its agents.