# MCP-gopls Usage Guide
## Configure the server
```bash
# Run inside your Go repo
mcp-gopls \
--workspace /path/to/repo \
--log-level debug \
--rpc-timeout 60s
```
> **Note:** `mcp-gopls` ensures `GOTOOLCHAIN=local` for the embedded `gopls` process so that it can run even when the requested Go toolchain hasn’t been published yet. Export your own `GOTOOLCHAIN` before starting the server if you prefer a different setting.
Environment variables:
|Variable|Purpose|
|---|---|
|`MCP_GOPLS_WORKSPACE`|Default workspace root|
|`MCP_GOPLS_BIN`|Path to `gopls` binary|
|`MCP_GOPLS_LOG_FILE`|Optional log file|
|`MCP_GOPLS_LOG_LEVEL`|debug, info, warn, error|
|`MCP_GOPLS_RPC_TIMEOUT`|LSP call timeout|
|`MCP_GOPLS_SHUTDOWN_TIMEOUT`|Graceful shutdown timeout|
## Docker / MCP Gateway
If you prefer a containerized server, use the official image and mount your workspace:
```bash
docker run --rm -i \
-v /absolute/path/to/your/go/project:/workspace \
ghcr.io/hloiseau/mcp-gopls:latest \
--workspace /workspace
```
For Docker MCP Gateway, copy `docs/docker-mcp.yaml`, update the bind mount path, and run:
```bash
docker mcp gateway run
```
If a tools catalog requires `toolsUrl`, point it at `docs/tools.json`.
## Resource & prompt catalog
|Resource URI|Description|
|---|---|
|`resource://workspace/overview`|JSON summary of top-level directories & Go files|
|`resource://workspace/go.mod`|Raw contents of go.mod|
|Prompt|Description|Arguments|
|---|---|---|
|`summarize_diagnostics`|Summarize diagnostics into actionable guidance|none|
|`refactor_plan`|Produce a quick refactor checklist based on diagnostics JSON|`diagnostics`|
## Recommended workflow
1. `check_diagnostics` > feed diagnostics into `summarize_diagnostics` prompt.
2. Read `resource://workspace/overview` to understand layout.
3. Run `run_go_test` or `analyze_coverage` to validate fixes.
4. Use `format_document` / `rename_symbol` / `list_code_actions` for refactors.
5. Finish with `run_go_mod_tidy`, `run_govulncheck`, and `module_graph` to keep dependencies healthy.
