agent-orchestrator-mcp-server 0.3.0 → 0.4.2

package/README.md

@@ -109,13 +109,14 @@ TOOL_GROUPS=sessions,notifications_readonly,triggers_readonly,health_readonly
 
 ### Environment Variables
 
-| Variable                      | Required | Description                                 | Default                                               |
-| ----------------------------- | -------- | ------------------------------------------- | ----------------------------------------------------- |
-| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API           | -                                                     |
-| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication                  | -                                                     |
-| `TOOL_GROUPS`                 | No       | Comma-separated list of enabled tool groups | `sessions,notifications,triggers,health` (all groups) |
-| `SKIP_HEALTH_CHECKS`          | No       | Skip API connectivity check at startup      | `false`                                               |
-| `HEALTH_CHECK_TIMEOUT`        | No       | Health check timeout in milliseconds        | `10000`                                               |
+| Variable                      | Required | Description                                                                                                                                                                                                                                   | Default                                               |
+| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API                                                                                                                                                                                                             | -                                                     |
+| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication                                                                                                                                                                                                                    | -                                                     |
+| `TOOL_GROUPS`                 | No       | Comma-separated list of enabled tool groups                                                                                                                                                                                                   | `sessions,notifications,triggers,health` (all groups) |
+| `ALLOWED_AGENT_ROOTS`         | No       | Comma-separated list of allowed agent root names. When set, constrains the server to only permit sessions with these specific agent roots and their exact default MCP servers. Also blocks `change_mcp_servers` and trigger creation/updates. | -                                                     |
+| `SKIP_HEALTH_CHECKS`          | No       | Skip API connectivity check at startup                                                                                                                                                                                                        | `false`                                               |
+| `HEALTH_CHECK_TIMEOUT`        | No       | Health check timeout in milliseconds                                                                                                                                                                                                          | `10000`                                               |
 
 ### Claude Desktop
 

package/build/index.js

@@ -34,6 +34,11 @@ function validateEnvironment() {
             description: 'Comma-separated list of tool groups to enable (sessions,sessions_readonly,notifications,notifications_readonly,triggers,triggers_readonly,health,health_readonly)',
             defaultValue: 'all groups enabled',
         },
+        {
+            name: 'ALLOWED_AGENT_ROOTS',
+            description: 'Comma-separated list of allowed agent root names. When set, only these agent roots are shown in get_configs and allowed in start_session (with their exact default MCP servers only)',
+            defaultValue: 'all agent roots allowed',
+        },
         {
             name: 'SKIP_HEALTH_CHECKS',
             description: 'Skip API connectivity check at startup (set to "true" to skip)',
@@ -72,6 +77,9 @@ function validateEnvironment() {
     if (process.env.TOOL_GROUPS) {
         logWarning('config', `Tool groups filter active: ${process.env.TOOL_GROUPS}`);
     }
+    if (process.env.ALLOWED_AGENT_ROOTS) {
+        logWarning('config', `Allowed agent roots filter active: ${process.env.ALLOWED_AGENT_ROOTS}`);
+    }
 }
 // =============================================================================
 // HEALTH CHECKS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",

package/shared/allowed-agent-roots.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ALLOWED_AGENT_ROOTS constraint system.
+ *
+ * When the ALLOWED_AGENT_ROOTS environment variable is set (comma-separated list of agent root names),
+ * the server is constrained to only allow sessions using those specific agent roots
+ * with their exact default MCP server configurations.
+ *
+ * This provides a way to lock down the server to only permit preconfigured invocations.
+ */
+import type { AgentRootInfo } from './types.js';
+/**
+ * Parse the ALLOWED_AGENT_ROOTS environment variable into a list of allowed agent root names.
+ * Returns null if the env var is not set (meaning no restrictions).
+ */
+export declare function parseAllowedAgentRoots(envValue?: string): string[] | null;
+/**
+ * Filter agent roots to only include those in the allowed list.
+ * If allowedRoots is null, returns all agent roots (no filtering).
+ */
+export declare function filterAgentRoots(agentRoots: AgentRootInfo[], allowedRoots: string[] | null): AgentRootInfo[];
+export interface AgentRootValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Validate a start_session request against the allowed agent roots constraints.
+ *
+ * When ALLOWED_AGENT_ROOTS is set:
+ * - git_root (and optionally branch/subdirectory) must match one of the allowed agent roots
+ * - mcp_servers must exactly match the default_mcp_servers of that agent root
+ *   (no more, no less — any deviation is rejected)
+ *
+ * When multiple allowed agent roots share the same git_root, branch and subdirectory
+ * are used to disambiguate. This is critical for monorepo setups where multiple agent
+ * roots point to the same repository but different subdirectories.
+ *
+ * Returns { valid: true } if the request is allowed, or { valid: false, error: string } if not.
+ */
+export declare function validateAgentRootConstraints(allowedRoots: string[] | null, agentRoots: AgentRootInfo[], gitRoot?: string, mcpServers?: string[], branch?: string, subdirectory?: string): AgentRootValidationResult;
+//# sourceMappingURL=allowed-agent-roots.d.ts.map

package/shared/allowed-agent-roots.js

@@ -0,0 +1,102 @@
+/**
+ * ALLOWED_AGENT_ROOTS constraint system.
+ *
+ * When the ALLOWED_AGENT_ROOTS environment variable is set (comma-separated list of agent root names),
+ * the server is constrained to only allow sessions using those specific agent roots
+ * with their exact default MCP server configurations.
+ *
+ * This provides a way to lock down the server to only permit preconfigured invocations.
+ */
+/**
+ * Parse the ALLOWED_AGENT_ROOTS environment variable into a list of allowed agent root names.
+ * Returns null if the env var is not set (meaning no restrictions).
+ */
+export function parseAllowedAgentRoots(envValue) {
+    const value = envValue ?? process.env.ALLOWED_AGENT_ROOTS ?? '';
+    if (!value.trim()) {
+        return null; // No restrictions
+    }
+    const roots = value
+        .split(',')
+        .map((r) => r.trim())
+        .filter((r) => r.length > 0);
+    if (roots.length === 0) {
+        return null;
+    }
+    return roots;
+}
+/**
+ * Filter agent roots to only include those in the allowed list.
+ * If allowedRoots is null, returns all agent roots (no filtering).
+ */
+export function filterAgentRoots(agentRoots, allowedRoots) {
+    if (allowedRoots === null) {
+        return agentRoots;
+    }
+    return agentRoots.filter((root) => allowedRoots.includes(root.name));
+}
+/**
+ * Validate a start_session request against the allowed agent roots constraints.
+ *
+ * When ALLOWED_AGENT_ROOTS is set:
+ * - git_root (and optionally branch/subdirectory) must match one of the allowed agent roots
+ * - mcp_servers must exactly match the default_mcp_servers of that agent root
+ *   (no more, no less — any deviation is rejected)
+ *
+ * When multiple allowed agent roots share the same git_root, branch and subdirectory
+ * are used to disambiguate. This is critical for monorepo setups where multiple agent
+ * roots point to the same repository but different subdirectories.
+ *
+ * Returns { valid: true } if the request is allowed, or { valid: false, error: string } if not.
+ */
+export function validateAgentRootConstraints(allowedRoots, agentRoots, gitRoot, mcpServers, branch, subdirectory) {
+    if (allowedRoots === null) {
+        return { valid: true };
+    }
+    // Find all allowed agent roots that match by git_root
+    const candidates = agentRoots.filter((root) => allowedRoots.includes(root.name) && root.git_root === gitRoot);
+    // When multiple candidates share the same git_root, disambiguate using branch and subdirectory
+    let matchingRoot;
+    if (candidates.length > 1) {
+        matchingRoot = candidates.find((root) => {
+            const branchMatch = !branch || (root.default_branch ?? 'main') === branch;
+            const subdirMatch = !subdirectory || root.default_subdirectory === subdirectory;
+            return branchMatch && subdirMatch;
+        });
+    }
+    else {
+        matchingRoot = candidates[0];
+    }
+    if (!matchingRoot) {
+        const allowedNames = allowedRoots.join(', ');
+        const allowedGitRoots = agentRoots
+            .filter((root) => allowedRoots.includes(root.name))
+            .map((root) => root.git_root);
+        return {
+            valid: false,
+            error: `ALLOWED_AGENT_ROOTS is set — only the following agent roots are permitted: ${allowedNames}. ` +
+                `The provided git_root "${gitRoot || '(not provided)'}" does not match any allowed agent root. ` +
+                (allowedGitRoots.length > 0
+                    ? `Allowed git_root values: ${allowedGitRoots.join(', ')}`
+                    : 'No matching agent roots found in configuration.'),
+        };
+    }
+    // Validate mcp_servers matches the default_mcp_servers exactly
+    const defaultServers = matchingRoot.default_mcp_servers ?? [];
+    const requestedServers = mcpServers ?? [];
+    const sortedDefault = [...defaultServers].sort();
+    const sortedRequested = [...requestedServers].sort();
+    const serversMatch = sortedDefault.length === sortedRequested.length &&
+        sortedDefault.every((s, i) => s === sortedRequested[i]);
+    if (!serversMatch) {
+        const defaultStr = defaultServers.length > 0 ? defaultServers.join(', ') : '(none)';
+        const requestedStr = requestedServers.length > 0 ? requestedServers.join(', ') : '(none)';
+        return {
+            valid: false,
+            error: `ALLOWED_AGENT_ROOTS is set — agent root "${matchingRoot.name}" must use its exact default MCP servers. ` +
+                `Expected: [${defaultStr}], but got: [${requestedStr}]. ` +
+                `You cannot add or remove MCP servers when ALLOWED_AGENT_ROOTS restrictions are active.`,
+        };
+    }
+    return { valid: true };
+}

package/shared/tools/action-session.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseAllowedAgentRoots } from '../allowed-agent-roots.js';
 const PARAM_DESCRIPTIONS = {
     session_id: 'Session ID (numeric) or slug (string). Required for most actions. Not required for "refresh_all" and "bulk_archive".',
     action: 'Action to perform: "follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "bulk_archive"',
@@ -146,6 +147,18 @@ export function actionSessionTool(_server, clientFactory) {
                         isError: true,
                     };
                 }
+                // Block change_mcp_servers when ALLOWED_AGENT_ROOTS is active
+                if (action === 'change_mcp_servers' && parseAllowedAgentRoots() !== null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "change_mcp_servers" action is not allowed when ALLOWED_AGENT_ROOTS is set. MCP servers are locked to the defaults configured for each allowed agent root.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 // Validate fork requires message_index
                 if (action === 'fork' && message_index === undefined) {
                     return {

package/shared/tools/action-trigger.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { parseAllowedAgentRoots } from '../allowed-agent-roots.js';
 const ACTION_ENUM = ['create', 'update', 'delete', 'toggle'];
 export const ActionTriggerSchema = z.object({
     action: z.enum(ACTION_ENUM),
@@ -63,6 +64,18 @@ export function actionTriggerTool(_server, clientFactory) {
                 const validated = ActionTriggerSchema.parse(args);
                 const client = clientFactory();
                 const { action, id } = validated;
+                // Block create/update when ALLOWED_AGENT_ROOTS is active
+                if ((action === 'create' || action === 'update') && parseAllowedAgentRoots() !== null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: The "${action}" action is not allowed when ALLOWED_AGENT_ROOTS is set. Triggers cannot be created or modified because sessions are restricted to specific preconfigured agent roots and their default MCP servers.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 let result;
                 switch (action) {
                     case 'create': {

package/shared/tools/get-configs.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { getConfigsCache, setConfigsCache } from '../cache/configs-cache.js';
+import { parseAllowedAgentRoots, filterAgentRoots } from '../allowed-agent-roots.js';
 export const GetConfigsSchema = z.object({
     force_refresh: z
         .boolean()
@@ -37,14 +38,14 @@ export function getConfigsTool(_server, clientFactory) {
                 // Use cached data if available and not forcing refresh
                 const cachedConfigs = getConfigsCache();
                 if (cachedConfigs !== null && !forceRefresh) {
-                    return formatResponse(cachedConfigs, true);
+                    return formatResponse(applyAgentRootFilter(cachedConfigs), true);
                 }
                 // Fetch fresh data using unified configs endpoint
                 const client = clientFactory();
                 const configs = await client.getConfigs();
-                // Update shared cache
+                // Update shared cache (store unfiltered data so filtering is always applied fresh)
                 setConfigsCache(configs);
-                return formatResponse(configs, false);
+                return formatResponse(applyAgentRootFilter(configs), false);
             }
             catch (error) {
                 return {
@@ -60,6 +61,16 @@ export function getConfigsTool(_server, clientFactory) {
         },
     };
 }
+function applyAgentRootFilter(configs) {
+    const allowedRoots = parseAllowedAgentRoots();
+    if (allowedRoots === null) {
+        return configs;
+    }
+    return {
+        ...configs,
+        agent_roots: filterAgentRoots(configs.agent_roots, allowedRoots),
+    };
+}
 function formatResponse(configs, fromCache) {
     const lines = [];
     // MCP Servers section
@@ -112,6 +123,7 @@ function formatResponse(configs, fromCache) {
     lines.push('');
     lines.push('- Use `name` values from **MCP Servers** in `start_session` `mcp_servers` parameter');
     lines.push('- Use `git_root` from **Agent Roots** to start sessions with preconfigured defaults');
+    lines.push('- If an **Agent Root** has a `default_subdirectory`, pass it as `subdirectory` in `start_session` — do not set `subdirectory` to arbitrary internal paths');
     lines.push('- Use `id` values from **Stop Conditions** in `start_session` `stop_condition` parameter');
     if (fromCache) {
         lines.push('');

package/shared/tools/start-session.d.ts

@@ -65,7 +65,7 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
             };
             subdirectory: {
                 type: string;
-                description: "Subdirectory within the repository to focus on.";
+                description: string;
             };
             title: {
                 type: string;
@@ -107,13 +107,13 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
             type: string;
             text: string;
         }[];
-        isError?: undefined;
+        isError: boolean;
     } | {
         content: {
             type: string;
             text: string;
         }[];
-        isError: boolean;
+        isError?: undefined;
     }>;
 };
 //# sourceMappingURL=start-session.d.ts.map

package/shared/tools/start-session.js

@@ -1,10 +1,17 @@
 import { z } from 'zod';
+import { parseAllowedAgentRoots, validateAgentRootConstraints } from '../allowed-agent-roots.js';
+import { getConfigsCache, setConfigsCache } from '../cache/configs-cache.js';
 const PARAM_DESCRIPTIONS = {
     agent_type: 'Agent type for the session. Currently only "claude_code" is supported. Default: "claude_code"',
     prompt: 'Initial prompt for the agent. If provided, the agent job is automatically queued. Omit for a clone-only session.',
     git_root: 'Repository URL or local path. Examples: "https://github.com/example/repo.git", "/path/to/repo"',
     branch: 'Git branch to work on. Default: "main"',
-    subdirectory: 'Subdirectory within the repository to focus on.',
+    subdirectory: 'Subdirectory within the repository to use as the agent working directory. ' +
+        'This should match a preconfigured agent root default_subdirectory from get_configs — it defines ' +
+        'the root scope for the agent session. Do NOT use this to point at internal package directories ' +
+        '(e.g. "experimental/gcs" in a monorepo) as this blinds the agent to root-level configuration ' +
+        'like CLAUDE.md, build scripts, CI workflows, and monorepo tooling. If no agent root defines ' +
+        'a default_subdirectory, leave this unset.',
     title: 'STRONGLY RECOMMENDED: Always set a title — treat it as effectively required. ' +
         'The title appears in the AO web UI and push notifications, making sessions identifiable at a glance. ' +
         'Compose a short, descriptive title (under 70 characters) that captures what the session is doing ' +
@@ -113,6 +120,23 @@ export function startSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = StartSessionSchema.parse(args);
                 const client = clientFactory();
+                // Enforce ALLOWED_AGENT_ROOTS constraints if set
+                const allowedRoots = parseAllowedAgentRoots();
+                if (allowedRoots !== null) {
+                    // Ensure we have configs (fetch if not cached)
+                    let configs = getConfigsCache();
+                    if (!configs) {
+                        configs = await client.getConfigs();
+                        setConfigsCache(configs);
+                    }
+                    const validation = validateAgentRootConstraints(allowedRoots, configs.agent_roots, validatedArgs.git_root, validatedArgs.mcp_servers, validatedArgs.branch, validatedArgs.subdirectory);
+                    if (!validation.valid) {
+                        return {
+                            content: [{ type: 'text', text: `Error starting session: ${validation.error}` }],
+                            isError: true,
+                        };
+                    }
+                }
                 const session = await client.createSession(validatedArgs);
                 const lines = [
                     `## Session Started Successfully`,