docpull 2.5.0__tar.gz → 2.5.1__tar.gz

{docpull-2.5.0/src/docpull.egg-info → docpull-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docpull
-Version: 2.5.0
+Version: 2.5.1
 Summary: Pull documentation from the web and convert to clean markdown
 Author-email: Zachary Roth <support@raintree.technology>
 Maintainer-email: Raintree Technology <support@raintree.technology>
@@ -222,7 +222,7 @@ pip install 'docpull[mcp]'
 docpull mcp  # starts the stdio server
 ```
 
-Add to Claude Desktop or Claude Code:
+Add to Claude Desktop or Claude Code manually:
 
 ```json
 {
@@ -235,13 +235,39 @@ Add to Claude Desktop or Claude Code:
 }
 ```
 
-Tools exposed:
+Or, if you use Claude Code, install the plugin instead — it bundles the MCP
+server, five slash commands (`/docs-add`, `/docs-search`, `/docs-list`,
+`/docs-refresh`, `/docs-remove`), and a meta-skill that teaches Claude
+when to reach for docpull automatically:
 
-- `fetch_url(url, max_tokens?)` — one-shot fetch, no crawl
-- `ensure_docs(source, force?)` — fetch a named library (cached 7 days)
+```bash
+# 1. Install docpull with the MCP extra (required for the plugin)
+pip install 'docpull[mcp]'
+```
+
+```
+# 2. Then in Claude Code:
+/plugin marketplace add raintree-technology/docpull
+/plugin install docpull@docpull
+```
+
+See [plugin/README.md](plugin/README.md) for details.
+
+Tools exposed (8 total — read tools advertise `readOnlyHint` so hosts that auto-approve safe tools won't prompt):
+
+Read:
+- `fetch_url(url, max_tokens?)` — one-shot fetch, no crawl. HTTPS-only, SSRF-validated.
 - `list_sources(category?)` — show available aliases (react, nextjs, fastapi, …)
-- `list_indexed()` — what has been fetched locally
-- `grep_docs(pattern, library?)` — regex search across fetched Markdown
+- `list_indexed()` — what has been fetched locally, with last-fetched age
+- `grep_docs(pattern, library?, limit?, context?)` — regex search across fetched Markdown (length-capped + wall-clock budgeted to mitigate ReDoS)
+- `read_doc(library, path, line_start?, line_end?)` — read a specific cached file, optionally line-sliced
+
+Write:
+- `ensure_docs(source, force?, profile?)` — fetch a named library (cached 7 days). Forwards progress to clients that supply a `progressToken`.
+- `add_source(name, url, description?, category?, max_pages?, force?)` — register a user alias (HTTPS-only, atomic write to `sources.yaml`).
+- `remove_source(name, delete_cache?)` — drop a user alias and (optionally) its cached docs.
+
+All tools that carry data also return `structuredContent` validated against an `outputSchema` for clients that prefer typed output.
 
 User-defined sources live in `~/.config/docpull-mcp/sources.yaml`:
 

{docpull-2.5.0 → docpull-2.5.1}/README.md

@@ -140,7 +140,7 @@ pip install 'docpull[mcp]'
 docpull mcp  # starts the stdio server
 ```
 
-Add to Claude Desktop or Claude Code:
+Add to Claude Desktop or Claude Code manually:
 
 ```json
 {
@@ -153,13 +153,39 @@ Add to Claude Desktop or Claude Code:
 }
 ```
 
-Tools exposed:
+Or, if you use Claude Code, install the plugin instead — it bundles the MCP
+server, five slash commands (`/docs-add`, `/docs-search`, `/docs-list`,
+`/docs-refresh`, `/docs-remove`), and a meta-skill that teaches Claude
+when to reach for docpull automatically:
 
-- `fetch_url(url, max_tokens?)` — one-shot fetch, no crawl
-- `ensure_docs(source, force?)` — fetch a named library (cached 7 days)
+```bash
+# 1. Install docpull with the MCP extra (required for the plugin)
+pip install 'docpull[mcp]'
+```
+
+```
+# 2. Then in Claude Code:
+/plugin marketplace add raintree-technology/docpull
+/plugin install docpull@docpull
+```
+
+See [plugin/README.md](plugin/README.md) for details.
+
+Tools exposed (8 total — read tools advertise `readOnlyHint` so hosts that auto-approve safe tools won't prompt):
+
+Read:
+- `fetch_url(url, max_tokens?)` — one-shot fetch, no crawl. HTTPS-only, SSRF-validated.
 - `list_sources(category?)` — show available aliases (react, nextjs, fastapi, …)
-- `list_indexed()` — what has been fetched locally
-- `grep_docs(pattern, library?)` — regex search across fetched Markdown
+- `list_indexed()` — what has been fetched locally, with last-fetched age
+- `grep_docs(pattern, library?, limit?, context?)` — regex search across fetched Markdown (length-capped + wall-clock budgeted to mitigate ReDoS)
+- `read_doc(library, path, line_start?, line_end?)` — read a specific cached file, optionally line-sliced
+
+Write:
+- `ensure_docs(source, force?, profile?)` — fetch a named library (cached 7 days). Forwards progress to clients that supply a `progressToken`.
+- `add_source(name, url, description?, category?, max_pages?, force?)` — register a user alias (HTTPS-only, atomic write to `sources.yaml`).
+- `remove_source(name, delete_cache?)` — drop a user alias and (optionally) its cached docs.
+
+All tools that carry data also return `structuredContent` validated against an `outputSchema` for clients that prefer typed output.
 
 User-defined sources live in `~/.config/docpull-mcp/sources.yaml`:
 

{docpull-2.5.0 → docpull-2.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docpull"
-version = "2.5.0"
+version = "2.5.1"
 dynamic = []
 description = "Pull documentation from the web and convert to clean markdown"
 readme = {file = "README.md", content-type = "text/markdown"}

{docpull-2.5.0 → docpull-2.5.1}/src/docpull/__init__.py

@@ -14,7 +14,7 @@ Usage:
             print(event)
 """
 
-__version__ = "2.5.0"
+__version__ = "2.5.1"
 
 from .cache import CacheManager, StreamingDeduplicator
 from .conversion.chunking import Chunk, TokenCounter, chunk_markdown

{docpull-2.5.0 → docpull-2.5.1}/src/docpull/mcp/server.py

@@ -103,7 +103,11 @@ _GREP_DOCS_OUTPUT_SCHEMA = {
             "items": {
                 "type": "object",
                 "properties": {
-                    "path": {"type": "string"},
+                    "library": {"type": "string"},
+                    "path": {
+                        "type": "string",
+                        "description": "Relative to the library root; pass directly to read_doc",
+                    },
                     "match_count": {"type": "integer"},
                     "matches": {
                         "type": "array",
@@ -119,7 +123,7 @@ _GREP_DOCS_OUTPUT_SCHEMA = {
                         },
                     },
                 },
-                "required": ["path", "match_count", "matches"],
+                "required": ["library", "path", "match_count", "matches"],
             },
         },
         "truncated": {"type": "boolean"},
@@ -333,8 +337,9 @@ async def _run_stdio() -> int:
                 description=(
                     "Regex search through fetched Markdown. Results are ranked by "
                     "match density (most matches per file first) and rendered with "
-                    "lines of surrounding context. Use ensure_docs first; then "
-                    "read_doc to pull more context around a hit."
+                    "lines of surrounding context. Each result returns the library "
+                    "and a path relative to the library root, so you can feed both "
+                    "fields straight into read_doc. Use ensure_docs first."
                 ),
                 annotations=ToolAnnotations(
                     title="Regex-search cached docs",
@@ -370,8 +375,9 @@ async def _run_stdio() -> int:
                 name="read_doc",
                 description=(
                     "Read a Markdown file from a fetched library, optionally sliced "
-                    "by line range. The natural follow-up to grep_docs: pass the "
-                    "library + path it returned to pull more surrounding context."
+                    "by line range. The natural follow-up to grep_docs: pass each "
+                    "result's library and path (path is already relative to the "
+                    "library root) to pull more surrounding context."
                 ),
                 annotations=ToolAnnotations(
                     title="Read a cached doc file",

{docpull-2.5.0 → docpull-2.5.1}/src/docpull/mcp/tools.py

@@ -392,9 +392,14 @@ class _FileHits:
 
     Each match is ``(lineno, before_lines, hit_line, after_lines)`` where
     ``before_lines`` / ``after_lines`` are 0..context lines of context.
+
+    ``library`` and ``path`` are split so that ``path`` is relative to the
+    library root and can be passed straight into ``read_doc`` alongside
+    ``library``. Human-readable rendering still uses ``library/path``.
     """
 
-    rel_path: str
+    library: str
+    path: str
     matches: list[tuple[int, list[str], str, list[str]]]
 
 
@@ -483,7 +488,8 @@ def grep_docs(
             if matches:
                 file_hits.append(
                     _FileHits(
-                        rel_path=str(file.relative_to(docs_dir)),
+                        library=root.name,
+                        path=str(file.relative_to(root)),
                         matches=matches,
                     )
                 )
@@ -505,7 +511,7 @@ def grep_docs(
         )
 
     # Rank by raw count; tie-break alphabetically so output is stable.
-    file_hits.sort(key=lambda fh: (-len(fh.matches), fh.rel_path))
+    file_hits.sort(key=lambda fh: (-len(fh.matches), fh.library, fh.path))
 
     blocks: list[str] = []
     files_payload: list[dict[str, Any]] = []
@@ -513,7 +519,8 @@ def grep_docs(
     for fh in file_hits:
         if rendered >= limit:
             break
-        block_lines = [f"## {fh.rel_path} ({len(fh.matches)} matches)"]
+        qualified = f"{fh.library}/{fh.path}"
+        block_lines = [f"## {qualified} ({len(fh.matches)} matches)"]
         rendered_matches: list[dict[str, Any]] = []
         for lineno, before, hit, after in fh.matches:
             if rendered >= limit:
@@ -532,7 +539,8 @@ def grep_docs(
         blocks.append("\n\n".join(block_lines))
         files_payload.append(
             {
-                "path": fh.rel_path,
+                "library": fh.library,
+                "path": fh.path,
                 "match_count": len(fh.matches),
                 "matches": rendered_matches,
             }
@@ -568,10 +576,11 @@ def read_doc(
 ) -> ToolResult:
     """Read a Markdown file from a fetched library, optionally line-sliced.
 
-    The natural follow-up to ``grep_docs``: once you have ``library/path.md``
-    and a line number, ``read_doc(library, path, line_start=N-20, line_end=N+20)``
-    pulls the surrounding context without filesystem access. Path is validated
-    against ``docs_dir / library`` to block traversal.
+    The natural follow-up to ``grep_docs``: each grep result returns
+    ``library`` and ``path`` (path relative to the library root), so
+    ``read_doc(library=..., path=..., line_start=N-20, line_end=N+20)``
+    pulls the surrounding context. Path is validated against
+    ``docs_dir / library`` to block traversal.
     """
     docs_dir = docs_dir or default_docs_dir()
     if not is_safe_library_name(library):

{docpull-2.5.0 → docpull-2.5.1/src/docpull.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docpull
-Version: 2.5.0
+Version: 2.5.1
 Summary: Pull documentation from the web and convert to clean markdown
 Author-email: Zachary Roth <support@raintree.technology>
 Maintainer-email: Raintree Technology <support@raintree.technology>
@@ -222,7 +222,7 @@ pip install 'docpull[mcp]'
 docpull mcp  # starts the stdio server
 ```
 
-Add to Claude Desktop or Claude Code:
+Add to Claude Desktop or Claude Code manually:
 
 ```json
 {
@@ -235,13 +235,39 @@ Add to Claude Desktop or Claude Code:
 }
 ```
 
-Tools exposed:
+Or, if you use Claude Code, install the plugin instead — it bundles the MCP
+server, five slash commands (`/docs-add`, `/docs-search`, `/docs-list`,
+`/docs-refresh`, `/docs-remove`), and a meta-skill that teaches Claude
+when to reach for docpull automatically:
 
-- `fetch_url(url, max_tokens?)` — one-shot fetch, no crawl
-- `ensure_docs(source, force?)` — fetch a named library (cached 7 days)
+```bash
+# 1. Install docpull with the MCP extra (required for the plugin)
+pip install 'docpull[mcp]'
+```
+
+```
+# 2. Then in Claude Code:
+/plugin marketplace add raintree-technology/docpull
+/plugin install docpull@docpull
+```
+
+See [plugin/README.md](plugin/README.md) for details.
+
+Tools exposed (8 total — read tools advertise `readOnlyHint` so hosts that auto-approve safe tools won't prompt):
+
+Read:
+- `fetch_url(url, max_tokens?)` — one-shot fetch, no crawl. HTTPS-only, SSRF-validated.
 - `list_sources(category?)` — show available aliases (react, nextjs, fastapi, …)
-- `list_indexed()` — what has been fetched locally
-- `grep_docs(pattern, library?)` — regex search across fetched Markdown
+- `list_indexed()` — what has been fetched locally, with last-fetched age
+- `grep_docs(pattern, library?, limit?, context?)` — regex search across fetched Markdown (length-capped + wall-clock budgeted to mitigate ReDoS)
+- `read_doc(library, path, line_start?, line_end?)` — read a specific cached file, optionally line-sliced
+
+Write:
+- `ensure_docs(source, force?, profile?)` — fetch a named library (cached 7 days). Forwards progress to clients that supply a `progressToken`.
+- `add_source(name, url, description?, category?, max_pages?, force?)` — register a user alias (HTTPS-only, atomic write to `sources.yaml`).
+- `remove_source(name, delete_cache?)` — drop a user alias and (optionally) its cached docs.
+
+All tools that carry data also return `structuredContent` validated against an `outputSchema` for clients that prefer typed output.
 
 User-defined sources live in `~/.config/docpull-mcp/sources.yaml`:
 

{docpull-2.5.0 → docpull-2.5.1}/tests/test_mcp_tools.py

@@ -576,11 +576,73 @@ def test_grep_docs_structured_payload(tmp_path):
     assert result.data["truncated"] is False
     assert result.data["timed_out"] is False
     files = result.data["files"]
-    assert files[0]["path"].endswith("a.md")
+    # path is library-relative (no library prefix), library is its own field
+    assert files[0]["library"] == "lib"
+    assert files[0]["path"] == "a.md"
     assert files[0]["matches"][0]["lineno"] == 2
     assert files[0]["matches"][0]["line"] == "TARGET"
 
 
+def test_grep_docs_path_is_library_relative_in_subdir(tmp_path):
+    """Files nested inside a library should still report library-relative path."""
+    lib = tmp_path / "hono"
+    (lib / "middleware").mkdir(parents=True)
+    (lib / "middleware" / "basic-auth.md").write_text("alpha\nbasicAuth\nbravo")
+    result = grep_docs("basicAuth", docs_dir=tmp_path)
+    files = result.data["files"]
+    assert files[0]["library"] == "hono"
+    assert files[0]["path"] == "middleware/basic-auth.md"
+
+
+def test_grep_to_read_doc_roundtrip(tmp_path):
+    """Regression: grep_docs results must be directly usable as read_doc inputs.
+
+    The contract (per the read_doc tool description) is that an agent can
+    pass each grep result's `library` and `path` straight into read_doc.
+    Prior to this fix grep returned `<library>/<path>` and read_doc
+    re-prepended the library, producing a doubled prefix.
+    """
+    lib = tmp_path / "hono"
+    (lib / "middleware").mkdir(parents=True)
+    (lib / "middleware" / "basic-auth.md").write_text(
+        "intro\nbasicAuth example\nmore text\nfinal line"
+    )
+    grep_result = grep_docs("basicAuth", docs_dir=tmp_path)
+    file_hit = grep_result.data["files"][0]
+
+    # Pass library + path verbatim — no manual munging.
+    read_result = read_doc(
+        file_hit["library"], file_hit["path"], docs_dir=tmp_path
+    )
+    assert read_result.is_error is False, read_result.text
+    assert "basicAuth example" in read_result.data["text"]
+
+
+def test_grep_to_read_doc_roundtrip_with_line_slice(tmp_path):
+    """Roundtrip should also work with line-range slicing around the hit."""
+    lib = tmp_path / "react"
+    lib.mkdir()
+    body = "\n".join(f"line{i}" for i in range(1, 21))  # line1..line20
+    body = body.replace("line10", "needle here")
+    (lib / "hooks.md").write_text(body)
+
+    grep_result = grep_docs("needle", docs_dir=tmp_path)
+    hit = grep_result.data["files"][0]
+    match = hit["matches"][0]
+
+    read_result = read_doc(
+        hit["library"],
+        hit["path"],
+        docs_dir=tmp_path,
+        line_start=match["lineno"] - 2,
+        line_end=match["lineno"] + 2,
+    )
+    assert read_result.is_error is False
+    assert "needle here" in read_result.data["text"]
+    assert read_result.data["line_start"] == 8
+    assert read_result.data["line_end"] == 12
+
+
 def test_grep_docs_no_matches_structured_payload(tmp_path):
     lib = tmp_path / "lib"
     lib.mkdir()