aliyun-sls-mcp

Instructions

Implementation Reference

• src/tools/get-log-histogram.ts:28-77 (handler)

  The 'handleGetLogHistogram' function executes the logic to fetch log histogram data and format it into a string output.

  export async function handleGetLogHistogram(input: GetLogHistogramInput): Promise<string> {
    let from: number;
    let to: number;
  
    if (input.from && input.to) {
      from = input.from;
      to = input.to;
    } else {
      const range = parseTimeRange(input.time_range);
      from = range.from;
      to = range.to;
    }
  
    const histograms = await getLogHistogram({
      project: input.project,
      logstore: input.logstore,
      query: input.query,
      from,
      to,
      region: input.region,
    });
  
    const fromStr = formatTimestamp(from);
    const toStr = formatTimestamp(to);
    const totalCount = histograms.reduce((sum, h) => sum + h.count, 0);
    const maxCount = Math.max(...histograms.map((h) => h.count), 1);
  
    const header = [
      `## Log Distribution`,
      `**Project**: ${input.project} / **Logstore**: ${input.logstore}`,
      `**Time**: ${fromStr} → ${toStr}`,
      `**Query**: \`${input.query}\``,
      `**Total Logs**: ${totalCount}`,
    ].join('\n');
  
    if (histograms.length === 0) {
      return `${header}\n\nNo data in this time range.`;
    }
  
    const rows = histograms
      .filter((h) => h.count > 0)
      .map((h) => {
        const timeStr = formatTimestamp(h.from);
        const bar = renderBar(h.count, maxCount);
        return `${timeStr}  ${bar}  ${h.count}`;
      })
      .join('\n');
  
    return `${header}\n\n\`\`\`\n${rows}\n\`\`\`\n\nUse this distribution to identify time windows with unusual activity, then query specific windows for detailed logs.`;
  }

• src/tools/get-log-histogram.ts:4-18 (schema)

  The 'getLogHistogramSchema' defines the input validation for the 'get_log_histogram' tool using Zod.

  export const getLogHistogramSchema = z.object({
    project: z.string().describe('SLS project name'),
    logstore: z.string().describe('SLS logstore name'),
    query: z.string().default('*').describe('SLS query statement to filter logs. Default: "*" for all logs'),
    time_range: z
      .string()
      .default('1h')
      .describe('Relative time range. Formats: 15m, 1h, 6h, 12h, 1d, 3d'),
    from: z.number().optional().describe('Start time as Unix timestamp (seconds). Overrides time_range.'),
    to: z.number().optional().describe('End time as Unix timestamp (seconds).'),
    region: z
      .string()
      .optional()
      .describe('Alibaba Cloud region ID, e.g. cn-hangzhou. Defaults to SLS_REGION env variable.'),
  });

• src/index.ts:44-48 (registration)

  Tool registration for 'get_log_histogram' in the MCP server's TOOL list.

    name: 'get_log_histogram',
    description:
      'Get the time-series distribution of log counts matching a query. Returns a visual histogram showing log volume over time. Useful for identifying when errors spiked or when unusual activity occurred.',
    inputSchema: zodToJsonSchema(getLogHistogramSchema) as Tool['inputSchema'],
  },

• src/index.ts:100-103 (handler)

  The handler registration inside the main server request handler to route 'get_log_histogram' calls to 'handleGetLogHistogram'.

  case 'get_log_histogram': {
    const input = getLogHistogramSchema.parse(args);
    text = await handleGetLogHistogram(input);
    break;