structured-code-search-mcp

Structured Code Search MCP

When to use

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

• Prefer installed/pinned structured code search binaries over remote npx -y ...@latest execution.
• 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 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

• 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 configured.
• Search and extract workflow returns enough source context without flooding the model context window.

References

• references/code-search-tool-selection.md