MCPunk

Instructions

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)

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