fix: minor cleanup fixes for new tools (#8)

* fix ignored-pattern guard, root permission error, and broad except

Only skip entries matching ignored_dir_patterns when they are actually
directories, surface PermissionError at root depth instead of returning
silent empty results, and narrow an overly broad except clause in
search_directory to catch only FileAccessError.

- Added minimum: 1 to max_depth and max_entries in the list_directory
  JSON schema

* fix misleading comment, noisy search hints, and unused test helper

Corrected the "Java-specific nodes" comment to include TypeScript, replaced low-signal Java search hints (void, public, private) with structural tokens (enum, import, @interface), and removed a dead _make_tree helper from list_directory tests.

* add list_directory API docs and fix search_directory doc errors

Added the missing list_directory detailed section to API.md. Fixed
several inaccuracies in search_directory docs: `directory` key renamed
to `path`, added `include_pattern` to return keys, removed non-existent
`match_count` from per-file results.

- Fixed double-pipe typo in API.md overview table
- Added trailing newline to configuration.md

* bump version to 0.1.6

Author: peteretelej

docs/API.md

@@ -7,7 +7,7 @@ Detailed documentation for the Largefile MCP Server tools.
 The Largefile MCP Server provides 7 tools for working with large text files:
 
 | Tool | Purpose |
-|------|---------||
+|------|---------|
 | **get_overview** | File structure analysis with Tree-sitter semantic outline |
 | **search_content** | Pattern search with fuzzy, regex, and invert matching |
 | **read_content** | Targeted reading by offset, pattern, tail, or head mode |
@@ -363,6 +363,57 @@ for backup in result["available_backups"]:
 }
 ```
 
+### list_directory
+
+List directory contents with optional recursive depth control.
+
+**Signature:**
+```python
+def list_directory(
+    absolute_dir_path: str,
+    max_depth: int = 1,
+    max_entries: int | None = None,
+    include_hidden: bool = False,
+) -> dict
+```
+
+**Parameters:**
+- `absolute_dir_path`: Absolute path to the directory to list (required)
+- `max_depth`: How many levels deep to recurse (default: 1 = direct children only)
+- `max_entries`: Maximum total entries to return (default: server config, 200)
+- `include_hidden`: Include entries starting with `.` (default: False)
+
+**Returns:** Dictionary with:
+- `path`: Absolute path of the listed directory
+- `entries`: List of entry objects (see below)
+- `total_files`: Number of files found
+- `total_dirs`: Number of directories found
+- `truncated`: True if `max_entries` cap was reached before listing all entries
+- `truncated_at`: Path of the entry where truncation occurred (if `truncated`)
+
+**Entry Object:**
+- `name`: Relative name from the listing root (e.g. `"src/utils.py"` at depth 2)
+- `type`: `"file"` or `"dir"`
+- `size_bytes`: File size in bytes (0 for directories)
+- `child_count`: Number of visible children for directories (null for files)
+
+**Example:**
+```python
+# List direct children
+result = list_directory("/path/to/project")
+for entry in result["entries"]:
+    if entry["type"] == "dir":
+        print(f"{entry['name']}/ ({entry['child_count']} children)")
+    else:
+        print(f"{entry['name']} ({entry['size_bytes']} bytes)")
+
+# Recurse two levels deep
+result = list_directory("/path/to/project", max_depth=2, include_hidden=True)
+print(f"Found {result['total_files']} files, {result['total_dirs']} dirs")
+```
+
+Directories are listed before files, sorted alphabetically within each group. `__pycache__`, `node_modules`, and `.git` are ignored by default (configurable via `LARGEFILE_IGNORED_DIR_PATTERNS`).
+
 ### search_directory
 
 Search for a pattern across all files in a directory tree.
@@ -403,19 +454,19 @@ def search_directory(
 - `truncated`: True if cap was reached before finishing
 - `truncated_at`: Relative path of file where truncation occurred (if `truncated`)
 - `pattern`: The search pattern used
-- `directory`: The absolute directory searched
+- `include_pattern`: The file glob pattern used to filter files
+- `path`: The absolute directory searched
 
 **Per-file Result Object:**
 - `file`: Relative path from the search root (e.g. `"src/tools.py"`)
 - `matches`: List of match objects (same structure as `search_content` results)
-- `match_count`: Number of matches in this file
 
 **Examples:**
 ```python
 # Find all TODO comments in Python files
 result = search_directory("/path/to/project", "TODO", include_pattern="*.py", fuzzy=False)
 for file_result in result["results"]:
-    print(f"{file_result['file']}: {file_result['match_count']} TODOs")
+    print(f"{file_result['file']}: {len(file_result['matches'])} TODOs")
 
 # Case-insensitive search (explicit)
 result = search_directory("/path/to/project", "error", case_sensitive=False, fuzzy=False)

docs/configuration.md

@@ -338,4 +338,4 @@ LARGEFILE_MAX_DIR_SEARCH_FILES=10000
 - `LARGEFILE_IGNORED_DIR_PATTERNS` is shared with `list_directory` — one config
   controls both tools.
 - `fuzzy=False` is the default for `search_directory`; enabling it on large trees
-  can be slow. Use `include_pattern` to narrow the scope first.
+  can be slow. Use `include_pattern` to narrow the scope first.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "largefile"
-version = "0.1.5"
+version = "0.1.6"
 description = "MCP server for AI assistants to navigate, search, and edit large codebases, logs, and data files with semantic code analysis"
 readme = "README.md"
 requires-python = ">=3.10"

src/mcp_schemas.py

@@ -257,10 +257,12 @@ def get_tool_schemas() -> list[types.Tool]:
                         "type": "integer",
                         "description": "How many levels deep to recurse (default: 1 = direct children only).",
                         "default": 1,
+                        "minimum": 1,
                     },
                     "max_entries": {
                         "type": "integer",
                         "description": "Maximum total entries to return. Defaults to server config (200).",
+                        "minimum": 1,
                     },
                     "include_hidden": {
                         "type": "boolean",

src/tools.py

@@ -168,7 +168,7 @@ def get_overview(absolute_file_path: str) -> dict:
     elif file_ext == ".rs":
         search_hints = ["fn ", "struct ", "impl ", "use "]
     elif file_ext == ".java":
-        search_hints = ["class ", "interface ", "void ", "public ", "private "]
+        search_hints = ["class ", "interface ", "enum ", "import ", "@interface "]
     else:
         search_hints = ["TODO", "FIXME", "NOTE", "HACK"]
 
@@ -699,7 +699,9 @@ def _collect_entries(
             os.scandir(dir_path),
             key=lambda e: (not e.is_dir(follow_symlinks=False), e.name.lower()),
         )
-    except PermissionError:
+    except PermissionError as exc:
+        if current_depth == 0:
+            raise FileAccessError(f"Permission denied: {dir_path}") from exc
         return entries
 
     for entry in raw:
@@ -711,7 +713,7 @@ def _collect_entries(
             break
         if not include_hidden and entry.name.startswith("."):
             continue
-        if entry.name in ignored_patterns:
+        if entry.is_dir(follow_symlinks=False) and entry.name in ignored_patterns:
             continue
 
         counter.total += 1
@@ -723,7 +725,9 @@ def _collect_entries(
                     1
                     for c in os.scandir(entry.path)
                     if (include_hidden or not c.name.startswith("."))
-                    and c.name not in ignored_patterns
+                    and not (
+                        c.is_dir(follow_symlinks=False) and c.name in ignored_patterns
+                    )
                 )
             except PermissionError:
                 child_count = 0
@@ -964,7 +968,7 @@ def search_directory(
 
         try:
             lines = read_file_lines(abs_path)
-        except Exception:
+        except FileAccessError:
             lines = []
 
         match_dicts: list[dict] = []

src/tree_parser.py

@@ -399,7 +399,7 @@ def create_outline_item_from_node(node: Any, depth: int) -> OutlineItem | None:
                 line_count=node.end_point[0] - node.start_point[0] + 1,
             )
 
-    # Java-specific nodes
+    # Java and TypeScript declaration nodes
     elif node_type == "class_declaration":
         name = extract_node_name(node, "identifier")
         if name:

tests/unit/test_tools_list_directory.py

@@ -6,30 +6,6 @@
 
 from src.tools import list_directory
 
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _make_tree(base: Path, structure: dict) -> None:
-    """Recursively create files/dirs described by *structure*.
-
-    Keys ending in '/' are directories; other keys are files.
-    Values for files are the byte-string content; values for dirs are
-    nested structure dicts.
-    """
-    for name, content in structure.items():
-        if name.endswith("/"):
-            child = base / name.rstrip("/")
-            child.mkdir(parents=True, exist_ok=True)
-            if isinstance(content, dict):
-                _make_tree(child, content)
-        else:
-            (base / name).write_bytes(
-                content if isinstance(content, bytes) else content.encode()
-            )
-
-
 # ---------------------------------------------------------------------------
 # TestListDirectoryErrors
 # ---------------------------------------------------------------------------
@@ -181,6 +157,36 @@ def test_default_ignores_dotgit(self, tmp_path: Path) -> None:
         names = [e["name"] for e in result["entries"]]
         assert ".git" not in names
 
+    def test_file_named_like_ignored_pattern_is_not_skipped(
+        self, tmp_path: Path
+    ) -> None:
+        """A file named '__pycache__' must still appear in listings."""
+        (tmp_path / "__pycache__").write_text("I am a file")
+        result = list_directory(str(tmp_path))
+        names = [e["name"] for e in result["entries"]]
+        assert "__pycache__" in names
+
+    def test_dir_named_like_ignored_pattern_is_still_skipped(
+        self, tmp_path: Path
+    ) -> None:
+        """A directory named '__pycache__' must be skipped."""
+        (tmp_path / "__pycache__").mkdir()
+        result = list_directory(str(tmp_path))
+        names = [e["name"] for e in result["entries"]]
+        assert "__pycache__" not in names
+
+    def test_child_count_includes_file_named_like_ignored_pattern(
+        self, tmp_path: Path
+    ) -> None:
+        """child_count must count files whose name matches an ignored pattern."""
+        parent = tmp_path / "parent"
+        parent.mkdir()
+        (parent / "__pycache__").write_text("I am a file")
+        (parent / "regular.txt").write_text("ok")
+        result = list_directory(str(tmp_path))
+        entry = next(e for e in result["entries"] if e["name"] == "parent")
+        assert entry["child_count"] == 2
+
     def test_empty_env_var_disables_all_ignore_patterns(self, tmp_path: Path) -> None:
         """LARGEFILE_IGNORED_DIR_PATTERNS='' must not produce a spurious [''] pattern."""
         with patch.dict(os.environ, {"LARGEFILE_IGNORED_DIR_PATTERNS": ""}):
@@ -283,14 +289,33 @@ def test_no_truncation_when_under_limit(self, tmp_path: Path) -> None:
 
 
 class TestListDirectoryErrorPaths:
-    def test_permission_error_on_root_scan_returns_empty(self, tmp_path: Path) -> None:
-        """PermissionError on os.scandir(dir_path) returns empty entries (lines 698-699)."""
+    def test_permission_error_on_root_scan_returns_error(self, tmp_path: Path) -> None:
+        """PermissionError on os.scandir(dir_path) at root depth returns error dict."""
         with patch("src.tools.os.scandir", side_effect=PermissionError):
             result = list_directory(str(tmp_path))
-        assert result["entries"] == []
-        assert result["total_files"] == 0
-        assert result["total_dirs"] == 0
-        assert result["truncated"] is False
+        assert "error" in result
+        assert "Permission denied" in result["error"]
+
+    def test_permission_error_on_nested_scan_returns_empty(
+        self, tmp_path: Path
+    ) -> None:
+        """PermissionError on a nested directory returns empty children gracefully."""
+        sub = tmp_path / "restricted"
+        sub.mkdir()
+
+        real_scandir = os.scandir
+        call_count = {"n": 0}
+
+        def patched_scandir(path: str) -> object:
+            call_count["n"] += 1
+            if call_count["n"] == 3:  # third call: recursing into restricted/
+                raise PermissionError("access denied")
+            return real_scandir(path)
+
+        with patch("src.tools.os.scandir", side_effect=patched_scandir):
+            result = list_directory(str(tmp_path), max_depth=2)
+        assert "error" not in result
+        assert result["total_dirs"] == 1
 
     def test_recursive_truncation_stops_parent_iteration(self, tmp_path: Path) -> None:
         """counter.truncated=True from recursive call breaks parent loop (line 703)."""

tests/unit/test_tools_search_directory.py

@@ -382,7 +382,10 @@ def test_read_file_lines_failure_yields_empty_context(self, tmp_path: Path) -> N
         """If read_file_lines fails after a match is found, context is empty."""
         (tmp_path / "f.txt").write_text("needle\n")
 
-        with patch("src.tools.read_file_lines", side_effect=OSError("read failed")):
+        with patch(
+            "src.tools.read_file_lines",
+            side_effect=FileAccessError("read failed"),
+        ):
             result = search_directory(str(tmp_path), "needle", fuzzy=False)
 
         assert result["total_matches"] == 1