mcp-server-go-quality

One MCP server for golangci-lint, govulncheck, and nilaway — a unified Diagnostic[] array with consistent file:line:column navigation, parallel execution, and zero-config auto-install.

Demo

Related MCP server: gopls-mcp

What it does

Wraps three Go code quality tools into a single MCP interface. Designed for AI coding agents (Claude Code, Codex, OpenCode, ...) but also useful for CI pipelines and local development. Call one tool (run_code_checks) and get a flat, sorted Diagnostic[] array — all three checkers run in parallel under independent timeouts. Tools auto-install on first use.

Tools bundled

MCP tools exposed

Output schema

Every tool returns a flat array of this shape, sorted by file then line:

[
  {
    "tool": "golangci-lint",
    "file": "cmd/main.go",
    "line": 115,
    "column": 1,
    "severity": "warning",
    "message": "cognitive complexity 18 is high (> 15)",
    "error": "",
    "native": {"FromLinter": "gocognit", "Text": "...", "SuggestedFixes": [...]}
  }
]

Installation

For AI agents (Claude Code, etc.)

claude mcp add go-quality -- go run github.com/afshinator/mcp-server-go-quality/cmd/mcp-server-go-quality@latest

For other MCP clients, add to your config:

{
  "mcpServers": {
    "go-quality": {
      "command": "mcp-server-go-quality",
      "args": []
    }
  }
}

For humans (local install)

go install github.com/afshinator/mcp-server-go-quality/cmd/mcp-server-go-quality@latest

Then run it directly on a Go project:

cd ~/my-go-project
mcp-server-go-quality
# Or specify a project path and config:
mcp-server-go-quality --config ./my-config.yaml

The server starts in stdio mode — connect any MCP client or test it interactively by piping JSON-RPC. Tools auto-install into $GOBIN on first use.

Prerequisites: Go 1.21+ on PATH (the toolchain directive in go.mod downloads the exact required version automatically).

Agent workflow

1. Install tools — call install_tools at session start. Returns installed, already_present, and failed lists. A fast no-op if binaries are at the correct version.

2. Run checks — call run_code_checks with project_path set to the project root (or any subdirectory — the server walks up to go.work or go.mod).

3. Process diagnostics — check error first (non-empty = tool failure), then navigate to file:line:column. The native field carries full raw output for remediation.

Full contract and processing loop: docs/agents/AGENTS.md
Error tables, remediation, and troubleshooting: docs/agents/reference.md

Configuration (.go-quality.yaml)

Place at the project root. All fields optional.

timeout: 5m          # per-tool deadline; increase for big monorepos or first vuln DB download

tools:
  golangci-lint:
    version: v2.11.4
    extra_args: []
  govulncheck:
    version: latest
    extra_args: []
  nilaway:
    version: latest
    extra_args: ["--exclude-pkgs=github.com/myorg/vendor"]

Precedence: --config flag > .go-quality.yaml at server CWD > compiled-in defaults.

Go workspace support

Supports single-module go.mod and go.work multi-module workspaces. Pass any subdirectory as project_path — the server walks up to find go.work first, then go.mod. Nilaway automatically collects module paths from use directives and passes them via -include-pkgs.

Contributing

TDD enforced — nearly every source file has a companion _test.go file. Integration tests run against testdata/sample_project/, a small Go module with intentional issues for all three tools.

make test       # unit tests (fast)
make test-all   # full suite including integration
make lint       # golangci-lint
make fmt        # gofumpt + goimports
make build      # compile the binary

MIT License