agent-orchestrator-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# Agent Orchestrator MCP Server
+
+> **Note**: This package is part of the [MCP Servers](https://github.com/pulsemcp/mcp-servers) monorepo. For the latest updates and full source code, visit the [Agent Orchestrator MCP Server directory](https://github.com/pulsemcp/mcp-servers/tree/main/experimental/agent-orchestrator).
+
+
+MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-parallelization system for agentic coding and ops done at PulseMCP.
+
+## Highlights
+
+- Simplified 4-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)
+- Tool grouping system for permission-based access control
+- TypeScript with strict type checking
+- Comprehensive testing setup (functional, integration, manual)
+
+## Capabilities
+
+### 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           |
+| `start_session`   | write    | Create and start a new agent session                                   |
+| `action_session`  | write    | Perform actions: follow_up, pause, restart, archive, unarchive         |
+
+### Resources
+
+| Resource                      | Description                                     |
+| ----------------------------- | ----------------------------------------------- |
+| `agent-orchestrator://config` | Server configuration and status (for debugging) |
+
+### Tool Groups
+
+Control which tools are available via the `ENABLED_TOOLGROUPS` environment variable:
+
+| Group      | Description                                                                 |
+| ---------- | --------------------------------------------------------------------------- |
+| `readonly` | Read-only operations (list, get, search)                                    |
+| `write`    | Write operations (create, update, follow_up, pause, restart, archive, etc.) |
+| `admin`    | Administrative operations (delete)                                          |
+
+**Examples:**
+
+- `ENABLED_TOOLGROUPS="readonly"` - Only read operations
+- `ENABLED_TOOLGROUPS="readonly,write"` - Read and write, no admin
+- Not set - All tools enabled (default)
+
+## Quick Start
+
+### Installation
+
+```bash
+npm run install-all
+npm run build
+```
+
+### Configuration
+
+Set the required environment variables:
+
+```bash
+export AGENT_ORCHESTRATOR_BASE_URL="http://localhost:3000"
+export AGENT_ORCHESTRATOR_API_KEY="your_api_key_here"
+```
+
+### Running
+
+```bash
+npm start
+```
+
+## 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 validation at startup    | `false`     |
+
+### Claude Desktop Configuration
+
+#### macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+#### Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "agent-orchestrator": {
+      "command": "node",
+      "args": ["/path/to/agent-orchestrator/local/build/index.js"],
+      "env": {
+        "AGENT_ORCHESTRATOR_BASE_URL": "http://localhost:3000",
+        "AGENT_ORCHESTRATOR_API_KEY": "your-api-key-here",
+        "ENABLED_TOOLGROUPS": "readonly,write"
+      }
+    }
+  }
+}
+```
+
+## Development
+
+### Running in Development Mode
+
+```bash
+npm run dev
+```
+
+### Testing
+
+```bash
+# Run functional tests in watch mode
+npm test
+
+# Run tests once
+npm run test:run
+
+# Run integration tests (full MCP protocol)
+npm run test:integration
+
+# Run all automated tests
+npm run test:all
+```
+
+### Linting and Formatting
+
+```bash
+# Check for linting issues
+npm run lint
+
+# Auto-fix linting issues
+npm run lint:fix
+
+# Format code
+npm run format
+```
+
+## API Coverage
+
+This MCP server provides tools for the following Agent Orchestrator REST API endpoints:
+
+### Sessions
+
+- `GET /api/v1/sessions` - List sessions
+- `GET /api/v1/sessions/search` - Search sessions
+- `GET /api/v1/sessions/:id` - Get session
+- `POST /api/v1/sessions` - Create session
+- `PATCH /api/v1/sessions/:id` - Update session
+- `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
+
+### Logs
+
+- `GET /api/v1/sessions/:session_id/logs` - List logs
+- `POST /api/v1/sessions/:session_id/logs` - Create log
+
+### Subagent Transcripts
+
+- `GET /api/v1/sessions/:session_id/subagent_transcripts` - List transcripts
+- `GET /api/v1/sessions/:session_id/subagent_transcripts/:id` - Get transcript
+
+## License
+
+MIT

package/build/index.integration-with-mock.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Integration Test Server Entry Point with Mock Client Factory
+ *
+ * This file is used for integration testing with a mocked AgentOrchestratorClient.
+ * It uses the real MCP server but injects a mock client factory.
+ *
+ * Mock data is passed via the ORCHESTRATOR_MOCK_DATA environment variable.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// Import from shared module via symlink (created by setup-dev.js)
+import { createMCPServer } from '../shared/index.js';
+// Import the mock client factory from the shared module
+import { createIntegrationMockOrchestratorClient } from '../shared/orchestrator-client/orchestrator-client.integration-mock.js';
+async function main() {
+    const transport = new StdioServerTransport();
+    // Parse mock data from environment variable
+    let mockData = {};
+    if (process.env.ORCHESTRATOR_MOCK_DATA) {
+        try {
+            mockData = JSON.parse(process.env.ORCHESTRATOR_MOCK_DATA);
+        }
+        catch (e) {
+            console.error('Failed to parse ORCHESTRATOR_MOCK_DATA:', e);
+        }
+    }
+    // Create client factory that returns our mock
+    const clientFactory = () => createIntegrationMockOrchestratorClient(mockData);
+    const { server, registerHandlers } = createMCPServer();
+    await registerHandlers(server, clientFactory);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/build/index.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMCPServer } from '../shared/index.js';
+import { logServerStart, logError, logWarning } from '../shared/logging.js';
+// =============================================================================
+// ENVIRONMENT VALIDATION
+// =============================================================================
+// Validates required environment variables at startup with helpful error messages.
+// =============================================================================
+function validateEnvironment() {
+    const required = [
+        {
+            name: 'AGENT_ORCHESTRATOR_BASE_URL',
+            description: 'Base URL for the Agent Orchestrator API',
+            example: 'http://localhost:3000',
+        },
+        {
+            name: 'AGENT_ORCHESTRATOR_API_KEY',
+            description: 'API key for authentication with the Agent Orchestrator',
+            example: 'your_api_key_here',
+        },
+    ];
+    const optional = [
+        {
+            name: 'ENABLED_TOOLGROUPS',
+            description: 'Comma-separated list of tool groups to enable (readonly,write,admin)',
+            defaultValue: 'all groups enabled',
+        },
+        {
+            name: 'SKIP_HEALTH_CHECKS',
+            description: 'Skip API validation at startup',
+            defaultValue: 'false',
+        },
+    ];
+    const missing = required.filter(({ name }) => !process.env[name]);
+    if (missing.length > 0) {
+        logError('validateEnvironment', 'Missing required environment variables:');
+        missing.forEach(({ name, description, example }) => {
+            console.error(`  - ${name}: ${description}`);
+            console.error(`    Example: ${example}`);
+        });
+        if (optional.length > 0) {
+            console.error('\nOptional environment variables:');
+            optional.forEach(({ name, description, defaultValue }) => {
+                const defaultStr = defaultValue ? ` (default: ${defaultValue})` : '';
+                console.error(`  - ${name}: ${description}${defaultStr}`);
+            });
+        }
+        console.error('\n----------------------------------------');
+        console.error('Please set the required environment variables and try again.');
+        console.error('\nExample commands:');
+        missing.forEach(({ name, example }) => {
+            console.error(`  export ${name}="${example}"`);
+        });
+        console.error('----------------------------------------\n');
+        process.exit(1);
+    }
+    // Log warnings for common configuration issues
+    if (process.env.ENABLED_TOOLGROUPS) {
+        logWarning('config', `Tool groups filter active: ${process.env.ENABLED_TOOLGROUPS}`);
+    }
+}
+// =============================================================================
+// HEALTH CHECKS
+// =============================================================================
+// Validates API credentials and connectivity before starting the server.
+// Set SKIP_HEALTH_CHECKS=true to disable (useful for testing).
+// =============================================================================
+async function performHealthChecks() {
+    if (process.env.SKIP_HEALTH_CHECKS === 'true') {
+        logWarning('healthcheck', 'Health checks skipped (SKIP_HEALTH_CHECKS=true)');
+        return;
+    }
+    // For agent-orchestrator, we could add a health check by calling the sessions endpoint
+    // For now, we skip complex validation since the API might not always be available
+}
+// =============================================================================
+// MAIN ENTRY POINT
+// =============================================================================
+async function main() {
+    // Step 1: Validate environment variables
+    validateEnvironment();
+    // Step 2: Perform health checks (validates credentials, connectivity)
+    await performHealthChecks();
+    // Step 3: Create server using factory
+    const { server, registerHandlers } = createMCPServer();
+    // Step 4: Register all handlers (resources and tools)
+    await registerHandlers(server);
+    // Step 5: Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logServerStart('agent-orchestrator');
+}
+// Run the server
+main().catch((error) => {
+    logError('main', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "agent-orchestrator-mcp-server",
+  "version": "0.1.0",
+  "description": "Local implementation of agent-orchestrator MCP server",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "agent-orchestrator-mcp-server": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "shared/**/*.js",
+    "shared/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:integration",
+    "build:integration": "tsc -p tsconfig.integration.json",
+    "start": "node build/index.js",
+    "dev": "tsx src/index.ts",
+    "predev": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prebuild": "cd ../shared && npm run build && cd ../local && node setup-dev.js",
+    "prepublishOnly": "node prepare-publish.js && node ../scripts/prepare-npm-readme.js",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "stage-publish": "npm version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.6",
+    "tsx": "^4.19.4",
+    "typescript": "^5.7.3"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "agent-orchestrator",
+    "pulsemcp"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT"
+}

package/shared/index.d.ts

@@ -0,0 +1,7 @@
+export { registerResources } 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';
+export type { Session, Log, SubagentTranscript, SessionStatus, LogLevel, SubagentStatus, Pagination, SessionsResponse, SearchSessionsResponse, SessionResponse, SessionActionResponse, LogsResponse, LogResponse, SubagentTranscriptsResponse, SubagentTranscriptResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, } from './types.js';
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';
+//# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -0,0 +1,8 @@
+// Core server exports
+export { registerResources } from './resources.js';
+export { registerTools, createRegisterTools, parseEnabledToolGroups, } from './tools.js';
+export { createMCPServer } from './server.js';
+// Client exports
+export { AgentOrchestratorClient, } from './orchestrator-client/orchestrator-client.js';
+// Logging exports (re-exported for convenience)
+export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/logging.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export declare function logServerStart(serverName: string, transport?: string): void;
+/**
+ * Log an error with context
+ */
+export declare function logError(context: string, error: unknown): void;
+/**
+ * Log a warning
+ */
+export declare function logWarning(context: string, message: string): void;
+/**
+ * Log debug information (only in development)
+ */
+export declare function logDebug(context: string, message: string): void;
+//# sourceMappingURL=logging.d.ts.map

package/shared/logging.js

@@ -0,0 +1,34 @@
+/**
+ * Logging utilities for consistent output across MCP servers
+ */
+/**
+ * Log server startup message
+ */
+export function logServerStart(serverName, transport = 'stdio') {
+    console.error(`MCP server ${serverName} running on ${transport}`);
+}
+/**
+ * Log an error with context
+ */
+export function logError(context, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    console.error(`[ERROR] ${context}: ${message}`);
+    if (stack) {
+        console.error(stack);
+    }
+}
+/**
+ * Log a warning
+ */
+export function logWarning(context, message) {
+    console.error(`[WARN] ${context}: ${message}`);
+}
+/**
+ * Log debug information (only in development)
+ */
+export function logDebug(context, message) {
+    if (process.env.NODE_ENV === 'development' || process.env.DEBUG) {
+        console.error(`[DEBUG] ${context}: ${message}`);
+    }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * Agent Orchestrator API Client
+ *
+ * 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';
+/**
+ * Interface for the Agent Orchestrator API client.
+ * Used for dependency injection and testing.
+ */
+export interface IAgentOrchestratorClient {
+    listSessions(options?: {
+        status?: SessionStatus;
+        agent_type?: string;
+        show_archived?: boolean;
+        page?: number;
+        per_page?: number;
+    }): Promise<SessionsResponse>;
+    searchSessions(query: string, options?: {
+        search_contents?: boolean;
+        status?: SessionStatus;
+        agent_type?: string;
+        show_archived?: boolean;
+        page?: number;
+        per_page?: number;
+    }): Promise<SearchSessionsResponse>;
+    getSession(id: string | number, includeTranscript?: boolean): Promise<Session>;
+    createSession(data: CreateSessionRequest): Promise<Session>;
+    updateSession(id: string | number, data: UpdateSessionRequest): Promise<Session>;
+    deleteSession(id: string | number): Promise<void>;
+    archiveSession(id: string | number): Promise<Session>;
+    unarchiveSession(id: string | number): Promise<Session>;
+    followUp(id: string | number, prompt: string): Promise<SessionActionResponse>;
+    pauseSession(id: string | number): Promise<SessionActionResponse>;
+    restartSession(id: string | number): Promise<SessionActionResponse>;
+    listLogs(sessionId: string | number, options?: {
+        level?: LogLevel;
+        page?: number;
+        per_page?: number;
+    }): Promise<LogsResponse>;
+    getLog(sessionId: string | number, logId: number): Promise<Log>;
+    createLog(sessionId: string | number, data: CreateLogRequest): Promise<Log>;
+    updateLog(sessionId: string | number, logId: number, data: UpdateLogRequest): Promise<Log>;
+    deleteLog(sessionId: string | number, logId: number): Promise<void>;
+    listSubagentTranscripts(sessionId: string | number, options?: {
+        status?: SubagentStatus;
+        subagent_type?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<SubagentTranscriptsResponse>;
+    getSubagentTranscript(sessionId: string | number, transcriptId: number, includeTranscript?: boolean): Promise<SubagentTranscript>;
+    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>;
+}
+/**
+ * Implementation of the Agent Orchestrator API client.
+ */
+export declare class AgentOrchestratorClient implements IAgentOrchestratorClient {
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    constructor(baseUrl: string, apiKey: string, timeoutMs?: number);
+    private request;
+    listSessions(options?: {
+        status?: SessionStatus;
+        agent_type?: string;
+        show_archived?: boolean;
+        page?: number;
+        per_page?: number;
+    }): Promise<SessionsResponse>;
+    searchSessions(query: string, options?: {
+        search_contents?: boolean;
+        status?: SessionStatus;
+        agent_type?: string;
+        show_archived?: boolean;
+        page?: number;
+        per_page?: number;
+    }): Promise<SearchSessionsResponse>;
+    getSession(id: string | number, includeTranscript?: boolean): Promise<Session>;
+    createSession(data: CreateSessionRequest): Promise<Session>;
+    updateSession(id: string | number, data: UpdateSessionRequest): Promise<Session>;
+    deleteSession(id: string | number): Promise<void>;
+    archiveSession(id: string | number): Promise<Session>;
+    unarchiveSession(id: string | number): Promise<Session>;
+    followUp(id: string | number, prompt: string): Promise<SessionActionResponse>;
+    pauseSession(id: string | number): Promise<SessionActionResponse>;
+    restartSession(id: string | number): Promise<SessionActionResponse>;
+    listLogs(sessionId: string | number, options?: {
+        level?: LogLevel;
+        page?: number;
+        per_page?: number;
+    }): Promise<LogsResponse>;
+    getLog(sessionId: string | number, logId: number): Promise<Log>;
+    createLog(sessionId: string | number, data: CreateLogRequest): Promise<Log>;
+    updateLog(sessionId: string | number, logId: number, data: UpdateLogRequest): Promise<Log>;
+    deleteLog(sessionId: string | number, logId: number): Promise<void>;
+    listSubagentTranscripts(sessionId: string | number, options?: {
+        status?: SubagentStatus;
+        subagent_type?: string;
+        page?: number;
+        per_page?: number;
+    }): Promise<SubagentTranscriptsResponse>;
+    getSubagentTranscript(sessionId: string | number, transcriptId: number, includeTranscript?: boolean): Promise<SubagentTranscript>;
+    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>;
+}
+//# sourceMappingURL=orchestrator-client.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * Integration mock for the Agent Orchestrator API client.
+ *
+ * Used in integration tests to simulate API responses without hitting real endpoints.
+ */
+import type { IAgentOrchestratorClient } from './orchestrator-client.js';
+import type { Session, Log, SubagentTranscript } from '../types.js';
+interface MockData {
+    sessions?: Session[];
+    logs?: Log[];
+    subagentTranscripts?: SubagentTranscript[];
+}
+/**
+ * Creates a mock Agent Orchestrator client for integration testing.
+ */
+export declare function createIntegrationMockOrchestratorClient(initialMockData?: MockData): IAgentOrchestratorClient & {
+    mockData: MockData;
+};
+export {};
+//# sourceMappingURL=orchestrator-client.integration-mock.d.ts.map