agent-orchestrator-mcp-server 0.2.4 → 0.3.0

package/README.md

@@ -7,11 +7,13 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 ## Highlights
 
-- Simplified 6-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)
+- 14-tool interface across 4 domains for full agent orchestration
+- Session management with lifecycle actions, message queue, and transcript retrieval
+- Notification management with badge counts, mark read, and dismiss
+- Automation trigger management (create, update, delete, toggle)
+- System health monitoring and maintenance operations
 - Static configuration access via tools and MCP resources
-- Tool grouping system for permission-based access control
+- Domain-based tool grouping system with read-only variants
 - TypeScript with strict type checking
 - Comprehensive testing setup (functional, integration, manual)
 
@@ -19,14 +21,22 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 ### Tools
 
-| Tool                     | Group    | Description                                                                        |
-| ------------------------ | -------- | ---------------------------------------------------------------------------------- |
-| `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 |
-| `send_push_notification` | write    | Send a push notification about a session needing human attention                   |
+| Tool                       | Tool Group    | Read/Write | Description                                                                                                                                                 |
+| -------------------------- | ------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `quick_search_sessions`    | sessions      | read       | Quick title-based search/list sessions with optional ID lookup, title query, and status filter                                                              |
+| `get_session`              | sessions      | read       | Get detailed session info with optional logs, transcripts, and transcript format (text/json)                                                                |
+| `get_configs`              | sessions      | read       | Fetch all static configuration (MCP servers, agent roots, stop conditions)                                                                                  |
+| `get_transcript_archive`   | sessions      | read       | Get download URL and metadata for the transcript archive zip file                                                                                           |
+| `start_session`            | sessions      | write      | Create and start a new agent session                                                                                                                        |
+| `action_session`           | sessions      | write      | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers, fork, refresh, refresh_all, update_notes, toggle_favorite, bulk_archive |
+| `manage_enqueued_messages` | sessions      | write      | Manage session message queue: list, get, create, update, delete, reorder, interrupt                                                                         |
+| `get_notifications`        | notifications | read       | Get/list notifications and badge count                                                                                                                      |
+| `send_push_notification`   | notifications | write      | Send a push notification about a session needing human attention                                                                                            |
+| `action_notification`      | notifications | write      | Mark read, mark all read, dismiss, dismiss all read notifications                                                                                           |
+| `search_triggers`          | triggers      | read       | Search/list automation triggers with optional channel info                                                                                                  |
+| `action_trigger`           | triggers      | write      | Create, update, delete, toggle automation triggers                                                                                                          |
+| `get_system_health`        | health        | read       | Get system health report and optional CLI status                                                                                                            |
+| `action_health`            | health        | write      | System maintenance: cleanup_processes, retry_sessions, archive_old, cli_refresh, cli_clear_cache                                                            |
 
 ### Resources
 
@@ -39,19 +49,56 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 ### Tool Groups
 
-Control which tools are available via the `ENABLED_TOOLGROUPS` environment variable:
+This server organizes tools into groups that can be selectively enabled or disabled. Each group has two variants:
 
-| Group      | Description                                                                 |
-| ---------- | --------------------------------------------------------------------------- |
-| `readonly` | Read-only operations (list, get, search)                                    |
-| `write`    | Write operations (create, update, follow_up, pause, restart, archive, etc.) |
-| `admin`    | Administrative operations (delete)                                          |
+- **Base group** (e.g., `sessions`): Full read + write access
+- **Readonly group** (e.g., `sessions_readonly`): Read-only access
+
+Control which tools are available via the `TOOL_GROUPS` environment variable:
+
+| Group                    | Description                                                                                              |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `sessions`               | All session tools (read + write): search, get, configs, transcript_archive, start, action, enqueued msgs |
+| `sessions_readonly`      | Session tools (read only): quick_search_sessions, get_session, get_configs, get_transcript_archive       |
+| `notifications`          | All notification tools (read + write): get, send, mark read, dismiss                                     |
+| `notifications_readonly` | Notification tools (read only): get_notifications                                                        |
+| `triggers`               | All trigger tools (read + write): search, create, update, delete, toggle                                 |
+| `triggers_readonly`      | Trigger tools (read only): search_triggers                                                               |
+| `health`                 | All health tools (read + write): health report, CLI status, maintenance                                  |
+| `health_readonly`        | Health tools (read only): get_system_health                                                              |
 
 **Examples:**
 
-- `ENABLED_TOOLGROUPS="readonly"` - Only read operations
-- `ENABLED_TOOLGROUPS="readonly,write"` - Read and write, no admin
-- Not set - All tools enabled (default)
+Enable all tools with full access (default):
+
+```bash
+# No TOOL_GROUPS needed - all base groups enabled
+```
+
+Enable only session tools:
+
+```bash
+TOOL_GROUPS=sessions
+```
+
+Enable sessions with read-only access:
+
+```bash
+TOOL_GROUPS=sessions_readonly
+```
+
+Enable all groups with read-only access:
+
+```bash
+TOOL_GROUPS=sessions_readonly,notifications_readonly,triggers_readonly,health_readonly
+```
+
+Mix full and read-only access per group:
+
+```bash
+# Full session access, read-only everything else
+TOOL_GROUPS=sessions,notifications_readonly,triggers_readonly,health_readonly
+```
 
 ## Setup
 
@@ -62,13 +109,13 @@ Control which tools are available via the `ENABLED_TOOLGROUPS` environment varia
 
 ### 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             | -           |
-| `ENABLED_TOOLGROUPS`          | No       | Comma-separated tool groups            | All enabled |
-| `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) |
+| `SKIP_HEALTH_CHECKS`          | No       | Skip API connectivity check at startup      | `false`                                               |
+| `HEALTH_CHECK_TIMEOUT`        | No       | Health check timeout in milliseconds        | `10000`                                               |
 
 ### Claude Desktop
 
@@ -95,7 +142,7 @@ Modify your `claude_desktop_config.json` file to add the following:
       "env": {
         "AGENT_ORCHESTRATOR_BASE_URL": "http://localhost:3000",
         "AGENT_ORCHESTRATOR_API_KEY": "your-api-key-here",
-        "ENABLED_TOOLGROUPS": "readonly,write"
+        "TOOL_GROUPS": "sessions,notifications,triggers,health"
       }
     }
   }
@@ -150,18 +197,66 @@ This MCP server provides tools for the following Agent Orchestrator REST API end
 - `GET /api/v1/sessions` - List sessions
 - `GET /api/v1/sessions/search` - Search sessions
 - `GET /api/v1/sessions/:id` - Get session
+- `GET /api/v1/sessions/:id/transcript` - Get session transcript (text/json)
 - `POST /api/v1/sessions` - Create session
-- `PATCH /api/v1/sessions/:id` - Update session
+- `PATCH /api/v1/sessions/:id` - Update session (change_mcp_servers, update_notes)
 - `DELETE /api/v1/sessions/:id` - Delete session
 - `POST /api/v1/sessions/:id/archive` - Archive session
 - `POST /api/v1/sessions/:id/unarchive` - Unarchive session
 - `POST /api/v1/sessions/:id/follow_up` - Send follow-up prompt
 - `POST /api/v1/sessions/:id/pause` - Pause session
 - `POST /api/v1/sessions/:id/restart` - Restart session
+- `POST /api/v1/sessions/:id/fork` - Fork session from message index
+- `POST /api/v1/sessions/:id/refresh` - Refresh session status
+- `POST /api/v1/sessions/refresh_all` - Refresh all active sessions
+- `POST /api/v1/sessions/:id/toggle_favorite` - Toggle favorite
+- `POST /api/v1/sessions/bulk_archive` - Bulk archive sessions
+
+### Transcript Archive
+
+- `GET /api/v1/transcript_archive/status` - Get transcript archive metadata
+- `GET /api/v1/transcript_archive/download` - Download transcript archive zip file
+
+### Enqueued Messages
+
+- `GET /api/v1/sessions/:session_id/enqueued_messages` - List enqueued messages
+- `GET /api/v1/sessions/:session_id/enqueued_messages/:id` - Get enqueued message
+- `POST /api/v1/sessions/:session_id/enqueued_messages` - Create enqueued message
+- `PATCH /api/v1/sessions/:session_id/enqueued_messages/:id` - Update enqueued message
+- `DELETE /api/v1/sessions/:session_id/enqueued_messages/:id` - Delete enqueued message
+- `POST /api/v1/sessions/:session_id/enqueued_messages/reorder` - Reorder messages
+- `POST /api/v1/sessions/:session_id/enqueued_messages/interrupt` - Interrupt with message
 
 ### Notifications
 
+- `GET /api/v1/notifications` - List notifications
+- `GET /api/v1/notifications/:id` - Get notification
+- `GET /api/v1/notifications/badge` - Get badge count
 - `POST /api/v1/notifications/push` - Send push notification
+- `POST /api/v1/notifications/:id/mark_read` - Mark notification read
+- `POST /api/v1/notifications/mark_all_read` - Mark all notifications read
+- `POST /api/v1/notifications/:id/dismiss` - Dismiss notification
+- `POST /api/v1/notifications/dismiss_all_read` - Dismiss all read notifications
+
+### Triggers
+
+- `GET /api/v1/triggers` - List triggers
+- `GET /api/v1/triggers/:id` - Get trigger
+- `GET /api/v1/triggers/channels` - Get trigger channels
+- `POST /api/v1/triggers` - Create trigger
+- `PATCH /api/v1/triggers/:id` - Update trigger
+- `DELETE /api/v1/triggers/:id` - Delete trigger
+- `POST /api/v1/triggers/:id/toggle` - Toggle trigger active state
+
+### Health
+
+- `GET /api/v1/health` - Get system health report
+- `POST /api/v1/health/cleanup_processes` - Cleanup stale processes
+- `POST /api/v1/health/retry_sessions` - Retry failed sessions
+- `POST /api/v1/health/archive_old` - Archive old sessions
+- `GET /api/v1/clis/status` - Get CLI status
+- `POST /api/v1/clis/refresh` - Refresh CLI
+- `POST /api/v1/clis/clear_cache` - Clear CLI cache
 
 ### Logs
 

package/build/index.js

@@ -30,8 +30,8 @@ function validateEnvironment() {
     ];
     const optional = [
         {
-            name: 'ENABLED_TOOLGROUPS',
-            description: 'Comma-separated list of tool groups to enable (readonly,write,admin)',
+            name: 'TOOL_GROUPS',
+            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',
         },
         {
@@ -69,8 +69,8 @@ function validateEnvironment() {
         process.exit(1);
     }
     // Log warnings for common configuration issues
-    if (process.env.ENABLED_TOOLGROUPS) {
-        logWarning('config', `Tool groups filter active: ${process.env.ENABLED_TOOLGROUPS}`);
+    if (process.env.TOOL_GROUPS) {
+        logWarning('config', `Tool groups filter active: ${process.env.TOOL_GROUPS}`);
     }
 }
 // =============================================================================

package/package.json

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

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, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse } from '../types.js';
+import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse, EnqueuedMessage, EnqueuedMessagesResponse, EnqueuedMessageInterruptResponse, EnqueuedMessageStatus, Trigger, TriggerType, TriggerStatus, TriggersResponse, TriggerResponse, TriggerChannelsResponse, CreateTriggerRequest, UpdateTriggerRequest, Notification, NotificationsResponse, NotificationBadgeResponse, NotificationMarkAllReadResponse, NotificationDismissAllReadResponse, HealthReport, HealthActionResponse, CliStatusResponse, CliActionResponse, ForkSessionResponse, RefreshSessionResponse, RefreshAllSessionsResponse, BulkArchiveResponse, TranscriptResponse, TranscriptArchiveStatusResponse } from '../types.js';
 /** Raw agent root shape as returned by the Rails API */
 export interface RawAgentRoot {
     name: string;
@@ -36,7 +36,6 @@ export interface IAgentOrchestratorClient {
         per_page?: number;
     }): Promise<SessionsResponse>;
     searchSessions(query: string, options?: {
-        search_contents?: boolean;
         status?: SessionStatus;
         agent_type?: string;
         show_archived?: boolean;
@@ -75,6 +74,67 @@ export interface IAgentOrchestratorClient {
     getMcpServers(): Promise<MCPServerInfo[]>;
     getConfigs(): Promise<ConfigsResponse>;
     sendPushNotification(sessionId: string | number, message: string): Promise<SendPushNotificationResponse>;
+    forkSession(id: string | number, messageIndex: number): Promise<ForkSessionResponse>;
+    refreshSession(id: string | number): Promise<RefreshSessionResponse>;
+    refreshAllSessions(): Promise<RefreshAllSessionsResponse>;
+    updateSessionNotes(id: string | number, notes: string): Promise<Session>;
+    toggleFavorite(id: string | number): Promise<Session & {
+        favorited: boolean;
+    }>;
+    bulkArchiveSessions(sessionIds: number[]): Promise<BulkArchiveResponse>;
+    getTranscript(id: string | number, format?: 'text' | 'json'): Promise<TranscriptResponse>;
+    listEnqueuedMessages(sessionId: string | number, options?: {
+        status?: EnqueuedMessageStatus;
+        page?: number;
+        per_page?: number;
+    }): Promise<EnqueuedMessagesResponse>;
+    getEnqueuedMessage(sessionId: string | number, messageId: number): Promise<EnqueuedMessage>;
+    createEnqueuedMessage(sessionId: string | number, data: {
+        content: string;
+        stop_condition?: string;
+    }): Promise<EnqueuedMessage>;
+    updateEnqueuedMessage(sessionId: string | number, messageId: number, data: {
+        content?: string;
+        stop_condition?: string;
+    }): Promise<EnqueuedMessage>;
+    deleteEnqueuedMessage(sessionId: string | number, messageId: number): Promise<void>;
+    reorderEnqueuedMessage(sessionId: string | number, messageId: number, position: number): Promise<EnqueuedMessage>;
+    interruptEnqueuedMessage(sessionId: string | number, messageId: number): Promise<EnqueuedMessageInterruptResponse>;
+    listTriggers(options?: {
+        trigger_type?: TriggerType;
+        status?: TriggerStatus;
+        page?: number;
+        per_page?: number;
+    }): Promise<TriggersResponse>;
+    getTrigger(id: number): Promise<TriggerResponse>;
+    createTrigger(data: CreateTriggerRequest): Promise<Trigger>;
+    updateTrigger(id: number, data: UpdateTriggerRequest): Promise<Trigger>;
+    deleteTrigger(id: number): Promise<void>;
+    toggleTrigger(id: number): Promise<Trigger>;
+    getTriggerChannels(): Promise<TriggerChannelsResponse>;
+    listNotifications(options?: {
+        status?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<NotificationsResponse>;
+    getNotification(id: number): Promise<Notification>;
+    getNotificationBadge(): Promise<NotificationBadgeResponse>;
+    markNotificationRead(id: number): Promise<Notification>;
+    markAllNotificationsRead(): Promise<NotificationMarkAllReadResponse>;
+    dismissNotification(id: number): Promise<void>;
+    dismissAllReadNotifications(): Promise<NotificationDismissAllReadResponse>;
+    getHealth(): Promise<HealthReport>;
+    cleanupProcesses(): Promise<HealthActionResponse>;
+    retrySessions(sessionIds?: number[]): Promise<HealthActionResponse>;
+    archiveOldSessions(days?: number): Promise<HealthActionResponse>;
+    getCliStatus(): Promise<CliStatusResponse>;
+    refreshCli(): Promise<CliActionResponse>;
+    clearCliCache(): Promise<CliActionResponse>;
+    getTranscriptArchiveStatus(): Promise<TranscriptArchiveStatusResponse>;
+    getTranscriptArchiveDownloadUrl(): {
+        url: string;
+        apiKey: string;
+    };
 }
 /**
  * Implementation of the Agent Orchestrator API client.
@@ -85,6 +145,11 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     private timeoutMs;
     constructor(baseUrl: string, apiKey: string, timeoutMs?: number);
     private request;
+    /**
+     * Like request(), but reads the response as text and wraps it in a TranscriptResponse.
+     * Used for API endpoints that return raw text instead of JSON (e.g., transcript with format=text).
+     */
+    private requestText;
     listSessions(options?: {
         status?: SessionStatus;
         agent_type?: string;
@@ -93,7 +158,6 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
         per_page?: number;
     }): Promise<SessionsResponse>;
     searchSessions(query: string, options?: {
-        search_contents?: boolean;
         status?: SessionStatus;
         agent_type?: string;
         show_archived?: boolean;
@@ -132,5 +196,66 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     getMcpServers(): Promise<MCPServerInfo[]>;
     getConfigs(): Promise<ConfigsResponse>;
     sendPushNotification(sessionId: string | number, message: string): Promise<SendPushNotificationResponse>;
+    forkSession(id: string | number, messageIndex: number): Promise<ForkSessionResponse>;
+    refreshSession(id: string | number): Promise<RefreshSessionResponse>;
+    refreshAllSessions(): Promise<RefreshAllSessionsResponse>;
+    updateSessionNotes(id: string | number, notes: string): Promise<Session>;
+    toggleFavorite(id: string | number): Promise<Session & {
+        favorited: boolean;
+    }>;
+    bulkArchiveSessions(sessionIds: number[]): Promise<BulkArchiveResponse>;
+    getTranscript(id: string | number, format?: 'text' | 'json'): Promise<TranscriptResponse>;
+    listEnqueuedMessages(sessionId: string | number, options?: {
+        status?: EnqueuedMessageStatus;
+        page?: number;
+        per_page?: number;
+    }): Promise<EnqueuedMessagesResponse>;
+    getEnqueuedMessage(sessionId: string | number, messageId: number): Promise<EnqueuedMessage>;
+    createEnqueuedMessage(sessionId: string | number, data: {
+        content: string;
+        stop_condition?: string;
+    }): Promise<EnqueuedMessage>;
+    updateEnqueuedMessage(sessionId: string | number, messageId: number, data: {
+        content?: string;
+        stop_condition?: string;
+    }): Promise<EnqueuedMessage>;
+    deleteEnqueuedMessage(sessionId: string | number, messageId: number): Promise<void>;
+    reorderEnqueuedMessage(sessionId: string | number, messageId: number, position: number): Promise<EnqueuedMessage>;
+    interruptEnqueuedMessage(sessionId: string | number, messageId: number): Promise<EnqueuedMessageInterruptResponse>;
+    listTriggers(options?: {
+        trigger_type?: TriggerType;
+        status?: TriggerStatus;
+        page?: number;
+        per_page?: number;
+    }): Promise<TriggersResponse>;
+    getTrigger(id: number): Promise<TriggerResponse>;
+    createTrigger(data: CreateTriggerRequest): Promise<Trigger>;
+    updateTrigger(id: number, data: UpdateTriggerRequest): Promise<Trigger>;
+    deleteTrigger(id: number): Promise<void>;
+    toggleTrigger(id: number): Promise<Trigger>;
+    getTriggerChannels(): Promise<TriggerChannelsResponse>;
+    listNotifications(options?: {
+        status?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<NotificationsResponse>;
+    getNotification(id: number): Promise<Notification>;
+    getNotificationBadge(): Promise<NotificationBadgeResponse>;
+    markNotificationRead(id: number): Promise<Notification>;
+    markAllNotificationsRead(): Promise<NotificationMarkAllReadResponse>;
+    dismissNotification(id: number): Promise<void>;
+    dismissAllReadNotifications(): Promise<NotificationDismissAllReadResponse>;
+    getHealth(): Promise<HealthReport>;
+    cleanupProcesses(): Promise<HealthActionResponse>;
+    retrySessions(sessionIds?: number[]): Promise<HealthActionResponse>;
+    archiveOldSessions(days?: number): Promise<HealthActionResponse>;
+    getCliStatus(): Promise<CliStatusResponse>;
+    refreshCli(): Promise<CliActionResponse>;
+    clearCliCache(): Promise<CliActionResponse>;
+    getTranscriptArchiveStatus(): Promise<TranscriptArchiveStatusResponse>;
+    getTranscriptArchiveDownloadUrl(): {
+        url: string;
+        apiKey: string;
+    };
 }
 //# sourceMappingURL=orchestrator-client.d.ts.map