Powerdrill MCP Server

Implementation Reference

• src/index.ts:445-446 (registration)

  Registration of the MCP tool 'mcp_powerdrill_list_sessions'

  server.tool(
    'mcp_powerdrill_list_sessions',

• src/index.ts:447-451 (schema)

  Zod schema defining input parameters for the list_sessions tool: pageNumber, pageSize, search.

  {
    pageNumber: z.number().optional().describe('The page number to start listing (default: 1)'),
    pageSize: z.number().optional().describe('The number of items on a single page (default: 10)'),
    search: z.string().optional().describe('Search for sessions by name')
  },

• src/index.ts:452-539 (handler)

  The handler function that implements the tool logic: initializes PowerdrillClient, calls listSessions API method, processes response, handles errors, and returns formatted MCP content.

  async (args, extra) => {
    try {
      const { pageNumber, pageSize, search } = args;
  
      // Initialize Powerdrill client
      const client = new (await import('./utils/powerdrillClient.js')).PowerdrillClient();
  
      // Fetch sessions
      const response = await client.listSessions({
        pageNumber,
        pageSize,
        search
      });
  
      // Check if response is valid
      if (!response) {
        throw new Error(`Empty response received from API`);
      }
  
      if (response.code !== 0) {
        throw new Error(`API returned error code: ${response.code}, message: ${response.message || 'No message'}`);
      }
  
      if (!response.data || !response.data.records) {
        throw new Error(`Invalid API response format: missing data.records property`);
      }
  
      const sessions = response.data.records || [];
  
      if (sessions.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                message: "No sessions found",
                sessions: []
              }, null, 2)
            }
          ]
        };
      }
  
      // Format the response as MCP content
      const result = {
        page_number: response.data.page_number,
        page_size: response.data.page_size,
        total_items: response.data.total_items,
        count: sessions.length,
        sessions: sessions.map((session: any) => ({
          id: session.id,
          name: session.name,
          output_language: session.output_language,
          job_mode: session.job_mode,
          max_contextual_job_history: session.max_contextual_job_history,
          agent_id: session.agent_id
        }))
      };
  
      // Return the formatted response
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (error: any) {
      console.error(`Error listing sessions: ${error.message}`);
      console.error(error.stack);
  
      // Return error response
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: `Error listing sessions: ${error.message}`,
              errorType: error.name,
              errorStack: process.env.NODE_ENV === 'development' ? error.stack : undefined
            }, null, 2)
          }
        ],
        isError: true
      };
    }
  }

• src/utils/powerdrillClient.ts:262-321 (helper)

  Supporting method PowerdrillClient.listSessions that constructs the API request to /sessions endpoint with query parameters and handles the HTTP response.

  async listSessions(options: { 
    pageNumber?: number;
    pageSize?: number;
    search?: string;
    timeout?: number;
  } = {}) {
    const timeout = options.timeout || 30000; // Default 30 second timeout
  
    try {
      // Build query parameters
      let queryParams = `user_id=${this.config.userId}`;
  
      if (options.pageNumber) {
        queryParams += `&page_number=${options.pageNumber}`;
      }
  
      if (options.pageSize) {
        queryParams += `&page_size=${options.pageSize}`;
      }
  
      if (options.search) {
        queryParams += `&search=${encodeURIComponent(options.search)}`;
      }
  
      const response = await this.client.get(`/sessions?${queryParams}`, {
        timeout: timeout,
        validateStatus: (status) => status >= 200 && status < 500 // Don't throw on 4xx errors
      });
  
      // Handle HTTP errors manually
      if (response.status >= 400) {
        throw new Error(`HTTP error ${response.status}: ${response.statusText || 'Unknown error'}`);
      }
  
      // Validate response structure
      if (!response.data) {
        throw new Error('Invalid API response: missing data');
      }
  
      return response.data;
    } catch (error: any) {
      if (error.code === 'ECONNABORTED') {
        console.error(`PowerdrillClient: Request timed out after ${timeout}ms`);
        throw new Error(`Request timed out after ${timeout}ms`);
      }
  
      if (error.response) {
        // The request was made and the server responded with a status code
        console.error(`PowerdrillClient: HTTP error ${error.response.status}`, error.response.data);
        throw new Error(`API error: ${error.response.status} ${error.response.statusText}`);
      } else if (error.request) {
        // The request was made but no response was received
        console.error('PowerdrillClient: No response received', error.request);
        throw new Error('No response received from API');
      }
  
      console.error('PowerdrillClient: Error listing sessions:', error.message);
      throw error;
    }
  }