Grafana MCP Server

Instructions

Implementation Reference

• src/services/ramp.ts:749-769 (handler)

  The annotateTest service method that executes the core logic: resolves the sensor, constructs the annotation body with text/tags/time, and makes a POST request to the Grafana API endpoint '/api/annotations'

  async annotateTest(options: {
    sensor?: string;
    text: string;
    tags?: string[];
    time?: number;
    timeEnd?: number;
    dashboardUid?: string;
  }): Promise<{ id: number }> {
    const { info, client } = this.resolveSensor(options.sensor);
    const now = Date.now();
    const body: Record<string, any> = {
      text: options.text,
      tags: options.tags ?? ['ramp-test'],
      time: options.time ?? now,
    };
    if (options.timeEnd) body.timeEnd = options.timeEnd;
    if (options.dashboardUid) body.dashboardUID = options.dashboardUid;
  
    const result = await client.post<{ id: number }>('/api/annotations', body);
    return result;
  }

• src/ramp-types.ts:98-105 (schema)

  AnnotateTestSchema Zod schema defining the input validation for the tool with fields: sensor (optional), text (required), tags (optional array), time (optional), timeEnd (optional), and dashboardUid (optional)

  export const AnnotateTestSchema = z.object({
    sensor: z.string().optional().describe('Sensor hostname'),
    text: z.string().min(1).describe('Annotation text'),
    tags: z.array(z.string()).optional().describe('Annotation tags (e.g., ["ramp-test", "ns2"])'),
    time: z.number().optional().describe('Annotation epoch timestamp (defaults to now)'),
    timeEnd: z.number().optional().describe('End epoch timestamp for range annotations'),
    dashboardUid: z.string().optional().describe('Dashboard UID to associate annotation with'),
  });

• src/tools/ramp.ts:321-358 (registration)

  Tool registration for 'annotate_test' that defines the tool metadata, parses input using AnnotateTestSchema, calls the rampService.annotateTest method, and handles errors with appropriate response formatting

  // 7. annotate_test
  registry.registerTool(
    {
      name: 'annotate_test',
      description:
        'Add a Grafana annotation on a sensor for test events ' +
        '(start/end/result/rate change). Supports range annotations and dashboard association. Tagged with ramp-test by default.',
      inputSchema: zodToJsonSchema(AnnotateTestSchema),
    },
    async (request) => {
      try {
        const params = AnnotateTestSchema.parse(request.params.arguments);
        const result = await rampService.annotateTest({
          sensor: params.sensor,
          text: params.text,
          tags: params.tags,
          time: params.time,
          timeEnd: params.timeEnd,
          dashboardUid: params.dashboardUid,
        });
  
        return {
          content: [
            {
              type: 'text',
              text: `Annotation created (id: ${result.id})`,
            },
          ],
        };
      } catch (error) {
        const msg = error instanceof Error ? error.message : 'Unknown error';
        return {
          content: [{ type: 'text', text: `Error creating annotation: ${msg}` }],
          isError: true,
        };
      }
    },
  );