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
@@ -0,0 +1,309 @@
1
+ """Run inside the zotero-mcp Python (not litloop's) to file a paper.
2
+
3
+ litloop starts this file with zotero-mcp's interpreter and passes one JSON
4
+ request on stdin; it prints one JSON result line on stdout. It imports nothing
5
+ from litloop, so it works with only zotero-mcp installed.
6
+
7
+ The item is added by DOI (or arXiv URL) with attach_mode="none", so CrossRef
8
+ metadata is used, then the downloaded PDF is attached with zotero-mcp's own
9
+ attach_file, which uploads to WebDAV when ZOTERO_WEBDAV_* is set.
10
+
11
+ Request: {"op", "env_script", ...}
12
+ op "push" (default): {"identifier", "file", "collections", "tags"}
13
+ op "collections": list every collection as {"key", "name", "parent", "path"}
14
+ op "ensure_collection": {"path": "LitLoop/My topic"} -> key, creating missing levels
15
+ op "collection_items": {"key"} -> regular items as {"key", "title", "doi", "year"} (no attachment check)
16
+ op "check_collection": {"key"} -> every regular item with the state of its PDF:
17
+ ok, missing (no PDF attachment), empty (attachments hold no file)
18
+ op "write_mode": how zotero-mcp would write: local, web, hybrid or none
19
+ op "authorize": ask Zotero for local-write permission (a dialog in Zotero; waits for it)
20
+ op "repair": {"item_key", "trash": [attachment keys], "file"} -> moves the
21
+ empty attachments to the Trash, then attaches file (if given)
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import contextlib
27
+ import json
28
+ import re
29
+ import runpy
30
+ import socket
31
+ import sys
32
+
33
+ _KEY_RE = re.compile(r"Item key: `([A-Z0-9]{8})`")
34
+ # "File attached to `PARENT`: name.pdf (key `ATTKEY`) ..."
35
+ _ATT_KEY_RE = re.compile(r"\(key `([A-Z0-9]{8})`\)")
36
+
37
+
38
+ def _source_for(identifier: str) -> str:
39
+ ident = identifier.strip()
40
+ m = re.match(r"(?i)^(?:arxiv:)?(\d{4}\.\d{4,5}(?:v\d+)?)$", ident)
41
+ if m:
42
+ return f"https://arxiv.org/abs/{m.group(1)}"
43
+ return ident
44
+
45
+
46
+ def _setup(req: dict) -> None:
47
+ if req.get("env_script"):
48
+ # The user's launcher sets ZOTERO_* env vars (decrypting secrets);
49
+ # its serve() call is guarded by __main__, so this only sets env.
50
+ runpy.run_path(req["env_script"], run_name="zotero_env")
51
+
52
+ try:
53
+ # Same config the server reads: ~/.config/zotero-mcp/config.json and
54
+ # Claude Desktop's env block. Never overrides variables already set.
55
+ from zotero_mcp.cli import setup_zotero_environment
56
+ setup_zotero_environment()
57
+ except Exception:
58
+ pass
59
+
60
+
61
+ def _collections() -> list[dict]:
62
+ """Every collection with its '/'-path, parents before children."""
63
+ from zotero_mcp.client import get_zotero_client
64
+ zot = get_zotero_client()
65
+ rows = zot.everything(zot.collections())
66
+ by_key = {c["data"]["key"]: c["data"] for c in rows}
67
+
68
+ def path(key: str, seen=()) -> str:
69
+ d = by_key[key]
70
+ parent = d.get("parentCollection") or None
71
+ if parent and parent in by_key and parent not in seen:
72
+ return path(parent, seen + (key,)) + "/" + d["name"]
73
+ return d["name"]
74
+
75
+ out = [{"key": k, "name": d["name"], "parent": d.get("parentCollection") or None, "path": path(k)}
76
+ for k, d in by_key.items()]
77
+ return sorted(out, key=lambda c: c["path"].lower())
78
+
79
+
80
+ def _ensure_collection(path: str) -> dict:
81
+ """Find the collection at path ('A/B/C'), creating the levels that are missing."""
82
+ from zotero_mcp.cli_standalone import CLIContext
83
+ from zotero_mcp.tools import write
84
+ parts = [p.strip() for p in path.split("/") if p.strip()]
85
+ if not parts:
86
+ return {"success": False, "error": "empty collection path"}
87
+ created, parent = [], None
88
+ for i in range(len(parts)):
89
+ want = "/".join(parts[: i + 1])
90
+ found = next((c for c in _collections() if c["path"] == want), None)
91
+ if found:
92
+ parent = found["key"]
93
+ continue
94
+ out = write.create_collection(name=parts[i], parent_collection=parent, ctx=CLIContext())
95
+ m = re.search(r"Collection key: `([A-Z0-9]{8})`", out or "")
96
+ if not m:
97
+ return {"success": False, "error": (out or "").strip()[:500]}
98
+ parent = m.group(1)
99
+ created.append(want)
100
+ return {"success": True, "key": parent, "path": "/".join(parts), "created": created}
101
+
102
+
103
+ def _plain(text) -> str:
104
+ """Zotero keeps rich-text titles (<sub>2</sub>, &amp;); show them as plain text."""
105
+ import html
106
+ return html.unescape(re.sub(r"<[^>]+>", "", text or "")).strip()
107
+
108
+
109
+ def _doi_of(data: dict) -> str:
110
+ doi = (data.get("DOI") or "").strip()
111
+ if not doi:
112
+ m = re.search(r"(?im)^DOI:\s*(\S+)", data.get("extra") or "")
113
+ doi = m.group(1) if m else ""
114
+ return doi.lower()
115
+
116
+
117
+ def _check_collection(key: str) -> dict:
118
+ """The PDF state of every regular item in the collection (read only)."""
119
+ from zotero_mcp.client import get_zotero_client
120
+ zot = get_zotero_client()
121
+ # One listing holds the items and their child attachments (children carry parentItem).
122
+ rows = [r.get("data", {}) for r in zot.everything(zot.collection_items(key))]
123
+ pdfs_of: dict[str, list] = {}
124
+ for d in rows:
125
+ if d.get("itemType") == "attachment" and d.get("parentItem") and d.get("contentType") == "application/pdf":
126
+ pdfs_of.setdefault(d["parentItem"], []).append(d)
127
+ out = []
128
+ for d in rows:
129
+ if d.get("itemType") in ("attachment", "note", "annotation") or d.get("parentItem"):
130
+ continue
131
+ pdfs = pdfs_of.get(d["key"], [])
132
+ if not pdfs:
133
+ state, empty = "missing", []
134
+ else:
135
+ linked = [a for a in pdfs if a.get("linkMode") == "linked_file"]
136
+ stored = [a for a in pdfs if a.get("linkMode") != "linked_file"]
137
+ empty = [a["key"] for a in stored if not _has_stored_file(a["key"])]
138
+ state = "ok" if linked or len(empty) < len(stored) else "empty"
139
+ year = re.search(r"\d{4}", d.get("date") or "")
140
+ out.append({"key": d["key"], "title": _plain(d.get("title")), "doi": _doi_of(d),
141
+ "year": int(year.group(0)) if year else None,
142
+ "journal": _plain(d.get("publicationTitle")) or None, "state": state,
143
+ "empty_attachments": empty if state == "empty" else []})
144
+ return {"success": True, "items": out}
145
+
146
+
147
+ def _repair(req: dict) -> dict:
148
+ """Trash the empty attachments of one item, then attach the local PDF."""
149
+ from zotero_mcp.cli_standalone import CLIContext
150
+ from zotero_mcp.tools import write
151
+ ctx = CLIContext()
152
+ trashed = []
153
+ for key in req.get("trash") or []:
154
+ out = write.delete_item(item_key=key, ctx=ctx)
155
+ if (out or "").lstrip().startswith("Error"):
156
+ return {"success": False, "error": out.strip()[:500], "trashed": trashed}
157
+ trashed.append(key)
158
+ if not req.get("file"):
159
+ return {"success": True, "trashed": trashed, "attached": False}
160
+ att = write.attach_file(item_key=req["item_key"], file_path=req["file"], ctx=ctx)
161
+ k = _ATT_KEY_RE.search(att)
162
+ ok = not att.lstrip().startswith("Error") and "FAILED" not in att and bool(k) and _has_stored_file(k.group(1))
163
+ return {"success": ok, "trashed": trashed, "attached": ok,
164
+ **({} if ok else {"error": att.strip()[:500]})}
165
+
166
+
167
+ def run(req: dict) -> dict:
168
+ _setup(req)
169
+ op = req.get("op") or "push"
170
+ if op == "collections":
171
+ return {"success": True, "collections": _collections()}
172
+ if op == "ensure_collection":
173
+ return _ensure_collection(req.get("path") or "")
174
+ if op == "write_mode":
175
+ from zotero_mcp.client import get_write_capabilities
176
+ caps = get_write_capabilities(probe=True)
177
+ return {"success": True, "mode": caps.get("mode"), "local_supported": caps.get("server_supports_local_writes")}
178
+ if op == "authorize":
179
+ from zotero_mcp.cli_standalone import CLIContext
180
+ from zotero_mcp.tools.local_auth import authorize_local_writes
181
+ out = authorize_local_writes(ctx=CLIContext())
182
+ from zotero_mcp.client import get_write_capabilities
183
+ mode = get_write_capabilities(probe=True).get("mode")
184
+ return {"success": mode == "local", "mode": mode, "message": (out or "").strip()[:500]}
185
+ if op == "collection_items":
186
+ from zotero_mcp.client import get_zotero_client
187
+ zot = get_zotero_client()
188
+ items = []
189
+ for row in zot.everything(zot.collection_items_top(req["key"])):
190
+ d = row.get("data", {})
191
+ if d.get("itemType") in ("attachment", "note", "annotation"):
192
+ continue
193
+ year = re.search(r"\d{4}", d.get("date") or "")
194
+ items.append({"key": d["key"], "title": _plain(d.get("title")), "doi": _doi_of(d),
195
+ "year": int(year.group(0)) if year else None})
196
+ return {"success": True, "items": items}
197
+ if op == "check_collection":
198
+ return _check_collection(req["key"])
199
+ if op == "repair":
200
+ return _repair(req)
201
+ if op != "push":
202
+ return {"success": False, "error": f"unknown op {op}"}
203
+
204
+ from zotero_mcp.cli_standalone import CLIContext
205
+ from zotero_mcp.tools import write
206
+
207
+ if not hasattr(write, "add_item") or not hasattr(write, "attach_file"):
208
+ return {"success": False, "error": "zotero-mcp is too old; "
209
+ "upgrade with: pip install -U zotero-mcp-server"}
210
+ ctx = CLIContext()
211
+ try:
212
+ added = write.add_item(
213
+ source=_source_for(req["identifier"]),
214
+ collections=req.get("collections") or None,
215
+ tags=req.get("tags") or None,
216
+ attach_mode="none",
217
+ if_exists="file",
218
+ ctx=ctx,
219
+ )
220
+ except TypeError as e: # older signature without if_exists
221
+ return {"success": False, "error": f"zotero-mcp is too old ({e}); "
222
+ "upgrade with: pip install -U zotero-mcp-server"}
223
+ m = _KEY_RE.search(added)
224
+ if not m:
225
+ return {"success": False, "error": added.strip()[:500]}
226
+ result = {
227
+ "success": True,
228
+ "zotero_key": m.group(1),
229
+ "reused": "Already in library:" in added,
230
+ "pdf_attached": False,
231
+ }
232
+
233
+ file_path = req.get("file")
234
+ if file_path:
235
+ att = write.attach_file(item_key=m.group(1), file_path=file_path, ctx=ctx)
236
+ ok = not att.lstrip().startswith("Error") and "FAILED" not in att
237
+ k = _ATT_KEY_RE.search(att)
238
+ if ok and k and "already present" in att and not _has_stored_file(k.group(1)):
239
+ # zotero-mcp dedupes by filename only; an upload that was cut off
240
+ # leaves an attachment record with no file behind it.
241
+ ok = False
242
+ att = (f"Attachment `{k.group(1)}` exists but holds no file (an earlier upload "
243
+ "was interrupted). Move it to the trash and push again.")
244
+ result["pdf_attached"] = ok
245
+ result["attach_message"] = att.strip()[:500]
246
+ if ok and k:
247
+ result["attachment_key"] = k.group(1)
248
+ return result
249
+
250
+
251
+ def _has_stored_file(attachment_key: str) -> bool:
252
+ """Whether the attachment has file content behind it.
253
+
254
+ Zotero records an md5 for files it stores itself. A file that went
255
+ straight to WebDAV has no md5 on the item; there the ``<KEY>.prop``
256
+ sidecar, written only after the zip upload completes, is the proof.
257
+ """
258
+ try:
259
+ from zotero_mcp.client import get_zotero_client
260
+ data = get_zotero_client().item(attachment_key).get("data", {})
261
+ except Exception:
262
+ return True # cannot tell: keep zotero-mcp's verdict
263
+ if data.get("md5"):
264
+ return True
265
+ try:
266
+ import requests
267
+ from zotero_mcp.webdav import get_webdav_config
268
+ config = get_webdav_config()
269
+ if not config:
270
+ return False
271
+ base, user, password = config
272
+ r = requests.head(f"{base}{attachment_key}.prop", auth=(user, password), timeout=15)
273
+ except Exception:
274
+ return True
275
+ return r.status_code != 404
276
+
277
+
278
+ def _localhost_ipv4_only() -> None:
279
+ """Resolve ``localhost`` to 127.0.0.1 only.
280
+
281
+ Zotero's local API listens on IPv4; on Windows ``localhost`` tries ::1
282
+ first and every request then waits ~2 s for that to fail, which made a
283
+ single push take 30-60 s.
284
+ """
285
+ orig = socket.getaddrinfo
286
+
287
+ def getaddrinfo(host, *args, **kwargs):
288
+ if host == "localhost":
289
+ host = "127.0.0.1"
290
+ return orig(host, *args, **kwargs)
291
+
292
+ socket.getaddrinfo = getaddrinfo
293
+
294
+
295
+ def main() -> int:
296
+ req = json.loads(sys.stdin.read())
297
+ _localhost_ipv4_only()
298
+ # zotero-mcp may print progress; keep stdout for the one result line.
299
+ with contextlib.redirect_stdout(sys.stderr):
300
+ try:
301
+ result = run(req)
302
+ except Exception as e: # report, never a traceback on stdout
303
+ result = {"success": False, "error": f"{type(e).__name__}: {e}"}
304
+ print(json.dumps(result, ensure_ascii=False))
305
+ return 0 if result.get("success") else 1
306
+
307
+
308
+ if __name__ == "__main__":
309
+ sys.exit(main())
@@ -0,0 +1,317 @@
1
+ """Zotero integration through zotero-mcp (github.com/54yyyu/zotero-mcp).
2
+
3
+ Everything goes through zotero-mcp's own code, run in its interpreter by
4
+ zotero_bridge.py: with local writes authorized it writes to the Zotero app on
5
+ this computer and Zotero syncs. LitLoop has no Zotero web-API code of its own.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import os
12
+ from pathlib import Path
13
+ from typing import Any
14
+
15
+ from ..log import get_logger
16
+
17
+ log = get_logger()
18
+
19
+
20
+ _PY_NAMES = ("python.exe", "python") if os.name == "nt" else ("python3", "python")
21
+ _VENV_BIN = "Scripts" if os.name == "nt" else "bin"
22
+ _DISCOVERED: dict[str, Any] | None = None
23
+
24
+
25
+ def _venv_python(bin_dir: Path) -> Path | None:
26
+ for name in _PY_NAMES:
27
+ p = bin_dir / name
28
+ if p.is_file():
29
+ return p
30
+ return None
31
+
32
+
33
+ def _tool_venv_pythons() -> list[Path]:
34
+ """Interpreters of zotero-mcp installed with `uv tool` or pipx."""
35
+ import shutil
36
+ import subprocess
37
+
38
+ roots: list[Path] = []
39
+ if shutil.which("uv"):
40
+ try:
41
+ out = subprocess.run(["uv", "tool", "dir"], capture_output=True,
42
+ text=True, timeout=10).stdout.strip()
43
+ if out:
44
+ roots.append(Path(out))
45
+ except (OSError, subprocess.SubprocessError):
46
+ pass
47
+ home = Path.home()
48
+ appdata = os.environ.get("APPDATA")
49
+ if appdata:
50
+ roots.append(Path(appdata) / "uv" / "tools")
51
+ roots += [home / ".local" / "share" / "uv" / "tools",
52
+ home / ".local" / "pipx" / "venvs", home / "pipx" / "venvs"]
53
+ if os.environ.get("PIPX_HOME"):
54
+ roots.append(Path(os.environ["PIPX_HOME"]) / "venvs")
55
+ found = []
56
+ for root in roots:
57
+ py = _venv_python(root / "zotero-mcp-server" / _VENV_BIN)
58
+ if py and py not in found:
59
+ found.append(py)
60
+ return found
61
+
62
+
63
+ def _resolve_server_entry(entry: dict[str, Any]) -> dict[str, Any] | None:
64
+ """Map an MCP client's zotero server entry to the Python that runs it."""
65
+ import shutil
66
+
67
+ cmd = str(entry.get("command") or "")
68
+ args = [str(a) for a in entry.get("args") or []]
69
+ env = {k: str(v) for k, v in (entry.get("env") or {}).items()}
70
+ base = Path(cmd).name.lower()
71
+ exe = Path(cmd) if Path(cmd).is_absolute() else Path(shutil.which(cmd) or cmd)
72
+
73
+ if base.startswith("python") or base == "py.exe":
74
+ if not exe.is_file():
75
+ return None
76
+ # `python launcher.py`: the launcher sets env, as the server would see it.
77
+ script = next((a for a in args if a.lower().endswith(".py")), "")
78
+ return {"python": exe, "env": env, "env_script": script}
79
+ if base.startswith("zotero-mcp"):
80
+ py = _venv_python(exe.parent) if exe.is_file() else None
81
+ if py:
82
+ return {"python": py, "env": env, "env_script": ""}
83
+ if base.startswith(("uv", "uvx", "pipx", "zotero-mcp")):
84
+ for py in _tool_venv_pythons():
85
+ return {"python": py, "env": env, "env_script": ""}
86
+ return None
87
+
88
+
89
+ def _mcp_client_configs() -> list[Path]:
90
+ home = Path.home()
91
+ paths = [home / ".claude.json", Path.cwd() / ".mcp.json"]
92
+ appdata = os.environ.get("APPDATA")
93
+ if appdata:
94
+ paths.append(Path(appdata) / "Claude" / "claude_desktop_config.json")
95
+ paths += [home / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
96
+ home / ".config" / "Claude" / "claude_desktop_config.json"]
97
+ return [p for p in paths if p.is_file()]
98
+
99
+
100
+ def _zotero_server_entries(cfg: dict[str, Any]) -> list[dict[str, Any]]:
101
+ blocks = [cfg.get("mcpServers") or {}]
102
+ for proj in (cfg.get("projects") or {}).values():
103
+ if isinstance(proj, dict):
104
+ blocks.append(proj.get("mcpServers") or {})
105
+ out = []
106
+ for block in blocks:
107
+ for name, entry in block.items():
108
+ if not isinstance(entry, dict):
109
+ continue
110
+ hay = " ".join([name, str(entry.get("command", ""))]
111
+ + [str(a) for a in entry.get("args") or []]).lower()
112
+ if "zotero" in hay:
113
+ out.append(entry)
114
+ return out
115
+
116
+
117
+ def discover_zotero_mcp(config: dict[str, Any]) -> dict[str, Any] | None:
118
+ """Find the Python that has zotero-mcp, plus the env its server runs with.
119
+
120
+ Order: explicit ``zotero_mcp_python``; zotero-mcp installed alongside
121
+ litloop; the zotero server registered in Claude Code / Claude Desktop;
122
+ `zotero-mcp` on PATH; uv-tool / pipx installs. ``zotero_mcp_python`` set to
123
+ "off" disables the route.
124
+ """
125
+ global _DISCOVERED
126
+ explicit = str(config.get("zotero_mcp_python") or "").strip()
127
+ if explicit.lower() == "off":
128
+ return None
129
+ if explicit and explicit.lower() != "auto":
130
+ path = Path(explicit).expanduser()
131
+ if not path.is_file():
132
+ return None
133
+ return {"python": path, "env": {},
134
+ "env_script": str(config.get("zotero_mcp_env_script") or "").strip()}
135
+ if _DISCOVERED is not None:
136
+ return _DISCOVERED or None
137
+
138
+ import importlib.util
139
+ import shutil
140
+ import sys
141
+
142
+ found: dict[str, Any] = {}
143
+ if importlib.util.find_spec("zotero_mcp") is not None:
144
+ found = {"python": Path(sys.executable), "env": {}, "env_script": ""}
145
+ if not found:
146
+ for cfg_path in _mcp_client_configs():
147
+ try:
148
+ cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
149
+ except (OSError, ValueError):
150
+ continue
151
+ for entry in _zotero_server_entries(cfg):
152
+ hit = _resolve_server_entry(entry)
153
+ if hit:
154
+ found = hit
155
+ break
156
+ if found:
157
+ break
158
+ if not found and shutil.which("zotero-mcp"):
159
+ hit = _resolve_server_entry({"command": "zotero-mcp"})
160
+ found = hit or {}
161
+ if not found:
162
+ pys = _tool_venv_pythons()
163
+ if pys:
164
+ found = {"python": pys[0], "env": {}, "env_script": ""}
165
+ if found and not found.get("env_script"):
166
+ found["env_script"] = str(config.get("zotero_mcp_env_script") or "").strip()
167
+ _DISCOVERED = found
168
+ if found:
169
+ log.info(f"Zotero: using zotero-mcp at {found['python']}")
170
+ return found or None
171
+
172
+
173
+ def push_via_zotero_mcp(
174
+ identifier: str,
175
+ pdf_path: Path | None,
176
+ config: dict[str, Any],
177
+ collections: list[str] | None = None,
178
+ tags: list[str] | None = None,
179
+ ) -> dict[str, Any]:
180
+ """File the paper with zotero-mcp's own add/attach code (zotero_bridge.py).
181
+
182
+ Runs in zotero-mcp's interpreter, so the item gets CrossRef metadata,
183
+ duplicates are reused, and the PDF goes to WebDAV when zotero-mcp is
184
+ configured for it.
185
+ """
186
+ found = discover_zotero_mcp(config)
187
+ if not found:
188
+ return {"success": False, "error": "zotero-mcp not found; install it "
189
+ "(pip install zotero-mcp-server) or set zotero_mcp_python"}
190
+ req = {
191
+ "identifier": identifier,
192
+ "file": str(pdf_path.resolve()) if pdf_path and pdf_path.is_file() else "",
193
+ "collections": collections or [],
194
+ "tags": tags or [],
195
+ }
196
+ # WebDAV uploads of large PDFs are allowed up to 600 s by zotero-mcp.
197
+ result = _run_bridge(found, req, int(config.get("zotero_push_timeout", 900)))
198
+ if result.get("success"):
199
+ log.info(f"Zotero (zotero-mcp): item {result.get('zotero_key')}, "
200
+ f"pdf_attached={result.get('pdf_attached')}")
201
+ return result
202
+
203
+
204
+ def zotero_collections(config: dict[str, Any]) -> dict[str, Any]:
205
+ """Every collection of the library as {key, name, parent, path} (read only)."""
206
+ found = discover_zotero_mcp(config)
207
+ if not found:
208
+ return {"success": False, "error": "zotero-mcp not found"}
209
+ return _run_bridge(found, {"op": "collections"}, 120)
210
+
211
+
212
+ def ensure_collection(path: str, config: dict[str, Any]) -> dict[str, Any]:
213
+ """The key of the collection at path ('LitLoop/My topic'), creating missing levels."""
214
+ found = discover_zotero_mcp(config)
215
+ if not found:
216
+ return {"success": False, "error": "zotero-mcp not found"}
217
+ return _run_bridge(found, {"op": "ensure_collection", "path": path}, 120)
218
+
219
+
220
+ def collection_dois(collection: str, config: dict[str, Any]) -> dict[str, Any]:
221
+ """DOIs of the items in a Zotero collection, given by '/'-path or key (read only).
222
+
223
+ Returns {"success", "key", "path", "dois", "without_doi"}; items without a DOI
224
+ (books, theses, web pages) are counted, not returned.
225
+ """
226
+ found = discover_zotero_mcp(config)
227
+ if not found:
228
+ return {"success": False, "error": "zotero-mcp not found"}
229
+ cols = _run_bridge(found, {"op": "collections"}, 120)
230
+ if not cols.get("success"):
231
+ return cols
232
+ want = collection.strip().strip("/")
233
+ hit = next((c for c in cols["collections"] if c["key"] == want or c["path"] == want), None)
234
+ if hit is None:
235
+ names = [c for c in cols["collections"] if c["name"] == want]
236
+ hit = names[0] if len(names) == 1 else None
237
+ if hit is None:
238
+ return {"success": False, "error": f"no Zotero collection {collection!r} (give its full path, e.g. A/B)"}
239
+ r = _run_bridge(found, {"op": "collection_items", "key": hit["key"]}, 120)
240
+ if not r.get("success"):
241
+ return r
242
+ dois = list(dict.fromkeys(i["doi"] for i in r["items"] if i.get("doi")))
243
+ return {"success": True, "key": hit["key"], "path": hit["path"], "dois": dois,
244
+ "without_doi": sum(1 for i in r["items"] if not i.get("doi"))}
245
+
246
+
247
+ def check_collection(key: str, config: dict[str, Any]) -> dict[str, Any]:
248
+ """Each item of the collection with its PDF state: ok, missing or empty (read only)."""
249
+ found = discover_zotero_mcp(config)
250
+ if not found:
251
+ return {"success": False, "error": "zotero-mcp not found"}
252
+ return _run_bridge(found, {"op": "check_collection", "key": key}, 600)
253
+
254
+
255
+ def repair_attachment(item_key: str, pdf: Path | None, trash: list[str], config: dict[str, Any]) -> dict[str, Any]:
256
+ """Move the item's empty attachments to the Zotero Trash, then attach pdf (when given)."""
257
+ found = discover_zotero_mcp(config)
258
+ if not found:
259
+ return {"success": False, "error": "zotero-mcp not found"}
260
+ req = {"op": "repair", "item_key": item_key, "trash": trash,
261
+ "file": str(pdf.resolve()) if pdf and pdf.is_file() else ""}
262
+ return _run_bridge(found, req, int(config.get("zotero_push_timeout", 900)))
263
+
264
+
265
+ def write_mode(config: dict[str, Any]) -> dict[str, Any]:
266
+ """How zotero-mcp writes: local (recommended), web, hybrid (local reads, web writes) or none."""
267
+ found = discover_zotero_mcp(config)
268
+ if not found:
269
+ return {"success": False, "error": "zotero-mcp not found"}
270
+ return _run_bridge(found, {"op": "write_mode"}, 60)
271
+
272
+
273
+ def authorize_local_writes(config: dict[str, Any]) -> dict[str, Any]:
274
+ """Ask Zotero for local-write permission; Zotero shows a dialog and this waits for the answer."""
275
+ found = discover_zotero_mcp(config)
276
+ if not found:
277
+ return {"success": False, "error": "zotero-mcp not found"}
278
+ return _run_bridge(found, {"op": "authorize"}, 120)
279
+
280
+
281
+ def _run_bridge(found: dict[str, Any], req: dict[str, Any], timeout: int) -> dict[str, Any]:
282
+ """Run zotero_bridge.py with zotero-mcp's interpreter: one JSON request in, one result out."""
283
+ import subprocess
284
+
285
+ python = found["python"]
286
+ env_script = found.get("env_script") or ""
287
+ req = {**req, "env_script": str(Path(env_script).expanduser()) if env_script else ""}
288
+ bridge = Path(__file__).with_name("bridge.py")
289
+ # The MCP client's env block for the zotero server (API key, WebDAV...).
290
+ env = dict(os.environ, **found.get("env", {}), PYTHONIOENCODING="utf-8", PYTHONUTF8="1")
291
+ try:
292
+ proc = subprocess.run(
293
+ [str(python), str(bridge)],
294
+ input=json.dumps(req, ensure_ascii=False),
295
+ capture_output=True,
296
+ text=True,
297
+ encoding="utf-8",
298
+ errors="replace",
299
+ env=env,
300
+ timeout=timeout,
301
+ creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
302
+ )
303
+ except subprocess.TimeoutExpired:
304
+ return {"success": False, "error": "zotero-mcp bridge timed out"}
305
+ except OSError as e:
306
+ return {"success": False, "error": f"cannot start zotero-mcp python: {e}"}
307
+
308
+ lines = [ln for ln in proc.stdout.splitlines() if ln.strip()]
309
+ try:
310
+ result = json.loads(lines[-1]) if lines else None
311
+ except json.JSONDecodeError:
312
+ result = None
313
+ if not isinstance(result, dict):
314
+ tail = (proc.stderr or proc.stdout or "").strip()[-500:]
315
+ return {"success": False, "error": f"zotero-mcp bridge failed (exit {proc.returncode}): {tail}"}
316
+ result["via"] = "zotero-mcp"
317
+ return result