Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (83 loc) · 3.53 KB

CLAUDE.md

File metadata and controls

113 lines (83 loc) · 3.53 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a FastMCP server that allows querying Loki logs from Grafana through the Model Context Protocol (MCP). The server provides tools to query logs, get label information, and format results for Grafana/Loki log analysis.

Development Commands

Setup and Installation

# Install dependencies using uv (preferred package manager)
uv pip install -e ".[dev]"

# Install uv if not available
pip install uv

Testing

# Run all tests
pytest

# Run tests with coverage
pytest --cov=. --cov-report=term

# Run specific test files
pytest tests/test_server.py
pytest tests/test_parse_grafana_time.py

Code Quality and Linting

# Run ruff linter
ruff check .

# Run black formatter
black .

# Run type checking
mypy .

Running the Server

# Development mode with environment variables
export GRAFANA_URL=https://your-grafana-instance.com
export GRAFANA_API_KEY=your-api-key
python -m grafana_loki_mcp

# With command line arguments
python -m grafana_loki_mcp -u https://your-grafana-instance.com -k your-api-key

# Using uvx (for production)
uvx grafana-loki-mcp -u GRAFANA_URL -k GRAFANA_API_KEY

Architecture

Core Components

  1. GrafanaClient (grafana_loki_mcp/server.py): Main client class that handles communication with Grafana API

    • Manages Loki datasource discovery and proxying
    • Handles time format conversion (ISO8601, Unix timestamps, Grafana relative times)
    • Provides error handling with detailed error messages

  2. FastMCP Server (grafana_loki_mcp/server.py): MCP server implementation using FastMCP framework

    • Exposes tools for querying Loki logs, getting labels, and formatting results
    • Handles dynamic tool description updates with available labels
    • Supports both stdio and SSE transport protocols

  3. Time Parsing (parse_grafana_time function): Handles multiple time formats

    • Grafana relative times (e.g., 'now-1h', 'now')
    • ISO8601 format
    • Unix timestamps
    • RFC3339 format

Available MCP Tools

  • query_loki: Query Loki logs with LogQL syntax
  • get_loki_labels: Get all available label names from Loki
  • get_loki_label_values: Get values for a specific label
  • format_loki_results: Format query results in text, JSON, or markdown
  • get_datasources: Get all Grafana datasources
  • get_datasource_by_id/name: Get specific datasource information

Key Configuration

  • Environment Variables: GRAFANA_URL, GRAFANA_API_KEY
  • Transport Protocols: stdio (default), sse
  • Server Port: 52229 (for SSE mode)

Test Structure

Tests use pytest with the following setup:

  • conftest.py: Provides session-scoped mocks for Grafana API calls during testing
  • Mock clients prevent actual API calls during test runs
  • Tests cover time parsing, server functionality, and error handling

Package Management

This project uses uv as the preferred package manager. Key dependencies:

  • fastmcp>=0.1.0: FastMCP framework for MCP server implementation
  • requests>=2.25.0: HTTP client for Grafana API communication
  • Development dependencies include: black, ruff, mypy, pytest, pytest-cov

Important Notes

  • The server automatically discovers Loki datasources from Grafana
  • Time handling supports both Grafana-style relative times and absolute timestamps
  • Log line truncation is configurable via max_per_line parameter
  • Error handling provides detailed information including response details from failed API calls