Merge pull request #104 from ZimoLiao/review/v1.5.0-release-readiness

Prepare v1.5.0 release readiness

Author: ZimoLiao

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-05-24
+
 ### Added
 
 - **Line-addressable evidence chunk search** ([#35](https://github.com/ZimoLiao/scholaraio/issues/35)): Added `scholaraio index --chunks` and `scholaraio search --chunk` so agents can build a paper-section chunk index from `paper.md` / `meta.json["toc"]` and retrieve source snippets with paper IDs, section titles, line ranges, and normal search filters such as `--year`, `--journal`, and `--type`.

CITATION.cff

@@ -5,8 +5,8 @@ abstract: "Scholar All-In-One — A research infrastructure for AI agents"
 type: software
 license: MIT
 repository-code: "https://github.com/zimoliao/scholaraio"
-version: 1.4.0
-date-released: "2026-04-27"
+version: 1.5.0
+date-released: "2026-05-24"
 authors:
   - family-names: Liao
     given-names: Zimo

config.yaml

@@ -71,6 +71,21 @@ ingest:
   pdf_fallback_order: [auto] # 完全自定义降级链；可写 [pymupdf] 或 [docling,pymupdf]，auto=自动检测本机可用解析器
   pdf_fallback_auto_detect: true # 是否启用自动检测（建议开启）
 
+# Optional web tools 外部实时网页工具
+# Prefer MCP endpoints for agent workflows. API keys, if used, should live in config.local.yaml.
+# Agent 工作流优先走 MCP endpoint；如启用认证，key 放 config.local.yaml。
+websearch:
+  transport: mcp
+  mcp_url: http://127.0.0.1:8765/mcp
+  api_key: null # optional bearer token -> config.local.yaml or env WEBSEARCH_API_KEY
+  mcp_tool: search_bing
+
+webextract:
+  transport: mcp
+  mcp_url: http://127.0.0.1:8766/mcp
+  api_key: null # optional bearer token -> config.local.yaml or env WEBEXTRACT_API_KEY
+  mcp_tool: fetch_url
+
 # Paper2Any external extension Paper2Any 外部增强组件
 # ScholarAIO talks to a lightweight MCP sidecar. The upstream OpenDCAI/Paper2Any
 # checkout stays outside tracked source, by default under data/runtime/extensions/paper2any/Paper2Any.

docs/getting-started/agent-setup.md

@@ -26,7 +26,7 @@ pip install -e ".[full]"
 scholaraio setup
 ```
 
-`scholaraio setup check` is the companion diagnostic command. It reports both the core setup state and optional advanced items such as Semantic Scholar / Zotero API keys. Current setup guidance prefers MinerU first whenever a MinerU path is available.
+`scholaraio setup check` is the companion diagnostic command. It reports both the core setup state and optional advanced items such as Semantic Scholar / Zotero API keys, websearch/webextract endpoints, and Paper2Any sidecar readiness. Current setup guidance prefers MinerU first whenever a MinerU path is available.
 
 Then start your agent in the repository root:
 

docs/getting-started/installation.md

@@ -66,7 +66,7 @@ scholaraio setup check
 `setup check` is the most complete initial diagnostic surface. It covers:
 
 - core setup items: dependency groups, `config.yaml`, LLM key, MinerU / Docling availability, parser recommendation, Graphviz `dot`, Inkscape, `contact_email`, and directory state
-- optional advanced items: Semantic Scholar API key and Zotero API key
+- optional advanced items: Semantic Scholar API key, Zotero API key, external websearch/webextract services, and Paper2Any sidecar readiness
 
 Current setup guidance prefers **MinerU first** whenever a MinerU path is available (local service or `mineru-open-api` + token). `Docling` and then PyMuPDF remain the fallback chain when MinerU is not usable or when the user explicitly prefers a lighter parser path.
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scholaraio"
-version = "1.4.0"
+version = "1.5.0"
 description = "Scholar All-In-One — A research infrastructure for AI agents"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.10"

scholaraio/__init__.py

@@ -1,3 +1,3 @@
 """ScholarAIO — A research infrastructure for AI agents."""
 
-__version__ = "1.4.0"
+__version__ = "1.5.0"

scholaraio/providers/mineru.py

@@ -240,10 +240,18 @@ def check_server(api_url: str = DEFAULT_API_URL) -> bool:
     Returns:
         可达返回 ``True``，不可达返回 ``False``。
     """
+    base_url = api_url.rstrip("/")
     try:
-        resp = requests.get(f"{api_url}/docs", timeout=5)
-        return resp.status_code == 200
-    except requests.ConnectionError:
+        resp = requests.get(f"{base_url}/openapi.json", timeout=5)
+        if resp.status_code != 200:
+            return False
+        try:
+            data = resp.json()
+        except ValueError:
+            return False
+        paths = data.get("paths", {}) if isinstance(data, dict) else {}
+        return isinstance(paths, dict) and PARSE_ENDPOINT in paths
+    except requests.RequestException:
         return False
 
 

scholaraio/providers/paper2any.py

@@ -50,14 +50,15 @@ def call_paper2any_tool(
 
 def _client(*, cfg: object | None, timeout: int) -> StreamableHttpMcpClient:
     return StreamableHttpMcpClient(
-        _paper2any_mcp_url(cfg),
+        resolve_paper2any_mcp_url(cfg),
         api_key=_paper2any_mcp_api_key(cfg),
         client_name="scholaraio-paper2any-client",
         timeout=timeout,
     )
 
 
-def _paper2any_mcp_url(cfg: object | None) -> str:
+def resolve_paper2any_mcp_url(cfg: object | None = None) -> str:
+    """Resolve the Paper2Any MCP endpoint using provider precedence."""
     env_url = os.environ.get("PAPER2ANY_MCP_URL", "").strip()
     if env_url:
         return env_url
@@ -66,6 +67,10 @@ def _paper2any_mcp_url(cfg: object | None) -> str:
     return config_url or DEFAULT_PAPER2ANY_MCP_URL
 
 
+def _paper2any_mcp_url(cfg: object | None) -> str:
+    return resolve_paper2any_mcp_url(cfg)
+
+
 def _paper2any_mcp_api_key(cfg: object | None) -> str:
     env_key = os.environ.get("PAPER2ANY_MCP_API_KEY", "").strip()
     if env_key:

scholaraio/providers/webtools.py

@@ -58,7 +58,7 @@ def _headers(api_key: str) -> dict[str, str]:
     return headers
 
 
-def _load_json_response(req: Request, *, timeout: int, error_prefix: str):
+def _load_json_response(req: Request, *, timeout: float, error_prefix: str):
     try:
         with urlopen(req, timeout=timeout) as response:
             raw = response.read().decode("utf-8")
@@ -83,11 +83,11 @@ def _load_json_response(req: Request, *, timeout: int, error_prefix: str):
 # ---------------------------------------------------------------------------
 
 
-def check_websearch_health(base_url: str | None = None) -> dict:
+def check_websearch_health(base_url: str | None = None, timeout: float = 5.0) -> dict:
     """Check whether the external web search service is healthy."""
     base = _resolve_base_url(base_url, "WEBSEARCH_URL", _DEFAULT_WEBSEARCH_URL)
     req = Request(f"{base}/health", method="GET")
-    return _load_json_response(req, timeout=5, error_prefix="搜索服务健康检查失败")
+    return _load_json_response(req, timeout=timeout, error_prefix="搜索服务健康检查失败")
 
 
 def websearch(
@@ -182,7 +182,7 @@ def check_websearch_service(cfg: Config | None = None, timeout: float = 3.0) ->
             )
             client.list_tools()
         else:
-            check_websearch_health(_get_websearch_base_url(cfg))
+            check_websearch_health(_get_websearch_base_url(cfg), timeout=timeout)
         return True
     except Exception as e:
         _log.debug("Health check failed: %s", e)
@@ -372,11 +372,11 @@ def search_and_fetch_arxiv(
 # ---------------------------------------------------------------------------
 
 
-def check_webextract_health(base_url: str | None = None) -> dict:
+def check_webextract_health(base_url: str | None = None, timeout: float = 5.0) -> dict:
     """Check whether the external web extraction service is healthy."""
     base = _resolve_base_url(base_url, "WEBEXTRACT_URL", _DEFAULT_WEBEXTRACT_URL)
     req = Request(f"{base}/health", method="GET")
-    return _load_json_response(req, timeout=5, error_prefix="提取服务健康检查失败")
+    return _load_json_response(req, timeout=timeout, error_prefix="提取服务健康检查失败")
 
 
 def webextract(url: str, pdf: bool | None = None, base_url: str | None = None) -> dict:
@@ -474,7 +474,7 @@ def check_webextract_service(cfg: Config | None = None, timeout: float = 3.0) ->
             )
             client.list_tools()
         else:
-            check_webextract_health(_get_webextract_base_url(cfg))
+            check_webextract_health(_get_webextract_base_url(cfg), timeout=timeout)
         return True
     except Exception as e:
         _log.debug("Health check failed: %s", e)