find_files_by_chunk_content
Locate files in a project containing specific text chunks within logical code segments. Use this tool to streamline codebase searches and identify relevant files for detailed analysis.
Instructions
Step 1: Find files containing chunks with matching text.
Returns file tree only showing which files contain matches.
You must use find_matching_chunks_in_file on each relevant file
to see the actual matches.
Example workflow:
1. Find files:
files = find_files_by_chunk_content(project, ["MyClass"])
2. For each file, find actual matches:
matches = find_matching_chunks_in_file(file, ["MyClass"])
3. Get content:
content = chunk_details(file, match_id)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chunk_contents_filter | Yes | Match if any of these strings appear. Match all if None/null. Single empty string or empty list will match all. | |
| project_name | Yes |
Input Schema (JSON Schema)
{
"properties": {
"chunk_contents_filter": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Match if any of these strings appear. Match all if None/null. Single empty string or empty list will match all.",
"title": "Chunk Contents Filter"
},
"project_name": {
"title": "Project Name",
"type": "string"
}
},
"required": [
"project_name",
"chunk_contents_filter"
],
"title": "find_files_by_chunk_contentArguments",
"type": "object"
}
Implementation Reference
- mcpunk/tools.py:340-360 (handler)The handler function decorated with @mcp.tool(), which registers the tool and executes the logic by filtering files based on chunk content matches using the helper function.@mcp.tool() @log_inputs_outputs() def find_files_by_chunk_content( project_name: str, chunk_contents_filter: FilterType, ) -> ToolResponse: """Step 1: Find files containing chunks with matching text. Returns file tree only showing which files contain matches. You must use find_matching_chunks_in_file on each relevant file to see the actual matches. Example workflow: 1. Find files: files = find_files_by_chunk_content(project, ["MyClass"]) 2. For each file, find actual matches: matches = find_matching_chunks_in_file(file, ["MyClass"]) 3. Get content: content = chunk_details(file, match_id) """ return _filter_files_by_chunk(project_name, chunk_contents_filter, "name_or_content").render()
- mcpunk/tools.py:484-501 (helper)Helper function implementing the core filtering logic: iterates over project files, checks if any chunk matches the filter on name or content, collects matching file paths, and generates a file tree.def _filter_files_by_chunk( project_name: str, filter_: FilterType, filter_on: Literal["name", "name_or_content"], ) -> MCPToolOutput: project = _get_project_or_error(project_name) matching_files: set[pathlib.Path] = set() for file in project.chunk_project.files: if any(c.matches_filter(filter_, filter_on) for c in file.chunks): matching_files.add(file.abs_path) data = create_file_tree(project_root=project.root, paths=matching_files) if data is None: return MCPToolOutput(text="No files found") elif isinstance(data, str): return MCPToolOutput(text=data) else: assert_never(data)
- mcpunk/tools.py:41-49 (schema)Pydantic schema type for the chunk_contents_filter parameter, defining the input validation and description.FilterType = Annotated[ str | list[str] | None, Field( description=( "Match if any of these strings appear. Match all if None/null. " "Single empty string or empty list will match all." ), ), ]