|
| 1 | +# MCP Tools Usage Guide: go42x-kwb vs gopls |
| 2 | + |
| 3 | +This guide explains when to use the **go42x-kwb** (Knowledge Base) MCP server versus the **gopls** (Go Language Server) MCP server for analyzing and working with Go code. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Both tools serve different purposes in Go code analysis: |
| 8 | +- **go42x-kwb**: A fast, indexed search tool for exploring codebases through keyword and pattern matching |
| 9 | +- **gopls**: A semantic Go analysis tool that understands Go syntax, types, and relationships |
| 10 | + |
| 11 | +## When to Use go42x-kwb |
| 12 | + |
| 13 | +The Knowledge Base server excels at **fast text-based searches** and **initial code exploration**. |
| 14 | + |
| 15 | +### Best Use Cases |
| 16 | + |
| 17 | +1. **Initial Codebase Exploration** |
| 18 | + - When you need to quickly understand what files exist in a project |
| 19 | + - Getting an overview of the codebase structure |
| 20 | + - Finding files by type (code, documentation, config) |
| 21 | + ``` |
| 22 | + Example: "Show me all configuration files in the project" |
| 23 | + Tool: mcp__go42x-kwb__list_files with type="config" |
| 24 | + ``` |
| 25 | + |
| 26 | +2. **Keyword and Pattern Search** |
| 27 | + - Finding all occurrences of a specific string or pattern |
| 28 | + - Searching for TODO comments, error messages, or specific text |
| 29 | + - Looking for configuration values or environment variables |
| 30 | + ``` |
| 31 | + Example: "Find all files mentioning 'database connection'" |
| 32 | + Tool: mcp__go42x-kwb__search with query="database connection" |
| 33 | + ``` |
| 34 | + |
| 35 | +3. **Quick File Content Retrieval** |
| 36 | + - When you know the exact file path and need its contents |
| 37 | + - Reading configuration files, documentation, or scripts |
| 38 | + - Accessing non-Go files (YAML, JSON, Markdown, etc.) |
| 39 | + ``` |
| 40 | + Example: "Show me the README file" |
| 41 | + Tool: mcp__go42x-kwb__get_file with path="README.md" |
| 42 | + ``` |
| 43 | + |
| 44 | +4. **Cross-Language Searches** |
| 45 | + - Searching across mixed codebases (Go, JavaScript, Python, etc.) |
| 46 | + - Finding patterns in build scripts, CI/CD configs, and documentation |
| 47 | + - Exploring test fixtures and data files |
| 48 | + |
| 49 | +### Strengths |
| 50 | +- ✅ Very fast search across large codebases |
| 51 | +- ✅ Works with any file type, not just Go |
| 52 | +- ✅ Great for text pattern matching |
| 53 | +- ✅ Efficient for initial exploration |
| 54 | +- ✅ Lightweight and quick to query |
| 55 | + |
| 56 | +### Limitations |
| 57 | +- ❌ No semantic understanding of Go code |
| 58 | +- ❌ Cannot find references or implementations |
| 59 | +- ❌ No type information or code relationships |
| 60 | +- ❌ No understanding of Go imports or packages |
| 61 | + |
| 62 | +## When to Use gopls |
| 63 | + |
| 64 | +The Go Language Server provides **deep semantic analysis** and **code intelligence** for Go projects. |
| 65 | + |
| 66 | +### Best Use Cases |
| 67 | + |
| 68 | +1. **Understanding Go Code Structure** |
| 69 | + - Analyzing package dependencies and imports |
| 70 | + - Understanding module and workspace layout |
| 71 | + - Getting package API summaries |
| 72 | + ``` |
| 73 | + Example: "What packages does this project contain?" |
| 74 | + Tool: mcp__gopls__go_workspace |
| 75 | + ``` |
| 76 | + |
| 77 | +2. **Finding Symbol Definitions and References** |
| 78 | + - Locating where a function, type, or variable is defined |
| 79 | + - Finding all usages of a specific symbol |
| 80 | + - Tracing method calls and type usage |
| 81 | + ``` |
| 82 | + Example: "Find all references to the Server.Run method" |
| 83 | + Tool: mcp__gopls__go_symbol_references with symbol="Server.Run" |
| 84 | + ``` |
| 85 | + |
| 86 | +3. **Semantic Code Search** |
| 87 | + - Finding symbols by name with fuzzy matching |
| 88 | + - Searching for types, interfaces, functions across packages |
| 89 | + - Locating implementations of interfaces |
| 90 | + ``` |
| 91 | + Example: "Find all types with 'Handler' in their name" |
| 92 | + Tool: mcp__gopls__go_search with query="handler" |
| 93 | + ``` |
| 94 | + |
| 95 | +4. **Code Context and Dependencies** |
| 96 | + - Understanding file dependencies within a package |
| 97 | + - Analyzing cross-file relationships |
| 98 | + - Getting context about imports and usage |
| 99 | + ``` |
| 100 | + Example: "What does server.go depend on?" |
| 101 | + Tool: mcp__gopls__go_file_context with file="/path/to/server.go" |
| 102 | + ``` |
| 103 | + |
| 104 | +5. **Package API Analysis** |
| 105 | + - Understanding public APIs of packages |
| 106 | + - Exploring third-party dependencies |
| 107 | + - Reviewing exported types and functions |
| 108 | + ``` |
| 109 | + Example: "Show me the public API of the storage package" |
| 110 | + Tool: mcp__gopls__go_package_api with packagePaths=["example.com/storage"] |
| 111 | + ``` |
| 112 | + |
| 113 | +6. **Code Quality and Diagnostics** |
| 114 | + - Finding compilation errors and issues |
| 115 | + - Checking for type errors |
| 116 | + - Validating code changes |
| 117 | + ``` |
| 118 | + Example: "Check for errors in the edited files" |
| 119 | + Tool: mcp__gopls__go_diagnostics with files=["/path/to/file.go"] |
| 120 | + ``` |
| 121 | + |
| 122 | +### Strengths |
| 123 | +- ✅ Deep semantic understanding of Go code |
| 124 | +- ✅ Accurate symbol resolution and type information |
| 125 | +- ✅ Understands Go imports, packages, and modules |
| 126 | +- ✅ Can find references, implementations, and dependencies |
| 127 | +- ✅ Provides compilation diagnostics |
| 128 | + |
| 129 | +### Limitations |
| 130 | +- ❌ Only works with Go code |
| 131 | +- ❌ Slower for simple text searches |
| 132 | +- ❌ Requires valid Go code to analyze |
| 133 | +- ❌ More resource-intensive than text search |
| 134 | + |
| 135 | +## Decision Flow Chart |
| 136 | + |
| 137 | +``` |
| 138 | +Start: What do you need to do? |
| 139 | +│ |
| 140 | +├─> Need to search for text/keywords? |
| 141 | +│ └─> Use go42x-kwb__search |
| 142 | +│ |
| 143 | +├─> Need to list/explore files? |
| 144 | +│ └─> Use go42x-kwb__list_files |
| 145 | +│ |
| 146 | +├─> Need to read a specific file? |
| 147 | +│ ├─> Is it a Go file you'll analyze? |
| 148 | +│ │ └─> Use Read tool (built-in) + gopls__go_file_context |
| 149 | +│ └─> Just need contents? |
| 150 | +│ └─> Use go42x-kwb__get_file |
| 151 | +│ |
| 152 | +├─> Need to find Go symbols/types? |
| 153 | +│ └─> Use gopls__go_search |
| 154 | +│ |
| 155 | +├─> Need to find symbol references? |
| 156 | +│ └─> Use gopls__go_symbol_references |
| 157 | +│ |
| 158 | +├─> Need to understand package structure? |
| 159 | +│ └─> Use gopls__go_workspace or gopls__go_package_api |
| 160 | +│ |
| 161 | +└─> Need to check for Go errors? |
| 162 | + └─> Use gopls__go_diagnostics |
| 163 | +``` |
| 164 | + |
| 165 | +## Practical Examples |
| 166 | + |
| 167 | +### Example 1: Understanding a New Codebase |
| 168 | +``` |
| 169 | +1. Start with go42x-kwb__list_files to see project structure |
| 170 | +2. Use go42x-kwb__search to find main entry points |
| 171 | +3. Switch to gopls__go_workspace for Go module information |
| 172 | +4. Use gopls__go_package_api to understand key packages |
| 173 | +``` |
| 174 | + |
| 175 | +### Example 2: Finding and Fixing a Bug |
| 176 | +``` |
| 177 | +1. Use go42x-kwb__search to find error messages or relevant keywords |
| 178 | +2. Use gopls__go_symbol_references to trace function calls |
| 179 | +3. Use gopls__go_file_context to understand dependencies |
| 180 | +4. After editing, use gopls__go_diagnostics to verify fixes |
| 181 | +``` |
| 182 | + |
| 183 | +### Example 3: Adding a New Feature |
| 184 | +``` |
| 185 | +1. Use gopls__go_search to find similar existing features |
| 186 | +2. Use gopls__go_package_api to understand available APIs |
| 187 | +3. Use go42x-kwb__search to find examples in tests |
| 188 | +4. Use gopls__go_diagnostics after implementation |
| 189 | +``` |
| 190 | + |
| 191 | +## Performance Considerations |
| 192 | + |
| 193 | +- **Use go42x-kwb** for: |
| 194 | + - Initial exploration (fast overview) |
| 195 | + - Broad text searches across many files |
| 196 | + - Non-Go file access |
| 197 | + - Quick keyword lookups |
| 198 | + |
| 199 | +- **Use gopls** for: |
| 200 | + - Precise symbol location |
| 201 | + - Understanding code relationships |
| 202 | + - Type-safe refactoring preparation |
| 203 | + - Compilation checking |
| 204 | + |
| 205 | +## Summary Rules |
| 206 | + |
| 207 | +1. **Start with go42x-kwb** when exploring unknown codebases |
| 208 | +2. **Use go42x-kwb** for text/pattern searches |
| 209 | +3. **Switch to gopls** when you need semantic understanding |
| 210 | +4. **Use gopls** for Go-specific analysis and refactoring |
| 211 | +5. **Combine both** for comprehensive code analysis |
| 212 | +6. **Prefer go42x-kwb** for non-Go files |
| 213 | +7. **Prefer gopls** for Go symbol resolution and type information |
| 214 | + |
| 215 | +Remember: go42x-kwb is your "grep on steroids" while gopls is your "Go code intelligence engine". Use them together for maximum effectiveness! |
0 commit comments