mcp-read-only-grafana: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

MCP Read-Only Grafana Server provides a read-only default command plus a separate write-capable command for Grafana via the Model Context Protocol (MCP). It uses session-based authentication and supports multiple Grafana connections simultaneously.

Runtime Config Location

• Live runtime config file: ~/.config/lukleh/mcp-read-only-grafana/connections.yaml
• Checked-in sample file: connections.yaml.sample

Important distinction:

• The installed server reads the live runtime file under ~/.config/... by default
• The checked-in sample file is documentation/source material only
• uv run mcp-read-only-grafana --write-sample-config writes the sample into the resolved runtime config directory
• uv run mcp-read-only-grafana --config-dir /path/to/config-dir changes the live config file to /path/to/config-dir/connections.yaml

Development Commands

# Install dependencies
uv sync --extra dev

# Run the server manually for testing
uv run mcp-read-only-grafana

# Show the resolved runtime paths
uv run mcp-read-only-grafana --print-paths

# Run the separate write-capable command
uv run mcp-grafana-write

# Write or refresh the default sample config
uv run mcp-read-only-grafana --write-sample-config
uv run mcp-read-only-grafana --write-sample-config --overwrite

# Validate configuration through the public root CLI
uv run mcp-read-only-grafana validate-config

# Test all configured connections or one named connection
uv run mcp-read-only-grafana test-connection
uv run mcp-read-only-grafana test-connection production_grafana

# Linting
uv run ruff check src/mcp_read_only_grafana/ tests/

# Run tests
uv run pytest -q

# Run ALL integration tests (requires Grafana credentials)
uv run pytest tests/test_integration_all_endpoints.py -v -m integration

# Run integration tests INCLUDING write-capable endpoints (requires privileged credentials)
RUN_WRITE_TESTS=1 uv run pytest tests/test_integration_all_endpoints.py -v -m integration

# Override the default integration-test connection name if needed
GRAFANA_TEST_CONNECTION_NAME=my_grafana uv run pytest tests/test_integration_all_endpoints.py -v -m integration

# Run specific test category (e.g., only alerting tests)
uv run pytest tests/test_integration_all_endpoints.py::TestAlertingProvisioningAPI -v

# Run only unit tests (no credentials needed)
uv run pytest -v -m "not integration"