agent-orchestrator-mcp-server 0.2.5 → 0.3.0

package/README.md

@@ -23,7 +23,7 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 | Tool                       | Tool Group    | Read/Write | Description                                                                                                                                                 |
 | -------------------------- | ------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `search_sessions`          | sessions      | read       | Search/list sessions with optional ID lookup, query, and status filter                                                                                      |
+| `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                                                                                           |
@@ -59,7 +59,7 @@ 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): search_sessions, get_session, get_configs, get_transcript_archive             |
+| `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                                 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.2.5",
+  "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

@@ -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;
@@ -146,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;
@@ -154,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;

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

@@ -111,7 +111,6 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             const paginatedSessions = sessions.slice(start, start + perPage);
             return {
                 query,
-                search_contents: options?.search_contents || false,
                 sessions: paginatedSessions,
                 pagination: {
                     page,

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

@@ -98,6 +98,67 @@ export class AgentOrchestratorClient {
         }
         return response.json();
     }
+    /**
+     * 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).
+     */
+    async requestText(method, path, body, queryParams) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (queryParams) {
+            Object.entries(queryParams).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, String(value));
+                }
+            });
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        if (body) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        const options = {
+            method,
+            headers,
+            signal: controller.signal,
+        };
+        if (body && (method === 'POST' || method === 'PATCH' || method === 'PUT')) {
+            options.body = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await fetch(url.toString(), options);
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`Request timeout after ${this.timeoutMs}ms`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        if (!response.ok) {
+            const errorText = await response.text();
+            let errorMessage;
+            try {
+                const errorJson = JSON.parse(errorText);
+                errorMessage = errorJson.message || errorJson.error || errorText;
+            }
+            catch {
+                errorMessage = errorText;
+            }
+            throw new Error(`API Error (${response.status}): ${errorMessage}`);
+        }
+        if (response.status === 204) {
+            return { transcript_text: '' };
+        }
+        const text = await response.text();
+        return { transcript_text: text };
+    }
     // Sessions
     async listSessions(options) {
         return this.request('GET', '/sessions', undefined, options);
@@ -234,6 +295,11 @@ export class AgentOrchestratorClient {
         });
     }
     async getTranscript(id, format = 'json') {
+        if (format === 'text') {
+            // The API returns raw text (not JSON) when format=text,
+            // so we must use response.text() instead of response.json()
+            return this.requestText('GET', `/sessions/${id}/transcript`, undefined, { format });
+        }
         return this.request('GET', `/sessions/${id}/transcript`, undefined, {
             format,
         });

package/shared/resources.js

@@ -67,7 +67,7 @@ export function createRegisterResources(clientFactory) {
                     },
                     toolGroups: {
                         sessions: 'All session tools (read + write): search, get, configs, start, action, enqueued messages',
-                        sessions_readonly: 'Session tools (read only): search_sessions, get_session, get_configs',
+                        sessions_readonly: 'Session tools (read only): quick_search_sessions, get_session, get_configs',
                         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',

package/shared/tools/search-sessions.d.ts

@@ -1,10 +1,9 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
 import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
-export declare const SearchSessionsSchema: z.ZodObject<{
+export declare const QuickSearchSessionsSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodNumber>;
     query: z.ZodOptional<z.ZodString>;
-    search_contents: z.ZodOptional<z.ZodBoolean>;
     status: z.ZodOptional<z.ZodEnum<["waiting", "running", "needs_input", "failed", "archived"]>>;
     agent_type: z.ZodOptional<z.ZodString>;
     show_archived: z.ZodOptional<z.ZodBoolean>;
@@ -16,7 +15,6 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }, {
@@ -25,11 +23,10 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }>;
-export declare function searchSessionsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+export declare function quickSearchSessionsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
     name: string;
     description: string;
     inputSchema: {
@@ -42,11 +39,7 @@ export declare function searchSessionsTool(_server: Server, clientFactory: () =>
             query: {
                 type: string;
                 maxLength: number;
-                description: "Search query to find sessions. Searches across title, metadata, and custom_metadata. Leave empty to list all sessions.";
-            };
-            search_contents: {
-                type: string;
-                description: "Also search within transcript contents. May be slow for sessions with large transcripts. Default: false";
+                description: "Search query to find sessions. Matches against session title only — this is a simple title search, not a full-text or semantic search. Leave empty to list all sessions.";
             };
             status: {
                 type: string;

package/shared/tools/search-sessions.js

@@ -1,18 +1,16 @@
 import { z } from 'zod';
 const PARAM_DESCRIPTIONS = {
     id: 'Get a specific session by ID. When provided, other filters are ignored.',
-    query: 'Search query to find sessions. Searches across title, metadata, and custom_metadata. Leave empty to list all sessions.',
-    search_contents: 'Also search within transcript contents. May be slow for sessions with large transcripts. Default: false',
+    query: 'Search query to find sessions. Matches against session title only — this is a simple title search, not a full-text or semantic search. Leave empty to list all sessions.',
     status: 'Filter results by status. Options: "waiting", "running", "needs_input", "failed", "archived"',
     agent_type: 'Filter results by agent type.',
     show_archived: 'Include archived sessions in results. Default: false',
     page: 'Page number for pagination. Default: 1',
     per_page: 'Number of results per page (1-100). Default: 25',
 };
-export const SearchSessionsSchema = z.object({
+export const QuickSearchSessionsSchema = z.object({
     id: z.number().optional().describe(PARAM_DESCRIPTIONS.id),
     query: z.string().max(1000).optional().describe(PARAM_DESCRIPTIONS.query),
-    search_contents: z.boolean().optional().describe(PARAM_DESCRIPTIONS.search_contents),
     status: z
         .enum(['waiting', 'running', 'needs_input', 'failed', 'archived'])
         .optional()
@@ -22,11 +20,13 @@ export const SearchSessionsSchema = z.object({
     page: z.number().min(1).optional().describe(PARAM_DESCRIPTIONS.page),
     per_page: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.per_page),
 });
-const TOOL_DESCRIPTION = `Search for agent sessions in the Agent Orchestrator.
+const TOOL_DESCRIPTION = `Quick title-based search for agent sessions in the Agent Orchestrator.
+
+**Important:** This tool only searches session titles. It is NOT a full-text or semantic search across session contents/transcripts. Use this when you roughly know the session title you're looking for.
 
 **Use cases:**
 - Find a specific session by ID (set id parameter)
-- Search sessions by keyword in title/prompt (set query parameter)
+- Search sessions by title keyword (set query parameter)
 - List all sessions with optional status filter
 - Monitor sessions requiring attention (status: "needs_input")
 
@@ -66,9 +66,9 @@ function formatSession(session) {
     lines.push(`- **Updated:** ${session.updated_at}`);
     return lines.join('\n');
 }
-export function searchSessionsTool(_server, clientFactory) {
+export function quickSearchSessionsTool(_server, clientFactory) {
     return {
-        name: 'search_sessions',
+        name: 'quick_search_sessions',
         description: TOOL_DESCRIPTION,
         inputSchema: {
             type: 'object',
@@ -82,10 +82,6 @@ export function searchSessionsTool(_server, clientFactory) {
                     maxLength: 1000,
                     description: PARAM_DESCRIPTIONS.query,
                 },
-                search_contents: {
-                    type: 'boolean',
-                    description: PARAM_DESCRIPTIONS.search_contents,
-                },
                 status: {
                     type: 'string',
                     enum: ['waiting', 'running', 'needs_input', 'failed', 'archived'],
@@ -115,7 +111,7 @@ export function searchSessionsTool(_server, clientFactory) {
         },
         handler: async (args) => {
             try {
-                const validatedArgs = SearchSessionsSchema.parse(args);
+                const validatedArgs = QuickSearchSessionsSchema.parse(args);
                 const client = clientFactory();
                 // If ID is provided, get that specific session
                 if (validatedArgs.id !== undefined) {
@@ -133,9 +129,8 @@ export function searchSessionsTool(_server, clientFactory) {
                 let sessions;
                 let pagination;
                 if (validatedArgs.query) {
-                    // Use search endpoint
+                    // Use search endpoint (title-only search, no content search)
                     const response = await client.searchSessions(validatedArgs.query, {
-                        search_contents: validatedArgs.search_contents,
                         status: validatedArgs.status,
                         agent_type: validatedArgs.agent_type,
                         show_archived: validatedArgs.show_archived,

package/shared/tools.js

@@ -1,6 +1,6 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 // 13 tools across 4 domains
-import { searchSessionsTool } from './tools/search-sessions.js';
+import { quickSearchSessionsTool } 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';
@@ -59,7 +59,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  * All available tools with their group assignments.
  *
  * 14 tools across 4 domains:
- * - search_sessions: Search/list/get sessions by ID (sessions, read)
+ * - quick_search_sessions: Quick title-based search/list/get sessions by ID (sessions, read)
  * - get_session: Get detailed session info with optional logs/transcripts (sessions, read)
  * - get_configs: Fetch all static configuration (sessions, read)
  * - get_transcript_archive: Get transcript archive download URL and metadata (sessions, read)
@@ -76,7 +76,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  */
 const ALL_TOOLS = [
     // Session tools - read operations
-    { factory: searchSessionsTool, group: 'sessions', isWriteOperation: false },
+    { factory: quickSearchSessionsTool, group: 'sessions', isWriteOperation: false },
     { factory: getSessionTool, group: 'sessions', isWriteOperation: false },
     { factory: getConfigsTool, group: 'sessions', isWriteOperation: false },
     { factory: getTranscriptArchiveTool, group: 'sessions', isWriteOperation: false },

package/shared/types.d.ts

@@ -68,7 +68,6 @@ export interface SessionsResponse {
 }
 export interface SearchSessionsResponse {
     query: string;
-    search_contents: boolean;
     sessions: Session[];
     pagination: Pagination;
 }