structured-code-search-mcp git:20260515.4c7d933A

Immutable. This exact content is served forever at /api/v1/blob/868b257b4745bfde.

---
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 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`