gopls-mcp

name

gopls-mcp

description

**REQUIRED for ALL Go code analysis.** NEVER use read_file, grep_search, or semantic_search directly on .go files for semantic understanding. ALWAYS use gopls-mcp tools first: go_definition (find definitions), go_references (find usages), go_hover (get types/docs), go_symbols (list symbols). Only use read_file AFTER gopls locates the code. This is MANDATORY for Go files - 5x more efficient and 100% accurate vs text-based tools.

gopls-mcp: Go Code Semantic Navigation

Purpose: Navigate Go code semantically using gopls Language Server Protocol (LSP) instead of text-based searching.

When to use: MANDATORY for ALL Go (.go) file analysis tasks. This includes:

• Finding where functions/types/variables are defined
• Understanding what a symbol does or its type
• Finding all places a symbol is used
• Listing functions/types in a file or workspace

CRITICAL RULE: Do NOT use read_file, grep_search, or semantic_search on .go files for semantic navigation. ALWAYS use gopls-mcp tools first. Only use read_file after gopls locates the exact code location.

Key advantage: 5x faster and 100% accurate compared to grep/read_file approaches.

---

Quick Start

Core Tools (4 total)

Tool	Use When	Token Cost
go_symbols	Overview of file/project structure	~500 tokens
go_definition	Jump to symbol definition	~200 tokens
go_hover	Get type info and docs	~300 tokens
go_references	Find all usages	~800 tokens

Typical Workflow

Understanding new Go project:
1. go_symbols(main.go) → discover entry points
2. go_definition(main_function) → see implementation
3. go_symbols(query="Handler") → find all handlers
4. go_references(ProcessRequest) → trace usage

Total: ~2,000 tokens vs grep+read_file: ~10,000 tokens

---

Tool Details

1. go_symbols

Purpose: Get all symbols (functions, types, variables) in a file or workspace.

Parameters:

{
  "file_path": "/absolute/path/to/file.go",  // optional
  "query": "Handler"                          // optional, for workspace search
}

Usage patterns:

# Pattern 1: File overview
go_symbols(file_path="/path/to/main.go")
→ Returns all top-level symbols in the file

# Pattern 2: Workspace search
go_symbols(query="Service")
→ Returns all symbols containing "Service" across workspace

Best for:

• Initial project exploration
• Finding all handlers/services/errors
• Understanding file structure

---

2. go_definition

Purpose: Jump to exact definition location of a symbol.

Parameters:

{
  "file_path": "/absolute/path/to/file.go",
  "line": 45,        // 0-based line number
  "character": 10    // 0-based column number
}

Usage pattern:

# Find where ProcessRequest is defined
go_definition(
  file_path="/path/to/handler.go",
  line=23,      # line where symbol appears
  character=5   # column where symbol starts
)
→ Returns exact file and location of definition

Best for:

• Following code flow
• Finding implementation details
• Navigating to type definitions

⚠️ Position indexing: Line and character are 0-based (first line is 0, first column is 0)

---

3. go_hover

Purpose: Get type signature, documentation, and metadata for a symbol.

Parameters: Same as go_definition

Usage pattern:

go_hover(
  file_path="/path/to/model.go",
  line=15,
  character=5
)
→ Returns type signature and doc comments

Returns:

• Function signatures
• Type definitions
• Documentation comments
• Field types

Best for:

• Understanding what a function does without reading implementation
• Getting type information
• Viewing documentation

---

4. go_references

Purpose: Find all places where a symbol is used/referenced.

Parameters: Same as go_definition

Usage pattern:

go_references(
  file_path="/path/to/service.go",
  line=30,
  character=8
)
→ Returns list of all files and locations using this symbol

Best for:

• Impact analysis (what breaks if I change this?)
• Understanding how a function is used
• Finding all callers

---

Usage Scenarios

Scenario 1: First-time Project Understanding

Goal: Understand a new Go project in 10 minutes

Progressive workflow:

Step 1: Entry point discovery
  go_symbols("main.go")
  → Found: main(), initServer(), registerRoutes()
  Token: ~500

Step 2: Core type discovery
  go_definition(Server, line: X, character: Y)
  → Jump to: server.go:50
  Token: ~200

Step 3: Structure analysis
  go_symbols("server.go")
  → Found: Server struct + methods
  Token: ~500

Step 4: Feature search
  go_symbols(query="Handler")
  → Found: all HTTP handlers
  Token: ~800

Total: ~2,000 tokens
Traditional approach: ~10,000 tokens

Scenario 2: Tracing Function Call Chain

Goal: Understand data flow from HTTP request to database

Workflow:

Step 1: Find entry point
  go_symbols(query="Login")
  → LoginHandler()

Step 2: See implementation
  go_definition(LoginHandler, ...)
  → Jump to handler.go:45

Step 3: Understand helper
  go_hover(ValidateUser, ...)
  → func ValidateUser(username, password string) error

Step 4: Find all callers
  go_references(ValidateUser, ...)
  → Called by: LoginHandler, ResetPassword, CheckAuth

Step 5: Trace to database
  go_definition(QueryUser, ...)
  → Follow to database layer

Scenario 3: Understanding Data Structures

Goal: Learn about a key type and its usage

Workflow:

Step 1: Find type definition
  go_definition(User, ...)
  → models/user.go:20

Step 2: Get field details
  go_hover(User.Email, ...)
  → Field type and validation rules

Step 3: Find usage patterns
  go_references(User, ...)
  → See all places creating/using User instances

---

Best Practices

✅ DO: Use gopls-mcp for Go code

✅ go_symbols(query="HandleRequest")    // Find all handlers
❌ grep_search("HandleRequest")          // Gets comments, strings, false matches

✅ go_definition(symbol)                 // Exact location
❌ read_file("handler.go")               // Read entire file, guess location

✅ go_hover(User)                        // Type info only
❌ read_file("models.go", lines: 1-500)  // Huge token cost

✅ go_references(ProcessRequest)         // All real usages
❌ grep "ProcessRequest"                 // Misses dynamic calls, false positives

❌ DON'T: Common mistakes

1. Using grep for symbols

   • grep finds comments, strings, test mocks
   • go_symbols finds only real symbols

2. Guessing file locations

   • Don't assume "handler.go" exists
   • Use go_definition to jump precisely

3. Reading entire files

   • Don't read_file to find types
   • Use go_hover for targeted info

4. Repeated queries

   • Cache definition locations
   • Don't re-query same symbols

🎯 Progressive Disclosure Pattern

Principle: Start broad, then drill down only as needed

Level 1: Overview (always)
  go_symbols(file) or go_symbols(query)
  ~500 tokens

Level 2: Locate (when needed)
  go_definition(symbol)
  ~200 tokens

Level 3: Details (optional)
  go_hover(symbol)
  ~300 tokens

Level 4: Impact (for analysis)
  go_references(symbol)
  ~800 tokens

Example:

Question: "How does this project handle errors?"

❌ Inefficient:
  grep_search("error") → 1000+ results
  read_file all files → 10,000+ tokens

✅ Efficient:
  go_symbols(query="Error") → Custom error types (~500 tokens)
  go_definition(CustomError) → Definition (~200 tokens)
  go_references(CustomError) → Usage sites (~800 tokens)
  Total: ~1,500 tokens

---

Standard Workflows

Workflow 1: Top-Down (Architecture)

Use case: First contact with project

User: "What does this project do?"
  ↓
go_symbols(main.go)
  ↓ Discover: main(), initConfig(), startServer()
  ↓
go_definition(startServer, ...)
  ↓ Jump: server.go
  ↓
go_symbols(server.go)
  ↓ Discover: Server struct, Start(), Stop()
  ↓
go_hover(Server, ...)
  ↓ Get: Type definition, field descriptions
  ↓
Output: "This is an HTTP server with..."

Workflow 2: Bottom-Up (Impact Analysis)

Use case: Change analysis

User: "If I modify ValidateToken(), what breaks?"
  ↓
go_definition(ValidateToken, ...)
  ↓ Confirm: auth.go, implementation
  ↓
go_references(ValidateToken, ...)
  ↓ Find callers: LoginHandler, RefreshToken, Middleware
  ↓
For each caller:
  go_hover(caller, ...)
  ↓ Understand: How it's used
  ↓
Output: "Affects login, token refresh, auth middleware"

Workflow 3: Lateral (Domain Exploration)

Use case: Understanding a functional area

User: "Where are all database operations?"
  ↓
go_symbols(query="Repository")
  ↓ Find: UserRepository, OrderRepository, ProductRepository
  ↓
For each Repository:
  go_definition(...) → Interface definition
  go_symbols(file) → List all methods
  go_references(...) → Find usage
  ↓
Output: Data access layer diagram + responsibilities

---

Token Efficiency Guide

Optimization Strategies

Strategy	Inefficient	Efficient	Savings
Overview	read_file multiple files	go_symbols(query)	90% ↓
Locate	grep + guess	go_definition	80% ↓
Type Info	read entire struct	go_hover	70% ↓
Caching	repeated queries	remember results	100% ↓

Real-world Token Costs

Operation	Typical Cost	Notes
go_symbols(file)	300-800	Depends on symbol count
go_symbols(query)	500-1,500	Depends on matches
go_definition	100-300	Just location info
go_hover	200-500	Type + docs
go_references	500-2,000	Depends on reference count

Comparison:

• grep_search: 1,000-5,000 tokens
• read_file (large): 3,000-10,000 tokens
• gopls-mcp workflow: 1,500-3,000 tokens

---

Position Parameters

All position parameters (line, character) are 0-based:

• line: 0 = first line of file
• character: 0 = first character of line

Example:

package main  // line: 0

func main() { // line: 2
    println("hello") // line: 3, character: 4 is 'p'
}

---

Troubleshooting

Problem: Symbol not found

Solution:

1. Verify file_path is absolute
2. Check line/character are on symbol name
3. Ensure gopls initialized correctly

Problem: Too many references

Solution:

1. Focus on project-internal references
2. Use go_hover first to confirm correct symbol
3. Filter critical locations from results

Problem: Empty symbol search

Solution:

1. Try partial name matching
2. Check for private symbols (lowercase)
3. Verify workspace path

---

Summary

Key Value Propositions

1. 🎯 Precision: Semantic analysis, not text matching (100% accuracy)
2. 🚀 Efficiency: 5x fewer tokens than grep/read_file
3. 🔍 Depth: Get types, docs, relationships - not just text
4. 🛠️ Composability: 4 tools cover all code navigation needs

Usage Principles

1. Symbol navigation first: symbols → definition → hover → references
2. Progressive disclosure: Start with overview, drill down as needed
3. Cache aggressively: Remember locations and types

When to Use

✅ MUST use gopls-mcp:

• Finding function/type definitions
• Understanding code structure
• Tracing call relationships
• Impact analysis

❌ Don't use:

• Simple text search (TODO comments)
• Reading config files (YAML/JSON)
• Viewing documentation (README)

---

Remember: gopls-mcp makes AI read Go code like a human developer using an IDE!