Create formal documentation (#759)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Ben Sully <ben.sully@grafana.com>

Author: 3 people

README.md

@@ -548,7 +548,7 @@ Forwarded headers are merged with any headers defined in `GRAFANA_EXTRA_HEADERS`
    - **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
-     to specify the directory where the binary should be installed. This should also be in your `PATH`.
+     to specify the directory where the binary should be installed. This should also be in your `$PATH`.
 
      ```bash
      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

docs/Makefile

@@ -0,0 +1,13 @@
+.DEFAULT_GOAL: help
+
+# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
+.PHONY: help
+help: ## Display this help.
+help:
+	@awk 'BEGIN {FS = ": ##"; printf "Usage:\n  make <target>\n\nTargets:\n"} /^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf "  %-45s %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+include docs.mk
+
+.PHONY: test
+test:
+	docker run -v $(CURDIR)/sources:/hugo/content/docs/mcp-server/latest -e HUGO_REFLINKSERRORLEVEL=ERROR --rm grafana/docs-base:latest /bin/bash -c 'exec make hugo'

docs/docs.agent/README.md

@@ -37,7 +37,7 @@ Ensure you have the necessary prerequisites to install, update, and use the agen
 
 ### Prerequisites
 
-- Python 3 `python3` in your shell `PATH`
+- Python 3 `python3` in your shell `$PATH`
 - A frontier AI model and agent, ideally with a GitHub MCP server
 
 I recommend [VS Code GitHub Copilot](https://code.visualstudio.com/) as it has the following benefits:

docs/docs.agent/context.md

@@ -2,29 +2,76 @@
 
 Follow and keep this documentation context and plan up to date.
 
-This repository <GIT_REPOSITORY> is the main context source.
+This repository **github.com/grafana/mcp-grafana** is the main context source.
 
 If you have additional project or repository context sources, list them here:
 
-- Source 1
-- Source 2
-- Source 3
+- [Model Context Protocol](https://modelcontextprotocol.io/) specification
+- [Grafana API documentation](https://grafana.com/docs/grafana/latest/developers/http_api/)
 
 Output docs to `docs/sources/`.
 
-Order sections and articles as they are below.
+Order sections as they appear below: Clients, then Set up, then Configure.
 
 Add articles as h3 subsections with a list of:
 
 - Relevant source files for context
 - Things to include and not include
 
+## Clients
+
+Output client-specific setup docs to `docs/sources/clients/`.
+
+One article per client. Each covers prerequisites, config file location, and a working server block.
+
+### Claude Desktop
+
+- **Context:** docs/clients/claude-desktop.md
+- **Include:** Config path by OS, JSON example, uvx and binary options.
+- **Exclude:** General MCP theory.
+
+### Cursor
+
+- **Context:** docs/clients/cursor.md
+- **Include:** Global vs project mcp.json, UI and manual config.
+- **Exclude:** Other clients.
+
+### Other clients (Codex, VS Code Copilot, Windsurf, Zed, Claude Code, Gemini CLI)
+
+- **Context:** docs/clients/*.md for each
+- **Include:** Same pattern – prerequisites, config path, example block.
+- **Exclude:** Duplicating README installation.
+
 ## Set up
 
 Output setup docs to `docs/sources/set-up/`.
 
-Create individual articles for each setup method.
-Order articles from recommended to advanced setups.
+Create individual articles for each setup method (install and run the server).
+Order articles from fewer steps to more involved (uvx, Docker, binary, Helm).
+
+### Install with uvx
+
+- **Context:** README.md (Quick Start, Usage), cmd/
+- **Include:** Prerequisite (uv), minimal JSON config, GRAFANA_URL and GRAFANA_SERVICE_ACCOUNT_TOKEN. Grafana Cloud URL example.
+- **Exclude:** All other install methods, deep configuration.
+
+### Install with Docker
+
+- **Context:** README.md (Docker image, STDIO vs SSE vs streamable-http)
+- **Include:** docker pull/run for stdio and SSE, port mapping, env vars. Override `-t stdio` for stdio mode.
+- **Exclude:** Helm, binary, TLS server config (cover in Configure).
+
+### Install the binary
+
+- **Context:** README.md (Download binary, Build from source)
+- **Include:** Releases page link, GOBIN/path, `go install` for source build.
+- **Exclude:** uvx and Docker steps.
+
+### Deploy with Helm
+
+- **Context:** README.md (Helm chart)
+- **Include:** helm repo add/install, grafana.apiKey and grafana.url. Link to helm-charts repo.
+- **Exclude:** In-cluster Grafana setup (out of scope).
 
 ## Configure
 
@@ -33,13 +80,53 @@ Output configure docs to `docs/sources/configure/`.
 Create individual articles for each feature or component.
 Order articles from foundational to advanced configuration.
 
+### Authentication
+
+- **Context:** README.md (Usage, service account, env vars)
+- **Include:** Service account token (recommended), username/password, GRAFANA_SERVICE_ACCOUNT_TOKEN and GRAFANA_API_KEY deprecation. Link to Grafana service account docs.
+- **Exclude:** TLS client certs (separate article).
+
+### Transports and addresses
+
+- **Context:** README.md (CLI Flags Reference, Transport Options)
+- **Include:** stdio (default for local), sse, streamable-http; --address, --base-path, --endpoint-path. When to use each.
+- **Exclude:** Client config examples (covered in Set up / client docs).
+
+### Enable and disable tools
+
+- **Context:** README.md (Tool Configuration, --enabled-tools, --disable-*)
+- **Include:** --enabled-tools for runpanelquery, examples, clickhouse, cloudwatch, etc. --disable-* by category. Read-only mode (--disable-write).
+- **Exclude:** Full tool list (refer to README or introduction).
+
+### Client TLS (Grafana connection)
+
+- **Context:** README.md (TLS Configuration, Client TLS)
+- **Include:** --tls-cert-file, --tls-key-file, --tls-ca-file, --tls-skip-verify. Env-based config not required for this article.
+- **Exclude:** Server TLS (streamable-http only).
+
+### Server TLS (streamable-http)
+
+- **Context:** README.md (Server TLS Configuration)
+- **Include:** --server.tls-cert-file, --server.tls-key-file. When and why (HTTPS for MCP server).
+- **Exclude:** Client TLS, Docker internal networking.
+
+### Multi-organization and headers
+
+- **Context:** README.md (Multi-Organization Support, Custom HTTP Headers)
+- **Include:** GRAFANA_ORG_ID, X-Grafana-Org-Id; GRAFANA_EXTRA_HEADERS JSON.
+- **Exclude:** RBAC (covered in introduction or separate doc if needed).
+
 ## introduction.md
 
 Create one `introduction.md` article covering these key unique concepts:
 
-- Concept 1
-- Concept 2
-- Concept 3
+- **Model Context Protocol (MCP):** What MCP is and how the Grafana MCP server lets AI assistants and LLM clients talk to Grafana (dashboards, datasources, metrics, logs, traces, alerts, incidents).
+- **Tools and capabilities:** High-level categories (dashboards, datasources, Prometheus/Loki/others, alerting, incidents, OnCall, Sift, navigation, rendering). Configurable tool set and context-window considerations.
+- **Authentication and RBAC:** Service account (or user) and Grafana RBAC; least-privilege vs Editor role; link to Grafana RBAC docs.
+
+- **Context:** README.md (Features, Requirements, RBAC sections)
+- **Include:** One-page overview for customers; link to set-up and configure; mention Grafana 9.0+.
+- **Exclude:** Step-by-step setup, full CLI reference (link to README or configure).
 
 ## Guides
 
@@ -52,6 +139,48 @@ Show the user how to use the product and its features to solve problems.
 Create individual articles for each use case.
 Order articles from foundational to advanced use cases.
 
+### Query metrics with Prometheus
+
+- **Context:** README.md (Prometheus Querying), MCP tool descriptions
+- **Include:** Use the MCP server from a client to run PromQL (instant/range), list metrics and labels. Example use case (e.g., check a metric in a conversation).
+- **Exclude:** Panel query execution, Loki or other datasources.
+
+### Query logs with Loki
+
+- **Context:** README.md (Loki Querying)
+- **Include:** LogQL log and metric queries, label names/values, patterns. Example use case.
+- **Exclude:** Search logs tool, ClickHouse.
+
+### Search and inspect dashboards
+
+- **Context:** README.md (Dashboards, Context Window Management)
+- **Include:** Search dashboards, get summary vs full JSON, get panel queries; when to use get_dashboard_property.
+- **Exclude:** Update/patch dashboard (separate guide if desired).
+
+### Manage alert rules
+
+- **Context:** README.md (Alerting)
+- **Include:** List/fetch alert rules, create/update/delete; contact points and routing. RBAC requirements.
+- **Exclude:** OnCall alert groups (different feature).
+
+### Generate deeplinks to Grafana
+
+- **Context:** README.md (Navigation)
+- **Include:** Dashboard, panel, and Explore deeplinks; time range and variables. Use case: share accurate links from an AI assistant.
+- **Exclude:** Rendering (get panel image).
+
+### Run a dashboard panel query
+
+- **Context:** README.md (Run Panel Query)
+- **Include:** Enabling runpanelquery, executing a panel query with time range and variable overrides.
+- **Exclude:** Writing new queries in Prometheus/Loki tools.
+
+### Use Grafana Incident and Sift
+
+- **Context:** README.md (Incidents, Sift Investigations)
+- **Include:** List/create/update incidents; list investigations, find error patterns, find slow requests. Viewer vs Editor role.
+- **Exclude:** OnCall schedules (separate).
+
 ## Developer
 
 Output developer docs to `docs/sources/developer/`.
@@ -61,3 +190,15 @@ Cover public user SDKs and APIs.
 Create individual articles for each SDK or API.
 Put SDKs before APIs.
 Order articles from most popular language or framework to least.
+
+### Go SDK (programmatic use)
+
+- **Context:** README.md (Programmatic Usage, TLS), pkg.go.dev reference
+- **Include:** Using the library in Go; ComposedStdioContextFunc, GrafanaConfig, TLSConfig. Link to pkg.go.dev.
+- **Exclude:** HTTP API of the server (no public HTTP API for end users).
+
+### Observability (metrics and tracing)
+
+- **Context:** README.md (Observability)
+- **Include:** --metrics, --metrics-address; Prometheus metrics (mcp_server_operation_duration_seconds, etc.). OTEL env vars and tracing.
+- **Exclude:** Grafana datasource setup for metrics (out of scope).

docs/docs.mk

@@ -0,0 +1,115 @@
+# The source of this file is https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk.
+# A changelog is included in the head of the `make-docs` script.
+include variables.mk
+-include variables.mk.local
+
+.ONESHELL:
+.DELETE_ON_ERROR:
+export SHELL     := bash
+export SHELLOPTS := pipefail:errexit
+MAKEFLAGS += --warn-undefined-variables
+MAKEFLAGS += --no-builtin-rule
+
+.DEFAULT_GOAL: help
+
+# Adapted from https://www.thapaliya.com/en/writings/well-documented-makefiles/
+.PHONY: help
+help: ## Display this help.
+help:
+	@awk 'BEGIN { \
+		FS = ": ##"; \
+		printf "Usage:\n  make <target>\n\nTargets:\n" \
+	} \
+	/^[a-zA-Z0-9_\.\-\/%]+: ##/ { printf "  %-15s %s\n", $$1, $$2 }' \
+	$(MAKEFILE_LIST)
+
+GIT_ROOT := $(shell git rev-parse --show-toplevel)
+
+PODMAN := $(shell if command -v podman >/dev/null 2>&1; then echo podman; else echo docker; fi)
+
+ifeq ($(PROJECTS),)
+$(error "PROJECTS variable must be defined in variables.mk")
+endif
+
+# Host port to publish container port to.
+ifeq ($(origin DOCS_HOST_PORT), undefined)
+export DOCS_HOST_PORT := 3002
+endif
+
+# Container image used to perform Hugo build.
+ifeq ($(origin DOCS_IMAGE), undefined)
+export DOCS_IMAGE := grafana/docs-base:latest
+endif
+
+# Container image used for Vale linting.
+ifeq ($(origin VALE_IMAGE), undefined)
+export VALE_IMAGE := grafana/vale:latest
+endif
+
+# PATH-like list of directories within which to find projects.
+# If all projects are checked out into the same directory, ~/repos/ for example, then the default should work.
+ifeq ($(origin REPOS_PATH), undefined)
+export REPOS_PATH := $(realpath $(GIT_ROOT)/..)
+endif
+
+# How to treat Hugo relref errors.
+ifeq ($(origin HUGO_REFLINKSERRORLEVEL), undefined)
+export HUGO_REFLINKSERRORLEVEL := WARNING
+endif
+
+# Whether to pull the latest container image before running the container.
+ifeq ($(origin PULL), undefined)
+export PULL := true
+endif
+
+.PHONY: docs-rm
+docs-rm: ## Remove the docs container.
+	$(PODMAN) rm -f $(DOCS_CONTAINER)
+
+.PHONY: docs-pull
+docs-pull: ## Pull documentation base image.
+	$(PODMAN) pull -q $(DOCS_IMAGE)
+
+make-docs: ## Fetch the latest make-docs script.
+make-docs:
+	if [[ ! -f "$(CURDIR)/make-docs" ]]; then
+		echo 'WARN: No make-docs script found in the working directory. Run `make update` to download it.' >&2
+		exit 1
+	fi
+
+.PHONY: docs
+docs: ## Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. To not pull the image, set `PULL=false`.
+ifeq ($(PULL), true)
+docs: docs-pull make-docs
+else
+docs: make-docs
+endif
+	$(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: docs-debug
+docs-debug: ## Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
+docs-debug: make-docs
+	WEBSITE_EXEC='hugo server --bind 0.0.0.0 --port 3002 --logLevel debug' $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: vale
+vale: ## Run vale on the entire docs folder which includes pulling the latest `VALE_IMAGE` (default: `grafana/vale:latest`) container image. To not pull the image, set `PULL=false`.
+vale: make-docs
+ifeq ($(PULL), true)
+	$(PODMAN) pull -q $(VALE_IMAGE)
+endif
+	DOCS_IMAGE=$(VALE_IMAGE) $(CURDIR)/make-docs $(PROJECTS)
+
+.PHONY: update
+update: ## Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/docs.mk
+	curl -s -LO https://raw.githubusercontent.com/grafana/writers-toolkit/main/docs/make-docs
+	chmod +x make-docs
+
+# ls static/templates/ | sed 's/-template\.md//' | xargs
+TOPIC_TYPES := concept multiple-tasks reference section task tutorial visualization
+.PHONY: $(patsubst %,topic/%,$(TOPIC_TYPES))
+topic/%: ## Create a topic from the Writers' Toolkit template. Specify the topic type as the target, for example, `make topic/task TOPIC_PATH=sources/my-new-topic.md`.
+$(patsubst %,topic/%,$(TOPIC_TYPES)):
+	$(if $(TOPIC_PATH),,$(error "You must set the TOPIC_PATH variable to the path where the $(@F) topic will be created. For example: make $(@) TOPIC_PATH=sources/my-new-topic.md"))
+	mkdir -p $(dir $(TOPIC_PATH))
+	curl -s -o $(TOPIC_PATH) https://raw.githubusercontent.com/grafana/writers-toolkit/refs/heads/main/docs/static/templates/$(@F)-template.md