Repository navigation
Requirements Director
This document tracks functional and technical requirements for the McpServerManager.Director CLI and TUI application.
A console application (McpServerManager.Director) shall provide agent orchestration commands (init, add, launch, ban, unban, delete, merge, login, list, agents, validate, interactive) dispatched through the CQRS framework. Authentication uses OIDC Device Authorization Flow with the configured provider. Interactive mode uses Terminal.Gui v2 with ViewModel-bound screens.
Status: ✅ Complete
Covered by: McpServerManager.Director project — 15 source files: Program.cs, McpHttpClient.cs, Auth/DirectorAuthOptions.cs, Auth/OidcAuthService.cs, Auth/TokenCache.cs, Commands/AuthCommands.cs, Commands/CommandHelpers.cs, Commands/DirectorCommands.cs, Commands/InteractiveCommand.cs, Screens/MainScreen.cs, Screens/HealthScreen.cs, Screens/AgentScreen.cs, Screens/TodoScreen.cs, Screens/SessionLogScreen.cs, Screens/MemoryScreen.cs, Screens/WorkspaceListScreen.cs, Screens/WorkspacePolicyScreen.cs, Screens/LoginDialog.cs, Screens/ViewModelBinder.cs
Implementation: 17 CLI commands registered via System.CommandLine 2.0.12 (SetAction, ParseResult.GetValue). Publish clears the tool publish directory and CommandLinePublishGuard rejects an assembly older than 2.0.3 or one without SetAction. All commands communicate with the MCP server via McpHttpClient (reads connection details from AGENTS-README-FIRST.yaml). Auth uses OIDC Device Authorization Flow with token caching to ~/.mcpserver/tokens.json. Interactive mode (director interactive|tui|ui) launches Terminal.Gui v2 including a Viewer-scoped Memory tab (after Sessions) for list/get/add/update/remove via MemoryListViewModel / MemoryDetailViewModel. Version is display-only (D11). ViewModels from McpServerManager.UI.Core are bound to Terminal.Gui controls via ViewModelBinder (INotifyPropertyChanged → Application.Invoke).
Director SHALL expose workspace Memory (GET/POST /mcpserver/memory, GET/PUT/DELETE /mcpserver/memory/{id}) on a Viewer tab placed immediately after Sessions. Version is display-only. No Operator role and no expectedVersion/OCC.
Status: Shipped — PLAN-MANAGER-MEMORY-UI-001 closed with box H-done AGREE (Accuracy 99 / Completeness 99) on 2026-09-20. Manager tip e1636b34545c0b3af428f59df202a18ee23ec3e5 (PR #7). Box MCP 1.0.0+720c2b49.
Lab: Director headless path uses Terminal.Gui FakeDriver + MemoryScreen Subviews walk (Refresh/Add/Edit/Remove/Filter). MCP five-verb awaits run after Application.Shutdown(). Live five-verb PASS; Version display-only (DisplayVersion only; no EditorVersion; update does not send expectedVersion). Receipt: docs/receipts/PLAN-MANAGER-MEMORY-UI-001/lab-smoke-director-box-20260920T001521Z.md.
Covered by: MemoryScreen, MemoryListViewModel, MemoryDetailViewModel, MemoryApiClientAdapter
The Director CLI shall support a director exec <ViewModelName> command that instantiates the named ViewModel from the registry, populates properties from JSON input (stdin or --input flag), executes the primary IRelayCommand, and returns the result as JSON to stdout. Exit code 0 = success, 1 = failure.
Covered by: McpServerManager.Director project, IViewModelRegistry
Director shall provide an Agent Pool tab to monitor pooled agents and one-shot queue state, connect to an agent, recycle an agent immediately, stop/start an agent, cancel/remove/reorder queued requests, and enqueue free-form one-shot requests.
Covered by: AgentPoolScreen (planned), AgentPoolViewModel (planned)
Director SHALL expose complete administrative endpoint coverage through the shared McpServerManager.UI.Core MVVM/CQRS layer so interactive tabs and director exec operations use the same command/query contracts, handlers, and authorization rules.
Each covered administration area SHALL provide ViewModel-first orchestration (list/detail or operation-focused ViewModel patterns), and Director screens SHALL remain presentation-only shells that delegate state and workflows to ViewModels and CQRS dispatch.
Tab composition SHALL be role-aware and declarative, with registration metadata separated from shell rendering logic and enforced via shared authorization policy checks.
Technical Implementation: TR-MCP-DIR-005 | TR-MCP-DIR-006 | TR-MCP-DIR-007 | TR-MCP-DIR-008
Director Console App with CQRS: McpServerManager.Director console application using System.CommandLine 2.0.12 for CLI parsing and McpServer.Cqrs for all action dispatch. CLI commands: health, list, agents (defs/ws/events), add, ban, unban, delete, validate, init, sync (status/run), todo, session-log, login, logout, whoami, interactive (aliases: tui, ui), exec, list-viewmodels. Interactive mode uses Terminal.Gui v2 with tabbed screens (Health, Workspaces, Agents, TODO, Sessions, Memory immediately after Sessions, Sync, Policy) plus LoginDialog, menu bar, auth status indicator, and keyboard shortcuts (F2 Login, F5 Refresh, Ctrl+Q Quit). Viewer Memory is list/get/add/update/remove; Version is display-only (D11). Headless lab path: Application.Init(new FakeDriver()), walk MemoryScreen Subviews, then MCP awaits after Application.Shutdown().
Status: ✅ Complete — 18 CLI commands, 9 Terminal.Gui screens, solution builds with 0 warnings
Covered by: McpServerManager.Director project (Program.cs, DirectorCommands.cs, AuthCommands.cs, InteractiveCommand.cs, McpHttpClient.cs, MainScreen.cs, HealthScreen.cs, AgentScreen.cs, TodoScreen.cs, SessionLogScreen.cs, SyncScreen.cs, WorkspaceListScreen.cs, WorkspacePolicyScreen.cs, LoginDialog.cs, ViewModelBinder.cs)
Director OIDC Authentication — OidcAuthService implements OIDC Device Authorization Flow against the configured provider. Initiates device flow, displays user code and verification URI, polls for token. Tokens cached to ~/.mcpserver/tokens.json via TokenCache. McpHttpClient.TrySetCachedBearerToken() loads cached tokens on startup. CLI commands: login, logout, whoami. TUI: LoginDialog with Device Flow UI, authority/client-id fields, user code display, polling status, and whoami frame. Token includes sub, preferred_username, email, realm_roles claims.
Status: ✅ Complete
Covered by: McpServerManager.Director project (Auth/OidcAuthService.cs, Auth/TokenCache.cs, Auth/DirectorAuthOptions.cs, Commands/AuthCommands.cs, Screens/LoginDialog.cs)
Director Exec Command — director exec <ViewModelName> CLI command. IViewModelRegistry maps ViewModel names/aliases to types. ExecCliCommand resolves ViewModel from DI, deserializes JSON input to properties via System.Text.Json, executes primary IRelayCommand, serializes Result<T> to JSON stdout. [ViewModelCommand("alias")] attribute for CLI aliases. Exit code 0/1 maps to Result success/failure.
Status: ✅ Complete
Covered by: McpServerManager.Director project (Program.cs exec/list-viewmodels commands), McpServerManager.UI.Core (IViewModelRegistry)
Director Agent Pool Tab and Queue Controls — Director interactive UI SHALL include an Agent Pool tab that renders pooled agent status, default-intent assignments, active work metadata, queue state, and notification events.
Tab actions SHALL include connect, immediate recycle, stop/start, queued-item move up/down (queued items only), cancel/remove, and free-form one-shot enqueue.
Status: 🔴 Planned
Covered by: AgentPoolScreen (planned), AgentPoolViewModel (planned), McpHttpClient (planned extension)
Director Endpoint-to-Handler Coverage Contract — Every Director-administered MCP endpoint in covered areas SHALL be represented by a UI.Core command/query message and a corresponding CQRS handler that delegates to a UI.Core API-client abstraction (I*ApiClient) rather than direct screen-level HTTP calls.
Director non-interactive command paths (director CLI commands and director exec) SHALL dispatch through the same CQRS handler layer used by interactive tabs to prevent duplicate business logic.
Status: ✅ Complete
Covered by: McpServerManager.UI.Core/Messages/*Messages.cs, McpServerManager.UI.Core/Handlers/*Handlers.cs, McpServerManager.Director/*ApiClientAdapter.cs, McpServerManager.Director/Commands/DirectorCommands.cs, McpServerManager.Director/Commands/AuthCommands.cs
Director ViewModel Conventions for Area Workflows — Covered administration areas SHALL expose ViewModel orchestration that owns UI-facing state (Items, Detail, IsLoading/IsBusy, StatusMessage, ErrorMessage) and uses Dispatcher for command/query execution.
List/detail areas SHALL follow AreaListViewModelBase<T> / AreaDetailViewModelBase<TDetail> conventions where applicable; operation-centric areas may use focused ObservableObject ViewModels with explicit async workflow methods.
Status: ✅ Complete
Covered by: McpServerManager.UI.Core/ViewModels/*ViewModel.cs, McpServerManager.UI.Core/ViewModels/Base/AreaListViewModelBase.cs, McpServerManager.UI.Core/ViewModels/Base/AreaDetailViewModelBase.cs, McpServerManager.Director/Screens/*Screen.cs
Director RBAC Visibility and Action Gating — Tab visibility and action execution SHALL be enforced through IAuthorizationPolicyService using normalized McpArea and McpActionKeys contracts with role tiers (viewer, agent-manager, admin).
Viewer-level users SHALL retain read access surfaces while admin-only surfaces (for example workspaces/policy mutation) remain hidden or blocked unless role requirements are satisfied.
Status: ✅ Complete
Covered by: McpServerManager.UI.Core/Authorization/McpArea.cs, McpServerManager.UI.Core/Authorization/McpActionKeys.cs, McpServerManager.Director/Auth/DirectorAuthorizationPolicyService.cs, McpServerManager.Director/Screens/MainScreen.cs, McpServerManager.UI.Core/Handlers/*Handlers.cs
Declarative Director Tab Registry — Director tab metadata SHALL be registered through a dedicated registry contract that captures area, caption, required role metadata, screen factory, and optional availability predicate.
Main shell rendering SHALL iterate registrations dynamically and avoid hardcoded per-tab branching in the tab rebuild path.
Status: ✅ Complete
Covered by: McpServerManager.UI.Core/Navigation/ITabRegistry.cs, McpServerManager.Director/DirectorTabRegistry.cs, McpServerManager.Director/Screens/MainScreen.cs, McpServerManager.Director/DirectorServiceRegistration.cs
Generated from MCP requirements wiki export.