litloop 1.18.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. litloop/__init__.py +89 -0
  2. litloop/__main__.py +6 -0
  3. litloop/_source_hygiene.py +158 -0
  4. litloop/agents/__init__.py +13 -0
  5. litloop/agents/client.py +164 -0
  6. litloop/agents/runner.py +123 -0
  7. litloop/agents/system.py +54 -0
  8. litloop/agents/tools.py +142 -0
  9. litloop/app_server.py +8 -0
  10. litloop/browser/__init__.py +1 -0
  11. litloop/browser/backend.py +1009 -0
  12. litloop/browser/camofox_api.py +368 -0
  13. litloop/browser/chrome_copy.py +136 -0
  14. litloop/browser/cloakbrowser_compat.py +72 -0
  15. litloop/browser/cookies.py +347 -0
  16. litloop/browser/engine.py +965 -0
  17. litloop/browser/login.py +636 -0
  18. litloop/browser/pdf.py +263 -0
  19. litloop/browser/profile_health.py +167 -0
  20. litloop/browser/runtime.py +210 -0
  21. litloop/cache.py +104 -0
  22. litloop/citations/__init__.py +1 -0
  23. litloop/citations/bib_import.py +102 -0
  24. litloop/citations/bibtex_crossref.py +143 -0
  25. litloop/citations/formats.py +225 -0
  26. litloop/citations/paper_list.py +200 -0
  27. litloop/citations/session_export.py +94 -0
  28. litloop/cli/__init__.py +12 -0
  29. litloop/cli/_utils.py +267 -0
  30. litloop/cli/commands.py +1098 -0
  31. litloop/cli/doctor.py +141 -0
  32. litloop/cli/main.py +1173 -0
  33. litloop/cli/web.py +190 -0
  34. litloop/config.py +413 -0
  35. litloop/data/VARCON-LICENSE.txt +62 -0
  36. litloop/data/elements.tsv +119 -0
  37. litloop/data/institutional_identity_policy.json +165 -0
  38. litloop/data/publisher_access_catalog.json +969 -0
  39. litloop/data/publisher_carsi.json +105 -0
  40. litloop/data/spelling_search.tsv.gz +0 -0
  41. litloop/data/spelling_us.tsv.gz +0 -0
  42. litloop/data/webvpn.dat +0 -0
  43. litloop/data/webvpn.json +603 -0
  44. litloop/db.py +1922 -0
  45. litloop/deps.py +128 -0
  46. litloop/desktop/__init__.py +1 -0
  47. litloop/desktop/agent_runner.py +537 -0
  48. litloop/desktop/download_jobs.py +571 -0
  49. litloop/desktop/error_text.py +192 -0
  50. litloop/desktop/server.py +999 -0
  51. litloop/desktop/settings.py +552 -0
  52. litloop/desktop/translate.py +103 -0
  53. litloop/diagnostics.py +126 -0
  54. litloop/download/__init__.py +1 -0
  55. litloop/download/doi_check.py +44 -0
  56. litloop/download/fetcher.py +975 -0
  57. litloop/download/markdown.py +130 -0
  58. litloop/download/pdf.py +454 -0
  59. litloop/download/pipeline.py +1166 -0
  60. litloop/download/progress.py +312 -0
  61. litloop/download/rename.py +211 -0
  62. litloop/extractors/__init__.py +0 -0
  63. litloop/extractors/html_extractor.py +31 -0
  64. litloop/extractors/pdf_extractor.py +151 -0
  65. litloop/extractors/publisher_adapters/__init__.py +0 -0
  66. litloop/extractors/publisher_adapters/acs.py +167 -0
  67. litloop/extractors/publisher_adapters/elsevier.py +178 -0
  68. litloop/extractors/publisher_adapters/generic.py +191 -0
  69. litloop/extractors/publisher_adapters/nature.py +204 -0
  70. litloop/extractors/publisher_adapters/rsc.py +154 -0
  71. litloop/extractors/publisher_adapters/tandfonline.py +154 -0
  72. litloop/extractors/publisher_adapters/wiley.py +160 -0
  73. litloop/http_utils.py +57 -0
  74. litloop/identifiers.py +134 -0
  75. litloop/institutional/__init__.py +1 -0
  76. litloop/institutional/auth.py +576 -0
  77. litloop/institutional/carsi_login.py +569 -0
  78. litloop/institutional/config_adapter.py +63 -0
  79. litloop/institutional/proxy_check.py +98 -0
  80. litloop/institutional/remote_assist.py +274 -0
  81. litloop/institutional/schools.py +102 -0
  82. litloop/institutional/session_heal.py +73 -0
  83. litloop/institutional/session_store.py +105 -0
  84. litloop/log.py +47 -0
  85. litloop/models.py +269 -0
  86. litloop/network.py +417 -0
  87. litloop/optional.py +310 -0
  88. litloop/publishers/__init__.py +1 -0
  89. litloop/publishers/access.py +232 -0
  90. litloop/publishers/pdf_router.py +451 -0
  91. litloop/publishers/profiles.py +899 -0
  92. litloop/publishers/strategies/__init__.py +122 -0
  93. litloop/publishers/strategies/_core.py +2340 -0
  94. litloop/publishers/strategies/_elsevier_api.py +578 -0
  95. litloop/publishers/strategies/acm.py +27 -0
  96. litloop/publishers/strategies/acs.py +42 -0
  97. litloop/publishers/strategies/aip.py +27 -0
  98. litloop/publishers/strategies/aps.py +29 -0
  99. litloop/publishers/strategies/asce.py +28 -0
  100. litloop/publishers/strategies/base.py +108 -0
  101. litloop/publishers/strategies/copernicus.py +24 -0
  102. litloop/publishers/strategies/elsevier.py +66 -0
  103. litloop/publishers/strategies/generic.py +39 -0
  104. litloop/publishers/strategies/ieee.py +28 -0
  105. litloop/publishers/strategies/iop.py +27 -0
  106. litloop/publishers/strategies/nature.py +27 -0
  107. litloop/publishers/strategies/oxford.py +27 -0
  108. litloop/publishers/strategies/registry.py +83 -0
  109. litloop/publishers/strategies/royalsociety.py +28 -0
  110. litloop/publishers/strategies/rsc.py +27 -0
  111. litloop/publishers/strategies/sage.py +30 -0
  112. litloop/publishers/strategies/science.py +27 -0
  113. litloop/publishers/strategies/springer.py +34 -0
  114. litloop/publishers/strategies/tandfonline.py +32 -0
  115. litloop/publishers/strategies/wiley.py +32 -0
  116. litloop/publishers/supplementary.py +219 -0
  117. litloop/quota.py +202 -0
  118. litloop/search/__init__.py +1 -0
  119. litloop/search/abstracts.py +291 -0
  120. litloop/search/deep.py +1216 -0
  121. litloop/search/quick.py +1102 -0
  122. litloop/search/scansci_find.py +410 -0
  123. litloop/search/screening.py +225 -0
  124. litloop/search/title_to_doi.py +163 -0
  125. litloop/search/watches.py +124 -0
  126. litloop/server.py +1731 -0
  127. litloop/sources/__init__.py +1339 -0
  128. litloop/sources/_batch.py +529 -0
  129. litloop/sources/_index.py +221 -0
  130. litloop/sources/_routes.py +290 -0
  131. litloop/sources/altcha.py +90 -0
  132. litloop/sources/arxiv.py +45 -0
  133. litloop/sources/attempt.py +91 -0
  134. litloop/sources/carsi.py +74 -0
  135. litloop/sources/core_api.py +46 -0
  136. litloop/sources/crossref.py +162 -0
  137. litloop/sources/elsevier_api.py +620 -0
  138. litloop/sources/elsevier_check.py +274 -0
  139. litloop/sources/europepmc.py +81 -0
  140. litloop/sources/ezproxy.py +317 -0
  141. litloop/sources/instsci.py +1295 -0
  142. litloop/sources/libgen.py +116 -0
  143. litloop/sources/nature.py +39 -0
  144. litloop/sources/oa_discovery.py +135 -0
  145. litloop/sources/openaire.py +122 -0
  146. litloop/sources/openalex.py +100 -0
  147. litloop/sources/publishers.py +684 -0
  148. litloop/sources/sage_cn.py +139 -0
  149. litloop/sources/scibban.py +10 -0
  150. litloop/sources/scihub.py +1379 -0
  151. litloop/sources/scihub_domains.py +203 -0
  152. litloop/sources/scihub_speed.py +187 -0
  153. litloop/sources/scoring.py +250 -0
  154. litloop/sources/semantic_scholar.py +146 -0
  155. litloop/sources/springer_tdm.py +172 -0
  156. litloop/sources/unpaywall.py +116 -0
  157. litloop/sources/vpnsci.py +38 -0
  158. litloop/store.py +264 -0
  159. litloop/templates/index.html +347 -0
  160. litloop/terms/__init__.py +1 -0
  161. litloop/terms/glossary.py +422 -0
  162. litloop/terms/spelling.py +89 -0
  163. litloop/terms/text.py +106 -0
  164. litloop/tor/__init__.py +1 -0
  165. litloop/tor/embedded.py +371 -0
  166. litloop/tor/proxy.py +110 -0
  167. litloop/updates.py +148 -0
  168. litloop/zotero/__init__.py +1 -0
  169. litloop/zotero/bridge.py +309 -0
  170. litloop/zotero/client.py +317 -0
  171. litloop-1.18.3.dist-info/METADATA +347 -0
  172. litloop-1.18.3.dist-info/RECORD +176 -0
  173. litloop-1.18.3.dist-info/WHEEL +5 -0
  174. litloop-1.18.3.dist-info/entry_points.txt +2 -0
  175. litloop-1.18.3.dist-info/licenses/LICENSE +197 -0
  176. litloop-1.18.3.dist-info/top_level.txt +1 -0
litloop/server.py ADDED
@@ -0,0 +1,1731 @@
1
+ """MCP server with tools for paper fetching."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import time
7
+ from pathlib import Path
8
+ from typing import Any
9
+
10
+ try:
11
+ from mcp.server.fastmcp import FastMCP # mcp 1.x
12
+ except ModuleNotFoundError: # mcp >= 2.0 renamed FastMCP to MCPServer
13
+ from mcp.server.mcpserver import MCPServer as FastMCP
14
+
15
+ from .cache import cache_clear, cache_get
16
+ from .config import get_config_safe, load_config, mask_config_value, update_config
17
+ from .network import fetch_json
18
+ from .citations.paper_list import parse_paper_list
19
+ from .search.title_to_doi import batch_resolve
20
+ from .search.quick import search_papers_v2 as search_papers
21
+ from .sources import batch_download, download
22
+ from .tor.proxy import check_tor_circuit, get_tor_proxy
23
+
24
+ mcp_app = FastMCP(
25
+ name="litloop",
26
+ instructions=(
27
+ "Academic paper downloader with 20+ sources, multi-university WebVPN, Tor, and Sci-Hub support. "
28
+ "Supports DOI, arXiv ID, keyword search, and resumable batch downloads. "
29
+ "Elsevier/ScienceDirect needs NO insttoken: an API key plus campus/institutional network egress is enough; "
30
+ "NOT_ENTITLED means off-campus network or the journal is not subscribed."
31
+ ),
32
+ )
33
+
34
+
35
+ @mcp_app.tool()
36
+ def litloop_download(
37
+ identifier: str,
38
+ output_dir: str | None = None,
39
+ scihub_enabled: bool | None = None,
40
+ use_tor: bool = False,
41
+ use_vpnsci: bool = False,
42
+ bibtex: bool = False,
43
+ strategy: str | None = None,
44
+ download_si: bool = False,
45
+ markdown: bool = False,
46
+ ) -> str:
47
+ """Download one paper by DOI/arXiv ID (13+ source racing; strategy override; download_si and markdown optional — PDF stays the default deliverable)."""
48
+ result = download(identifier, output_dir, scihub_enabled=scihub_enabled, use_tor=use_tor, use_vpnsci=use_vpnsci, bibtex=bibtex, strategy=strategy)
49
+
50
+ # Add actionable hints for agents when download fails
51
+ if not result.get("success"):
52
+ error_type = result.get("error_type", "")
53
+ action = result.get("action", "")
54
+ doi = result.get("doi", result.get("identifier", ""))
55
+ if error_type == "paywall" or action == "login_required":
56
+ result["agent_hint"] = (
57
+ f"此论文需要机构登录才能下载。请运行 litloop_login(identifier=\"{doi}\") "
58
+ "打开浏览器让用户登录机构账号,登录后关闭浏览器,然后重试下载。"
59
+ )
60
+ elif error_type == "cloudflare_blocked":
61
+ result["agent_hint"] = (
62
+ "Cloudflare 防护阻止访问。请提示用户启动 CloakBrowser(端口 9377),"
63
+ "或配置代理后重试。"
64
+ )
65
+ # Elsevier papers: API fast-path guidance
66
+ if doi.startswith("10.1016/"):
67
+ config = load_config()
68
+ result.setdefault("hint", {})
69
+ if isinstance(result.get("hint"), str):
70
+ result["hint"] = {"message": result["hint"]}
71
+ if not config.get("elsevier_api_key"):
72
+ result["hint"]["elsevier_setup"] = (
73
+ "Elsevier 论文可通过 API Key 直接下载(1-2秒),免费申请。"
74
+ "请运行 litloop_elsevier_setup 获取配置指引。"
75
+ )
76
+ else:
77
+ from .network import configured_proxy as _configured_proxy
78
+
79
+ if _configured_proxy(config):
80
+ result["hint"]["elsevier_note"] = (
81
+ "Elsevier API 已配置但本次下载失败。已走配置出口:若自检/日志出现 403 "
82
+ "'Requestor configuration settings insufficient',多为机构未给该 key 开 "
83
+ "API 全文权限(联系机构 Elsevier 管理员;insttoken 仅在拿不到校园出口时才需要),"
84
+ "或该代理出口不在机构注册 IP 段。先运行 litloop elsevier-check --doi <DOI> 复核,"
85
+ "再转灰色源/机构浏览器渠道。"
86
+ )
87
+ else:
88
+ result["hint"]["elsevier_note"] = (
89
+ "Elsevier API 已配置但本次下载失败:多为未连接校园网/机构网络出口(NOT_ENTITLED;"
90
+ "403 'Requestor configuration settings insufficient' 即出口 IP 不在机构注册段)。"
91
+ "API key + 校园网出口即可,insttoken 仅在拿不到校园出口时才需要。"
92
+ "若靠代理连校园网:HTTP_PROXY/HTTPS_PROXY 环境变量会被忽略(trust_env=False),"
93
+ "请改用 config_set network_proxy \"代理地址\" 或设 LITLOOP_PROXY 后重试;"
94
+ "也可连接校园网后重试,或改走灰色源/机构浏览器渠道。"
95
+ )
96
+
97
+ if result.get("success") and download_si:
98
+ try:
99
+ from pathlib import Path as _P
100
+
101
+ from .publishers.supplementary import fetch_supplementary
102
+
103
+ out_dir = str(_P(result["file"]).parent) if result.get("file") else (output_dir or "")
104
+ if out_dir:
105
+ result["supplementary"] = fetch_supplementary(
106
+ result.get("doi", identifier), out_dir, load_config()
107
+ )
108
+ except Exception as exc:
109
+ result["supplementary_error"] = str(exc)
110
+
111
+ if result.get("success") and markdown:
112
+ try:
113
+ from .download.markdown import pdf_to_markdown_detailed
114
+
115
+ md_out, md_warnings = pdf_to_markdown_detailed(result["file"])
116
+ result["markdown"] = str(md_out)
117
+ if md_warnings:
118
+ result["markdown_warnings"] = md_warnings
119
+ except Exception as exc:
120
+ result["markdown_error"] = str(exc)
121
+
122
+ return json.dumps(result, ensure_ascii=False)
123
+
124
+
125
+ def _batch_download_impl(
126
+ identifiers: list[str],
127
+ output_dir: str | None = None,
128
+ scihub_enabled: bool | None = None,
129
+ use_tor: bool = False,
130
+ use_vpnsci: bool = False,
131
+ batch_id: str | None = None,
132
+ resume: bool = True,
133
+ lanes: bool | None = None,
134
+ ctx: Any = None,
135
+ keep_attempts: bool = False,
136
+ rounds: str = "all",
137
+ ) -> str:
138
+ """Download multiple papers by DOI or arXiv ID.
139
+
140
+ Args:
141
+ identifiers: List of DOIs or arXiv IDs (queue-contract lines
142
+ "identifier<TAB>channel<TAB>oa_url" are honored too)
143
+ output_dir: Override default output directory
144
+ scihub_enabled: Enable/disable Sci-Hub
145
+ use_tor: Route Sci-Hub/LibGen through Tor
146
+ use_vpnsci: Try WebVPN institutional proxy as last resort (requires prior login via litloop_login(kind='webvpn'))
147
+ batch_id: Unique ID for this batch (auto-generated if omitted). Used for resume support.
148
+ resume: Skip items completed in a previous run (default true). Set false to re-download all.
149
+ lanes: Channel-lane scheduling (default on for >=3 items): S2-batch
150
+ pretriage -> fast HTTP lane (OA/Elsevier/MDPI CDN) -> grey racing
151
+ -> institutional cascade. Lane mode ignores batch_id/resume (the
152
+ grey lane keeps its own resume). Set false for per-item racing.
153
+ keep_attempts: keep each paper's ``attempts`` (the app's download jobs
154
+ show them); the MCP tool leaves them out to keep its answer small.
155
+ rounds: "free" or "single" run that part of the short-list rounds
156
+ whatever the list's length (``pipeline.run_scihub_then_single``;
157
+ the app's long lists and their publisher queues).
158
+ """
159
+ from .log import get_logger
160
+ _log = get_logger()
161
+
162
+ def _progress_report(current: int, total: int, identifier: str, result: dict[str, Any]) -> None:
163
+ ok = result.get("success", False)
164
+ src = result.get("source", "?")
165
+ status = "OK" if ok else "FAIL"
166
+ _log.info(f" [{current}/{total}] {status} {src} {identifier}")
167
+ if ctx and hasattr(ctx, "report_progress"):
168
+ try:
169
+ ctx.report_progress(current, total)
170
+ except Exception:
171
+ pass
172
+
173
+ cfg = load_config()
174
+ use_lanes = (
175
+ (lanes if lanes is not None else bool(cfg.get("batch_default_lanes", True)))
176
+ # Short lists take run_scihub_then_single below (one paper included, so
177
+ # it gets the school's routes too); lanes start above batch_small_max.
178
+ and len(identifiers) >= 1
179
+ # Grey-oriented strategies express a lane-ORDER preference that the
180
+ # fast->grey->institutional schedule would invert — keep racing.
181
+ and cfg.get("download_strategy", "fastest") not in ("scihub_only", "grey_only", "scihub_first")
182
+ )
183
+ if use_lanes:
184
+ from .download.pipeline import grey_allowed, parse_queue, run_lanes
185
+ from .sources import _write_download_results
186
+
187
+ all_entries = parse_queue("\n".join(identifiers))
188
+ entries = [e for e in all_entries if e.identifier and not e.unresolved]
189
+ dropped = [e for e in all_entries if e.unresolved or not e.identifier]
190
+ allow_grey = (scihub_enabled is not False) and grey_allowed(cfg)
191
+ out_dir = output_dir or cfg.get("output_dir") or str(Path.cwd())
192
+ if rounds != "all" or len(entries) <= int(cfg.get("batch_small_max", 30) or 0):
193
+ from .download.pipeline import run_scihub_then_single
194
+ _log.info(f"Short list ({len(entries)} items, rounds {rounds}): Sci-Hub for all, then a full single download for each miss")
195
+ raw = run_scihub_then_single(entries, out_dir, config=cfg, allow_grey=allow_grey,
196
+ workers=int(cfg.get("batch_small_workers", 1) or 1), rounds=rounds)
197
+ else:
198
+ _log.info(f"Lane scheduling {len(entries)} items: pretriage -> fast HTTP -> grey -> institutional")
199
+ raw = run_lanes(entries, out_dir, config=cfg, allow_grey=allow_grey)
200
+ raw += [
201
+ {"doi": (e.raw or "")[:80], "success": False,
202
+ "error": "unrecognized identifier (lane mode)"}
203
+ for e in dropped
204
+ ]
205
+ succeeded = sum(1 for r in raw if r.get("success"))
206
+ summary = {
207
+ "total": len(identifiers),
208
+ "unique": len(all_entries),
209
+ "succeeded": succeeded,
210
+ "failed": len(raw) - succeeded,
211
+ "results": raw if keep_attempts else _without_attempts(raw),
212
+ "failed_dois": [r.get("doi") or r.get("identifier", "")
213
+ for r in raw if not r.get("success")],
214
+ "batch_id": batch_id or "lanes",
215
+ "mode": "lanes",
216
+ }
217
+ _write_download_results(raw, out_dir)
218
+ return json.dumps(summary, ensure_ascii=False)
219
+
220
+ result = batch_download(
221
+ identifiers, output_dir,
222
+ scihub_enabled=scihub_enabled, use_tor=use_tor, use_vpnsci=use_vpnsci,
223
+ batch_id=batch_id, resume=resume,
224
+ progress_callback=_progress_report,
225
+ )
226
+
227
+ # Add agent hint if any paywall failures detected
228
+ failed_results = [r for r in result.get("results", []) if not r.get("success")]
229
+ paywall_failures = [r for r in failed_results if r.get("error_type") == "paywall"]
230
+ if paywall_failures:
231
+ dois = [r.get("doi", r.get("identifier", "?")) for r in paywall_failures[:3]]
232
+ result["agent_hint"] = (
233
+ f"{len(paywall_failures)} 篇论文需要机构登录才能下载(如 {', '.join(dois)})。"
234
+ "请运行 litloop_login(identifier=\"第一篇DOI\") 打开浏览器让用户登录,"
235
+ "登录后关闭浏览器,然后重新批量下载。"
236
+ )
237
+
238
+ if isinstance(result.get("results"), list):
239
+ result["results"] = result["results"] if keep_attempts else _without_attempts(result["results"])
240
+ return json.dumps(result, ensure_ascii=False)
241
+
242
+
243
+ def _without_attempts(results: list[dict[str, Any]]) -> list[dict[str, Any]]:
244
+ """A batch's results for the agent, without each paper's ``attempts`` (every way
245
+ tried, with timings: about 20 KB for 30 papers that the agent does not use;
246
+ the app reads them from the job file). Single downloads keep theirs."""
247
+ return [{k: v for k, v in r.items() if k != "attempts"} if isinstance(r, dict) else r for r in results]
248
+
249
+
250
+ @mcp_app.tool()
251
+ def litloop_search(
252
+ query: str = "",
253
+ limit: int = 10,
254
+ year_from: int | None = None,
255
+ year_to: int | None = None,
256
+ sort: str | None = None,
257
+ author: str | None = None,
258
+ author_id: str | None = None,
259
+ out_file: str | None = None,
260
+ max_cas_zone: int | None = None,
261
+ max_cas_sub_zone: int | None = None,
262
+ max_jcr_quartile: int | None = None,
263
+ exclude_warning: bool = False,
264
+ exclude_retracted: bool = False,
265
+ ) -> str:
266
+ """Search papers by English keywords/author; sort=cited|date; journal filters (max_cas_zone / max_cas_sub_zone / max_jcr_quartile) are off unless set. out_file queues."""
267
+ stats: dict = {}
268
+ expansions: list = []
269
+ results = search_papers(
270
+ query,
271
+ limit=min(limit, 50),
272
+ year_from=year_from,
273
+ year_to=year_to,
274
+ sort=sort,
275
+ author=author,
276
+ author_id=author_id,
277
+ max_cas_zone=max_cas_zone,
278
+ max_cas_sub_zone=max_cas_sub_zone,
279
+ max_jcr_quartile=max_jcr_quartile,
280
+ exclude_warning=exclude_warning,
281
+ exclude_retracted=exclude_retracted,
282
+ stats=stats,
283
+ expansions=expansions,
284
+ )
285
+ filtered = {k: v for k, v in stats.items() if v}
286
+ extra = {**({"filtered": filtered} if filtered else {}), **({"glossary": expansions} if expansions else {})}
287
+ if out_file and results:
288
+ from .download.pipeline import QueueEntry, predict_channel, write_queue
289
+
290
+ qe = [
291
+ QueueEntry(
292
+ identifier=r.get("doi") or r.get("arxiv_id") or "",
293
+ channel=predict_channel(r.get("doi") or ""),
294
+ title=str(r.get("title", "")),
295
+ )
296
+ for r in results
297
+ if r.get("doi") or r.get("arxiv_id")
298
+ ]
299
+ path = write_queue(qe, out_file)
300
+ return _with_update_notice(json.dumps(
301
+ {"results": results, "queue_file": str(path), "queued": len(qe),
302
+ **extra},
303
+ ensure_ascii=False,
304
+ ))
305
+ return _with_update_notice(json.dumps({"results": results, **extra}, ensure_ascii=False))
306
+
307
+
308
+ def _with_update_notice(out: str) -> str:
309
+ """Add update_notice (updates.py: a newer LitLoop / easyseek / zotero-mcp) to a tool's JSON result."""
310
+ from . import updates
311
+ try:
312
+ note = updates.notice()
313
+ data = json.loads(out) if note else None
314
+ except Exception: # the reminder must never break a result
315
+ return out
316
+ if not isinstance(data, dict):
317
+ return out
318
+ data["update_notice"] = note
319
+ return json.dumps(data, ensure_ascii=False)
320
+
321
+
322
+ @mcp_app.tool()
323
+ def litloop_screening(
324
+ action: str = "save",
325
+ question: str = "",
326
+ items: list[dict] | None = None,
327
+ criteria: list[str] | None = None,
328
+ query: str = "",
329
+ mode: str = "quick",
330
+ session: str | None = None,
331
+ selected: list[str] | None = None,
332
+ rejected: list[str] | None = None,
333
+ out_file: str | None = None,
334
+ ) -> str:
335
+ """Screening record: save (items: doi,title,relevance 高/中/低/不相关,reason), decide (selected nos/DOIs), translate (items: doi,abstract_zh), list, show."""
336
+ from .search import screening
337
+ try:
338
+ if action == "save":
339
+ return json.dumps(screening.save(question, items or [], criteria=criteria, query=query,
340
+ mode=mode, session=session), ensure_ascii=False)
341
+ if action == "decide":
342
+ if not session:
343
+ return json.dumps({"error": "session is required"})
344
+ return json.dumps(screening.decide(session, selected or [], rejected, out_file),
345
+ ensure_ascii=False)
346
+ if action == "translate":
347
+ if not session:
348
+ return json.dumps({"error": "session is required"})
349
+ return json.dumps(screening.translate(session, items or []), ensure_ascii=False)
350
+ if action == "list":
351
+ return json.dumps({"sessions": screening.list_sessions()}, ensure_ascii=False)
352
+ if action == "show":
353
+ if not session:
354
+ return json.dumps({"error": "session is required"})
355
+ return json.dumps(screening.load(session), ensure_ascii=False)
356
+ return json.dumps({"error": f"unknown action {action!r}; use save|decide|translate|list|show"})
357
+ except (ValueError, FileNotFoundError) as exc:
358
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
359
+
360
+
361
+ def litloop_plan_search(
362
+ query: str,
363
+ domain: str = "general",
364
+ depth: str = "standard",
365
+ ) -> str:
366
+ """Build an auditable search protocol before running a search (ScanSci Find 13-source engine).
367
+
368
+ Args:
369
+ query: Research topic (e.g. "carbon emission reduction China").
370
+ domain: Domain profile: general/medicine/computer_science/chinese_general/...
371
+ depth: quick/standard/systematic.
372
+ """
373
+ from .search.scansci_find import plan
374
+ try:
375
+ return json.dumps(plan(query, domain=domain, depth=depth), ensure_ascii=False)
376
+ except Exception as exc:
377
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
378
+
379
+
380
+ def litloop_estimate_search(
381
+ query: str,
382
+ domain: str = "general",
383
+ depth: str = "standard",
384
+ ) -> str:
385
+ """Estimate result volume (size_band: narrow/workable/broad/revise_query) before a full search.
386
+
387
+ Args:
388
+ query: Research topic.
389
+ domain: Domain profile.
390
+ depth: quick/standard/systematic.
391
+ """
392
+ from .search.scansci_find import estimate
393
+ try:
394
+ return json.dumps(estimate(query, domain=domain, depth=depth), ensure_ascii=False)
395
+ except Exception as exc:
396
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
397
+
398
+
399
+ def litloop_smoke_search(
400
+ query: str,
401
+ domain: str = "general",
402
+ ) -> str:
403
+ """Fetch 4 records per source and validate the candidate contract before the real search."""
404
+ from .search.scansci_find import smoke
405
+ try:
406
+ return json.dumps(smoke(query, domain=domain), ensure_ascii=False)
407
+ except Exception as exc:
408
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
409
+
410
+
411
+ def litloop_calibrate_search(
412
+ query: str,
413
+ domain: str = "general",
414
+ depth: str = "standard",
415
+ sample_size: int = 100,
416
+ ) -> str:
417
+ """Run a bounded calibration sample; reports human_queue_rate and gold-set recall.
418
+
419
+ Args:
420
+ query: Research topic.
421
+ domain: Domain profile.
422
+ depth: quick/standard/systematic.
423
+ sample_size: Records to sample (default 100).
424
+ """
425
+ from .search.scansci_find import calibrate
426
+ try:
427
+ return json.dumps(calibrate(query, domain=domain, depth=depth, sample_size=sample_size),
428
+ ensure_ascii=False)
429
+ except Exception as exc:
430
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
431
+
432
+
433
+ @mcp_app.tool()
434
+ def litloop_deep_search(
435
+ action: str = "start",
436
+ question: str = "",
437
+ queries: list[str] | None = None,
438
+ seeds: list[str] | None = None,
439
+ core_terms: list[str] | None = None,
440
+ seed_collection: str | None = None,
441
+ criteria: list[str] | None = None,
442
+ must_find: list[str] | None = None,
443
+ year_from: int | None = None,
444
+ year_to: int | None = None,
445
+ batch_size: int = 20,
446
+ session: str | None = None,
447
+ ratings: list[dict] | None = None,
448
+ ) -> str:
449
+ """Deep search: start (question, 4-8 queries, seed DOIs and/or a Zotero seed_collection, core_terms), rate (ratings=[{n, relevance, reason}]), next, status."""
450
+ from .search import deep as deep_search
451
+ try:
452
+ if action == "start":
453
+ from_zotero = None
454
+ if seed_collection:
455
+ # The papers the user already keeps on the topic: seeds (and positives).
456
+ from .zotero.client import collection_dois
457
+ got = collection_dois(seed_collection, load_config())
458
+ if not got.get("success"):
459
+ return json.dumps({"error": f"seed_collection: {got.get('error')}"}, ensure_ascii=False)
460
+ seeds = list(dict.fromkeys([*(seeds or []), *got["dois"]]))
461
+ from_zotero = {"path": got["path"], "seeds": len(got["dois"]), "without_doi": got["without_doi"]}
462
+ out = deep_search.start(question, queries or [], seeds or [], core_terms or [],
463
+ criteria=criteria, must_find=must_find, year_from=year_from,
464
+ year_to=year_to, batch_size=max(5, min(batch_size, 60)))
465
+ if from_zotero:
466
+ out["seed_collection"] = from_zotero
467
+ elif action in ("next", "status", "rate"):
468
+ if not session:
469
+ return json.dumps({"error": "session is required"})
470
+ if action == "rate":
471
+ out = deep_search.rate(session, ratings or [])
472
+ else:
473
+ out = deep_search.next_batch(session) if action == "next" else deep_search.status(session)
474
+ else:
475
+ return json.dumps({"error": f"unknown action {action!r}; use start|rate|next|status"})
476
+ return json.dumps(out, ensure_ascii=False)
477
+ except (ValueError, FileNotFoundError, RuntimeError) as exc:
478
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
479
+
480
+
481
+ def litloop_verify_identifiers(candidates_json: str) -> str:
482
+ """Verify DOI/PMID/arXiv identifiers in a candidate list against authoritative APIs.
483
+
484
+ Args:
485
+ candidates_json: JSON array of candidates (as produced by ScanSci Find), or a path to one.
486
+ """
487
+ from .search.scansci_find import DiscoveryTimeoutError, verify
488
+ try:
489
+ return json.dumps(verify(candidates_json), ensure_ascii=False)
490
+ except DiscoveryTimeoutError as exc:
491
+ return json.dumps(_discovery_timeout_payload(exc), ensure_ascii=False)
492
+ except Exception as exc:
493
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
494
+
495
+
496
+ def litloop_resolve_oa(candidates_json: str) -> str:
497
+ """Resolve open-access locations for DOIs in a candidate list via Unpaywall.
498
+
499
+ Args:
500
+ candidates_json: JSON array of candidates (as produced by ScanSci Find), or a path to one.
501
+ """
502
+ from .search.scansci_find import DiscoveryTimeoutError, resolve_oa
503
+ try:
504
+ return json.dumps(resolve_oa(candidates_json), ensure_ascii=False)
505
+ except DiscoveryTimeoutError as exc:
506
+ return json.dumps(_discovery_timeout_payload(exc), ensure_ascii=False)
507
+ except Exception as exc:
508
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
509
+
510
+
511
+ def _discovery_timeout_payload(exc: Any) -> dict[str, Any]:
512
+ """Structured timeout payload so agents can tell dependency timeouts apart
513
+ from 'paper not found' or 'rate limited'."""
514
+ return {
515
+ "error": str(exc),
516
+ "stage": "discovery",
517
+ "provider": "scansci-find",
518
+ "timeout_seconds": getattr(exc, "timeout_seconds", None),
519
+ "retryable": getattr(exc, "retryable", True),
520
+ "fallback_used": False,
521
+ }
522
+
523
+
524
+ def litloop_build_download_queue(
525
+ query: str,
526
+ limit: int = 10,
527
+ depth: str = "quick",
528
+ ) -> str:
529
+ """Search via the 13-source discovery engine and return a ready download identifier queue.
530
+
531
+ Args:
532
+ query: Search topic.
533
+ limit: Max identifiers (default 10).
534
+ depth: quick/standard (default quick).
535
+ """
536
+ import tempfile as _tempfile
537
+ from .search.scansci_find import build_download_queue, search
538
+ try:
539
+ with _tempfile.TemporaryDirectory(prefix="scansci_find_") as tmp:
540
+ payload = search(query, tmp, depth=depth, limit=min(limit * 2, 60))
541
+ identifiers = build_download_queue(tmp)
542
+ return json.dumps({
543
+ "query": query,
544
+ "total_found": payload.get("total", 0),
545
+ "identifiers": identifiers[:limit],
546
+ "hint": "Feed identifiers to litloop_batch_download",
547
+ }, ensure_ascii=False)
548
+ except Exception as exc:
549
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
550
+
551
+
552
+ def litloop_health_check(detailed: bool = False) -> str:
553
+ """Check availability of all download sources with latency and status.
554
+
555
+ Args:
556
+ detailed: If true, include Sci-Hub domain stats from cache
557
+ """
558
+ config = load_config()
559
+ probes = {
560
+ "europepmc": "https://www.ebi.ac.uk/europepmc/webservices/rest/search?query=DOI:10.1038/nature12373&format=json&pageSize=1",
561
+ "unpaywall": f"https://api.unpaywall.org/v2/10.1038/nature12373?email={config.get('email', 'test@example.com')}",
562
+ "core": "https://api.core.ac.uk/v3/search/works?q=doi:%2210.1038/nature12373%22&limit=1",
563
+ "semanticscholar": "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1038/nature12373?fields=openAccessPdf",
564
+ "openalex": "https://api.openalex.org/works/doi:10.1038/nature12373",
565
+ "crossref": "https://api.crossref.org/works/10.1038/nature12373",
566
+ }
567
+ checks: dict[str, Any] = {}
568
+ for name, url in probes.items():
569
+ t0 = time.time()
570
+ try:
571
+ resp = fetch_json(url, config)
572
+ latency = round((time.time() - t0) * 1000)
573
+ if resp:
574
+ checks[name] = {"status": "ok", "latency_ms": latency}
575
+ else:
576
+ checks[name] = {"status": "error", "reason": "no response", "latency_ms": latency}
577
+ except Exception as exc:
578
+ latency = round((time.time() - t0) * 1000)
579
+ checks[name] = {"status": "error", "reason": type(exc).__name__, "latency_ms": latency}
580
+
581
+ # Probe WITH config so tor_proxy / the embedded instance are honored —
582
+ # an env-default 1080 probe used to report "unavailable" while downloads
583
+ # were flowing through a working proxy on another port (#61).
584
+ tor_ok = check_tor_circuit(config)
585
+ checks["tor"] = {"status": "ok" if tor_ok else "unavailable", "proxy": get_tor_proxy(config)}
586
+
587
+ from .browser.engine import is_available as browser_ok
588
+ checks["browser"] = {"status": "ok" if browser_ok(config) else "unavailable"}
589
+
590
+ overall = "ok" if all(c.get("status") == "ok" for c in checks.values()) else "degraded"
591
+
592
+ result: dict[str, Any] = {
593
+ "overall": overall,
594
+ "scihub_enabled": config.get("scihub_enabled", False),
595
+ "checks": checks,
596
+ }
597
+
598
+ if detailed:
599
+ from .sources.scihub_domains import load_stats
600
+ stats = load_stats(config)
601
+ scihub_domains = []
602
+ for domain, s in stats.items():
603
+ if domain.startswith("_"):
604
+ continue
605
+ total = s.get("success", 0) + s.get("fail", 0)
606
+ scihub_domains.append({
607
+ "domain": domain,
608
+ "success": s.get("success", 0),
609
+ "fail": s.get("fail", 0),
610
+ "rate": round(s.get("success", 0) / total * 100, 1) if total > 0 else 0,
611
+ "avg_latency_ms": s.get("avg_latency_ms"),
612
+ "reachable": s.get("reachable"),
613
+ })
614
+ scihub_domains.sort(key=lambda d: d["rate"], reverse=True)
615
+ result["scihub_domains"] = scihub_domains[:10]
616
+
617
+ return json.dumps(result, ensure_ascii=False, indent=2)
618
+
619
+
620
+ def litloop_browser_doctor() -> str:
621
+ """Report reusable shared browser runtime options before suggesting installs."""
622
+ from .browser.runtime import doctor
623
+
624
+ return json.dumps(doctor(), ensure_ascii=False, indent=2)
625
+
626
+
627
+ def litloop_source_scores() -> str:
628
+ """Show adaptive source health scores based on download history.
629
+
630
+ Returns per-source success rate (EMA), latency, and attempts.
631
+ Sources with low scores are deprioritized in download racing.
632
+ """
633
+ from .sources.scoring import get_all_scores
634
+ scores = get_all_scores()
635
+ if not scores:
636
+ return json.dumps({"message": "No download history yet. Scores will build after first downloads."})
637
+ # Sort by score descending
638
+ sorted_scores = sorted(scores.items(), key=lambda x: x[1].get("success_ema", 0), reverse=True)
639
+ result = []
640
+ for source, data in sorted_scores:
641
+ result.append({
642
+ "source": source,
643
+ "success_rate": round(data.get("success_ema", 0) * 100, 1),
644
+ "avg_latency_ms": round(data.get("latency_ema", 0)),
645
+ "attempts": data.get("attempts", 0),
646
+ "last_error": data.get("last_error", ""),
647
+ })
648
+ return json.dumps({"sources": result}, ensure_ascii=False, indent=2)
649
+
650
+
651
+ def litloop_auto_setup() -> str:
652
+ """One-click setup: auto-start Tor, check browser, probe Sci-Hub domains.
653
+
654
+ Run this once before downloading papers. No configuration needed — everything is auto-detected.
655
+ Returns what was set up and what needs manual attention.
656
+ """
657
+ config = load_config()
658
+ report: dict[str, Any] = {"actions": [], "status": {}}
659
+
660
+ # 1. Auto-start Tor
661
+ try:
662
+ from .tor.proxy import ensure_tor, check_tor_circuit
663
+ tor_proxy = ensure_tor(config)
664
+ if tor_proxy:
665
+ report["actions"].append(f"Tor started at {tor_proxy}")
666
+ report["status"]["tor"] = "running"
667
+ else:
668
+ report["actions"].append("Tor could not be started (will retry on download)")
669
+ report["status"]["tor"] = "unavailable"
670
+ except Exception as e:
671
+ report["actions"].append(f"Tor error: {e}")
672
+ report["status"]["tor"] = "error"
673
+
674
+ # 2. Check browser
675
+ try:
676
+ from .browser.engine import is_available
677
+ if is_available(config):
678
+ report["actions"].append("CloakBrowser is running")
679
+ report["status"]["browser"] = "running"
680
+ else:
681
+ report["actions"].append("CloakBrowser not running (optional, for Cloudflare bypass)")
682
+ report["status"]["browser"] = "not_running"
683
+ except Exception:
684
+ report["status"]["browser"] = "unknown"
685
+
686
+ # 3. Probe Sci-Hub domains
687
+ try:
688
+ from .sources.scihub import _probe_scihub_domains
689
+ from .sources.scihub_domains import load_stats
690
+ config_copy = config.copy()
691
+ config_copy["_force_probe"] = True
692
+ # Reset probe timestamp to force re-probe
693
+ from .sources.scihub_domains import set_probe_timestamp
694
+ set_probe_timestamp(config_copy, timestamp=0)
695
+ _probe_scihub_domains(config_copy)
696
+ stats = load_stats(config_copy)
697
+ reachable = [d for d, s in stats.items()
698
+ if not d.startswith("_") and isinstance(s, dict) and s.get("reachable")]
699
+ report["actions"].append(f"Sci-Hub: {len(reachable)} domains reachable")
700
+ report["status"]["scihub_domains"] = reachable[:5]
701
+ except Exception as e:
702
+ report["actions"].append(f"Sci-Hub probe error: {e}")
703
+
704
+ # 4. Check WebVPN/CARSI
705
+ report["status"]["webvpn"] = "configured" if config.get("vpnsci_enabled") else "not_configured"
706
+ report["status"]["carsi"] = "configured" if config.get("carsi_enabled") else "not_configured"
707
+
708
+ # 5. Check Elsevier API key
709
+ if config.get("elsevier_api_key"):
710
+ report["status"]["elsevier_api"] = "configured"
711
+ report["actions"].append("Elsevier API key configured (ScienceDirect fast-track enabled)")
712
+ else:
713
+ report["status"]["elsevier_api"] = "not_configured"
714
+ report["actions"].append(
715
+ "Elsevier API key not set — ScienceDirect downloads will use browser fallback. "
716
+ "Run litloop_elsevier_setup to configure (free, recommended)."
717
+ )
718
+
719
+ report["summary"] = "Ready to download. Use litloop_download with a DOI."
720
+ return json.dumps(report, ensure_ascii=False, indent=2)
721
+
722
+
723
+ @mcp_app.tool()
724
+ def litloop_elsevier_setup(test: bool = False) -> str:
725
+ """Set up the Elsevier API key (opens portal, guides registration, validates). No insttoken — campus egress covers it. Institutional email + campus network at creation, else key never binds (403)."""
726
+ import webbrowser
727
+ config = load_config()
728
+ api_key = config.get("elsevier_api_key", "")
729
+
730
+ result: dict[str, Any] = {}
731
+
732
+ if api_key:
733
+ result["status"] = "configured"
734
+ result["key_preview"] = f"{api_key[:8]}...{api_key[-4:]}"
735
+ result["message"] = "Elsevier API key 已配置。"
736
+
737
+ if test:
738
+ # Validate by hitting the serial title API (lightweight, no PDF download)
739
+ import requests
740
+ from .network import USER_AGENT, configured_proxy
741
+ try:
742
+ s = requests.Session()
743
+ s.trust_env = False
744
+ proxy = configured_proxy(config)
745
+ if proxy:
746
+ s.proxies = {"http": proxy, "https": proxy}
747
+ resp = s.get(
748
+ "https://api.elsevier.com/content/serial/title",
749
+ headers={"Accept": "application/json", "X-ELS-APIKey": api_key, "User-Agent": USER_AGENT},
750
+ params={"count": 1},
751
+ timeout=15,
752
+ )
753
+ if resp.status_code == 200:
754
+ result["test"] = "passed"
755
+ result["message"] += " API Key 验证有效!ScienceDirect 论文可直接 API 下载。"
756
+ else:
757
+ result["test"] = "failed"
758
+ result["message"] += f" API Key 验证失败(HTTP {resp.status_code}),请检查 key 是否正确。"
759
+ except Exception as e:
760
+ result["test"] = "error"
761
+ result["message"] += f" 验证请求失败: {e}"
762
+ else:
763
+ result["message"] += " 运行 litloop_elsevier_setup(test=true) 验证 key 有效性。"
764
+ else:
765
+ result["status"] = "not_configured"
766
+ # Open browser to Elsevier Developer Portal
767
+ try:
768
+ webbrowser.open("https://dev.elsevier.com/")
769
+ result["browser_opened"] = True
770
+ except Exception:
771
+ result["browser_opened"] = False
772
+
773
+ result["message"] = (
774
+ "Elsevier API Key 未配置。请按以下步骤操作:\n\n"
775
+ "1. 浏览器已打开 Elsevier Developer Portal(如未打开请访问 https://dev.elsevier.com/)\n"
776
+ "2. 用机构邮箱(@xxx.edu.cn)注册或登录 Elsevier 账号——个人邮箱也能建 key,"
777
+ "但账号绑不上机构,key 从创建那刻就拿不到全文权益(403 Requestor configuration settings insufficient)\n"
778
+ "3. 在校园网/学校 VPN 环境下创建 key——门户靠注册时的邮箱域 + 出口 IP 识别机构,校外创建大概率识别失败\n"
779
+ "4. 点击 \"My API Key\" → \"Create new key\",应用名称随意,选择 \"ScienceDirect Article Retrieval\" API\n"
780
+ "5. 复制生成的 API Key(32位字符串)\n"
781
+ "6. 运行配置命令:\n"
782
+ " litloop_config(key=\"elsevier_api_key\", value=\"你的APIKey\")\n"
783
+ "7. 配置后当场验证:运行 litloop elsevier-check——无 key 基线 406、大刊样本 200 即机构绑定成功\n\n"
784
+ "配置后所有 Elsevier/ScienceDirect/Cell Press 论文自动走 API 直接下载(1-2秒)。"
785
+ "insttoken 不需要(API key + 校园网出口即可;仅拿不到校园出口时找机构管理员申请)。"
786
+ )
787
+
788
+ return json.dumps(result, ensure_ascii=False, indent=2)
789
+
790
+
791
+ @mcp_app.tool()
792
+ def litloop_springer_setup(test: bool = False) -> str:
793
+ """Set up the Springer TDM API key (subscription full text; entitlement follows the institution via ORCID-affiliated key; test=true probes entitlement with a paywalled article)."""
794
+ import webbrowser
795
+ config = load_config()
796
+ api_key = str(config.get("springer_api_key", "") or "")
797
+
798
+ result: dict[str, Any] = {}
799
+
800
+ if api_key:
801
+ result["status"] = "configured"
802
+ result["key_preview"] = f"{api_key[:8]}...{api_key[-4:]}"
803
+ result["message"] = "Springer TDM API key 已配置。"
804
+ if test:
805
+ from .sources.springer_tdm import validate_springer_key
806
+
807
+ v = validate_springer_key(api_key, config)
808
+ result["test"] = v["status"]
809
+ if v["status"] == "entitled":
810
+ result["message"] += (
811
+ " ✅ 验证通过:机构订阅全文可用,10.1007 论文可走 TDM 车道(JATS XML 全文,1-2 秒)。"
812
+ )
813
+ elif v["status"] == "not_entitled":
814
+ result["message"] += (
815
+ f" ⚠️ {v['detail']}。无权限时 10.1007 走 WebVPN/CARSI 机构级联。"
816
+ )
817
+ elif v["status"] == "oa_only":
818
+ result["message"] += (
819
+ " ⚠️ 这是 Open Access API key,没有 TDM 全文权限;TDM 车道自动跳过,"
820
+ "Springer 论文照常走 PDF 车道(OA 直链/机构 IP/WebVPN/CARSI)。"
821
+ )
822
+ elif v["status"] == "invalid_key":
823
+ result["message"] += f" ❌ {v['detail']},请到 dev.springernature.com 重新生成。"
824
+ else:
825
+ result["message"] += f" ⚠️ 验证未完成({v['status']}),稍后重试。"
826
+ else:
827
+ result["message"] += " 运行 litloop_springer_setup(test=true) 验证机构权限。"
828
+ else:
829
+ result["status"] = "not_configured"
830
+ try:
831
+ webbrowser.open("https://dev.springernature.com/")
832
+ result["browser_opened"] = True
833
+ except Exception:
834
+ result["browser_opened"] = False
835
+
836
+ result["message"] = (
837
+ "Springer TDM API key 未配置。机构订阅用户按以下步骤操作:\n\n"
838
+ "1. 浏览器已打开 Springer Nature 开发者门户(如未打开请访问 https://dev.springernature.com/)\n"
839
+ "2. 注册账号,注册/登录时用学校邮箱或关联 ORCID(订阅权限跟机构走)\n"
840
+ "3. 在 API Portal 创建 API key(Full Text API/TDM)\n"
841
+ "4. 若门户要求接受 TDM 条款/验证机构身份,按提示完成(需要学校订阅 Springer 且含 TDM 权限)\n"
842
+ "5. 运行配置命令:\n"
843
+ " litloop_config(key=\"springer_api_key\", value=\"你的APIKey\")\n"
844
+ "6. 运行 litloop_springer_setup(test=true) 验证权限\n\n"
845
+ "配置后 10.1007 Springer 论文自动尝试 TDM 全文车道(JATS XML,1-2 秒);"
846
+ "PDF 仍优先走 OA 直链/浏览器车道。无机构权限时该车道自动让位给 WebVPN/CARSI。"
847
+ )
848
+
849
+ return json.dumps(result, ensure_ascii=False, indent=2)
850
+
851
+
852
+ def litloop_network_diagnose() -> str:
853
+ """Diagnose network connectivity and provide actionable fix suggestions.
854
+
855
+ Tests DNS resolution, TCP connectivity, proxy, Tor, and CloakBrowser status.
856
+ Returns specific configuration commands to fix detected issues.
857
+ """
858
+ from .sources.scoring import diagnose_network
859
+ config = load_config()
860
+ report = diagnose_network(config)
861
+ return json.dumps(report, ensure_ascii=False, indent=2)
862
+
863
+
864
+ def litloop_config_get() -> str:
865
+ """Get current litloop configuration (sensitive values masked)."""
866
+ return json.dumps(get_config_safe(), ensure_ascii=False, indent=2)
867
+
868
+
869
+ def _config_set_impl(key: str, value: str) -> str:
870
+ """Update a litloop configuration setting.
871
+
872
+ Args:
873
+ key: Config key (e.g. "email", "scihub_enabled", "vpnsci_school", "vpnsci_enabled", "network_proxy", "batch_workers")
874
+ value: New value (booleans as "true"/"false", numbers as strings)
875
+ """
876
+ try:
877
+ update_config(key, value)
878
+ return json.dumps({"success": True, "key": key, "value": mask_config_value(key, value)})
879
+ except Exception as exc:
880
+ return json.dumps({"success": False, "key": key, "error": str(exc)})
881
+
882
+
883
+ @mcp_app.tool()
884
+ def litloop_cache_clear(identifier: str | None = None) -> str:
885
+ """Clear the paper download cache (identifier optional — omit to clear all)."""
886
+ config = load_config()
887
+ cleared = cache_clear(identifier, config)
888
+ return json.dumps({"cleared": cleared})
889
+
890
+
891
+ @mcp_app.tool()
892
+ def litloop_cancel() -> str:
893
+ """Cancel all in-flight downloads/batches: stop racing, skip pending papers, close their browser windows."""
894
+ from .sources import cancel_downloads
895
+ return json.dumps(cancel_downloads(), ensure_ascii=False)
896
+
897
+
898
+ def litloop_import_bib(
899
+ bib_file: str,
900
+ output_dir: str | None = None,
901
+ scihub_enabled: bool | None = None,
902
+ use_tor: bool = False,
903
+ ctx: Any = None,
904
+ ) -> str:
905
+ """Import DOIs from a .bib file and download all papers.
906
+
907
+ Args:
908
+ bib_file: Path to .bib file
909
+ output_dir: Override default output directory
910
+ scihub_enabled: Enable/disable Sci-Hub
911
+ use_tor: Route through Tor
912
+ """
913
+ from .citations.bib_import import parse_bib_file
914
+ from .log import get_logger
915
+ _log = get_logger()
916
+ entries = parse_bib_file(bib_file)
917
+ if not entries:
918
+ return json.dumps({"success": False, "error": "No entries with DOI found in .bib file"})
919
+
920
+ identifiers = [e["doi"] for e in entries]
921
+
922
+ def _bib_progress(current: int, total: int, identifier: str, result: dict[str, Any]) -> None:
923
+ ok = result.get("success", False)
924
+ src = result.get("source", "?")
925
+ status = "OK" if ok else "FAIL"
926
+ _log.info(f" [{current}/{total}] {status} {src} {identifier}")
927
+ if ctx and hasattr(ctx, "report_progress"):
928
+ try:
929
+ ctx.report_progress(current, total)
930
+ except Exception:
931
+ pass
932
+
933
+ result = batch_download(identifiers, output_dir, scihub_enabled=scihub_enabled, use_tor=use_tor, progress_callback=_bib_progress)
934
+ result["bib_entries"] = len(entries)
935
+ result["bib_file"] = bib_file
936
+ return json.dumps(result, ensure_ascii=False)
937
+
938
+
939
+ def _citation_impl(identifier: str, format: str = "bibtex") -> str:
940
+ """Get citation for a paper in various formats.
941
+
942
+ Args:
943
+ identifier: DOI or arXiv ID
944
+ format: Citation format: "bibtex", "ris", or "endnote"
945
+ """
946
+ from .identifiers import normalize_doi
947
+ config = load_config()
948
+ doi = normalize_doi(identifier)
949
+
950
+ if format == "bibtex":
951
+ from .citations.bibtex_crossref import fetch_bibtex
952
+ citation = fetch_bibtex(doi, config)
953
+ elif format == "ris":
954
+ from .citations.formats import to_ris
955
+ citation = to_ris(doi, config)
956
+ elif format == "endnote":
957
+ from .citations.formats import to_endnote
958
+ citation = to_endnote(doi, config)
959
+ else:
960
+ return json.dumps({"success": False, "error": f"Unknown format: {format}. Use bibtex, ris, or endnote"})
961
+
962
+ if citation:
963
+ return json.dumps({"success": True, "doi": doi, "format": format, "citation": citation})
964
+ return json.dumps({"success": False, "doi": doi, "error": "Failed to fetch metadata"})
965
+
966
+
967
+ def litloop_paper_metadata(doi: str) -> str:
968
+ """Get metadata for a paper by DOI from Semantic Scholar.
969
+
970
+ Returns title, authors, year, abstract, citation count, and identifiers.
971
+ Lighter than fetch_paper — does not download full text.
972
+
973
+ Args:
974
+ doi: The DOI of the paper (e.g. "10.1038/nphys1509").
975
+ """
976
+ from .sources.semantic_scholar import get_paper
977
+
978
+ result = get_paper(f"DOI:{doi}")
979
+ if result is None:
980
+ return json.dumps({"success": False, "doi": doi, "error": "Paper not found"})
981
+
982
+ return json.dumps({
983
+ "success": True,
984
+ "doi": result.doi,
985
+ "title": result.title,
986
+ "authors": result.authors,
987
+ "year": result.year,
988
+ "journal": result.journal,
989
+ "abstract": result.abstract,
990
+ "citation_count": result.citation_count,
991
+ "arxiv_id": result.arxiv_id,
992
+ "s2_url": result.s2_url,
993
+ }, ensure_ascii=False)
994
+
995
+
996
+ @mcp_app.tool()
997
+ def litloop_zotero_push(
998
+ identifier: str,
999
+ collections: list[str] | None = None,
1000
+ tags: list[str] | None = None,
1001
+ ) -> str:
1002
+ """Push a downloaded paper and its PDF to Zotero (via zotero-mcp).
1003
+
1004
+ Args:
1005
+ identifier: DOI/arXiv ID of a downloaded paper
1006
+ collections: existing collections
1007
+ tags: tags
1008
+ """
1009
+ from .identifiers import normalize_doi
1010
+ from .zotero.client import push_via_zotero_mcp
1011
+ config = load_config()
1012
+
1013
+ # Check if paper is in cache
1014
+ cached = cache_get(identifier, config)
1015
+ if not cached or not cached.get("success"):
1016
+ return json.dumps({"success": False, "error": "Paper not found in cache. Download it first."})
1017
+
1018
+ doi = cached.get("doi", normalize_doi(identifier))
1019
+ pdf_path = Path(cached.get("file", "")) if cached.get("file") else None
1020
+
1021
+ result = push_via_zotero_mcp(doi, pdf_path, config, collections, tags)
1022
+ return json.dumps(result, ensure_ascii=False)
1023
+
1024
+
1025
+ def litloop_vpnsci_login() -> str:
1026
+ """Open browser for WebVPN institutional proxy login (CAS authentication).
1027
+
1028
+ Login happens in your browser - passwords never pass through this program.
1029
+ Only session cookies are saved. Run this before using use_vpnsci=true.
1030
+ """
1031
+ config = load_config()
1032
+ if not config.get("vpnsci_enabled"):
1033
+ return json.dumps({"success": False, "error": "WebVPN not enabled. Run: litloop_config key=vpnsci_enabled value=true"})
1034
+
1035
+ from .sources.vpnsci import vpnsci_login, _validate_session, _get_webvpn_base
1036
+ if _validate_session(config):
1037
+ return json.dumps({"success": True, "message": "Already logged in. Session is valid."})
1038
+
1039
+ base = _get_webvpn_base(config)
1040
+ if not base:
1041
+ return json.dumps({"success": False, "error": "No WebVPN URL. Set vpnsci_school or vpnsci_base_url."})
1042
+
1043
+ ok = vpnsci_login(config)
1044
+ if ok:
1045
+ return json.dumps({"success": True, "message": "Login successful. Cookies saved."})
1046
+ return json.dumps({"success": False, "error": "Login failed or timed out. Make sure Chrome is installed."})
1047
+
1048
+
1049
+ def litloop_vpnsci_test(doi: str | None = None) -> str:
1050
+ """Test WebVPN connectivity by attempting to access a paper.
1051
+
1052
+ Args:
1053
+ doi: DOI to test (default: 10.1038/nature12373)
1054
+ """
1055
+ from .sources.vpnsci import vpnsci_is_configured, _validate_session, convert_url, _get_webvpn_base
1056
+ config = load_config()
1057
+ test_doi = doi or "10.1038/nature12373"
1058
+
1059
+ if not vpnsci_is_configured(config):
1060
+ return json.dumps({"success": False, "error": "WebVPN not configured. Set vpnsci_enabled=true and vpnsci_school."})
1061
+
1062
+ if not _validate_session(config):
1063
+ return json.dumps({"success": False, "error": "No valid session. Run litloop_login(kind='webvpn') first."})
1064
+
1065
+ base = _get_webvpn_base(config)
1066
+ doi_url = f"https://doi.org/{test_doi}"
1067
+ proxy_url = convert_url(doi_url, base, config)
1068
+ return json.dumps({
1069
+ "success": True,
1070
+ "message": "Session is valid.",
1071
+ "test_url": proxy_url[:150] + "..." if len(proxy_url) > 150 else proxy_url,
1072
+ })
1073
+
1074
+
1075
+ def litloop_vpnsci_status() -> str:
1076
+ """Check WebVPN configuration and login status."""
1077
+ from .sources.vpnsci import vpnsci_is_configured, _validate_session, vpnsci_cookie_path, _get_webvpn_base
1078
+ config = load_config()
1079
+
1080
+ enabled = config.get("vpnsci_enabled", False)
1081
+ school = config.get("vpnsci_school", "")
1082
+ base_url = _get_webvpn_base(config)
1083
+ cookie_path = vpnsci_cookie_path(config)
1084
+ has_cookies = cookie_path.exists()
1085
+ session_valid = _validate_session(config) if enabled and has_cookies else False
1086
+
1087
+ return json.dumps({
1088
+ "vpnsci_enabled": enabled,
1089
+ "vpnsci_school": school,
1090
+ "vpnsci_base_url": base_url,
1091
+ "cookie_file": str(cookie_path),
1092
+ "has_cookies": has_cookies,
1093
+ "session_valid": session_valid,
1094
+ })
1095
+
1096
+
1097
+ def litloop_vpnsci_schools(query: str | None = None) -> str:
1098
+ """List or search supported WebVPN universities.
1099
+
1100
+ Args:
1101
+ query: Search by name, province, or host. Omit to list all schools.
1102
+ """
1103
+ from .institutional.schools import list_schools, search_schools
1104
+ if query:
1105
+ results = search_schools(query)
1106
+ else:
1107
+ results = list_schools()
1108
+
1109
+ schools = [{"name": s.name, "province": s.province, "host": s.host} for s in results[:50]]
1110
+ return json.dumps({"total": len(results), "showing": len(schools), "schools": schools}, ensure_ascii=False)
1111
+
1112
+
1113
+ def litloop_carsi_login(publisher: str | None = None) -> str:
1114
+ """Login via CARSI federated authentication for publisher institutional access.
1115
+
1116
+ Opens browser to publisher's institutional login page. Cookies are saved
1117
+ and reused for subsequent downloads. Works with ScienceDirect, Springer, Wiley, etc.
1118
+
1119
+ Args:
1120
+ publisher: Publisher key (sciencedirect, springer, wiley, ieee, tandfonline, nature).
1121
+ Auto-detected from DOI if omitted.
1122
+ """
1123
+ from .institutional.carsi_login import CARSIClient
1124
+
1125
+ config = load_config()
1126
+ if not config.get("carsi_enabled"):
1127
+ return json.dumps({"success": False, "error": "CARSI not enabled. Run: litloop_config(key='carsi_enabled', value='true')"})
1128
+
1129
+ idp_name = config.get("carsi_idp_name", "")
1130
+ if not idp_name:
1131
+ return json.dumps({"success": False, "error": "No IdP set. Run: litloop_config key=carsi_idp_name value=你的学校名称(如 北京大学、浙江大学)"})
1132
+
1133
+ target_publisher = publisher or "sciencedirect"
1134
+ client = CARSIClient(config)
1135
+ if target_publisher not in client._publisher_configs:
1136
+ available = list(client._publisher_configs.keys())
1137
+ return json.dumps({"success": False, "error": f"Unknown publisher: {target_publisher}", "available": available})
1138
+
1139
+ ok = client.login(target_publisher)
1140
+ if ok:
1141
+ return json.dumps({"success": True, "message": f"CARSI login successful for {target_publisher}.", "idp": idp_name})
1142
+ return json.dumps({"success": False, "error": "Login failed or timed out. Make sure Chrome is installed."})
1143
+
1144
+
1145
+ def litloop_carsi_status() -> str:
1146
+ """Check CARSI configuration and login status."""
1147
+ from .institutional.carsi_login import CARSIClient
1148
+
1149
+ config = load_config()
1150
+ enabled = config.get("carsi_enabled", False)
1151
+ idp_name = config.get("carsi_idp_name", "")
1152
+
1153
+ if not enabled:
1154
+ return json.dumps({"carsi_enabled": False, "message": "CARSI not enabled."})
1155
+
1156
+ client = CARSIClient(config)
1157
+ publishers = {}
1158
+ for pub_key in client._publisher_configs:
1159
+ cookie_file = client._cookie_path(pub_key)
1160
+ has_cookies = cookie_file.exists()
1161
+ publishers[pub_key] = {
1162
+ "has_cookies": has_cookies,
1163
+ "cookie_file": str(cookie_file),
1164
+ }
1165
+
1166
+ return json.dumps({
1167
+ "carsi_enabled": True,
1168
+ "carsi_idp_name": idp_name,
1169
+ "hint": f"当前学校: {idp_name}。如需更换,运行 litloop_config key=carsi_idp_name value=新学校名称" if idp_name else "未设置学校。运行 litloop_config key=carsi_idp_name value=你的学校名称",
1170
+ "publishers": publishers,
1171
+ }, ensure_ascii=False)
1172
+
1173
+
1174
+ def litloop_ezproxy_login() -> str:
1175
+ """Open browser for EZProxy institutional proxy login.
1176
+
1177
+ Uses the university library's EZProxy service to access papers.
1178
+ Login happens in your browser - only session cookies are saved.
1179
+ """
1180
+ from .sources.ezproxy import ezproxy_login, _validate_ezproxy_session
1181
+
1182
+ config = load_config()
1183
+ if not config.get("ezproxy_enabled"):
1184
+ return json.dumps({"success": False, "error": "EZProxy not enabled. Run: litloop_config key=ezproxy_enabled value=true"})
1185
+
1186
+ if _validate_ezproxy_session(config):
1187
+ return json.dumps({"success": True, "message": "Already logged in. Session is valid."})
1188
+
1189
+ ok = ezproxy_login(config)
1190
+ if ok:
1191
+ return json.dumps({"success": True, "message": "Login successful. Cookies saved."})
1192
+ return json.dumps({"success": False, "error": "Login failed or timed out. Make sure Chrome is installed."})
1193
+
1194
+
1195
+ def litloop_ezproxy_status() -> str:
1196
+ """Check EZProxy configuration and login status."""
1197
+ from .sources.ezproxy import _get_ezproxy_base, _validate_ezproxy_session, _ezproxy_cookie_path
1198
+
1199
+ config = load_config()
1200
+ enabled = config.get("ezproxy_enabled", False)
1201
+ base_url = _get_ezproxy_base(config)
1202
+ cookie_path = _ezproxy_cookie_path(config)
1203
+ has_cookies = cookie_path.exists()
1204
+ session_valid = _validate_ezproxy_session(config) if enabled and has_cookies else False
1205
+
1206
+ return json.dumps({
1207
+ "ezproxy_enabled": enabled,
1208
+ "ezproxy_login_url": base_url,
1209
+ "cookie_file": str(cookie_path),
1210
+ "has_cookies": has_cookies,
1211
+ "session_valid": session_valid,
1212
+ }, ensure_ascii=False)
1213
+
1214
+
1215
+ def litloop_vpnsci_set_school(school: str) -> str:
1216
+ """Set the university for WebVPN access.
1217
+
1218
+ Args:
1219
+ school: University name (e.g. "北京大学", "浙江大学", "复旦大学")
1220
+ """
1221
+ from .institutional.schools import get_school
1222
+ try:
1223
+ entry = get_school(school)
1224
+ except ValueError as e:
1225
+ return json.dumps({"success": False, "error": str(e)})
1226
+
1227
+ update_config("vpnsci_school", entry.name)
1228
+ update_config("vpnsci_base_url", entry.host)
1229
+ update_config("vpnsci_enabled", "true")
1230
+ return json.dumps({
1231
+ "success": True,
1232
+ "school": entry.name,
1233
+ "province": entry.province,
1234
+ "host": entry.host,
1235
+ }, ensure_ascii=False)
1236
+
1237
+
1238
+ @mcp_app.tool()
1239
+ def litloop_parse_list(file_path: str) -> str:
1240
+ """Parse a paper list file (APA/BibTeX/DOI list/queue TSV/csv/xlsx) into structured entries."""
1241
+ try:
1242
+ entries = parse_paper_list(file_path)
1243
+ except FileNotFoundError as e:
1244
+ return json.dumps({"success": False, "error": str(e)})
1245
+ except Exception as e:
1246
+ return json.dumps({"success": False, "error": f"Parse error: {e}"})
1247
+
1248
+ result = []
1249
+ for i, entry in enumerate(entries):
1250
+ result.append({
1251
+ "index": i + 1,
1252
+ "title": entry.title,
1253
+ "authors": entry.authors,
1254
+ "year": entry.year,
1255
+ "doi": entry.doi,
1256
+ "journal": entry.journal,
1257
+ })
1258
+
1259
+ dois_found = sum(1 for e in entries if e.doi)
1260
+ return json.dumps({
1261
+ "success": True,
1262
+ "total": len(entries),
1263
+ "with_doi": dois_found,
1264
+ "without_doi": len(entries) - dois_found,
1265
+ "entries": result,
1266
+ }, ensure_ascii=False, indent=2)
1267
+
1268
+
1269
+ def litloop_resolve_and_download(
1270
+ file_path: str,
1271
+ output_dir: str | None = None,
1272
+ scihub_enabled: bool | None = None,
1273
+ use_tor: bool = False,
1274
+ use_vpnsci: bool = False,
1275
+ resolve_titles: bool = True,
1276
+ ctx: Any = None,
1277
+ ) -> str:
1278
+ """Parse paper list → fix DOI format → resolve missing DOIs by title search → batch download.
1279
+
1280
+ Full pipeline: parses APA/BibTeX/DOI list, repairs unicode hyphens in DOIs,
1281
+ searches OpenAlex for papers without DOIs, then downloads all.
1282
+
1283
+ Args:
1284
+ file_path: Path to paper list file (.md, .txt, .bib)
1285
+ output_dir: Override default output directory
1286
+ scihub_enabled: Enable/disable Sci-Hub
1287
+ use_tor: Route through Tor
1288
+ use_vpnsci: Try WebVPN institutional proxy as last resort
1289
+ resolve_titles: Search OpenAlex for papers without DOI (default true)
1290
+ """
1291
+ try:
1292
+ entries = parse_paper_list(file_path)
1293
+ except FileNotFoundError as e:
1294
+ return json.dumps({"success": False, "error": str(e)})
1295
+ except Exception as e:
1296
+ return json.dumps({"success": False, "error": f"Parse error: {e}"})
1297
+
1298
+ if not entries:
1299
+ return json.dumps({"success": False, "error": "No entries found in file"})
1300
+
1301
+ config = load_config()
1302
+
1303
+ # Resolve missing DOIs by title search
1304
+ resolve_stats = {"total": len(entries), "already_has_doi": 0, "resolved_by_title": 0, "unresolvable": 0}
1305
+ if resolve_titles:
1306
+ result = batch_resolve(entries, config)
1307
+ entries = result["entries"]
1308
+ resolve_stats = result["stats"]
1309
+
1310
+ # Collect DOIs for download
1311
+ dois = [e.doi for e in entries if e.doi]
1312
+ if not dois:
1313
+ return json.dumps({
1314
+ "success": False,
1315
+ "error": "No valid DOIs found after resolution",
1316
+ "resolve_stats": resolve_stats,
1317
+ })
1318
+
1319
+ # Deduplicate
1320
+ seen = set()
1321
+ unique_dois = []
1322
+ for d in dois:
1323
+ if d not in seen:
1324
+ seen.add(d)
1325
+ unique_dois.append(d)
1326
+
1327
+ # Download
1328
+ from .log import get_logger
1329
+ _log = get_logger()
1330
+ def _resolve_progress(current: int, total: int, identifier: str, result: dict[str, Any]) -> None:
1331
+ ok = result.get("success", False)
1332
+ src = result.get("source", "?")
1333
+ status = "OK" if ok else "FAIL"
1334
+ _log.info(f" [{current}/{total}] {status} {src} {identifier}")
1335
+ if ctx and hasattr(ctx, "report_progress"):
1336
+ try:
1337
+ ctx.report_progress(current, total)
1338
+ except Exception:
1339
+ pass
1340
+
1341
+ dl_result = batch_download(
1342
+ unique_dois, output_dir,
1343
+ scihub_enabled=scihub_enabled,
1344
+ use_tor=use_tor,
1345
+ use_vpnsci=use_vpnsci,
1346
+ progress_callback=_resolve_progress,
1347
+ )
1348
+
1349
+ dl_result["parse_stats"] = {
1350
+ "total_entries": len(entries),
1351
+ "entries_with_doi": len(dois),
1352
+ "unique_dois": len(unique_dois),
1353
+ }
1354
+ dl_result["resolve_stats"] = resolve_stats
1355
+
1356
+ return json.dumps(dl_result, ensure_ascii=False, indent=2)
1357
+
1358
+
1359
+ def litloop_setup_check() -> str:
1360
+ """Check system environment and return setup recommendations.
1361
+
1362
+ Returns OS info, component status, and installation suggestions
1363
+ for missing dependencies. Use this to guide users through setup.
1364
+ """
1365
+ from .cli.doctor import setup_check
1366
+ result = setup_check()
1367
+ return json.dumps(result, ensure_ascii=False, indent=2)
1368
+
1369
+
1370
+ def litloop_tor_install() -> str:
1371
+ """Download and install Tor Expert Bundle to ~/.litloop/tor/.
1372
+
1373
+ No Docker or system-wide installation needed. Tor binary is managed
1374
+ entirely within the litloop data directory.
1375
+ """
1376
+ config = load_config()
1377
+ from .tor.proxy import install_tor
1378
+ result = install_tor(config)
1379
+ return json.dumps(result, ensure_ascii=False, indent=2)
1380
+
1381
+
1382
+ def litloop_tor_start(use_bridges: bool = False) -> str:
1383
+ """Start embedded Tor SOCKS5 proxy.
1384
+
1385
+ Downloads Tor binary if not already installed. No Docker needed.
1386
+ After starting, use_tor=true in download tools will route through this proxy.
1387
+
1388
+ Args:
1389
+ use_bridges: Use obfs4 bridges for restricted networks (e.g. behind firewall). Default false.
1390
+ """
1391
+ config = load_config()
1392
+ if use_bridges:
1393
+ update_config("tor_use_bridges", "true")
1394
+ update_config("use_tor_for_scihub", "true")
1395
+
1396
+ from .tor.proxy import start_embedded_tor
1397
+ result = start_embedded_tor(config)
1398
+ return json.dumps(result, ensure_ascii=False, indent=2)
1399
+
1400
+
1401
+ def litloop_tor_stop() -> str:
1402
+ """Stop the embedded Tor SOCKS5 proxy."""
1403
+ from .tor.proxy import stop_embedded_tor
1404
+ result = stop_embedded_tor()
1405
+ return json.dumps(result, ensure_ascii=False, indent=2)
1406
+
1407
+
1408
+ def litloop_import_browser_cookies(
1409
+ url: str = "https://www.sciencedirect.com/",
1410
+ max_wait: int = 300,
1411
+ ) -> str:
1412
+ """Extract publisher cookies via CloakBrowser for institutional access.
1413
+
1414
+ Opens a visible stealth browser window. Log in to your institution (university library),
1415
+ then close the browser. Cookies are saved and automatically used for all future downloads.
1416
+
1417
+ No WebVPN or special configuration needed — works with any institution.
1418
+
1419
+ Args:
1420
+ url: Page to open (default: ScienceDirect). Use publisher-specific URL for best results.
1421
+ max_wait: Max seconds to wait for login (default 300).
1422
+ """
1423
+ config = load_config()
1424
+ from .browser.cookies import extract_via_browser
1425
+ result = extract_via_browser(config, url=url, max_wait=max_wait)
1426
+ return json.dumps(result, ensure_ascii=False, indent=2)
1427
+
1428
+
1429
+ def _publisher_login_impl(
1430
+ identifier: str,
1431
+ max_wait: int = 300,
1432
+ ) -> str:
1433
+ """Login to publisher via your institution for paywall access.
1434
+
1435
+ Opens a stealth browser to the article or publisher page. Click
1436
+ 'Access through your institution' or 'Log In', select your
1437
+ institution, and complete SSO login. Close the browser when done.
1438
+ Cookies are automatically captured and saved for all future downloads.
1439
+
1440
+ No WebVPN or CARSI configuration needed — works with any institution.
1441
+
1442
+ Args:
1443
+ identifier: DOI (e.g. 10.1126/science.aec6396) or publisher name
1444
+ (e.g. "elsevier", "wiley", "nature", "springer", "ieee",
1445
+ "science", "tandfonline", "pnas", "acs", "rsc", "aip",
1446
+ "aps", "iop", "oxford", "acm")
1447
+ max_wait: Max seconds to wait for login (default 300)
1448
+ """
1449
+ config = load_config()
1450
+ from .browser.cookies import publisher_login
1451
+ result = publisher_login(identifier, config, max_wait=max_wait)
1452
+ return json.dumps(result, ensure_ascii=False, indent=2)
1453
+
1454
+
1455
+ def litloop_browser_status() -> str:
1456
+ """Check CloakBrowser availability and configuration."""
1457
+ config = load_config()
1458
+ from .browser.engine import is_available
1459
+ available = is_available(config)
1460
+ return json.dumps({
1461
+ "available": available,
1462
+ "status": "ok" if available else "unreachable",
1463
+ }, ensure_ascii=False, indent=2)
1464
+
1465
+
1466
+ def litloop_browser_login(
1467
+ login_type: str = "webvpn",
1468
+ custom_url: str | None = None,
1469
+ ) -> str:
1470
+ """Open a stealth browser for institutional login (WebVPN/CARSI/EZProxy/custom).
1471
+
1472
+ Captures cookies after login and auto-imports them into CloakBrowser.
1473
+
1474
+ Args:
1475
+ login_type: One of "webvpn", "carsi", "ezproxy", "custom"
1476
+ custom_url: URL to open (required when login_type is "custom")
1477
+ """
1478
+ config = load_config()
1479
+ from .browser.login import open_login_browser, webvpn_login, ezproxy_login
1480
+ from .config import DATA_DIR
1481
+ from pathlib import Path
1482
+
1483
+ if login_type == "webvpn":
1484
+ success = webvpn_login(config)
1485
+ elif login_type == "ezproxy":
1486
+ success = ezproxy_login(config)
1487
+ elif login_type == "custom":
1488
+ if not custom_url:
1489
+ return json.dumps({"error": "custom_url is required for login_type=custom"})
1490
+ cache_dir = Path(config.get("cache_dir", str(DATA_DIR / "cache")))
1491
+ cookie_file = cache_dir / "custom_cookies.json"
1492
+ success = open_login_browser(custom_url, config, cookie_file=cookie_file)
1493
+ elif login_type == "carsi":
1494
+ return json.dumps({"error": "Use the CARSI publisher-specific login flow instead"})
1495
+ else:
1496
+ return json.dumps({"error": f"Unknown login_type: {login_type}. Use webvpn/ezproxy/custom"})
1497
+
1498
+ return json.dumps({"login_type": login_type, "success": success}, ensure_ascii=False)
1499
+
1500
+
1501
+ def litloop_browser_import_cookies(cookie_file: str) -> str:
1502
+ """Import Netscape-format cookies into CloakBrowser.
1503
+
1504
+ Args:
1505
+ cookie_file: Path to Netscape-format cookie file
1506
+ """
1507
+ config = load_config()
1508
+ from .browser.engine import import_cookies, is_available
1509
+ if not is_available(config):
1510
+ return json.dumps({"error": "CloakBrowser is not running"})
1511
+ try:
1512
+ count = import_cookies(cookie_file, config)
1513
+ return json.dumps({"imported": count, "file": cookie_file}, ensure_ascii=False)
1514
+ except Exception as exc:
1515
+ return json.dumps({"error": str(exc)}, ensure_ascii=False)
1516
+
1517
+
1518
+ # ---------------------------------------------------------------------------
1519
+ # Consolidated tool surface (v1.11): one tool per intent, engines unchanged.
1520
+ # ---------------------------------------------------------------------------
1521
+
1522
+ @mcp_app.tool()
1523
+ def litloop_find(
1524
+ action: str = "plan",
1525
+ query: str = "",
1526
+ domain: str = "general",
1527
+ depth: str = "standard",
1528
+ sample_size: int = 100,
1529
+ ) -> str:
1530
+ """ScanSci Find engine: action=plan|estimate|smoke|calibrate a systematic search (query, domain, depth, sample_size)."""
1531
+ if action == "plan":
1532
+ return litloop_plan_search(query=query, domain=domain, depth=depth)
1533
+ if action == "estimate":
1534
+ return litloop_estimate_search(query=query, domain=domain, depth=depth)
1535
+ if action == "smoke":
1536
+ return litloop_smoke_search(query=query, domain=domain)
1537
+ if action == "calibrate":
1538
+ return litloop_calibrate_search(query=query, domain=domain, depth=depth, sample_size=sample_size)
1539
+ return json.dumps({"error": f"unknown action: {action}", "allowed": ["plan", "estimate", "smoke", "calibrate"]}, ensure_ascii=False)
1540
+
1541
+
1542
+ @mcp_app.tool()
1543
+ def litloop_prepare_queue(
1544
+ action: str = "verify",
1545
+ candidates_json: str = "",
1546
+ query: str = "",
1547
+ limit: int = 10,
1548
+ depth: str = "standard",
1549
+ ) -> str:
1550
+ """Prepare a download queue: action=verify|resolve_oa|build|full (candidates_json for verify/resolve_oa/full; query/limit/depth for build)."""
1551
+ if action == "verify":
1552
+ return litloop_verify_identifiers(candidates_json)
1553
+ if action == "resolve_oa":
1554
+ return litloop_resolve_oa(candidates_json)
1555
+ if action == "build":
1556
+ return litloop_build_download_queue(query=query, limit=limit, depth=depth)
1557
+ if action == "full":
1558
+ from .search.scansci_find import DiscoveryTimeoutError, resolve_oa, verify
1559
+ # Shared budget: verify + resolve-oa together must not take the sum of
1560
+ # two light budgets (45s each). Each subprocess gets the remaining time.
1561
+ budget_seconds = 75
1562
+ t0 = time.time()
1563
+ try:
1564
+ verified = verify(candidates_json, timeout=max(10, int(budget_seconds - (time.time() - t0))))
1565
+ except DiscoveryTimeoutError as exc:
1566
+ verified = _discovery_timeout_payload(exc)
1567
+ except Exception as exc:
1568
+ verified = {"error": str(exc)}
1569
+ try:
1570
+ with_oa = resolve_oa(candidates_json, timeout=max(10, int(budget_seconds - (time.time() - t0))))
1571
+ except DiscoveryTimeoutError as exc:
1572
+ with_oa = _discovery_timeout_payload(exc)
1573
+ except Exception as exc:
1574
+ with_oa = {"error": str(exc)}
1575
+ return json.dumps({"verified": verified, "oa": with_oa}, ensure_ascii=False)
1576
+ return json.dumps({"error": f"unknown action: {action}", "allowed": ["verify", "resolve_oa", "build", "full"]}, ensure_ascii=False)
1577
+
1578
+
1579
+ @mcp_app.tool()
1580
+ def litloop_login(
1581
+ kind: str = "publisher",
1582
+ identifier: str = "",
1583
+ publisher: str = "",
1584
+ custom_url: str = "",
1585
+ cookie_file: str = "",
1586
+ max_wait: int = 300,
1587
+ ) -> str:
1588
+ """Unified institutional login; cookies reused. kind: publisher (DOI SSO, default) | webvpn | carsi (+publisher) | ezproxy | custom (+custom_url) | cookie_import (+cookie_file)."""
1589
+ if kind == "publisher":
1590
+ return _publisher_login_impl(identifier, max_wait)
1591
+ if kind == "webvpn":
1592
+ return litloop_vpnsci_login()
1593
+ if kind == "carsi":
1594
+ return litloop_carsi_login(publisher=publisher)
1595
+ if kind == "ezproxy":
1596
+ return litloop_ezproxy_login()
1597
+ if kind == "custom":
1598
+ return litloop_browser_login(login_type="custom", custom_url=custom_url)
1599
+ if kind == "cookie_import":
1600
+ if cookie_file:
1601
+ return litloop_browser_import_cookies(cookie_file=cookie_file)
1602
+ return litloop_import_browser_cookies(max_wait=max_wait)
1603
+ return json.dumps({"error": f"unknown kind: {kind}", "allowed": ["publisher", "webvpn", "carsi", "ezproxy", "custom", "cookie_import"]}, ensure_ascii=False)
1604
+
1605
+
1606
+ @mcp_app.tool()
1607
+ def litloop_channel_status(kind: str = "webvpn", doi: str = "") -> str:
1608
+ """Institutional channel status: kind=webvpn|carsi|ezproxy|browser|browser_doctor|webvpn_test (+doi for the test)."""
1609
+ if kind == "carsi":
1610
+ return litloop_carsi_status()
1611
+ if kind == "ezproxy":
1612
+ return litloop_ezproxy_status()
1613
+ if kind == "browser":
1614
+ return litloop_browser_status()
1615
+ if kind == "browser_doctor":
1616
+ return litloop_browser_doctor()
1617
+ if kind == "webvpn_test":
1618
+ return litloop_vpnsci_test(doi=doi)
1619
+ return litloop_vpnsci_status()
1620
+
1621
+
1622
+ @mcp_app.tool()
1623
+ def litloop_schools(action: str = "search", query: str = "", school: str = "") -> str:
1624
+ """Search (query) or set (school) supported WebVPN universities — 100+ Chinese universities."""
1625
+ if action == "set":
1626
+ return litloop_vpnsci_set_school(school=school)
1627
+ return litloop_vpnsci_schools(query=query)
1628
+
1629
+
1630
+ @mcp_app.tool()
1631
+ def litloop_diagnostics(check: str = "health", detailed: bool = False) -> str:
1632
+ """Diagnostics: check=health|network|sources|setup|auto_setup|quota (API usage and limits)."""
1633
+ if check == "quota":
1634
+ from . import quota
1635
+ return json.dumps({"openalex_official": quota.openalex_live(), "providers": quota.summary(),
1636
+ "warnings": quota.warnings()}, ensure_ascii=False)
1637
+ if check == "network":
1638
+ return litloop_network_diagnose()
1639
+ if check == "sources":
1640
+ return litloop_source_scores()
1641
+ if check == "setup":
1642
+ return litloop_setup_check()
1643
+ if check == "auto_setup":
1644
+ return litloop_auto_setup()
1645
+ return litloop_health_check(detailed=detailed)
1646
+
1647
+
1648
+ @mcp_app.tool()
1649
+ def litloop_config(key: str = "", value: str = "") -> str:
1650
+ """Get the full masked config (no key) / one key's value (key only) / set key=value (key + value)."""
1651
+ if key and value:
1652
+ return _config_set_impl(key=key, value=value)
1653
+ if key:
1654
+ cfg = json.loads(litloop_config_get())
1655
+ return json.dumps({"key": key, "value": cfg.get(key, "(unset)")}, ensure_ascii=False)
1656
+ return litloop_config_get()
1657
+
1658
+
1659
+ @mcp_app.tool()
1660
+ def litloop_glossary(action: str = "list", terms: list[str] | None = None, entry_id: str = "", note: str = "") -> str:
1661
+ """Abbreviation/synonym glossary searches expand: action=list|add (terms; waits for the user)|confirm|edit|delete (entry_id)."""
1662
+ from .terms import glossary
1663
+ try:
1664
+ if action == "add":
1665
+ return json.dumps(glossary.add(terms or [], note=note, source="agent"), ensure_ascii=False)
1666
+ if action == "confirm":
1667
+ return json.dumps(glossary.update(entry_id, confirm=True), ensure_ascii=False)
1668
+ if action == "edit":
1669
+ return json.dumps(glossary.update(entry_id, terms=terms, note=note or None), ensure_ascii=False)
1670
+ if action == "delete":
1671
+ glossary.delete(entry_id)
1672
+ return json.dumps({"deleted": entry_id}, ensure_ascii=False)
1673
+ if action != "list":
1674
+ return json.dumps({"error": f"unknown action: {action}",
1675
+ "allowed": ["list", "add", "confirm", "edit", "delete"]}, ensure_ascii=False)
1676
+ return json.dumps({"active": glossary.entries("active"), "suggested": glossary.entries("suggested"),
1677
+ "builtin_disabled": sorted(glossary.disabled()),
1678
+ "note": "Suggested entries count only after the user confirms them. Element "
1679
+ "symbols/names (Al = aluminum) and British/American spellings are built in; "
1680
+ "builtin_disabled lists those the user switched off."}, ensure_ascii=False)
1681
+ except (KeyError, ValueError) as exc:
1682
+ return json.dumps({"error": str(exc).strip("'\"")}, ensure_ascii=False)
1683
+
1684
+
1685
+ @mcp_app.tool()
1686
+ def litloop_tor(action: str = "start", use_bridges: bool = False) -> str:
1687
+ """Embedded Tor SOCKS5 proxy: action=install|start|stop; use_bridges enables obfs4 when Tor itself is blocked."""
1688
+ if action == "install":
1689
+ return litloop_tor_install()
1690
+ if action == "stop":
1691
+ return litloop_tor_stop()
1692
+ return litloop_tor_start(use_bridges=use_bridges)
1693
+
1694
+
1695
+ @mcp_app.tool()
1696
+ def litloop_batch_download(
1697
+ identifiers: list[str] | None = None,
1698
+ file: str | None = None,
1699
+ output_dir: str | None = None,
1700
+ scihub_enabled: bool | None = None,
1701
+ use_tor: bool = False,
1702
+ use_vpnsci: bool = False,
1703
+ batch_id: str | None = None,
1704
+ resume: bool = True,
1705
+ resolve_titles: bool = True,
1706
+ lanes: bool | None = None,
1707
+ ) -> str:
1708
+ """Batch download: identifiers OR file (txt/csv/xlsx/BibTeX/APA); auto DOI resolution; resumable batch_id; >=3 items default to lane scheduling (fast->grey->institutional); lanes=false for racing."""
1709
+ if file:
1710
+ suffix = Path(file).suffix.lower()
1711
+ if suffix == ".bib":
1712
+ return litloop_import_bib(bib_file=file, output_dir=output_dir, scihub_enabled=scihub_enabled, use_tor=use_tor)
1713
+ return litloop_resolve_and_download(
1714
+ file_path=file, output_dir=output_dir, scihub_enabled=scihub_enabled,
1715
+ use_tor=use_tor, use_vpnsci=use_vpnsci, resolve_titles=resolve_titles,
1716
+ )
1717
+ if not identifiers:
1718
+ return json.dumps({"error": "provide identifiers[] or file"}, ensure_ascii=False)
1719
+ return _with_update_notice(_batch_download_impl(
1720
+ identifiers=identifiers, output_dir=output_dir, scihub_enabled=scihub_enabled,
1721
+ use_tor=use_tor, use_vpnsci=use_vpnsci, batch_id=batch_id, resume=resume,
1722
+ lanes=lanes,
1723
+ ))
1724
+
1725
+
1726
+ @mcp_app.tool()
1727
+ def litloop_citation(identifier: str, format: str = "bibtex") -> str:
1728
+ """Citation for a paper: format=bibtex|ris|endnote|metadata (Semantic Scholar JSON)."""
1729
+ if format == "metadata":
1730
+ return litloop_paper_metadata(doi=identifier)
1731
+ return _citation_impl(identifier=identifier, format=format)