find_matching_chunks_in_file

Locate specific code segments in a file by searching for matching strings or patterns, ideal for identifying function references or definitions within your project.

Instructions

Step 2: Find the actual matching chunks in a specific file.

Required after find_files_by_chunk_content or list_all_files_in_project to see
matches, as those tools only show files, not their contents.

This can be used for things like:
  - Finding all chunks in a file that make reference to a specific function
    (e.g. find_matching_chunks_in_file(..., ["my_funk"])
  - Finding a chunk where a specific function is defined
    (e.g. find_matching_chunks_in_file(..., ["def my_funk"])

Some chunks are split into multiple parts, because they are too large. This
will look like 'chunkx_part1', 'chunkx_part2', ...

Input Schema

TableJSON Schema

Name	Required	Description
`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
`rel_path`	Yes	Relative to project root

Implementation Reference

mcpunk/tools.py:363-385 (handler)

Handler function for the 'find_matching_chunks_in_file' tool, decorated with @mcp.tool(). It constructs a ProjectFile and delegates to the helper _list_chunks_in_file to find and list matching chunks.

@mcp.tool()
@log_inputs_outputs()
def find_matching_chunks_in_file(
    project_name: str,
    rel_path: Annotated[pathlib.Path, Field(description="Relative to project root")],
    filter_: FilterType,
) -> ToolResponse:
    """Step 2: Find the actual matching chunks in a specific file.

    Required after find_files_by_chunk_content or list_all_files_in_project to see
    matches, as those tools only show files, not their contents.

    This can be used for things like:
      - Finding all chunks in a file that make reference to a specific function
        (e.g. find_matching_chunks_in_file(..., ["my_funk"])
      - Finding a chunk where a specific function is defined
        (e.g. find_matching_chunks_in_file(..., ["def my_funk"])

    Some chunks are split into multiple parts, because they are too large. This
    will look like 'chunkx_part1', 'chunkx_part2', ...
    """
    proj_file = ProjectFile(project_name=project_name, rel_path=rel_path)
    return _list_chunks_in_file(proj_file, filter_, "name_or_content").render()

mcpunk/tools.py:41-49 (schema)

Pydantic type definition for the filter_ parameter, which accepts a string, list of strings, or None to match chunks by name or content.

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."
        ),
    ),
]

mcpunk/tools.py:468-481 (helper)

Helper function that filters chunks in a file based on the filter and filter_on criteria, formats their IDs with category and size, and returns a formatted MCPToolOutput.

def _list_chunks_in_file(
    proj_file: ProjectFile,
    filter_: FilterType,
    filter_on: Literal["name", "name_or_content"],
) -> MCPToolOutput:
    target_file = proj_file.file
    chunks = [x for x in target_file.chunks if x.matches_filter(filter_, filter_on)]
    resp_data = [
        f"id={x.id_(path=target_file.abs_path)} (category={x.category} chars={len(x.content)})"
        for x in chunks
    ]
    resp_text = "\n".join(resp_data)
    chunk_info = f"({len(chunks)} of {len(target_file.chunks)} chunks)"
    return MCPToolOutput(text=f"{chunk_info}\n{resp_text}")

MCPunk