{"id":50940942,"url":"https://github.com/afshinator/mcp-server-go-quality","last_synced_at":"2026-06-17T14:33:31.445Z","repository":{"id":359862008,"uuid":"1247702829","full_name":"afshinator/mcp-server-go-quality","owner":"afshinator","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-09T19:10:28.000Z","size":14867,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T21:10:16.853Z","etag":null,"topics":["code-quality","go","golang","linting","mcp","mcp-server","security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afshinator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T17:03:10.000Z","updated_at":"2026-06-09T19:12:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/afshinator/mcp-server-go-quality","commit_stats":null,"previous_names":["afshinator/mcp-server-go-quality"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/afshinator/mcp-server-go-quality","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afshinator%2Fmcp-server-go-quality","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afshinator%2Fmcp-server-go-quality/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afshinator%2Fmcp-server-go-quality/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afshinator%2Fmcp-server-go-quality/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afshinator","download_url":"https://codeload.github.com/afshinator/mcp-server-go-quality/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afshinator%2Fmcp-server-go-quality/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34453431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-quality","go","golang","linting","mcp","mcp-server","security"],"created_at":"2026-06-17T14:33:29.416Z","updated_at":"2026-06-17T14:33:31.433Z","avatar_url":"https://github.com/afshinator.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![mcp-server-go-quality](./project-image-01.png)\n\n# mcp-server-go-quality\n\n**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.**\n\n---\n\n[![Test](https://github.com/afshinator/mcp-server-go-quality/actions/workflows/test.yml/badge.svg)](https://github.com/afshinator/mcp-server-go-quality/actions/workflows/test.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/afshinator/mcp-server-go-quality)](https://goreportcard.com/report/github.com/afshinator/mcp-server-go-quality)\n[![Go Reference](https://pkg.go.dev/badge/github.com/afshinator/mcp-server-go-quality.svg)](https://pkg.go.dev/github.com/afshinator/mcp-server-go-quality)\n[![MCP](https://img.shields.io/badge/MCP-2025--03--26-blueviolet)]()\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n---\n\n## Demo\n\n![demo](demo.gif)\n\n---\n\n## What it does\n\nWraps 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.\n\n| Concern | Raw CLI | This server |\n|---|---|---|\n| Entry points | 3 separate `go install` + invocation | 1 MCP tool call |\n| Output format | 3 incompatible schemas | 1 unified `Diagnostic[]` array |\n| Tool install | Manual per machine | Auto-install with version pinning |\n| Concurrency | Sequential by default | Parallel goroutines, per-tool timeouts |\n| Error handling | Parse exit codes and stderr manually | Canonical `error` field per diagnostic, panic recovery |\n| Path normalization | Raw absolute paths | Relative to project root |\n| Workspace support | Manual `go.work` parsing | Two-pass root discovery (`go.work` \u003e `go.mod`) |\n\n---\n\n## Tools bundled\n\n| Tool | Version | Checks |\n|---|---|---|\n| [golangci-lint](https://golangci-lint.run) | **v2.11.4** (pinned) | Lint violations, complexity (`gocyclo`/`gocognit`), security (`gosec`) |\n| [govulncheck](https://pkg.go.dev/golang.org/x/vuln/cmd/govulncheck) | latest | Known CVEs reachable from your code via call-graph analysis |\n| [nilaway](https://github.com/uber-go/nilaway) | latest | Inter-procedural nil-panic paths the compiler won't catch |\n\n---\n\n## MCP tools exposed\n\n| Tool | Description |\n|---|---|\n| `run_code_checks` | Run all 3 checkers in parallel (or a subset via `tools` param). Returns sorted `Diagnostic[]`. |\n| `run_lint` | Run golangci-lint only. |\n| `run_vuln_check` | Run govulncheck only. |\n| `run_nil_check` | Run nilaway only. |\n| `install_tools` | Pre-install all three tools with pinned/latest versions. Call this at session start. |\n\n---\n\n## Output schema\n\nEvery tool returns a flat array of this shape, sorted by `file` then `line`:\n\n```json\n[\n  {\n    \"tool\": \"golangci-lint\",\n    \"file\": \"cmd/main.go\",\n    \"line\": 115,\n    \"column\": 1,\n    \"severity\": \"warning\",\n    \"message\": \"cognitive complexity 18 is high (\u003e 15)\",\n    \"error\": \"\",\n    \"native\": {\"FromLinter\": \"gocognit\", \"Text\": \"...\", \"SuggestedFixes\": [...]}\n  }\n]\n```\n\n| Field | Notes |\n|---|---|\n| `severity` | Absent (not `\"\"`) for govulncheck and nilaway — they have no severity concept |\n| `native` | Full raw tool output. `null` for error diagnostics that carry no raw context. Govulncheck parse errors carry raw error strings as a JSON array. |\n| `error` | Non-empty on tool failure or panic. **Check this first** before reading `file`/`line`. |\n\n---\n\n## Installation\n\n### For AI agents (Claude Code, etc.)\n\n```bash\nclaude mcp add go-quality -- go run github.com/afshinator/mcp-server-go-quality/cmd/mcp-server-go-quality@latest\n```\n\nFor other MCP clients, add to your config:\n\n```json\n{\n  \"mcpServers\": {\n    \"go-quality\": {\n      \"command\": \"mcp-server-go-quality\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### For humans (local install)\n\n```bash\ngo install github.com/afshinator/mcp-server-go-quality/cmd/mcp-server-go-quality@latest\n```\n\nThen run it directly on a Go project:\n\n```bash\ncd ~/my-go-project\nmcp-server-go-quality\n# Or specify a project path and config:\nmcp-server-go-quality --config ./my-config.yaml\n```\n\nThe 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.\n\n**Prerequisites:** Go 1.21+ on `PATH` (the toolchain directive in `go.mod` downloads the exact required version automatically).\n\n---\n\n## Agent workflow\n\n1. **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.\n2. **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`).\n3. **Process diagnostics** — check `error` first (non-empty = tool failure), then navigate to `file:line:column`. The `native` field carries full raw output for remediation.\n\nFull contract and processing loop: **[docs/agents/AGENTS.md](docs/agents/AGENTS.md)**  \nError tables, remediation, and troubleshooting: **[docs/agents/reference.md](docs/agents/reference.md)**\n\n---\n\n## Configuration (`.go-quality.yaml`)\n\nPlace at the project root. All fields optional.\n\n```yaml\ntimeout: 5m          # per-tool deadline; increase for big monorepos or first vuln DB download\n\ntools:\n  golangci-lint:\n    version: v2.11.4\n    extra_args: []\n  govulncheck:\n    version: latest\n    extra_args: []\n  nilaway:\n    version: latest\n    extra_args: [\"--exclude-pkgs=github.com/myorg/vendor\"]\n```\n\nPrecedence: `--config` flag \u003e `.go-quality.yaml` at server CWD \u003e compiled-in defaults.\n\n---\n\n## Go workspace support\n\nSupports 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`.\n\n---\n\n## Contributing\n\nTDD enforced — nearly every source file has a companion `_test.go` file. Integration tests run against [`testdata/sample_project/`](testdata/sample_project/), a small Go module with intentional issues for all three tools.\n\n```bash\nmake test       # unit tests (fast)\nmake test-all   # full suite including integration\nmake lint       # golangci-lint\nmake fmt        # gofumpt + goimports\nmake build      # compile the binary\n```\n\n---\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafshinator%2Fmcp-server-go-quality","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafshinator%2Fmcp-server-go-quality","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafshinator%2Fmcp-server-go-quality/lists"}