Majordomo 2/7: an MCP server exposing the tool vocabulary over the existing orchestrator paths

CodeyBox.slnx

@@ -34,6 +34,7 @@
     <Project Path="src/CodeyBox.Audit.Presets/CodeyBox.Audit.Presets.csproj" />
     <Project Path="src/CodeyBox.Audit.Shell/CodeyBox.Audit.Shell.csproj" />
     <Project Path="src/CodeyBox.Audit/CodeyBox.Audit.csproj" />
+    <Project Path="src/CodeyBox.Composition/CodeyBox.Composition.csproj" />
     <Project Path="src/CodeyBox.Core/CodeyBox.Core.csproj" />
     <Project Path="src/CodeyBox.Deployment/CodeyBox.Deployment.csproj" />
     <Project Path="src/CodeyBox.Executor/CodeyBox.Executor.csproj" />

docs/reference/api.md

@@ -62,6 +62,13 @@ quota meter). Give each executor host its own token environment variable and
 matching `ExecutorHostId`, and put that token (not the operator key) in the
 executor's `ApiKeyEnvVar` on that host.
 
+The majordomo MCP endpoint (`/mcp/majordomo`) is another host-scoped surface:
+it accepts only the named API client configured by
+`CodeyBox:Majordomo:ClientName` (default `majordomo`). Every other credential —
+the operator key included — is refused, so the majordomo's calls are
+attributable to its own principal and the token can be revoked without
+rotating the operator key.
+
 ### GitHub App delivery credentials
 
 For team installations, configure the GitHub upstream with a GitHub App

docs/reference/configuration.md

@@ -1226,6 +1226,28 @@ Read-only parser settings for agent stream analytics.
 | `MaxLineBytes` | `67108864` | Maximum JSONL event size accepted by the parser. Defaults to 64 MiB so large tool-result events fit under the default stream file cap. |
 | `MaxJsonDepth` | `64` | Maximum JSON nesting depth accepted by the parser. |
 
+## `Majordomo`
+
+The majordomo's MCP endpoint (`POST /mcp/majordomo`, stateless streamable
+HTTP) publishes exactly the majordomo tool vocabulary. These values are
+hot-reloadable; the executor reads the current options on every call.
+
+```json
+"Majordomo": {
+  "Mode": "proposed",
+  "MaxMutatedItemsPerTurn": 8,
+  "ClientName": "majordomo",
+  "TurnWindowSeconds": 120
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `Mode` | `proposed` | `autonomous` executes mutations immediately; `proposed` returns an operator-reviewable proposal with the validated change set instead of mutating. |
+| `MaxMutatedItemsPerTurn` | `8` | Per-call and cumulative per-turn cap on mutated work items (hard ceiling 100). |
+| `ClientName` | `majordomo` | The `CodeyBox:ApiClients` entry whose token is the majordomo credential. Only that client may reach the endpoint — the operator key and other named clients are refused — so majordomo calls are attributable and the credential is revocable independently. |
+| `TurnWindowSeconds` | `120` | Rolling window over which mutations from one identity accumulate toward the per-turn cap. 1–3600. |
+
 ## `Projects`
 
 See [docs/concepts/projects.md](../concepts/projects.md).

src/CodeyBox.Api/ApiKeyAuth.cs

@@ -61,6 +61,15 @@ public static void Configure(WebApplicationBuilder builder)
                         configuration,
                         environment,
                         RequiredConfigurationValidator.ApiClientsEntryMessage);
+                // The auth-disabled sentinel name is reserved: a configured
+                // client carrying it would be treated as the loopback
+                // operator by every host-scoped gate that asks
+                // IsAuthenticationDisabled.
+                if (string.Equals(client.Name, AuthenticationDisabledClientName, StringComparison.Ordinal))
+                    throw RequiredConfigurationValidator.CreateAggregateException(
+                        configuration,
+                        environment,
+                        $"CodeyBox:ApiClients entry name '{AuthenticationDisabledClientName}' is reserved.");
                 var token = Environment.GetEnvironmentVariable(client.TokenEnvVar);
                 if (string.IsNullOrWhiteSpace(token) || token.Length < 32)
                     throw RequiredConfigurationValidator.CreateAggregateException(

src/CodeyBox.Api/CodeyBox.Api.csproj

@@ -1,7 +1,9 @@
 <Project Sdk="Microsoft.NET.Sdk.Web">
 
   <ItemGroup>
+    <ProjectReference Include="..\CodeyBox.Composition\CodeyBox.Composition.csproj" />
     <ProjectReference Include="..\CodeyBox.Core\CodeyBox.Core.csproj" />
+    <ProjectReference Include="..\CodeyBox.Majordomo\CodeyBox.Majordomo.csproj" />
     <ProjectReference Include="..\CodeyBox.Deployment\CodeyBox.Deployment.csproj" />
     <ProjectReference Include="..\CodeyBox.AdminSeed\CodeyBox.AdminSeed.csproj" />
     <ProjectReference Include="..\CodeyBox.Orchestrator\CodeyBox.Orchestrator.csproj" />
@@ -82,6 +84,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="ModelContextProtocol.AspNetCore" Version="2.2.0" />
     <PackageReference Include="Serilog.AspNetCore" Version="8.0.3" />
     <PackageReference Include="Serilog.Extensions.Hosting" Version="8.0.0" />
     <PackageReference Include="Serilog.Sinks.File" Version="6.0.0" />