ara_query

Instructions

Implementation Reference

• ara-server.js:207-229 (registration)

  Registration of the 'ara_query' tool in the getToolsList() function, including its name, description, and input schema. This list is returned by the ListToolsRequestSchema handler.

  {
    name: 'ara_query',
    description: 'Query Ara API endpoints with automatic pagination defaults (limit=3, order=-started)',
    inputSchema: {
      type: 'object',
      properties: {
        endpoint: {
          type: 'string',
          description: 'API endpoint path (e.g., /api/v1/playbooks, /api/v1/plays/1). Supports query parameters like ?limit=10&offset=20&order=-started. If no limit is specified, defaults to 3 results.',
        },
        method: {
          type: 'string',
          enum: ['GET', 'POST'],
          default: 'GET',
        },
        body: {
          type: 'object',
          description: 'Request body for POST requests',
        },
      },
      required: ['endpoint'],
    },
  },

• ara-server.js:210-228 (schema)

  Input schema definition for the 'ara_query' tool, specifying parameters like endpoint, method, and body.

  inputSchema: {
    type: 'object',
    properties: {
      endpoint: {
        type: 'string',
        description: 'API endpoint path (e.g., /api/v1/playbooks, /api/v1/plays/1). Supports query parameters like ?limit=10&offset=20&order=-started. If no limit is specified, defaults to 3 results.',
      },
      method: {
        type: 'string',
        enum: ['GET', 'POST'],
        default: 'GET',
      },
      body: {
        type: 'object',
        description: 'Request body for POST requests',
      },
    },
    required: ['endpoint'],
  },

• ara-server.js:396-444 (handler)

  Handler logic for the 'ara_query' tool within the CallToolRequestSchema request handler. Performs HTTP request to the ARA API endpoint with authentication, pagination defaults, and returns JSON response or error.

  if (name === 'ara_query') {
    const { endpoint, method = 'GET', body } = args;
  
    // Apply pagination defaults to prevent token overflow
    const paginatedEndpoint = addPaginationDefaults(endpoint);
  
    const options = {
      method,
      headers: createAuthHeaders(),
    };
  
    if (body && method === 'POST') {
      options.body = JSON.stringify(body);
    }
  
    try {
      const fullUrl = `${ARA_API_SERVER}${paginatedEndpoint}`;
      console.error(`[DEBUG] Fetching URL: ${fullUrl}`);
      console.error(`[DEBUG] Headers:`, JSON.stringify(options.headers, null, 2));
  
      const response = await fetch(fullUrl, options);
  
      console.error(`[DEBUG] Response status: ${response.status}`);
  
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText} - URL: ${fullUrl}`);
      }
  
      const data = await response.json();
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(data, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${error.message}`,
          },
        ],
      };
    }
  }

• ara-server.js:278-295 (helper)

  Helper function addPaginationDefaults used by ara_query to automatically add limit=3 and order=-started to API endpoints preventing token overflow.

  // Helper function to add pagination defaults to endpoints
  function addPaginationDefaults(endpoint) {
    const url = new URL(`${ARA_API_SERVER}${endpoint}`);
  
    // Add default pagination if not already present
    if (!url.searchParams.has('limit')) {
      url.searchParams.set('limit', '3');
    }
  
    // Add default ordering by most recent if not present
    if (!url.searchParams.has('order') &&
        (endpoint.includes('/playbooks') || endpoint.includes('/plays') ||
         endpoint.includes('/tasks') || endpoint.includes('/results'))) {
      url.searchParams.set('order', '-started');
    }
  
    return url.pathname + url.search;
  }

• ara-server.js:67-80 (helper)

  Helper function createAuthHeaders used by ara_query for HTTP authentication.

  function createAuthHeaders() {
    const headers = {
      'Content-Type': 'application/json',
      'User-Agent': 'ara-records-mcp/1.0',
    };
  
    // Add basic authentication if credentials are provided
    if (ARA_USERNAME && ARA_PASSWORD) {
      const credentials = Buffer.from(`${ARA_USERNAME}:${ARA_PASSWORD}`).toString('base64');
      headers['Authorization'] = `Basic ${credentials}`;
    }
  
    return headers;
  }