feat: adds admin category for listing teams (#124)

* feat: adds admin category for listing teams

* rename to admin

* add: admin e2e tests

* fix: check for grafana env set and removal of duplicate function

* revert back enforcement of GRAFANA_API_KEY

* change wording of text and tool description

* test to call out to the grafana api for team creation

* call out to api to create tests for test setup

* make the judge look at the team name

Author: eleijonmarck

README.md

@@ -49,6 +49,12 @@ This provides access to your Grafana instance and the surrounding ecosystem.
   - [x] Get current on-call users
   - [x] List teams and users
   - [ ] List alert groups
+- [x] Admin functionality
+  - [ ] List users
+  - [x] List teams
+  - [ ] List roles
+  - [ ] List assignments of roles
+  - [ ] Debug role assignments
 
 The list of tools is configurable, so you can choose which tools you want to make available to the MCP client.
 This is useful if you don't use certain functionality or if you don't want to take up too much of the context window.
@@ -58,7 +64,8 @@ the OnCall tools, use `--disable-oncall`.
 ### Tools
 
 | Tool                              | Category    | Description                                                        |
-|-----------------------------------|-------------|--------------------------------------------------------------------|
+| --------------------------------- | ----------- | ------------------------------------------------------------------ |
+| `list_teams`                      | Admin       | List all teams                                                     |
 | `search_dashboards`               | Search      | Search for dashboards                                              |
 | `get_dashboard_by_uid`            | Dashboard   | Get a dashboard by uid                                             |
 | `update_dashboard`                | Dashboard   | Update or create a new dashboard                                   |
@@ -100,16 +107,16 @@ the OnCall tools, use `--disable-oncall`.
 
 2. You have several options to install `mcp-grafana`:
 
-   * **Docker image**: Use the pre-built Docker image from Docker Hub:
+   - **Docker image**: Use the pre-built Docker image from Docker Hub:
 
      ```bash
      docker pull mcp/grafana
      docker run -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana
      ```
 
-   * **Download binary**: Download the latest release of `mcp-grafana` from the [releases page](https://github.com/grafana/mcp-grafana/releases) and place it in your `$PATH`.
+   - **Download binary**: Download the latest release of `mcp-grafana` from the [releases page](https://github.com/grafana/mcp-grafana/releases) and place it in your `$PATH`.
 
-   * **Build from source**: If you have a Go toolchain installed you can also build and install it from source, using the `GOBIN` environment variable
+   - **Build from source**: If you have a Go toolchain installed you can also build and install it from source, using the `GOBIN` environment variable
      to specify the directory where the binary should be installed. This should also be in your `PATH`.
 
      ```bash
@@ -119,6 +126,7 @@ the OnCall tools, use `--disable-oncall`.
 3. Add the server configuration to your client configuration file. For example, for Claude Desktop:
 
    **If using the binary:**
+
    ```json
    {
      "mcpServers": {
@@ -135,6 +143,7 @@ the OnCall tools, use `--disable-oncall`.
    ```
 
    **If using Docker:**
+
    ```json
    {
      "mcpServers": {
@@ -162,7 +171,6 @@ the OnCall tools, use `--disable-oncall`.
 
 > Note: if you see `Error: spawn mcp-grafana ENOENT` in Claude Desktop, you need to specify the full path to `mcp-grafana`.
 
-
 **Using VSCode with remote MCP server**
 
 Make sure your `.vscode/settings.json` includes:
@@ -185,6 +193,7 @@ You can enable debug mode for the Grafana transport by adding the `-debug` flag
 To use debug mode with the Claude Desktop configuration, update your config as follows:
 
 **If using the binary:**
+
 ```json
 {
   "mcpServers": {
@@ -201,6 +210,7 @@ To use debug mode with the Claude Desktop configuration, update your config as f
 ```
 
 **If using Docker:**
+
 ```json
 {
   "mcpServers": {
@@ -256,24 +266,29 @@ docker run -it --rm -p 8000:8000 mcp-grafana:latest
 There are three types of tests available:
 
 1. Unit Tests (no external dependencies required):
+
 ```bash
 make test-unit
 ```
 
 You can also run unit tests with:
+
 ```bash
 make test
 ```
 
 2. Integration Tests (requires docker containers to be up and running):
+
 ```bash
 make test-integration
 ```
 
 3. Cloud Tests (requires cloud Grafana instance and credentials):
+
 ```bash
 make test-cloud
 ```
+
 > Note: Cloud tests are automatically configured in CI. For local development, you'll need to set up your own Grafana Cloud instance and credentials.
 
 More comprehensive integration tests will require a Grafana instance to be running locally on port 3000; you can start one with Docker Compose:

cmd/mcp-grafana/main.go

@@ -34,7 +34,7 @@ type disabledTools struct {
 
 	search, datasource, incident,
 	prometheus, loki, alerting,
-	dashboard, oncall, asserts, sift bool
+	dashboard, oncall, asserts, sift, admin bool
 }
 
 // Configuration for the Grafana client.
@@ -44,7 +44,7 @@ type grafanaConfig struct {
 }
 
 func (dt *disabledTools) addFlags() {
-	flag.StringVar(&dt.enabledTools, "enabled-tools", "search,datasource,incident,prometheus,loki,alerting,dashboard,oncall,asserts,sift", "A comma separated list of tools enabled for this server. Can be overwritten entirely or by disabling specific components, e.g. --disable-search.")
+	flag.StringVar(&dt.enabledTools, "enabled-tools", "search,datasource,incident,prometheus,loki,alerting,dashboard,oncall,asserts,sift,admin", "A comma separated list of tools enabled for this server. Can be overwritten entirely or by disabling specific components, e.g. --disable-search.")
 
 	flag.BoolVar(&dt.search, "disable-search", false, "Disable search tools")
 	flag.BoolVar(&dt.datasource, "disable-datasource", false, "Disable datasource tools")
@@ -56,6 +56,7 @@ func (dt *disabledTools) addFlags() {
 	flag.BoolVar(&dt.oncall, "disable-oncall", false, "Disable oncall tools")
 	flag.BoolVar(&dt.asserts, "disable-asserts", false, "Disable asserts tools")
 	flag.BoolVar(&dt.sift, "disable-sift", false, "Disable sift tools")
+	flag.BoolVar(&dt.admin, "disable-admin", false, "Disable admin tools")
 }
 
 func (gc *grafanaConfig) addFlags() {
@@ -74,6 +75,7 @@ func (dt *disabledTools) addTools(s *server.MCPServer) {
 	maybeAddTools(s, tools.AddOnCallTools, enabledTools, dt.oncall, "oncall")
 	maybeAddTools(s, tools.AddAssertsTools, enabledTools, dt.asserts, "asserts")
 	maybeAddTools(s, tools.AddSiftTools, enabledTools, dt.sift, "sift")
+	maybeAddTools(s, tools.AddAdminTools, enabledTools, dt.admin, "admin")
 }
 
 func newServer(dt disabledTools) *server.MCPServer {

tests/admin_test.py

@@ -0,0 +1,103 @@
+from typing import Dict
+import pytest
+from langevals import expect
+from langevals_langevals.llm_boolean import (
+    CustomLLMBooleanEvaluator,
+    CustomLLMBooleanSettings,
+)
+from litellm import Message, acompletion
+from mcp import ClientSession
+import aiohttp
+import uuid
+import os
+from conftest import DEFAULT_GRAFANA_URL
+
+from conftest import models
+from utils import (
+    get_converted_tools,
+    llm_tool_call_sequence,
+)
+
+pytestmark = pytest.mark.anyio
+
+
+@pytest.fixture
+async def grafana_team():
+    """Create a temporary test team and clean it up after the test is done."""
+    # Generate a unique team name to avoid conflicts
+    team_name = f"test-team-{uuid.uuid4().hex[:8]}"
+
+    # Get Grafana URL and API key from environment
+    grafana_url = os.environ.get("GRAFANA_URL", DEFAULT_GRAFANA_URL)
+
+    auth_header = None
+    if api_key := os.environ.get("GRAFANA_API_KEY"):
+        auth_header = {"Authorization": f"Bearer {api_key}"}
+
+    if not auth_header:
+        pytest.skip("No authentication credentials available to create team")
+
+    # Create the team using Grafana API
+    team_id = None
+    async with aiohttp.ClientSession() as session:
+        create_url = f"{grafana_url}/api/teams"
+        async with session.post(
+            create_url,
+            headers=auth_header,
+            json={"name": team_name, "email": f"{team_name}@example.com"},
+        ) as response:
+            if response.status != 200:
+                resp_text = await response.text()
+                pytest.skip(f"Failed to create team: {resp_text}")
+            resp_data = await response.json()
+            team_id = resp_data.get("teamId")
+
+    # Yield the team info for the test to use
+    yield {"id": team_id, "name": team_name}
+
+    # Clean up after the test
+    if team_id:
+        async with aiohttp.ClientSession() as session:
+            delete_url = f"{grafana_url}/api/teams/{team_id}"
+            async with session.delete(delete_url, headers=auth_header) as response:
+                if response.status != 200:
+                    resp_text = await response.text()
+                    print(f"Warning: Failed to delete team: {resp_text}")
+
+
+@pytest.mark.parametrize("model", models)
+@pytest.mark.flaky(max_runs=3)
+async def test_list_teams_tool(
+    model: str, mcp_client: ClientSession, grafana_team: Dict[str, str]
+):
+    tools = await get_converted_tools(mcp_client)
+    team_name = grafana_team["name"]
+    prompt = "Can you list the teams in Grafana?"
+
+    messages = [
+        Message(role="system", content="You are a helpful assistant."),
+        Message(role="user", content=prompt),
+    ]
+
+    # 1. Call the list teams tool
+    messages = await llm_tool_call_sequence(
+        model,
+        messages,
+        tools,
+        mcp_client,
+        "list_teams",
+    )
+
+    # 2. Final LLM response
+    response = await acompletion(model=model, messages=messages, tools=tools)
+    content = response.choices[0].message.content
+    panel_queries_checker = CustomLLMBooleanEvaluator(
+        settings=CustomLLMBooleanSettings(
+            prompt=(
+                "Does the response contain specific information about "
+                "the teams in Grafana?"
+                f"There should be a team named {team_name}. "
+            ),
+        )
+    )
+    expect(input=prompt, output=content).to_pass(panel_queries_checker)

tests/conftest.py

@@ -40,17 +40,6 @@ async def mcp_client(mcp_url, grafana_headers):
 def mcp_url():
     return os.environ.get("MCP_GRAFANA_URL", DEFAULT_MCP_URL)
 
-
-@pytest.fixture
-def grafana_headers():
-    headers = {
-        "X-Grafana-URL": os.environ.get("GRAFANA_URL", DEFAULT_GRAFANA_URL),
-    }
-    if key := os.environ.get("GRAFANA_API_KEY"):
-        headers["X-Grafana-API-Key"] = key
-    return headers
-
-
 @pytest.fixture
 async def mcp_client(mcp_url, grafana_headers):
     async with sse_client(mcp_url, headers=grafana_headers) as (

tools/admin.go

@@ -0,0 +1,39 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/mark3labs/mcp-go/server"
+
+	"github.com/grafana/grafana-openapi-client-go/client/teams"
+	"github.com/grafana/grafana-openapi-client-go/models"
+	mcpgrafana "github.com/grafana/mcp-grafana"
+)
+
+type ListTeamsParams struct {
+	Query string `json:"query" jsonschema:"description=The query to search for teams. Can be left empty to fetch all teams"`
+}
+
+func listTeams(ctx context.Context, args ListTeamsParams) (*models.SearchTeamQueryResult, error) {
+	c := mcpgrafana.GrafanaClientFromContext(ctx)
+	params := teams.NewSearchTeamsParamsWithContext(ctx)
+	if args.Query != "" {
+		params.SetQuery(&args.Query)
+	}
+	search, err := c.Teams.SearchTeams(params)
+	if err != nil {
+		return nil, fmt.Errorf("search teams for %+v: %w", c, err)
+	}
+	return search.Payload, nil
+}
+
+var ListTeams = mcpgrafana.MustTool(
+	"list_teams",
+	"Search for Grafana teams by a query string. Returns a list of matching teams with details like name, ID, and URL.",
+	listTeams,
+)
+
+func AddAdminTools(mcp *server.MCPServer) {
+	ListTeams.Register(mcp)
+}