structured-code-search-mcp · diff
git:20260505.b8aef85 to git:20260515.4c7d933
40 added, 22 removed. Audit A to A.
---
name: structured-code-search-mcp
description: Use when designing or using MCP-backed structured code search with search, AST query, symbol inventory, and bounded extraction workflows.
---
# Structured Code Search MCP
## When to use
- Use when developing a new MCP server, debugging an MCP connection, or integrating an agent with standard MCP protocols.
+ Use when an agent needs to search, navigate, or extract code using structural queries — AST patterns, symbol lookups, or cross-file reference tracing — beyond what simple grep or glob can provide, via an MCP-backed code search server.
## Requirements / Checks
- - This is primarily an informational/reference skill.
- Prefer installed/pinned structured code search binaries over remote `npx -y ...@latest` execution.
- - Confirm MCP client supports required transport and method filtering.
- - Bound any search path to the current workspace unless user approves otherwise.
+ - Confirm the MCP client supports the required transport and method filtering.
+ - Bound any search path to the current workspace unless the user explicitly approves otherwise.
## Workflow
- 1. **Choose mode**: Decide whether the client needs raw tools, an agent layer, or direct CLI.
- 2. **Bound scope**: Set base path/default paths and token/result limits before broad search.
- 3. **Expose tools**: Keep tool schemas strict for search, AST query, extraction, and symbol listing.
- 4. **Filter methods**: Use allowlists for read/search methods and block destructive methods by default.
- 5. **Handle transport**: Support stdio or HTTP intentionally; set connect/tool timeouts.
- 6. **Debug minimally**: Enable debug logs only long enough to capture connection, tool discovery, and failed calls.
- ## Tool Model To Preserve
- - `search_code`: text/boolean search with session dedup and result limits.
- - `query_code`: AST/structural search for code shapes.
- - `extract_code`: file/line/symbol extraction after search narrows scope.
- - `symbols_code`: symbol inventory for target files.
+ 1. **Choose the right tool for the query**:
+ | Need | Tool |
+ |---|---|
+ | Text/boolean search across files | `search_code` |
+ | Structural pattern (function shape, class with field) | `query_code` |
+ | Extract a specific file, range, or symbol | `extract_code` |
+ | List all symbols in target files | `symbols_code` |
+
+ 2. **Bound scope before searching** — set base path and default paths to the workspace. Set a result limit before running broad queries (e.g., max 20 results).
+
+ 3. **Iterate from broad to narrow**:
+ - Start with `search_code` or `symbols_code` to identify candidate files.
+ - Use `query_code` to narrow to the specific structural pattern.
+ - Use `extract_code` to retrieve the exact code range needed.
+
+ 4. **Filter methods at the server** — use allowlists for read/search methods. Block write and edit methods by default; only enable if code modification is explicitly part of the task.
+
+ 5. **Handle transport** — support stdio or HTTP intentionally; set connect and tool call timeouts.
+
+ 6. **Debug minimally** — enable debug logs only long enough to capture connection, tool discovery, and failed calls. Disable after diagnosis.
+
+ ## Tool Interface (illustrative — actual names depend on your server)
+
+ - `search_code` — text/boolean search with session dedup and result limits.
+ - `query_code` — AST/structural search for code shapes.
+ - `extract_code` — file/line/symbol extraction after search narrows scope.
+ - `symbols_code` — symbol inventory for target files.
+
+ Exact tool names and schemas vary by implementation. Read the server's tool list before assuming names.
+
## Safety Constraints
- - Always validate input arguments to MCP tools against the defined JSON schema before execution.
- - MCP servers must enforce strict path boundaries.
- - Do not expose write/edit modes unless the user explicitly requested code modification.
- - Do not include test files or broad dirs by default when the task asks for production behavior only.
+ - Validate all input arguments against the defined JSON schema before execution.
+ - Enforce strict path boundaries — refuse requests for paths outside the workspace.
+ - Do not expose write or edit modes unless code modification is explicitly requested.
+ - Do not include test files or broad directories by default when the task asks for production behavior only.
## Validation / Done Criteria
- - MCP setup has bounded paths, strict schemas, filtered methods, and timeouts.
- - Search/extract workflow returns enough source context without flooding the model.
+ - MCP setup has bounded paths, strict schemas, filtered methods, and timeouts configured.
+ - Search and extract workflow returns enough source context without flooding the model context window.
## References
- - `references/structured code search-tool-selection.md`
+ - `references/code-search-tool-selection.md`