auto trim TOC, rewrite test to use actual MPC calls

tests/conftest.py

@@ -1,23 +1,36 @@
 """Shared fixtures for pdf-mcp tests."""
 
+import asyncio
 import subprocess
 import sys
 from pathlib import Path
 
 import pytest
 
+from pdf_mcp.server import mcp
+
 ASSETS = Path(__file__).parent.parent / "assets"
 
 
 def pytest_configure(config):
     """Generate test PDFs before the test session if they don't exist."""
-    expected = ["basic.pdf", "diagrams.pdf", "nested_toc.pdf", "search_targets.pdf"]
+    expected = ["basic.pdf", "diagrams.pdf", "nested_toc.pdf", "search_targets.pdf", "large_toc.pdf", "mega_toc.pdf"]
     if not all((ASSETS / f).exists() for f in expected):
         subprocess.check_call(
             [sys.executable, str(ASSETS / "generate.py")],
         )
 
 
+@pytest.fixture
+def call_tool():
+    """Call an MCP tool by name, going through the real FastMCP call path."""
+    def _call(tool_name: str, **kwargs):
+        tools = mcp._tool_manager.list_tools()
+        tool = next(t for t in tools if t.name == tool_name)
+        return asyncio.run(tool.run(kwargs))
+    return _call
+
+
 @pytest.fixture
 def basic_pdf() -> str:
     return str(ASSETS / "basic.pdf")
@@ -36,3 +49,13 @@ def nested_toc_pdf() -> str:
 @pytest.fixture
 def search_pdf() -> str:
     return str(ASSETS / "search_targets.pdf")
+
+
+@pytest.fixture
+def large_toc_pdf() -> str:
+    return str(ASSETS / "large_toc.pdf")
+
+
+@pytest.fixture
+def mega_toc_pdf() -> str:
+    return str(ASSETS / "mega_toc.pdf")

tests/test_get_page_image.py

@@ -3,75 +3,70 @@ from pathlib import Path
 
 from mcp.server.fastmcp import Image
 
-from pdf_mcp.server import get_page_image
-
 
 class TestGetPageImageBase64:
-    def test_returns_image_object(self, basic_pdf):
-        result = get_page_image(basic_pdf, page=1)
+    def test_returns_image_object(self, basic_pdf, call_tool):
+        result = call_tool("get_page_image", filename=basic_pdf, page=1)
         assert isinstance(result, Image)
 
-    def test_image_has_data(self, basic_pdf):
-        result = get_page_image(basic_pdf, page=1)
+    def test_image_has_data(self, basic_pdf, call_tool):
+        result = call_tool("get_page_image", filename=basic_pdf, page=1)
         assert len(result.data) > 0
 
-    def test_png_signature(self, basic_pdf):
-        result = get_page_image(basic_pdf, page=1)
-        # PNG files start with the 8-byte signature
+    def test_png_signature(self, basic_pdf, call_tool):
+        result = call_tool("get_page_image", filename=basic_pdf, page=1)
         assert result.data[:4] == b"\x89PNG"
 
-    def test_different_pages(self, basic_pdf):
-        img1 = get_page_image(basic_pdf, page=1)
-        img2 = get_page_image(basic_pdf, page=2)
+    def test_different_pages(self, basic_pdf, call_tool):
+        img1 = call_tool("get_page_image", filename=basic_pdf, page=1)
+        img2 = call_tool("get_page_image", filename=basic_pdf, page=2)
         assert img1.data != img2.data
 
 
 class TestGetPageImageFile:
-    def test_returns_string_with_path(self, basic_pdf):
-        result = get_page_image(basic_pdf, page=1, output="file")
+    def test_returns_string_with_path(self, basic_pdf, call_tool):
+        result = call_tool("get_page_image", filename=basic_pdf, page=1, output="file")
         assert isinstance(result, str)
         assert "Image saved to" in result
 
-    def test_file_exists(self, basic_pdf):
-        result = get_page_image(basic_pdf, page=1, output="file")
-        # Extract path from "Image saved to /path/to/file.png (WxHpx)"
+    def test_file_exists(self, basic_pdf, call_tool):
+        result = call_tool("get_page_image", filename=basic_pdf, page=1, output="file")
         path = result.split("Image saved to ")[1].split(" (")[0]
         assert Path(path).exists()
         os.unlink(path)
 
-    def test_file_is_valid_png(self, basic_pdf):
-        result = get_page_image(basic_pdf, page=1, output="file")
+    def test_file_is_valid_png(self, basic_pdf, call_tool):
+        result = call_tool("get_page_image", filename=basic_pdf, page=1, output="file")
         path = result.split("Image saved to ")[1].split(" (")[0]
         with open(path, "rb") as f:
             assert f.read(4) == b"\x89PNG"
         os.unlink(path)
 
-    def test_file_includes_dimensions(self, basic_pdf):
-        result = get_page_image(basic_pdf, page=1, output="file")
-        # Should contain something like "(1240x1754px)"
+    def test_file_includes_dimensions(self, basic_pdf, call_tool):
+        result = call_tool("get_page_image", filename=basic_pdf, page=1, output="file")
         assert "px)" in result
 
 
 class TestGetPageImageDpi:
-    def test_higher_dpi_larger_file(self, basic_pdf):
-        low = get_page_image(basic_pdf, page=1, dpi=72)
-        high = get_page_image(basic_pdf, page=1, dpi=300)
+    def test_higher_dpi_larger_file(self, basic_pdf, call_tool):
+        low = call_tool("get_page_image", filename=basic_pdf, page=1, dpi=72)
+        high = call_tool("get_page_image", filename=basic_pdf, page=1, dpi=300)
         assert len(high.data) > len(low.data)
 
-    def test_default_dpi(self, basic_pdf):
-        default = get_page_image(basic_pdf, page=1)
-        explicit_150 = get_page_image(basic_pdf, page=1, dpi=150)
+    def test_default_dpi(self, basic_pdf, call_tool):
+        default = call_tool("get_page_image", filename=basic_pdf, page=1)
+        explicit_150 = call_tool("get_page_image", filename=basic_pdf, page=1, dpi=150)
         assert len(default.data) == len(explicit_150.data)
 
 
 class TestGetPageImageDiagrams:
-    def test_diagrams_renders(self, diagrams_pdf):
-        result = get_page_image(diagrams_pdf, page=1)
+    def test_diagrams_renders(self, diagrams_pdf, call_tool):
+        result = call_tool("get_page_image", filename=diagrams_pdf, page=1)
         assert isinstance(result, Image)
         assert len(result.data) > 0
 
-    def test_diagrams_file_output(self, diagrams_pdf):
-        result = get_page_image(diagrams_pdf, page=1, output="file")
+    def test_diagrams_file_output(self, diagrams_pdf, call_tool):
+        result = call_tool("get_page_image", filename=diagrams_pdf, page=1, output="file")
         path = result.split("Image saved to ")[1].split(" (")[0]
         assert Path(path).exists()
         assert Path(path).stat().st_size > 0

tests/test_get_page_text.py

@@ -1,120 +1,116 @@
-from pdf_mcp.server import get_page_text
-
-
 class TestGetPageTextJson:
-    def test_default_format_is_json(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1)
+    def test_default_format_is_json(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1)
         assert isinstance(result, list)
         assert len(result) == 1
         assert isinstance(result[0], dict)
 
-    def test_json_has_page_number(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=2)
+    def test_json_has_page_number(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=2)
         assert result[0]["page_number"] == 2
 
-    def test_json_has_blocks(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1)
+    def test_json_has_blocks(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1)
         assert "blocks" in result[0]
         assert len(result[0]["blocks"]) > 0
 
-    def test_json_page_range(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, end_page=3, format="json")
+    def test_json_page_range(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, end_page=3, format="json")
         assert len(result) == 3
         assert result[0]["page_number"] == 1
         assert result[2]["page_number"] == 3
 
 
 class TestGetPageTextPlain:
-    def test_text_format_returns_string(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="text")
+    def test_text_format_returns_string(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="text")
         assert isinstance(result, str)
 
-    def test_text_contains_content(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="text")
+    def test_text_contains_content(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="text")
         assert "Chapter 1" in result
         assert "introductory material" in result
 
-    def test_text_page_range_has_breaks(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, end_page=2, format="text")
+    def test_text_page_range_has_breaks(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, end_page=2, format="text")
         assert "--- Page Break ---" in result
         assert "Chapter 1" in result
         assert "Chapter 2" in result
 
-    def test_text_single_page_no_break(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="text")
+    def test_text_single_page_no_break(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="text")
         assert "--- Page Break ---" not in result
 
 
 class TestGetPageTextMarkdown:
-    def test_markdown_returns_string(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="markdown")
+    def test_markdown_returns_string(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="markdown")
         assert isinstance(result, str)
 
-    def test_markdown_contains_content(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="markdown")
+    def test_markdown_contains_content(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="markdown")
         assert "Chapter 1" in result
 
-    def test_markdown_page_range(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, end_page=3, format="markdown")
+    def test_markdown_page_range(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, end_page=3, format="markdown")
         assert "Chapter 1" in result
         assert "Chapter 3" in result
 
 
 class TestGetPageTextHtml:
-    def test_html_returns_string(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="html")
+    def test_html_returns_string(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="html")
         assert isinstance(result, str)
 
-    def test_html_has_tags(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="html")
+    def test_html_has_tags(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="html")
         assert "<div" in result
         assert "<span" in result
 
-    def test_html_contains_content(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="html")
+    def test_html_contains_content(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="html")
         assert "Chapter 1" in result
 
 
 class TestGetPageTextHeaderFooter:
-    def test_with_headers_footers(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=1, format="text", include_headers_footers=True)
+    def test_with_headers_footers(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=1, format="text", include_headers_footers=True)
         assert "Header" in result
         assert "Page 1 of 3" in result
 
-    def test_without_headers_footers(self, basic_pdf):
-        result = get_page_text(
-            basic_pdf, start_page=1, format="text", include_headers_footers=False
+    def test_without_headers_footers(self, basic_pdf, call_tool):
+        result = call_tool(
+            "get_page_text", filename=basic_pdf, start_page=1, format="text", include_headers_footers=False
         )
-        # Header text is at y=30, footer at y=820 — both within the 50pt margin crop
         assert "Header" not in result
         assert "Page 1 of 3" not in result
 
-    def test_body_preserved_without_headers_footers(self, basic_pdf):
-        result = get_page_text(
-            basic_pdf, start_page=1, format="text", include_headers_footers=False
+    def test_body_preserved_without_headers_footers(self, basic_pdf, call_tool):
+        result = call_tool(
+            "get_page_text", filename=basic_pdf, start_page=1, format="text", include_headers_footers=False
         )
         assert "Chapter 1" in result
         assert "introductory material" in result
 
-    def test_markdown_without_headers_footers(self, basic_pdf):
-        result = get_page_text(
-            basic_pdf, start_page=1, format="markdown", include_headers_footers=False
+    def test_markdown_without_headers_footers(self, basic_pdf, call_tool):
+        result = call_tool(
+            "get_page_text", filename=basic_pdf, start_page=1, format="markdown", include_headers_footers=False
         )
         assert "Chapter 1" in result
         assert "Header" not in result
 
 
 class TestGetPageTextEndPageDefault:
-    def test_end_page_defaults_to_start(self, basic_pdf):
-        result = get_page_text(basic_pdf, start_page=2, format="text")
+    def test_end_page_defaults_to_start(self, basic_pdf, call_tool):
+        result = call_tool("get_page_text", filename=basic_pdf, start_page=2, format="text")
         assert "Chapter 2" in result
         assert "Chapter 1" not in result
         assert "Chapter 3" not in result
 
 
 class TestGetPageTextDiagrams:
-    def test_diagrams_text_extraction(self, diagrams_pdf):
-        result = get_page_text(diagrams_pdf, start_page=1, format="text")
+    def test_diagrams_text_extraction(self, diagrams_pdf, call_tool):
+        result = call_tool("get_page_text", filename=diagrams_pdf, start_page=1, format="text")
         assert "Component A" in result
         assert "Component B" in result
         assert "Pin Configuration" in result

tests/test_get_pdf_info.py

@@ -1,9 +1,6 @@
-from pdf_mcp.server import get_pdf_info
-
-
 class TestGetPdfInfo:
-    def test_basic_metadata(self, basic_pdf):
-        info = get_pdf_info(basic_pdf)
+    def test_basic_metadata(self, basic_pdf, call_tool):
+        info = call_tool("get_pdf_info", filename=basic_pdf)
         assert info["page_count"] == 3
         assert info["metadata"]["title"] == "Test Document"
         assert info["metadata"]["author"] == "Test Author"
@@ -12,18 +9,18 @@ class TestGetPdfInfo:
         assert info["metadata"]["creator"] == "generate.py"
         assert info["is_encrypted"] is False
 
-    def test_filename_returned(self, basic_pdf):
-        info = get_pdf_info(basic_pdf)
+    def test_filename_returned(self, basic_pdf, call_tool):
+        info = call_tool("get_pdf_info", filename=basic_pdf)
         assert info["filename"] == basic_pdf
 
-    def test_single_page_pdf(self, diagrams_pdf):
-        info = get_pdf_info(diagrams_pdf)
+    def test_single_page_pdf(self, diagrams_pdf, call_tool):
+        info = call_tool("get_pdf_info", filename=diagrams_pdf)
         assert info["page_count"] == 1
 
-    def test_multi_page_pdf(self, nested_toc_pdf):
-        info = get_pdf_info(nested_toc_pdf)
+    def test_multi_page_pdf(self, nested_toc_pdf, call_tool):
+        info = call_tool("get_pdf_info", filename=nested_toc_pdf)
         assert info["page_count"] == 9
 
-    def test_search_targets_page_count(self, search_pdf):
-        info = get_pdf_info(search_pdf)
+    def test_search_targets_page_count(self, search_pdf, call_tool):
+        info = call_tool("get_pdf_info", filename=search_pdf)
         assert info["page_count"] == 3

tests/test_get_table_of_contents.py

@@ -1,39 +1,177 @@
-from pdf_mcp.server import get_table_of_contents
-
-
 class TestGetTableOfContents:
-    def test_basic_toc(self, basic_pdf):
-        toc = get_table_of_contents(basic_pdf)
-        assert len(toc) == 3
-        assert toc[0] == {"level": 1, "title": "Chapter 1", "page": 1}
-        assert toc[1] == {"level": 1, "title": "Chapter 2", "page": 2}
-        assert toc[2] == {"level": 1, "title": "Chapter 3", "page": 3}
+    def test_basic_toc(self, basic_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=basic_pdf)
+        assert result["total_entries"] == 3
+        entries = result["entries"]
+        assert entries[0] == {"level": 1, "title": "Chapter 1", "page": 1}
+        assert entries[1] == {"level": 1, "title": "Chapter 2", "page": 2}
+        assert entries[2] == {"level": 1, "title": "Chapter 3", "page": 3}
 
-    def test_nested_toc_entries(self, nested_toc_pdf):
-        toc = get_table_of_contents(nested_toc_pdf)
-        assert len(toc) == 9
+    def test_nested_toc_entries(self, nested_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=nested_toc_pdf)
+        assert result["total_entries"] == 9
 
-    def test_nested_toc_levels(self, nested_toc_pdf):
-        toc = get_table_of_contents(nested_toc_pdf)
-        levels = [e["level"] for e in toc]
+    def test_nested_toc_levels(self, nested_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=nested_toc_pdf)
+        levels = [e["level"] for e in result["entries"]]
         assert levels == [1, 1, 2, 2, 3, 3, 1, 2, 2]
 
-    def test_nested_toc_titles(self, nested_toc_pdf):
-        toc = get_table_of_contents(nested_toc_pdf)
-        titles = [e["title"] for e in toc]
+    def test_nested_toc_titles(self, nested_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=nested_toc_pdf)
+        titles = [e["title"] for e in result["entries"]]
         assert "Introduction" in titles
         assert "Database Layer" in titles
         assert "Kubernetes" in titles
 
-    def test_nested_toc_page_numbers(self, nested_toc_pdf):
-        toc = get_table_of_contents(nested_toc_pdf)
-        pages = [e["page"] for e in toc]
+    def test_nested_toc_page_numbers(self, nested_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=nested_toc_pdf)
+        pages = [e["page"] for e in result["entries"]]
         assert pages == list(range(1, 10))
 
-    def test_no_toc(self, search_pdf):
-        toc = get_table_of_contents(search_pdf)
-        assert toc == []
+    def test_no_toc(self, search_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=search_pdf)
+        assert result["total_entries"] == 0
+        assert result["entries"] == []
 
-    def test_no_toc_diagrams(self, diagrams_pdf):
-        toc = get_table_of_contents(diagrams_pdf)
-        assert toc == []
+    def test_no_toc_diagrams(self, diagrams_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=diagrams_pdf)
+        assert result["total_entries"] == 0
+        assert result["entries"] == []
+
+    def test_no_auto_trim_small_toc(self, nested_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=nested_toc_pdf)
+        assert "auto_trimmed_to_level" not in result
+        assert "hint" not in result
+
+
+class TestAutoTrim:
+    """Test auto-trimming with 402-entry, 4-level deep mega TOC.
+
+    mega_toc.pdf structure:
+      2 volumes (L1) × 8 chapters (L2) × 8 sections (L3) × 2 subsections (L4)
+
+      Cumulative:  ≤L1=2,  ≤L2=18,  ≤L3=146,  ≤L4=402
+      Threshold: 100
+    """
+
+    def test_full_toc_auto_trims_to_level_2(self, mega_toc_pdf, call_tool):
+        """Full TOC (402 entries) auto-trims to level 2 (18 entries ≤ 100)."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf)
+        assert result["auto_trimmed_to_level"] == 2
+        assert result["total_entries"] == 18
+        assert all(e["level"] <= 2 for e in result["entries"])
+
+    def test_auto_trim_hint_present(self, mega_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf)
+        assert "hint" in result
+        assert "402" in result["hint"]
+        assert "18" in result["hint"]
+        assert "level 2" in result["hint"]
+
+    def test_auto_trim_entries_are_volumes_and_chapters(self, mega_toc_pdf, call_tool):
+        """Trimmed entries should be exactly the 2 volumes + 16 chapters."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf)
+        entries = result["entries"]
+        assert len(entries) == 18
+        volumes = [e for e in entries if e["level"] == 1]
+        chapters = [e for e in entries if e["level"] == 2]
+        assert len(volumes) == 2
+        assert len(chapters) == 16
+
+    def test_explicit_max_level_skips_auto_trim(self, mega_toc_pdf, call_tool):
+        """When max_level is explicitly set, auto-trim must not activate."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, max_level=4)
+        assert "auto_trimmed_to_level" not in result
+        assert "hint" not in result
+        assert result["total_entries"] == 402
+
+    def test_explicit_max_level_3(self, mega_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, max_level=3)
+        assert "auto_trimmed_to_level" not in result
+        assert result["total_entries"] == 146
+
+    def test_explicit_max_level_1(self, mega_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, max_level=1)
+        assert result["total_entries"] == 2
+        assert all(e["level"] == 1 for e in result["entries"])
+
+
+class TestAutoTrimWithParent:
+    """Test auto-trim when filtering by parent.
+
+    Volume 1 subtree: 8 ch + 64 sec + 128 subsec = 200 children
+      ≤L2=8, ≤L3=72, ≤L4=200  → auto-trim to L3 (72 entries)
+      applied_max_level = 3 - 1 = 2 (relative to Volume 1)
+
+    Chapter 1.1 subtree: 8 sec + 16 subsec = 24 children (< 100, no trim)
+    """
+
+    def test_parent_subtree_auto_trims(self, mega_toc_pdf, call_tool):
+        """Volume 1's 200-entry subtree should auto-trim to 72 entries."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Volume 1")
+        assert result["auto_trimmed_to_level"] == 2  # relative to parent
+        assert result["total_entries"] == 72
+        assert "hint" in result
+
+    def test_parent_subtree_trimmed_levels(self, mega_toc_pdf, call_tool):
+        """After trimming, only chapters (L2) and sections (L3) remain."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Volume 1")
+        levels = {e["level"] for e in result["entries"]}
+        assert levels == {2, 3}
+
+    def test_parent_small_subtree_no_trim(self, mega_toc_pdf, call_tool):
+        """Chapter 1.1 subtree (24 entries) should not trigger auto-trim."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Chapter 1.1")
+        assert "auto_trimmed_to_level" not in result
+        assert "hint" not in result
+        assert result["total_entries"] == 24
+
+    def test_parent_small_subtree_all_levels(self, mega_toc_pdf, call_tool):
+        """Small subtree should include all levels (sections + subsections)."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Chapter 1.1")
+        levels = {e["level"] for e in result["entries"]}
+        assert levels == {3, 4}
+
+    def test_parent_with_explicit_max_level_1(self, mega_toc_pdf, call_tool):
+        """parent + max_level=1 → direct children only, no auto-trim."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Volume 1", max_level=1)
+        assert "auto_trimmed_to_level" not in result
+        assert result["total_entries"] == 8
+        assert all(e["level"] == 2 for e in result["entries"])
+
+    def test_parent_with_explicit_max_level_2(self, mega_toc_pdf, call_tool):
+        """parent + max_level=2 → children + grandchildren, no auto-trim."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Volume 1", max_level=2)
+        assert "auto_trimmed_to_level" not in result
+        assert result["total_entries"] == 72
+
+    def test_parent_not_found(self, mega_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Nonexistent Section")
+        assert result["error"] == "No TOC entry matching 'Nonexistent Section'"
+        assert result["total_entries"] == 0
+
+    def test_parent_case_insensitive(self, mega_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="volume 1")
+        assert result["total_entries"] > 0
+
+    def test_parent_partial_match(self, mega_toc_pdf, call_tool):
+        """Parent matching is substring-based."""
+        result = call_tool("get_table_of_contents", filename=mega_toc_pdf, parent="Chapter 2.")
+        assert result["total_entries"] > 0
+
+
+class TestAutoTrimOldPdf:
+    """Regression tests with large_toc.pdf (205 entries, 3 levels)."""
+
+    def test_auto_trim_large_toc(self, large_toc_pdf, call_tool):
+        """large_toc.pdf: 205 entries, auto-trims to level 2 (45 entries)."""
+        result = call_tool("get_table_of_contents", filename=large_toc_pdf)
+        assert result["auto_trimmed_to_level"] == 2
+        assert result["total_entries"] == 45
+        assert "hint" in result
+        assert all(e["level"] <= 2 for e in result["entries"])
+
+    def test_no_auto_trim_when_explicit_max_level(self, large_toc_pdf, call_tool):
+        result = call_tool("get_table_of_contents", filename=large_toc_pdf, max_level=3)
+        assert "auto_trimmed_to_level" not in result
+        assert "hint" not in result

tests/test_search_text.py

@@ -1,88 +1,84 @@
-from pdf_mcp.server import search_text
-
-
 class TestSearchTextBasic:
-    def test_unique_marker_on_two_pages(self, search_pdf):
-        hits = search_text(search_pdf, query="UNIQUE_MARKER_ALPHA")
+    def test_unique_marker_on_two_pages(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="UNIQUE_MARKER_ALPHA")
         pages = [h["page"] for h in hits]
         assert pages == [1, 3]
 
-    def test_unique_marker_single_page(self, search_pdf):
-        hits = search_text(search_pdf, query="UNIQUE_MARKER_BETA")
+    def test_unique_marker_single_page(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="UNIQUE_MARKER_BETA")
         assert len(hits) == 1
         assert hits[0]["page"] == 2
 
-    def test_no_results(self, search_pdf):
-        hits = search_text(search_pdf, query="NONEXISTENT_TEXT_XYZ")
+    def test_no_results(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="NONEXISTENT_TEXT_XYZ")
         assert hits == []
 
-    def test_multi_page_hits(self, search_pdf):
-        hits = search_text(search_pdf, query="resistance")
+    def test_multi_page_hits(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="resistance")
         pages = [h["page"] for h in hits]
         assert 1 in pages
         assert 2 in pages
 
 
 class TestSearchTextCaseInsensitive:
-    def test_lowercase_query(self, search_pdf):
-        hits = search_text(search_pdf, query="unique_marker_alpha")
+    def test_lowercase_query(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="unique_marker_alpha")
         assert len(hits) == 2
 
-    def test_mixed_case_query(self, search_pdf):
-        hits = search_text(search_pdf, query="Unique_Marker_Alpha")
+    def test_mixed_case_query(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="Unique_Marker_Alpha")
         assert len(hits) == 2
 
-    def test_case_insensitive_content(self, search_pdf):
-        lower = search_text(search_pdf, query="resistance")
-        upper = search_text(search_pdf, query="RESISTANCE")
+    def test_case_insensitive_content(self, search_pdf, call_tool):
+        lower = call_tool("search_text", filename=search_pdf, query="resistance")
+        upper = call_tool("search_text", filename=search_pdf, query="RESISTANCE")
         assert len(lower) == len(upper)
 
 
 class TestSearchTextContext:
-    def test_context_contains_query(self, search_pdf):
-        hits = search_text(search_pdf, query="UNIQUE_MARKER_BETA")
+    def test_context_contains_query(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="UNIQUE_MARKER_BETA")
         assert "UNIQUE_MARKER_BETA" in hits[0]["context"]
 
-    def test_context_has_surrounding_text(self, search_pdf):
-        hits = search_text(search_pdf, query="UNIQUE_MARKER_BETA")
-        # The context should include text around the match
+    def test_context_has_surrounding_text(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="UNIQUE_MARKER_BETA")
         assert len(hits[0]["context"]) > len("UNIQUE_MARKER_BETA")
 
-    def test_custom_context_chars(self, search_pdf):
-        short = search_text(search_pdf, query="UNIQUE_MARKER_BETA", context_chars=10)
-        long = search_text(search_pdf, query="UNIQUE_MARKER_BETA", context_chars=200)
+    def test_custom_context_chars(self, search_pdf, call_tool):
+        short = call_tool("search_text", filename=search_pdf, query="UNIQUE_MARKER_BETA", context_chars=10)
+        long = call_tool("search_text", filename=search_pdf, query="UNIQUE_MARKER_BETA", context_chars=200)
         assert len(short[0]["context"]) <= len(long[0]["context"])
 
-    def test_zero_context(self, search_pdf):
-        hits = search_text(search_pdf, query="UNIQUE_MARKER_BETA", context_chars=0)
+    def test_zero_context(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="UNIQUE_MARKER_BETA", context_chars=0)
         assert hits[0]["context"] == "UNIQUE_MARKER_BETA"
 
 
 class TestSearchTextHitStructure:
-    def test_hit_has_page(self, search_pdf):
-        hits = search_text(search_pdf, query="resistance")
+    def test_hit_has_page(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="resistance")
         for hit in hits:
             assert "page" in hit
             assert isinstance(hit["page"], int)
 
-    def test_hit_has_context(self, search_pdf):
-        hits = search_text(search_pdf, query="resistance")
+    def test_hit_has_context(self, search_pdf, call_tool):
+        hits = call_tool("search_text", filename=search_pdf, query="resistance")
         for hit in hits:
             assert "context" in hit
             assert isinstance(hit["context"], str)
 
 
 class TestSearchTextOnOtherPdfs:
-    def test_search_basic_pdf(self, basic_pdf):
-        hits = search_text(basic_pdf, query="introductory")
+    def test_search_basic_pdf(self, basic_pdf, call_tool):
+        hits = call_tool("search_text", filename=basic_pdf, query="introductory")
         assert len(hits) == 1
         assert hits[0]["page"] == 1
 
-    def test_search_diagrams_pdf(self, diagrams_pdf):
-        hits = search_text(diagrams_pdf, query="Component A")
+    def test_search_diagrams_pdf(self, diagrams_pdf, call_tool):
+        hits = call_tool("search_text", filename=diagrams_pdf, query="Component A")
         assert len(hits) == 1
         assert hits[0]["page"] == 1
 
-    def test_search_nested_toc_pdf(self, nested_toc_pdf):
-        hits = search_text(nested_toc_pdf, query="Kubernetes")
+    def test_search_nested_toc_pdf(self, nested_toc_pdf, call_tool):
+        hits = call_tool("search_text", filename=nested_toc_pdf, query="Kubernetes")
         assert len(hits) >= 1