MCP Grafana Server Development

Development assistant for working with the mcp-grafana MCP server codebase. This skill provides project-specific guidance on commands, architecture, testing patterns, and best practices.

Project Context

This is an MCP (Model Context Protocol) server that exposes Grafana API operations through MCP tools. Built with Go using the mark3labs/mcp-go framework. The server enables Claude and other MCP clients to interact with Grafana programmatically.

Key Commands Reference

When the user asks about running tests, building, formatting, or working with the MCP server, use these exact commands:

**Testing:**

**Building:**

**MCP Server Testing:**

Architecture Overview

When explaining or modifying the codebase structure, reference these core components:

**MCP Server Entry Point** (`cmd/server/main.go`):

1. `prompts.RegisterMCPPrompts()`

2. `resources.RegisterMCPResources()`

3. `tools.RegisterMCPTools()`

**Tool Registration** (`internal/tools/register.go`):

Detailed Documentation

For comprehensive guidance on specific development areas, always consult these documents:

Task Workflow

When the user requests development work, follow this pattern:

1. **Read relevant documentation** - Before implementing changes, check if guidance exists in `docs/*.md`

2. **Understand existing patterns** - Review similar existing code (tools, tests, registrations)

3. **Run appropriate tests** - Use `make test` for full suite, specific test commands for targeted testing

4. **Check formatting** - Run `make fmt` before committing

5. **Verify linting** - Run `make lint` to catch issues locally

6. **Test MCP integration** - Use `make mcp-shell` to verify tools work end-to-end

Testing Best Practices

Common Development Scenarios

**Adding a new MCP tool:**

1. Read `docs/mcp-server-development.md` for tool development patterns

2. Implement tool in `internal/tools/`

3. Register in `internal/tools/register.go`

4. Write tests

5. Test interactively with `make mcp-shell`

**Updating dependencies:**

1. Consult `docs/dependency-management.md`

2. Use `go get -u` for updates

3. Run `go mod tidy`

4. Test thoroughly with `make test`

**CI/CD issues:**

1. Check `docs/ci-best-practices.md` for workflow details

2. Verify local tests pass: `make test-ci`

3. Check formatting: `make format-ci`

4. Run linters: `make lint-ci`

Important Reminders

Getting Help

When uncertain about implementation details:

1. Check if a `docs/*.md` file covers the topic

2. Review similar existing implementations in the codebase

3. Use `make mcp-shell` to explore existing tool behavior

4. Refer to the mark3labs/mcp-go documentation for MCP framework specifics