agent-orchestrator-mcp-server 0.1.2 → 0.2.1

package/README.md

@@ -7,9 +7,10 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 ## Highlights
 
-- Simplified 4-tool interface for full agent session management
+- Simplified 5-tool interface for full agent session management
 - Search, filter, and retrieve sessions with optional logs and transcripts
 - Session lifecycle actions (pause, restart, archive, unarchive, follow_up, change_mcp_servers)
+- Static configuration access via tools and MCP resources
 - Tool grouping system for permission-based access control
 - TypeScript with strict type checking
 - Comprehensive testing setup (functional, integration, manual)
@@ -22,14 +23,18 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 | ----------------- | -------- | ---------------------------------------------------------------------------------- |
 | `search_sessions` | readonly | Search/list sessions with optional ID lookup, query, and status filter             |
 | `get_session`     | readonly | Get detailed session info with optional logs and transcripts                       |
+| `get_configs`     | readonly | Fetch all static configuration (MCP servers, agent roots, stop conditions)         |
 | `start_session`   | write    | Create and start a new agent session                                               |
 | `action_session`  | write    | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers |
 
 ### Resources
 
-| Resource                      | Description                                     |
-| ----------------------------- | ----------------------------------------------- |
-| `agent-orchestrator://config` | Server configuration and status (for debugging) |
+| Resource                                       | Description                                     |
+| ---------------------------------------------- | ----------------------------------------------- |
+| `agent-orchestrator://config`                  | Server configuration and status (for debugging) |
+| `agent-orchestrator://configs/mcp-servers`     | List of available MCP servers for sessions      |
+| `agent-orchestrator://configs/agent-roots`     | Preconfigured repository settings with defaults |
+| `agent-orchestrator://configs/stop-conditions` | Session completion criteria definitions         |
 
 ### Tool Groups
 

package/package.json

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

package/shared/cache/configs-cache.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared cache for unified configs response.
+ *
+ * This module provides a centralized cache for the configs response
+ * that is shared between get_configs and get_available_mcp_servers tools.
+ *
+ * Cache behavior:
+ * - Session-level caching (persists for the lifetime of the MCP server process)
+ * - No TTL (time-to-live) - data is considered valid until force_refresh
+ * - Force refresh available via tool parameter
+ */
+import type { ConfigsResponse } from '../types.js';
+/**
+ * Clear the configs cache.
+ * Useful for testing and for manual cache invalidation.
+ */
+export declare function clearConfigsCache(): void;
+/**
+ * Get the current configs cache state.
+ * Returns null if no data is cached.
+ */
+export declare function getConfigsCache(): ConfigsResponse | null;
+/**
+ * Update the configs cache with new data.
+ */
+export declare function setConfigsCache(configs: ConfigsResponse): void;
+//# sourceMappingURL=configs-cache.d.ts.map

package/shared/cache/configs-cache.js

@@ -0,0 +1,33 @@
+/**
+ * Shared cache for unified configs response.
+ *
+ * This module provides a centralized cache for the configs response
+ * that is shared between get_configs and get_available_mcp_servers tools.
+ *
+ * Cache behavior:
+ * - Session-level caching (persists for the lifetime of the MCP server process)
+ * - No TTL (time-to-live) - data is considered valid until force_refresh
+ * - Force refresh available via tool parameter
+ */
+// Module-level cache for configs (shared between tools)
+let configsCache = null;
+/**
+ * Clear the configs cache.
+ * Useful for testing and for manual cache invalidation.
+ */
+export function clearConfigsCache() {
+    configsCache = null;
+}
+/**
+ * Get the current configs cache state.
+ * Returns null if no data is cached.
+ */
+export function getConfigsCache() {
+    return configsCache;
+}
+/**
+ * Update the configs cache with new data.
+ */
+export function setConfigsCache(configs) {
+    configsCache = configs;
+}

package/shared/index.d.ts

@@ -1,4 +1,4 @@
-export { registerResources } from './resources.js';
+export { createRegisterResources } from './resources.js';
 export { registerTools, createRegisterTools, type ToolGroup, parseEnabledToolGroups, } from './tools.js';
 export { createMCPServer, type ClientFactory, type IAgentOrchestratorClient } from './server.js';
 export { AgentOrchestratorClient, type IAgentOrchestratorClient as AgentOrchestratorClientInterface, } from './orchestrator-client/orchestrator-client.js';

package/shared/index.js

@@ -1,5 +1,5 @@
 // Core server exports
-export { registerResources } from './resources.js';
+export { createRegisterResources } from './resources.js';
 export { registerTools, createRegisterTools, parseEnabledToolGroups, } from './tools.js';
 export { createMCPServer } from './server.js';
 // Client exports

package/shared/orchestrator-client/orchestrator-client.d.ts

@@ -3,7 +3,7 @@
  *
  * A client for interacting with the Agent Orchestrator REST API.
  */
-import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus } from '../types.js';
+import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, ConfigsResponse } from '../types.js';
 /**
  * Interface for the Agent Orchestrator API client.
  * Used for dependency injection and testing.
@@ -53,6 +53,8 @@ export interface IAgentOrchestratorClient {
     createSubagentTranscript(sessionId: string | number, data: CreateSubagentTranscriptRequest): Promise<SubagentTranscript>;
     updateSubagentTranscript(sessionId: string | number, transcriptId: number, data: UpdateSubagentTranscriptRequest): Promise<SubagentTranscript>;
     deleteSubagentTranscript(sessionId: string | number, transcriptId: number): Promise<void>;
+    getMcpServers(): Promise<MCPServerInfo[]>;
+    getConfigs(): Promise<ConfigsResponse>;
 }
 /**
  * Implementation of the Agent Orchestrator API client.
@@ -107,5 +109,7 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     createSubagentTranscript(sessionId: string | number, data: CreateSubagentTranscriptRequest): Promise<SubagentTranscript>;
     updateSubagentTranscript(sessionId: string | number, transcriptId: number, data: UpdateSubagentTranscriptRequest): Promise<SubagentTranscript>;
     deleteSubagentTranscript(sessionId: string | number, transcriptId: number): Promise<void>;
+    getMcpServers(): Promise<MCPServerInfo[]>;
+    getConfigs(): Promise<ConfigsResponse>;
 }
 //# sourceMappingURL=orchestrator-client.d.ts.map

package/shared/orchestrator-client/orchestrator-client.integration-mock.js

@@ -380,5 +380,57 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             }
             mockData.subagentTranscripts?.splice(index, 1);
         },
+        async getMcpServers() {
+            return [
+                {
+                    name: 'github-development',
+                    title: 'GitHub Development',
+                    description: 'Interact with GitHub repositories, issues, and pull requests',
+                },
+                {
+                    name: 'slack',
+                    title: 'Slack',
+                    description: 'Send and receive messages in Slack workspaces',
+                },
+            ];
+        },
+        async getConfigs() {
+            return {
+                mcp_servers: [
+                    {
+                        name: 'github-development',
+                        title: 'GitHub Development',
+                        description: 'Interact with GitHub repositories, issues, and pull requests',
+                    },
+                    {
+                        name: 'slack',
+                        title: 'Slack',
+                        description: 'Send and receive messages in Slack workspaces',
+                    },
+                ],
+                agent_roots: [
+                    {
+                        name: 'mcp-servers',
+                        title: 'MCP Servers',
+                        description: 'PulseMCP MCP servers monorepo',
+                        git_root: 'https://github.com/pulsemcp/mcp-servers.git',
+                        default_branch: 'main',
+                        default_mcp_servers: ['github-development'],
+                    },
+                ],
+                stop_conditions: [
+                    {
+                        id: 'pr_merged',
+                        name: 'PR Merged',
+                        description: 'Stop when the pull request is merged',
+                    },
+                    {
+                        id: 'ci_passing',
+                        name: 'CI Passing',
+                        description: 'Stop when CI checks pass',
+                    },
+                ],
+            };
+        },
     };
 }

package/shared/orchestrator-client/orchestrator-client.js

@@ -169,4 +169,13 @@ export class AgentOrchestratorClient {
     async deleteSubagentTranscript(sessionId, transcriptId) {
         await this.request('DELETE', `/sessions/${sessionId}/subagent_transcripts/${transcriptId}`);
     }
+    // MCP Servers
+    async getMcpServers() {
+        const response = await this.request('GET', '/mcp_servers');
+        return response.mcp_servers;
+    }
+    // Unified Configs
+    async getConfigs() {
+        return this.request('GET', '/configs');
+    }
 }

package/shared/resources.d.ts

@@ -1,3 +1,10 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-export declare function registerResources(server: Server): void;
+import type { IAgentOrchestratorClient } from './orchestrator-client/orchestrator-client.js';
+export type ClientFactory = () => IAgentOrchestratorClient;
+/**
+ * Creates a function to register all resources with the server.
+ * @param clientFactory - Factory function that creates client instances
+ * @returns Function that registers all resources with a server
+ */
+export declare function createRegisterResources(clientFactory: ClientFactory): (server: Server) => void;
 //# sourceMappingURL=resources.d.ts.map

package/shared/resources.js

@@ -1,67 +1,149 @@
 import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-// =============================================================================
-// RESOURCES IMPLEMENTATION
-// =============================================================================
-// Resources expose data that can be read by MCP clients.
-// For agent-orchestrator, we expose a configuration resource for debugging.
-// =============================================================================
-export function registerResources(server) {
-    // List available resources
-    server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        return {
-            resources: [
-                {
-                    uri: 'agent-orchestrator://config',
-                    name: 'Server Configuration',
-                    description: 'Current server configuration and status. Useful for debugging and verifying setup.',
-                    mimeType: 'application/json',
-                },
-            ],
-        };
-    });
-    // Read resource contents
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-        const { uri } = request.params;
-        // =========================================================================
-        // CONFIG RESOURCE - Server Status and Configuration
-        // =========================================================================
-        if (uri === 'agent-orchestrator://config') {
-            const config = {
-                server: {
-                    name: 'agent-orchestrator-mcp-server',
-                    version: '0.1.0',
-                    transport: 'stdio',
-                },
-                environment: {
-                    AGENT_ORCHESTRATOR_BASE_URL: process.env.AGENT_ORCHESTRATOR_BASE_URL
-                        ? '***configured***'
-                        : 'not set',
-                    AGENT_ORCHESTRATOR_API_KEY: process.env.AGENT_ORCHESTRATOR_API_KEY
-                        ? '***configured***'
-                        : 'not set',
-                    ENABLED_TOOLGROUPS: process.env.ENABLED_TOOLGROUPS || 'all (default)',
-                    SKIP_HEALTH_CHECKS: process.env.SKIP_HEALTH_CHECKS || 'false',
-                },
-                capabilities: {
-                    tools: true,
-                    resources: true,
-                },
-                toolGroups: {
-                    readonly: 'Read-only operations (list, get, search)',
-                    write: 'Write operations (create, update, follow_up, pause, restart, archive, unarchive)',
-                    admin: 'Administrative operations (delete)',
-                },
-            };
+import { getConfigsCache, setConfigsCache } from './cache/configs-cache.js';
+/**
+ * Creates a function to register all resources with the server.
+ * @param clientFactory - Factory function that creates client instances
+ * @returns Function that registers all resources with a server
+ */
+export function createRegisterResources(clientFactory) {
+    return (server) => {
+        // List available resources
+        server.setRequestHandler(ListResourcesRequestSchema, async () => {
             return {
-                contents: [
+                resources: [
                     {
                         uri: 'agent-orchestrator://config',
+                        name: 'Server Configuration',
+                        description: 'Current server configuration and status. Useful for debugging and verifying setup.',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'agent-orchestrator://configs/mcp-servers',
+                        name: 'Available MCP Servers',
+                        description: 'List of available MCP servers that can be used with start_session.',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'agent-orchestrator://configs/agent-roots',
+                        name: 'Agent Roots',
+                        description: 'Preconfigured repository settings with default branch, MCP servers, and stop conditions.',
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'agent-orchestrator://configs/stop-conditions',
+                        name: 'Stop Conditions',
+                        description: 'Available session completion criteria for use with start_session.',
                         mimeType: 'application/json',
-                        text: JSON.stringify(config, null, 2),
                     },
                 ],
             };
-        }
-        throw new Error(`Resource not found: ${uri}`);
-    });
+        });
+        // Read resource contents
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            const { uri } = request.params;
+            // =========================================================================
+            // CONFIG RESOURCE - Server Status and Configuration
+            // =========================================================================
+            if (uri === 'agent-orchestrator://config') {
+                const config = {
+                    server: {
+                        name: 'agent-orchestrator-mcp-server',
+                        version: '0.2.0',
+                        transport: 'stdio',
+                    },
+                    environment: {
+                        AGENT_ORCHESTRATOR_BASE_URL: process.env.AGENT_ORCHESTRATOR_BASE_URL
+                            ? '***configured***'
+                            : 'not set',
+                        AGENT_ORCHESTRATOR_API_KEY: process.env.AGENT_ORCHESTRATOR_API_KEY
+                            ? '***configured***'
+                            : 'not set',
+                        ENABLED_TOOLGROUPS: process.env.ENABLED_TOOLGROUPS || 'all (default)',
+                        SKIP_HEALTH_CHECKS: process.env.SKIP_HEALTH_CHECKS || 'false',
+                    },
+                    capabilities: {
+                        tools: true,
+                        resources: true,
+                    },
+                    toolGroups: {
+                        readonly: 'Read-only operations (list, get, search)',
+                        write: 'Write operations (create, update, follow_up, pause, restart, archive, unarchive)',
+                        admin: 'Administrative operations (delete)',
+                    },
+                };
+                return {
+                    contents: [
+                        {
+                            uri: 'agent-orchestrator://config',
+                            mimeType: 'application/json',
+                            text: JSON.stringify(config, null, 2),
+                        },
+                    ],
+                };
+            }
+            // =========================================================================
+            // CONFIGS RESOURCES - Static configuration from API
+            // =========================================================================
+            if (uri.startsWith('agent-orchestrator://configs/')) {
+                // Fetch configs (using cache if available)
+                const configs = await fetchConfigs(clientFactory);
+                if (uri === 'agent-orchestrator://configs/mcp-servers') {
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: 'application/json',
+                                text: JSON.stringify({
+                                    mcp_servers: configs.mcp_servers,
+                                    _usage: 'Use the "name" field when specifying mcp_servers in start_session',
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                if (uri === 'agent-orchestrator://configs/agent-roots') {
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: 'application/json',
+                                text: JSON.stringify({
+                                    agent_roots: configs.agent_roots,
+                                    _usage: 'Use the "git_root" field when starting sessions. Default settings will be applied automatically.',
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                if (uri === 'agent-orchestrator://configs/stop-conditions') {
+                    return {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: 'application/json',
+                                text: JSON.stringify({
+                                    stop_conditions: configs.stop_conditions,
+                                    _usage: 'Use the "id" field when specifying stop_condition in start_session',
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+            }
+            throw new Error(`Resource not found: ${uri}`);
+        });
+    };
+}
+/**
+ * Fetch configs from API, using cache if available.
+ */
+async function fetchConfigs(clientFactory) {
+    const cached = getConfigsCache();
+    if (cached) {
+        return cached;
+    }
+    const client = clientFactory();
+    const configs = await client.getConfigs();
+    setConfigsCache(configs);
+    return configs;
 }

package/shared/server.js

@@ -1,11 +1,11 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { registerResources } from './resources.js';
+import { createRegisterResources } from './resources.js';
 import { createRegisterTools } from './tools.js';
 import { AgentOrchestratorClient, } from './orchestrator-client/orchestrator-client.js';
 export function createMCPServer() {
     const server = new Server({
         name: 'agent-orchestrator-mcp-server',
-        version: '0.1.0',
+        version: '0.2.0',
     }, {
         capabilities: {
             resources: {},
@@ -26,6 +26,7 @@ export function createMCPServer() {
                 }
                 return new AgentOrchestratorClient(baseUrl, apiKey);
             });
+        const registerResources = createRegisterResources(factory);
         registerResources(server);
         const registerTools = createRegisterTools(factory);
         registerTools(server);

package/shared/tools/get-configs.d.ts

@@ -0,0 +1,37 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const GetConfigsSchema: z.ZodObject<{
+    force_refresh: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    force_refresh?: boolean | undefined;
+}, {
+    force_refresh?: boolean | undefined;
+}>;
+export declare function getConfigsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            force_refresh: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-configs.d.ts.map

package/shared/tools/get-configs.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import { getConfigsCache, setConfigsCache } from '../cache/configs-cache.js';
+export const GetConfigsSchema = z.object({
+    force_refresh: z
+        .boolean()
+        .optional()
+        .describe('Force refresh the cache and fetch fresh data from the API. Default: false'),
+});
+const TOOL_DESCRIPTION = `Fetches all static configuration data in a single call.
+
+Returns:
+- **MCP servers**: Available servers for use with start_session (name, title, description)
+- **Agent roots**: Preconfigured repository settings with defaults (git_root, branch, mcp_servers, stop_condition)
+- **Stop conditions**: Available session completion criteria (id, name, description)
+
+**Use this tool** to get all configuration options before calling start_session.
+
+**Caching:** Results are cached in memory for the session. Use force_refresh=true to fetch fresh data.`;
+export function getConfigsTool(_server, clientFactory) {
+    return {
+        name: 'get_configs',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                force_refresh: {
+                    type: 'boolean',
+                    description: 'Force refresh the cache and fetch fresh data from the API. Default: false',
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = GetConfigsSchema.parse(args);
+                const forceRefresh = validatedArgs.force_refresh ?? false;
+                // Use cached data if available and not forcing refresh
+                const cachedConfigs = getConfigsCache();
+                if (cachedConfigs !== null && !forceRefresh) {
+                    return formatResponse(cachedConfigs, true);
+                }
+                // Fetch fresh data using unified configs endpoint
+                const client = clientFactory();
+                const configs = await client.getConfigs();
+                // Update shared cache
+                setConfigsCache(configs);
+                return formatResponse(configs, false);
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error fetching configs: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+function formatResponse(configs, fromCache) {
+    const lines = [];
+    // MCP Servers section
+    lines.push('## MCP Servers');
+    lines.push('');
+    if (configs.mcp_servers.length === 0) {
+        lines.push('*No MCP servers available.*');
+    }
+    else {
+        lines.push(`Found ${configs.mcp_servers.length} server${configs.mcp_servers.length === 1 ? '' : 's'}:`);
+        lines.push('');
+        for (const server of configs.mcp_servers) {
+            formatMcpServer(lines, server);
+        }
+    }
+    // Agent Roots section
+    lines.push('---');
+    lines.push('');
+    lines.push('## Agent Roots');
+    lines.push('');
+    if (configs.agent_roots.length === 0) {
+        lines.push('*No agent roots configured.*');
+    }
+    else {
+        lines.push(`Found ${configs.agent_roots.length} preconfigured repositor${configs.agent_roots.length === 1 ? 'y' : 'ies'}:`);
+        lines.push('');
+        for (const root of configs.agent_roots) {
+            formatAgentRoot(lines, root);
+        }
+    }
+    // Stop Conditions section
+    lines.push('---');
+    lines.push('');
+    lines.push('## Stop Conditions');
+    lines.push('');
+    if (configs.stop_conditions.length === 0) {
+        lines.push('*No stop conditions defined.*');
+    }
+    else {
+        lines.push(`Found ${configs.stop_conditions.length} stop condition${configs.stop_conditions.length === 1 ? '' : 's'}:`);
+        lines.push('');
+        for (const condition of configs.stop_conditions) {
+            formatStopCondition(lines, condition);
+        }
+    }
+    // Usage hints
+    lines.push('---');
+    lines.push('');
+    lines.push('### Usage Notes');
+    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('- Use `id` values from **Stop Conditions** in `start_session` `stop_condition` parameter');
+    if (fromCache) {
+        lines.push('');
+        lines.push('*(Returned from cache. Use `force_refresh: true` to fetch fresh data.)*');
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+    };
+}
+function formatMcpServer(lines, server) {
+    lines.push(`### ${server.title}`);
+    lines.push(`- **Name:** \`${server.name}\``);
+    lines.push(`- **Description:** ${server.description}`);
+    lines.push('');
+}
+function formatAgentRoot(lines, root) {
+    lines.push(`### ${root.title}`);
+    lines.push(`- **Name:** \`${root.name}\``);
+    lines.push(`- **Git Root:** \`${root.git_root}\``);
+    lines.push(`- **Description:** ${root.description}`);
+    if (root.default_branch) {
+        lines.push(`- **Default Branch:** \`${root.default_branch}\``);
+    }
+    if (root.default_subdirectory) {
+        lines.push(`- **Default Subdirectory:** \`${root.default_subdirectory}\``);
+    }
+    if (root.default_mcp_servers && root.default_mcp_servers.length > 0) {
+        lines.push(`- **Default MCP Servers:** ${root.default_mcp_servers.map((s) => `\`${s}\``).join(', ')}`);
+    }
+    if (root.default_stop_condition) {
+        lines.push(`- **Default Stop Condition:** \`${root.default_stop_condition}\``);
+    }
+    lines.push('');
+}
+function formatStopCondition(lines, condition) {
+    lines.push(`### ${condition.name}`);
+    lines.push(`- **ID:** \`${condition.id}\``);
+    lines.push(`- **Description:** ${condition.description}`);
+    lines.push('');
+}

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

@@ -15,8 +15,8 @@ export declare const StartSessionSchema: z.ZodObject<{
     config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     custom_metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    title?: string | undefined;
     agent_type?: string | undefined;
+    title?: string | undefined;
     prompt?: string | undefined;
     git_root?: string | undefined;
     branch?: string | undefined;
@@ -28,8 +28,8 @@ export declare const StartSessionSchema: z.ZodObject<{
     config?: Record<string, unknown> | undefined;
     custom_metadata?: Record<string, unknown> | undefined;
 }, {
-    title?: string | undefined;
     agent_type?: string | undefined;
+    title?: string | undefined;
     prompt?: string | undefined;
     git_root?: string | undefined;
     branch?: string | undefined;

package/shared/tools/start-session.js

@@ -32,6 +32,8 @@ export const StartSessionSchema = z.object({
 });
 const TOOL_DESCRIPTION = `Start a new agent session in the Agent Orchestrator.
 
+**IMPORTANT:** Before starting a session, call get_configs to discover available MCP servers, stop conditions, and preconfigured agent roots.
+
 **Returns:** The created session with its ID, status, and configuration.
 
 **Behavior:**

package/shared/tools.js

@@ -1,9 +1,10 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-// Simplified tool surface - 4 tools
+// Simplified tool surface - 5 tools
 import { searchSessionsTool } from './tools/search-sessions.js';
 import { startSessionTool } from './tools/start-session.js';
 import { getSessionTool } from './tools/get-session.js';
 import { actionSessionTool } from './tools/action-session.js';
+import { getConfigsTool } from './tools/get-configs.js';
 const ALL_TOOL_GROUPS = ['readonly', 'write', 'admin'];
 /**
  * Parse enabled tool groups from environment variable.
@@ -31,11 +32,13 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  * - start_session: Create a new session
  * - get_session: Get detailed session info with optional logs/transcripts
  * - action_session: Perform actions (follow_up, pause, restart, archive, unarchive)
+ * - get_configs: Fetch all static configuration (MCP servers, agent roots, stop conditions)
  */
 const ALL_TOOLS = [
     // Read operations
     { factory: searchSessionsTool, groups: ['readonly', 'write', 'admin'] },
     { factory: getSessionTool, groups: ['readonly', 'write', 'admin'] },
+    { factory: getConfigsTool, groups: ['readonly', 'write', 'admin'] },
     // Write operations
     { factory: startSessionTool, groups: ['write', 'admin'] },
     { factory: actionSessionTool, groups: ['write', 'admin'] },

package/shared/types.d.ts

@@ -98,6 +98,34 @@ export interface ApiError {
     message?: string;
     messages?: string[];
 }
+export interface MCPServerInfo {
+    name: string;
+    title: string;
+    description: string;
+}
+export interface MCPServersResponse {
+    mcp_servers: MCPServerInfo[];
+}
+export interface AgentRootInfo {
+    name: string;
+    title: string;
+    description: string;
+    git_root: string;
+    default_branch?: string;
+    default_subdirectory?: string;
+    default_stop_condition?: string;
+    default_mcp_servers?: string[];
+}
+export interface StopConditionInfo {
+    id: string;
+    name: string;
+    description: string;
+}
+export interface ConfigsResponse {
+    mcp_servers: MCPServerInfo[];
+    agent_roots: AgentRootInfo[];
+    stop_conditions: StopConditionInfo[];
+}
 export interface CreateSessionRequest {
     agent_type?: string;
     prompt?: string;