| name | gopls |
| description | How to use the gopls MCP for analyzing Go code. Use when working on a Go codebase. |
Project Instructions for AI Code Assistant with gopls-mcp
When reading this file please explicitly mention that you did.
Context
You are an AI programming assistant helping users with Go code. You have access to gopls-mcp tools
for semantic code analysis.
CRITICAL PROHIBITIONS (NEVER DO THIS)
- NEVER use
go_search for text content (comments, strings, TODOs). Use Grep tool.
- NEVER use grep/ripgrep for symbol discovery (definitions, references, implementations).
- NEVER fall back from exclusive capabilities (see Tool Selection Guide).
Tool Selection Guide
Code relationships (Exclusive Capabilities - NO FALLBACK)
| Task | Tool |
|---|
| Find interface implementations | go_implementation |
| Trace call relationships | go_get_call_hierarchy |
| Find symbol references | go_symbol_references |
| Jump to definition | go_definition |
| Analyze dependencies | go_get_dependency_graph |
| Preview renaming | go_dryrun_rename_symbol |
Code exploration (Enhanced Capabilities - FALLBACK ALLOWED)
| Task | Tool | Fallback after 3 failures |
|---|
| List package symbols | go_list_package_symbols | Glob + Read |
| List module packages | go_list_module_packages | find |
| Analyze workspace | go_analyze_workspace | Manual exploration |
| Quick project overview | go_get_started | Read README + go.mod |
| Search symbols by name | go_search | grep + Read |
| Check compilation | go_build_check | go build |
| Get symbol details | go_get_package_symbol_detail | Read |
| List modules | go_list_modules | Read go.mod |
Integration Workflow
- Classify task type: Route to Exclusive capabilities, Enhanced capabilities, or Grep tool
based on the Tool Selection Guide.
- Validate: Check intent against "Tool-Specific Parameters & Constraints" BEFORE execution.
- Construct & Execute: Extract exact symbol names and file paths, execute the tool.
- Format Output: Present file:line locations, signatures, and documentation cleanly. Do not
dump raw JSON.
Tool-Specific Parameters & Constraints
- go_search:
- FATAL:
query MUST NOT contain spaces or semantic descriptions.
- Must be symbol names only (single token). Correct:
query="ParseInt".
- Does NOT search comments or documentation.
- go_implementation:
- Only for interfaces and types. STRICTLY PROHIBITED for functions.
- go_get_package_symbol_detail:
symbol_filters format: [{name: "Start", receiver: "*Server"}].
receiver requires exact string match ("*Server" != "Server").
- General Parameters:
symbol_name: Do not include package prefix (Use "Start", not "Server.Start").
context_file: Obtain strictly from the current file being analyzed.
Error Handling & Retry (Self-Correction)
- Check if parameters strictly follow the constraints above.
- Try a shorter/simpler symbol name.
- Re-analyze code context before retrying.
Fallback Conditions (For Enhanced Capabilities ONLY)
Trigger fallback manually IF AND ONLY IF:
- 3 consecutive tool failures.
- Timeout exceeds 30 seconds.
- Empty result returned when code existence is absolutely certain. Note: Retry gopls-mcp tool
first on the very next user query even after a previous fallback.