run_nrql_query

Instructions

Implementation Reference

• src/tools/nrql.ts:44-65 (handler)

  Main execution handler for run_nrql_query. Validates input (non-empty NRQL, valid account ID), then calls this.client.runNrqlQuery() and returns the result.

    async execute(input: { nrql?: string; target_account_id?: string }): Promise<NrqlQueryResult> {
      // Validate input
      if (!input.nrql || typeof input.nrql !== 'string' || input.nrql.trim() === '') {
        throw new Error('Invalid or empty NRQL query provided');
      }
  
      if (!input.target_account_id) {
        throw new Error('Account ID must be provided');
      }
  
      if (input.target_account_id && !/^\d+$/.test(input.target_account_id)) {
        throw new Error('Invalid account ID format');
      }
  
      const result = await this.client.runNrqlQuery({
        nrql: input.nrql,
        accountId: input.target_account_id,
      });
  
      return result;
    }
  }

• src/tools/nrql.ts:5-8 (schema)

  Zod input validation schema for run_nrql_query: nrql (required, min 1 char) and target_account_id (optional string).

  const _NrqlInputSchema = z.object({
    nrql: z.string().min(1),
    target_account_id: z.string().optional(),
  });

• src/tools/nrql.ts:27-42 (schema)

  JSON Schema input schema for the tool definition: nrql (required string) and target_account_id (optional string) properties.

  getInputSchema() {
    return {
      type: 'object' as const,
      properties: {
        nrql: {
          type: 'string',
          description: 'The NRQL query to execute',
        },
        target_account_id: {
          type: 'string',
          description: 'Optional New Relic account ID to query',
        },
      },
      required: ['nrql'],
    };
  }

• src/server.ts:57-106 (registration)

  Tool registration: NrqlTool instantiated with client, getToolDefinition() called to build tool metadata, stored in the tools Map for MCP discovery.

  private registerTools(): void {
    const nrqlTool = new NrqlTool(this.client);
    const apmTool = new ApmTool(this.client);
    const entityTool = new EntityTool(this.client);
    const alertTool = new AlertTool(this.client);
    const syntheticsTool = new SyntheticsTool(this.client);
    const nerdGraphTool = new NerdGraphTool(this.client);
    const restDeployments = new RestDeploymentsTool();
    const restApm = new RestApmTool();
    const restMetrics = new RestMetricsTool();
  
    // Register all tools
    const tools = [
      nrqlTool.getToolDefinition(),
      apmTool.getListApplicationsTool(),
      entityTool.getSearchTool(),
      entityTool.getDetailsTool(),
      alertTool.getPoliciesTool(),
      alertTool.getIncidentsTool(),
      alertTool.getAcknowledgeTool(),
      syntheticsTool.getListMonitorsTool(),
      syntheticsTool.getCreateMonitorTool(),
      nerdGraphTool.getQueryTool(),
      // REST v2 tools
      restDeployments.getCreateTool(),
      restDeployments.getListTool(),
      restDeployments.getDeleteTool(),
      restApm.getListApplicationsTool(),
      restMetrics.getListMetricNamesTool(),
      restMetrics.getMetricDataTool(),
      restMetrics.getListApplicationHostsTool(),
      {
        name: 'get_account_details',
        description: 'Get New Relic account details',
        inputSchema: {
          type: 'object' as const,
          properties: {
            target_account_id: {
              type: 'string' as const,
              description: 'Optional account ID to get details for',
            },
          },
        },
      },
    ];
  
    tools.forEach((tool) => {
      this.tools.set(tool.name, tool);
    });
  }

• src/client/newrelic-client.ts:114-187 (helper)

  Client helper that executes the actual NRQL query via New Relic's NerdGraph API. Builds a GraphQL query, calls executeNerdGraphQuery, parses results, and detects time series queries.

  async runNrqlQuery(params: { nrql: string; accountId: string }): Promise<NrqlQueryResult> {
    if (!params.nrql || typeof params.nrql !== 'string') {
      throw new Error('Invalid or empty NRQL query provided');
    }
  
    if (!params.accountId || !/^\d+$/.test(params.accountId)) {
      throw new Error('Invalid account ID format');
    }
  
    const query = `{
      actor {
        account(id: ${params.accountId}) {
          nrql(query: "${params.nrql.replace(/"/g, '\\"')}") {
            results
            metadata {
              eventTypes
              timeWindow {
                begin
                end
              }
              facets
            }
          }
        }
      }
    }`;
  
    try {
      type NrqlResponse = {
        actor?: {
          account?: {
            nrql?: {
              results?: Array<Record<string, unknown>>;
              metadata?: {
                eventTypes?: string[];
                timeWindow?: { begin: number; end: number };
                facets?: string[];
              };
            };
          };
        };
      };
      const response = (await this.executeNerdGraphQuery<NrqlResponse>(
        query
      )) as GraphQLResponse<NrqlResponse>;
  
      if (response.errors) {
        const errorMessage = response.errors[0]?.message || 'NRQL query failed';
        throw new Error(errorMessage);
      }
  
      const nrqlResult = response.data?.actor?.account?.nrql;
  
      if (!nrqlResult) {
        throw new Error('No results returned from NRQL query');
      }
  
      // Detect if it's a time series query
      const isTimeSeries = params.nrql.toLowerCase().includes('timeseries');
  
      return {
        results: nrqlResult.results || [],
        metadata: {
          ...nrqlResult.metadata,
          timeSeries: isTimeSeries,
        },
      };
    } catch (error: unknown) {
      if (error instanceof Error && error.message.includes('Syntax error')) {
        throw new Error(`NRQL Syntax error: ${error.message}`);
      }
      throw error instanceof Error ? error : new Error(String(error));
    }
  }