Merge pull request #2 from grafana/prometheus-tools

Author: sd2k

README.md

@@ -9,14 +9,15 @@ This provides access to your Grafana instance and the surrounding ecosystem.
 - [x] Search for dashboards
 - [x] List and fetch datasource information
 - [ ] Query datasources
-  - [ ] Prometheus
+  - [x] Prometheus
   - [ ] Loki (log queries, metric queries)
   - [ ] Tempo
   - [ ] Pyroscope
-- [ ] Query Prometheus metadata
-  - [ ] Metric names
-  - [ ] Label names
-  - [ ] Label values
+- [x] Query Prometheus metadata
+  - [x] Metric metadata
+  - [x] Metric names
+  - [x] Label names
+  - [x] Label values
 - [x] Search, create, update and close incidents
 - [ ] Start Sift investigations and view the results
 
@@ -31,6 +32,11 @@ This is useful if you don't use certain functionality or if you don't want to ta
 | `list_datasources` | Datasources | List datasources |
 | `get_datasource_by_uid` | Datasources | Get a datasource by uid |
 | `get_datasource_by_name` | Datasources | Get a datasource by name |
+| `query_prometheus` | Prometheus | Execute a query against a Prometheus datasource |
+| `get_prometheus_metric_metadata` | Prometheus | Get metadata for a metric |
+| `get_prometheus_metric_names` | Prometheus | Get list of available metric names |
+| `get_prometheus_label_names` | Prometheus | Get list of label names for a metric |
+| `get_prometheus_label_values` | Prometheus | Get values for a specific label |
 | `list_incidents` | Incident | List incidents in Grafana Incident |
 | `create_incident` | Incident | Create an incident in Grafana Incident |
 | `add_activity_to_incident` | Incident | Add an activity item to an incident in Grafana Incident |

src/mcp_grafana/client.py

@@ -147,7 +147,7 @@ async def query(self, _from: datetime, to: datetime, queries: list[Query]) -> by
         body = {
             "from": str(math.floor(_from.timestamp() * 1000)),
             "to": str(math.floor(to.timestamp() * 1000)),
-            "queries": query_list.dump_python(queries),
+            "queries": query_list.dump_python(queries, by_alias=True),
         }
         return await self.post("/api/ds/query", json=body)
 

src/mcp_grafana/settings.py

@@ -36,10 +36,21 @@ class IncidentSettings(BaseSettings):
     )
 
 
+class PrometheusSettings(BaseSettings):
+    """
+    Settings for the Prometheus tools.
+    """
+
+    enabled: bool = Field(
+        default=True, description="Whether to enable the Prometheus tools."
+    )
+
+
 class ToolSettings(BaseSettings):
     search: SearchSettings = Field(default_factory=SearchSettings)
     datasources: DatasourcesSettings = Field(default_factory=DatasourcesSettings)
     incident: IncidentSettings = Field(default_factory=IncidentSettings)
+    prometheus: PrometheusSettings = Field(default_factory=PrometheusSettings)
 
 
 class GrafanaSettings(BaseSettings):

src/mcp_grafana/tools/__init__.py

@@ -1,6 +1,6 @@
 from mcp.server import FastMCP
 
-from . import datasources, incident, search
+from . import datasources, incident, prometheus, search
 from ..settings import grafana_settings
 
 
@@ -14,3 +14,5 @@ def add_tools(mcp: FastMCP):
         datasources.add_tools(mcp)
     if grafana_settings.tools.incident.enabled:
         incident.add_tools(mcp)
+    if grafana_settings.tools.prometheus.enabled:
+        prometheus.add_tools(mcp)

src/mcp_grafana/tools/prometheus.py

@@ -0,0 +1,179 @@
+import re
+from datetime import datetime
+from typing import Literal
+
+from mcp.server import FastMCP
+
+from ..client import grafana_client
+from ..grafana_types import (
+    DatasourceRef,
+    DSQueryResponse,
+    PrometheusMetricMetadata,
+    Query,
+    ResponseWrapper,
+    Selector,
+)
+
+
+PrometheusQueryType = Literal["range", "instant"]
+
+
+async def query_prometheus(
+    datasource_uid: str,
+    expr: str,
+    start_rfc3339: str,
+    end_rfc3339: str,
+    step_seconds: int,
+    query_type: PrometheusQueryType = "range",
+) -> DSQueryResponse:
+    """
+    Query Prometheus using a range request.
+
+    # Parameters.
+
+    datasource_uid: The uid of the datasource to query.
+    expr: The PromQL expression to query.
+    start_rfc3339: The start time in RFC3339 format.
+    end_rfc3339: The end time in RFC3339 format. Ignored if `query_type` is 'instant'.
+    step_seconds: The time series step size in seconds. Ignored if `query_type` is 'instant'.
+    query_type: The type of query to use. Either 'range' or 'instant'.
+    """
+    start = datetime.fromisoformat(start_rfc3339)
+    end = datetime.fromisoformat(end_rfc3339)
+    query = Query(
+        refId="A",
+        datasource=DatasourceRef(
+            uid=datasource_uid,
+            type="prometheus",
+        ),
+        queryType=query_type,
+        expr=expr,  # type: ignore
+        intervalMs=step_seconds * 1000,
+    )
+    response = await grafana_client.query(start, end, [query])
+    return DSQueryResponse.model_validate_json(response)
+
+
+async def get_prometheus_metric_metadata(
+    datasource_uid: str,
+    limit: int | None = None,
+    limit_per_metric: int | None = None,
+    metric: str | None = None,
+) -> dict[str, list[PrometheusMetricMetadata]]:
+    """
+    Get metadata for all metrics in Prometheus.
+
+    # Parameters.
+
+    datasource_uid: The uid of the Grafana datasource to query.
+    limit: Optionally, the maximum number of results to return.
+    limit_per_metric: Optionally, the maximum number of results to return per metric.
+    metric: Optionally, a metric name to filter the results by.
+
+    # Returns.
+
+    A mapping from metric name to all available metadata for that metric.
+    """
+    response = await grafana_client.get_prometheus_metric_metadata(
+        datasource_uid,
+        limit=limit,
+        limit_per_metric=limit_per_metric,
+        metric=metric,
+    )
+    return (
+        ResponseWrapper[dict[str, list[PrometheusMetricMetadata]]]
+        .model_validate_json(response)
+        .data
+    )
+
+
+async def get_prometheus_metric_names(
+    datasource_uid: str,
+    regex: str,
+) -> list[str]:
+    """
+    Get metric names in a Prometheus datasource that match the given regex.
+
+    # Parameters.
+
+    datasource_uid: The uid of the Grafana datasource to query.
+    regex: The regex to match against the metric names. Uses Python's re.match.
+
+    # Returns.
+
+    A list of metric names that match the given regex.
+    """
+    name_label_values = await get_prometheus_label_values(datasource_uid, "__name__")
+    compiled = re.compile(regex)
+    return [name for name in name_label_values if compiled.match(name)]
+
+
+async def get_prometheus_label_names(
+    datasource_uid: str,
+    matches: list[Selector] | None = None,
+    start: datetime | None = None,
+    end: datetime | None = None,
+    limit: int | None = None,
+) -> list[str]:
+    """
+    Get the label names in a Prometheus datasource, optionally filtered to those
+    matching the given selectors and within the given time range.
+
+    If you want to get the label names for a specific metric, pass a matcher
+    like `{__name__="metric_name"}` to the `matches` parameter.
+
+    # Parameters.
+
+    datasource_uid: The uid of the Grafana datasource to query.
+    matches: Optionally, a list of label matchers to filter the results by.
+    start: Optionally, the start time of the time range to filter the results by.
+    end: Optionally, the end time of the time range to filter the results by.
+    limit: Optionally, the maximum number of results to return.
+    """
+    response = await grafana_client.get_prometheus_label_names(
+        datasource_uid,
+        matches=matches,
+        start=start,
+        end=end,
+        limit=limit,
+    )
+    return ResponseWrapper[list[str]].model_validate_json(response).data
+
+
+async def get_prometheus_label_values(
+    datasource_uid: str,
+    label_name: str,
+    matches: list[Selector] | None = None,
+    start: datetime | None = None,
+    end: datetime | None = None,
+    limit: int | None = None,
+):
+    """
+    Get the values of a label in Prometheus.
+
+    # Parameters.
+
+    datasource_uid: The uid of the Grafana datasource to query.
+    label_name: The name of the label to query.
+    matches: Optionally, a list of selectors to filter the results by.
+    start: Optionally, the start time of the query.
+    end: Optionally, the end time of the query.
+    limit: Optionally, the maximum number of results to return.
+    """
+    response = await grafana_client.get_prometheus_label_values(
+        datasource_uid,
+        label_name,
+        matches=matches,
+        start=start,
+        end=end,
+        limit=limit,
+    )
+    return ResponseWrapper[list[str]].model_validate_json(response).data
+
+
+def add_tools(mcp: FastMCP):
+    mcp.add_tool(query_prometheus)
+    mcp.add_tool(get_prometheus_metric_metadata)
+    mcp.add_tool(get_prometheus_metric_names)
+    mcp.add_tool(get_prometheus_label_names)
+    mcp.add_tool(get_prometheus_label_values)

tests/tools/prometheus_test.py

@@ -0,0 +1,73 @@
+from datetime import datetime, timedelta
+
+import pytest
+
+from mcp_grafana.grafana_types import LabelMatcher, Selector
+from mcp_grafana.tools.prometheus import (
+    query_prometheus,
+    get_prometheus_metric_metadata,
+    get_prometheus_metric_names,
+    get_prometheus_label_names,
+    get_prometheus_label_values,
+)
+
+from . import mark_integration
+
+pytestmark = mark_integration
+
+
+@pytest.mark.parametrize("step_seconds", [15, 60, 300])
+async def test_query_prometheus_range(step_seconds):
+    end = datetime.now()
+    start = end - timedelta(minutes=10)
+
+    results = await query_prometheus(
+        "robustperception",
+        start_rfc3339=start.isoformat(),
+        end_rfc3339=end.isoformat(),
+        step_seconds=step_seconds,
+        expr="node_load1",
+        query_type="range",
+    )
+    query_result = results.results["A"]
+    assert query_result.status == 200
+    assert (
+        query_result.frames[0].data.values[0][0] - start.timestamp() * 1000
+        < step_seconds * 1000
+    )
+    assert (
+        len(query_result.frames[0].data.values[0])
+        == (end - start).total_seconds() // step_seconds + 1
+    )
+
+
+async def test_get_prometheus_metric_metadata():
+    # Test fetching metric metadata
+    metadata = await get_prometheus_metric_metadata("robustperception", 10)
+    assert 0 < len(metadata) <= 10
+
+
+async def test_get_prometheus_metric_names():
+    # Test getting list of available metric names
+    metric_names = await get_prometheus_metric_names("robustperception", ".*")
+    assert isinstance(metric_names, list)
+    assert len(metric_names) > 0
+    assert "up" in metric_names  # 'up' metric should always be present
+
+
+async def test_get_prometheus_label_names():
+    # Test getting list of label names for a metric
+    label_names = await get_prometheus_label_names(
+        "robustperception",
+        [Selector(filters=[LabelMatcher(name="job", value="node")])],
+    )
+    assert isinstance(label_names, list)
+    assert len(label_names) > 0
+    assert "instance" in label_names  # 'instance' is a common label
+
+
+async def test_get_prometheus_label_values():
+    # Test getting values for a specific label
+    label_values = await get_prometheus_label_values("robustperception", "job")
+    assert isinstance(label_values, list)
+    assert len(label_values) > 0