litdb 2.1.9__tar.gz → 2.2.0__tar.gz

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 (47) hide show
  1. {litdb-2.1.9/src/litdb.egg-info → litdb-2.2.0}/PKG-INFO +1 -1
  2. {litdb-2.1.9 → litdb-2.2.0}/pyproject.toml +1 -1
  3. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/install.py +41 -7
  4. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/db.py +75 -18
  5. litdb-2.2.0/src/litdb/mcp_server.py +689 -0
  6. {litdb-2.1.9 → litdb-2.2.0/src/litdb.egg-info}/PKG-INFO +1 -1
  7. litdb-2.1.9/src/litdb/mcp_server.py +0 -168
  8. {litdb-2.1.9 → litdb-2.2.0}/LICENSE +0 -0
  9. {litdb-2.1.9 → litdb-2.2.0}/README.org +0 -0
  10. {litdb-2.1.9 → litdb-2.2.0}/setup.cfg +0 -0
  11. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/__init__.py +0 -0
  12. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/app.py +0 -0
  13. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/audio.py +0 -0
  14. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/bibtex.py +0 -0
  15. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/chat.py +0 -0
  16. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/cli.py +0 -0
  17. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/coa.py +0 -0
  18. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/__init__.py +0 -0
  19. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/data_processing.py +0 -0
  20. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/export.py +0 -0
  21. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/filters.py +0 -0
  22. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/manage.py +0 -0
  23. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/openalex_commands.py +0 -0
  24. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/research_commands.py +0 -0
  25. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/review.py +0 -0
  26. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/search.py +0 -0
  27. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/tags.py +0 -0
  28. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/commands/utilities.py +0 -0
  29. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/crawl.py +0 -0
  30. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/doe_collaborators.py +0 -0
  31. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/extract.py +0 -0
  32. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/gpt.py +0 -0
  33. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/images.py +0 -0
  34. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/lab.py +0 -0
  35. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/lsearch.py +0 -0
  36. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/openalex.py +0 -0
  37. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/pdf.py +0 -0
  38. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/research.py +0 -0
  39. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/server.py +0 -0
  40. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/summary.py +0 -0
  41. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/utils.py +0 -0
  42. {litdb-2.1.9 → litdb-2.2.0}/src/litdb/youtube.py +0 -0
  43. {litdb-2.1.9 → litdb-2.2.0}/src/litdb.egg-info/SOURCES.txt +0 -0
  44. {litdb-2.1.9 → litdb-2.2.0}/src/litdb.egg-info/dependency_links.txt +0 -0
  45. {litdb-2.1.9 → litdb-2.2.0}/src/litdb.egg-info/entry_points.txt +0 -0
  46. {litdb-2.1.9 → litdb-2.2.0}/src/litdb.egg-info/requires.txt +0 -0
  47. {litdb-2.1.9 → litdb-2.2.0}/src/litdb.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: litdb
3
- Version: 2.1.9
3
+ Version: 2.2.0
4
4
  Summary: A literature database tool with GPT integration.
5
5
  Author-email: John Kitchin <jkitchin@andrew.cmu.edu>
6
6
  Maintainer-email: John Kitchin <jkitchin@andrew.cmu.edu>
@@ -7,7 +7,7 @@ where = ["src"]
7
7
 
8
8
  [project]
9
9
  name = "litdb"
10
- version = "2.1.9"
10
+ version = "2.2.0"
11
11
  authors = [
12
12
  {name = "John Kitchin", email = "jkitchin@andrew.cmu.edu"},
13
13
  ]
@@ -62,7 +62,13 @@ def install_claude_skill():
62
62
  default=None,
63
63
  help="Path to litdb database. If not specified, uses the current database from config.",
64
64
  )
65
- def install_mcp_server(db):
65
+ @click.option(
66
+ "--yes",
67
+ "-y",
68
+ is_flag=True,
69
+ help="Skip confirmation prompt and install immediately.",
70
+ )
71
+ def install_mcp_server(db, yes):
66
72
  """Install the litdb MCP server for Claude Desktop.
67
73
 
68
74
  This configures Claude Desktop to use litdb as an MCP server.
@@ -73,20 +79,28 @@ def install_mcp_server(db):
73
79
 
74
80
  try:
75
81
  config = get_config()
76
- litdb_root = config.get("LITDB_ROOT")
77
- if litdb_root:
78
- db = os.path.join(litdb_root, "litdb.libsql")
82
+ root = config.get("root")
83
+ if root:
84
+ db = os.path.join(root, "litdb.libsql")
79
85
  else:
80
86
  richprint(
81
- "[red]Error: No database path specified and LITDB_ROOT not in config[/red]"
87
+ "[red]Error: Could not determine database location from config[/red]"
88
+ )
89
+ richprint(
90
+ "[yellow]Run this command from a directory with litdb.toml or set LITDB_ROOT[/yellow]"
82
91
  )
83
92
  richprint(
84
- "[yellow]Use --db option to specify the database path[/yellow]"
93
+ "[yellow]Or use --db option to specify the database path explicitly[/yellow]"
85
94
  )
86
95
  raise click.Abort()
87
96
  except SystemExit:
88
97
  richprint("[red]Error: Could not load litdb config[/red]")
89
- richprint("[yellow]Use --db option to specify the database path[/yellow]")
98
+ richprint(
99
+ "[yellow]Make sure you are in a directory with litdb.toml[/yellow]"
100
+ )
101
+ richprint(
102
+ "[yellow]Or use --db option to specify the database path explicitly[/yellow]"
103
+ )
90
104
  raise click.Abort()
91
105
 
92
106
  # Expand path
@@ -95,8 +109,28 @@ def install_mcp_server(db):
95
109
 
96
110
  if not os.path.exists(db):
97
111
  richprint(f"[red]Error: Database not found at {db}[/red]")
112
+ richprint(
113
+ "[yellow]Make sure the database exists before installing the MCP server[/yellow]"
114
+ )
98
115
  raise click.Abort()
99
116
 
117
+ # Get database size for display
118
+ db_size_mb = os.path.getsize(db) / (1024 * 1024)
119
+
120
+ # Show details and ask for confirmation
121
+ richprint("\n[bold]MCP Server Installation Details:[/bold]")
122
+ richprint(f"[blue]Database path:[/blue] {db}")
123
+ richprint(f"[blue]Database size:[/blue] {db_size_mb:.2f} MB")
124
+
125
+ if not yes:
126
+ richprint(
127
+ "\n[yellow]This will configure Claude Desktop to use this litdb database.[/yellow]"
128
+ )
129
+ confirm = input("Continue with installation? (y/N): ")
130
+ if not confirm.lower().startswith("y"):
131
+ richprint("[yellow]Installation cancelled[/yellow]")
132
+ raise click.Abort()
133
+
100
134
  # Get Claude Desktop config file path based on platform
101
135
  if platform.system() == "Darwin":
102
136
  cfgfile = (
@@ -13,7 +13,6 @@ from sentence_transformers import SentenceTransformer
13
13
  from langchain_text_splitters import RecursiveCharacterTextSplitter
14
14
  from tqdm import tqdm
15
15
  import datetime
16
- import requests
17
16
  import bibtexparser
18
17
  from rich import print
19
18
 
@@ -157,18 +156,76 @@ def add_source(source, text, extra=None):
157
156
  db.commit()
158
157
 
159
158
 
160
- def get_citation(doi):
161
- """Get a citation string for doi."""
162
- config = get_config()
163
- citeas = "https://api.citeas.org/product/"
164
- cp = {"mailto": config["openalex"]["email"]}
165
-
166
- resp = requests.get(citeas + doi, cp)
167
- if resp.status_code == 200:
168
- cdata = resp.json()
169
- citations = cdata.get("citations", [])
170
- return citations[0]["citation"]
171
- else:
159
+ def get_citation(openalex_data):
160
+ """Generate a citation string from OpenAlex metadata with full author list.
161
+
162
+ Args:
163
+ openalex_data: dict containing OpenAlex work metadata
164
+
165
+ Returns:
166
+ str: formatted citation with all authors
167
+ """
168
+ if not openalex_data:
169
+ return None
170
+
171
+ try:
172
+ parts = []
173
+
174
+ # Title
175
+ title = openalex_data.get("title") or openalex_data.get("display_name")
176
+ if title:
177
+ parts.append(title)
178
+
179
+ # All authors (not truncated!)
180
+ if openalex_data.get("authorships"):
181
+ authors = [
182
+ a["author"]["display_name"]
183
+ for a in openalex_data["authorships"]
184
+ if a.get("author", {}).get("display_name")
185
+ ]
186
+ if authors:
187
+ parts.append(", ".join(authors))
188
+
189
+ # Journal/venue
190
+ host_venue = openalex_data.get("host_venue") or {}
191
+ venue = host_venue.get("display_name")
192
+ if venue:
193
+ parts.append(venue)
194
+
195
+ # Volume and issue
196
+ biblio = openalex_data.get("biblio") or {}
197
+ volume = biblio.get("volume")
198
+ issue = biblio.get("issue")
199
+
200
+ if volume and issue:
201
+ parts.append(f"{volume}({issue})")
202
+ elif volume:
203
+ parts.append(str(volume))
204
+
205
+ # Pages
206
+ first_page = biblio.get("first_page")
207
+ last_page = biblio.get("last_page")
208
+ if first_page and last_page:
209
+ parts.append(f"{first_page}-{last_page}")
210
+ elif first_page:
211
+ parts.append(str(first_page))
212
+
213
+ # Year
214
+ year = openalex_data.get("publication_year")
215
+ if year:
216
+ parts.append(f"({year})")
217
+
218
+ # DOI or URL
219
+ doi = openalex_data.get("doi")
220
+ if doi:
221
+ parts.append(doi)
222
+ elif openalex_data.get("id"):
223
+ parts.append(openalex_data["id"])
224
+
225
+ return " ".join(parts) if parts else None
226
+
227
+ except Exception as e:
228
+ print(f"Error generating citation: {e}")
172
229
  return None
173
230
 
174
231
 
@@ -197,7 +254,7 @@ def add_work(workid, references=False, citing=False, related=False):
197
254
  print(f"No id found for {workid}.\n{data}")
198
255
  return
199
256
 
200
- data["citation"] = get_citation(workid)
257
+ data["citation"] = get_citation(data)
201
258
  data["bibtex"] = dump_bibtex(data)
202
259
 
203
260
  add_source(workid, get_text(data), data)
@@ -210,7 +267,7 @@ def add_work(workid, references=False, citing=False, related=False):
210
267
  print(f"Something failed for {wid}. continuing")
211
268
  continue
212
269
  text = get_text(rdata)
213
- rdata["citation"] = get_citation(source)
270
+ rdata["citation"] = get_citation(rdata)
214
271
  rdata["bibtex"] = dump_bibtex(rdata)
215
272
  add_source(source, text, rdata)
216
273
 
@@ -222,7 +279,7 @@ def add_work(workid, references=False, citing=False, related=False):
222
279
  print(f"Something failed for {wid}. continuing")
223
280
  continue
224
281
  text = get_text(rdata)
225
- rdata["citation"] = get_citation(source)
282
+ rdata["citation"] = get_citation(rdata)
226
283
  rdata["bibtex"] = dump_bibtex(rdata)
227
284
  add_source(source, text, rdata)
228
285
 
@@ -252,7 +309,7 @@ def add_work(workid, references=False, citing=False, related=False):
252
309
  for work in tqdm(cdata["results"]):
253
310
  source = work.get("doi") or work["id"]
254
311
  text = get_text(work)
255
- work["citation"] = get_citation(source)
312
+ work["citation"] = get_citation(work)
256
313
  work["bibtex"] = dump_bibtex(work)
257
314
  add_source(source, text, work)
258
315
 
@@ -334,7 +391,7 @@ def update_filter(f, last_updated=None, silent=False):
334
391
 
335
392
  for work in tqdm(data["results"], disable=silent):
336
393
  source = work.get("doi") or work.get("id")
337
- citation = get_citation(source)
394
+ citation = get_citation(work)
338
395
  work["citation"] = citation
339
396
 
340
397
  bibtex = dump_bibtex(work)
@@ -0,0 +1,689 @@
1
+ """An MCP server for litdb.
2
+
3
+ Provides Claude-Desktop tools to interact with litdb. This is mostly a proof of
4
+ concept to retrieve information from litdb, and it does not currently support
5
+ modifying the litdb.
6
+
7
+ There is a cli, litdb_mcp, that runs the server. The cli is installed as a
8
+ script.
9
+
10
+ You can install the server using:
11
+
12
+ > litdb install mcp-server
13
+
14
+ and uninstall it with
15
+
16
+ > litdb install uninstall-mcp
17
+
18
+ This should work on Windows, but is untested there.
19
+
20
+ The mcp server provides the following tools:
21
+
22
+ CORE TOOLS:
23
+ about_litdb: Describes the server and database location.
24
+
25
+ vsearch: Performs a vector search in your litdb database. Returns formatted
26
+ summaries with title, authors, year, DOI, similarity score, and full abstract.
27
+
28
+ openalex: Performs a keyword search in OpenAlex API. Returns formatted summaries
29
+ with title, authors, year, venue, DOI, citation count, and full abstract.
30
+
31
+ SEARCH TOOLS:
32
+ fulltext_search: Full-text search using SQLite FTS5 with BM25 ranking. Supports
33
+ FTS5 query syntax (AND, OR, NOT). Returns snippets and relevance scores.
34
+
35
+ find_similar: Find articles similar to a given source using vector similarity.
36
+ Great for "more like this" discovery.
37
+
38
+ METADATA & CITATION TOOLS:
39
+ get_source_details: Get complete details for a specific source including full
40
+ metadata, abstract, and citation information.
41
+
42
+ get_citation: Generate a formatted citation string for a source.
43
+
44
+ get_bibtex: Generate a BibTeX entry for a source (for LaTeX/bibliography managers).
45
+
46
+ ORGANIZATION TOOLS:
47
+ list_tags: List all defined tags in the database.
48
+
49
+ get_tagged_articles: Get all articles with a specific tag.
50
+
51
+ NSF GRANT TOOLS:
52
+ generate_nsf_coa: Generate NSF Collaborators and Other Affiliations (COA) Table 4.
53
+ Creates an Excel file with co-authors from publications in the last 4 years, formatted
54
+ for NSF grant applications.
55
+
56
+ All tools return formatted, readable text with complete information.
57
+
58
+ """
59
+
60
+ from mcp.server.fastmcp import FastMCP
61
+ import requests
62
+ import json
63
+ import platform
64
+ import os
65
+ import shutil
66
+ import sys
67
+
68
+ from sentence_transformers import SentenceTransformer
69
+ import numpy as np
70
+ import libsql
71
+
72
+ from .bibtex import dump_bibtex
73
+ from .coa import get_coa
74
+
75
+
76
+ # Initialize FastMCP server
77
+ mcp = FastMCP("litdb")
78
+
79
+
80
+ # Note I added _litdb here because Claude Desktop had trouble with other
81
+ # functions named about...
82
+ @mcp.tool()
83
+ def about_litdb():
84
+ """Describe litdb."""
85
+ return f"""Litdb is a database of scientific literature.
86
+
87
+ The MCP server has three tools, this one, a vector search tool, and an
88
+ OpenAlex search integration.
89
+
90
+ Using the db at {os.environ["litdb"]}.
91
+ """
92
+
93
+
94
+ @mcp.tool()
95
+ def vsearch(query: str, n: int = 3) -> str:
96
+ """Do a vector search in your litdb.
97
+
98
+ QUERY: string, natural language query.
99
+ N: int, number of results to return.
100
+ """
101
+ db = libsql.connect(os.environ["litdb"])
102
+
103
+ model = SentenceTransformer("all-MiniLM-L6-v2")
104
+ emb = model.encode([query]).astype(np.float32).tobytes()
105
+
106
+ c = db.execute(
107
+ """select sources.source, sources.text,
108
+ sources.extra, vector_distance_cos(?, embedding)
109
+ from vector_top_k('embedding_idx', ?, ?)
110
+ join sources on sources.rowid = id""",
111
+ (emb, emb, n),
112
+ )
113
+
114
+ results = c.fetchall()
115
+
116
+ # Format results concisely to avoid hitting token limits
117
+ formatted_results = []
118
+ for i, (source, text, extra, distance) in enumerate(results, 1):
119
+ try:
120
+ extra_data = json.loads(extra) if extra else {}
121
+ title = extra_data.get("title") or extra_data.get(
122
+ "display_name", "No title"
123
+ )
124
+
125
+ # Get authors (limit to first 3)
126
+ authors = []
127
+ if extra_data.get("authorships"):
128
+ authors = [
129
+ a.get("author", {}).get("display_name", "Unknown")
130
+ for a in extra_data["authorships"][:3]
131
+ ]
132
+ if len(extra_data["authorships"]) > 3:
133
+ authors.append("et al.")
134
+
135
+ # Get publication year
136
+ year = extra_data.get("publication_year", "")
137
+
138
+ # Get abstract (full text)
139
+ abstract = extra_data.get("abstract", "")
140
+ if not abstract and text:
141
+ # Use first 500 chars of full text if no abstract
142
+ abstract = text[:500] + "..." if len(text) > 500 else text
143
+
144
+ result_text = f"{i}. {title}"
145
+ if authors:
146
+ result_text += f"\n Authors: {', '.join(authors)}"
147
+ if year:
148
+ result_text += f"\n Year: {year}"
149
+ result_text += f"\n Source: {source}"
150
+ result_text += f"\n Similarity: {1 - distance:.3f}"
151
+ if abstract:
152
+ result_text += f"\n Abstract: {abstract}"
153
+
154
+ formatted_results.append(result_text)
155
+ except Exception as e:
156
+ formatted_results.append(f"{i}. {source}\n Error: {str(e)}")
157
+
158
+ return "\n\n".join(formatted_results)
159
+
160
+
161
+ @mcp.tool()
162
+ def openalex(query: str, n: int = 5):
163
+ """Run a simple keyword query in OpenAlex.
164
+
165
+ Args:
166
+ query: string, natural language query.
167
+ n: int, number of results to return.
168
+ """
169
+ params = {"filter": f"default.search:{query}", "per_page": n}
170
+
171
+ resp = requests.get("https://api.openalex.org/works", params)
172
+ data = resp.json()
173
+
174
+ # Format results concisely to avoid hitting token limits
175
+ results = data.get("results", [])
176
+ formatted_results = []
177
+
178
+ for i, work in enumerate(results, 1):
179
+ title = work.get("title") or work.get("display_name", "No title")
180
+
181
+ # Get authors (limit to first 3)
182
+ authors = []
183
+ if work.get("authorships"):
184
+ authors = [
185
+ a.get("author", {}).get("display_name", "Unknown")
186
+ for a in work["authorships"][:3]
187
+ ]
188
+ if len(work["authorships"]) > 3:
189
+ authors.append("et al.")
190
+
191
+ # Get publication year
192
+ year = work.get("publication_year", "")
193
+
194
+ # Get abstract (full text)
195
+ abstract_inv = work.get("abstract_inverted_index", {})
196
+ if abstract_inv:
197
+ # Reconstruct abstract from inverted index
198
+ word_positions = []
199
+ for word, positions in abstract_inv.items():
200
+ for pos in positions:
201
+ word_positions.append((pos, word))
202
+ # Sort by position and join
203
+ word_positions.sort()
204
+ abstract = " ".join(word for pos, word in word_positions)
205
+ else:
206
+ abstract = ""
207
+
208
+ # Get DOI or OpenAlex ID
209
+ doi = work.get("doi") or work.get("id", "")
210
+
211
+ # Get journal/venue
212
+ venue = ""
213
+ if work.get("host_venue"):
214
+ venue = work["host_venue"].get("display_name", "")
215
+ elif work.get("primary_location", {}).get("source"):
216
+ venue = work["primary_location"]["source"].get("display_name", "")
217
+
218
+ result_text = f"{i}. {title}"
219
+ if authors:
220
+ result_text += f"\n Authors: {', '.join(authors)}"
221
+ if year:
222
+ result_text += f"\n Year: {year}"
223
+ if venue:
224
+ result_text += f"\n Venue: {venue}"
225
+ if doi:
226
+ result_text += f"\n DOI/ID: {doi}"
227
+ result_text += f"\n Citations: {work.get('cited_by_count', 0)}"
228
+ if abstract:
229
+ result_text += f"\n Abstract: {abstract}"
230
+
231
+ formatted_results.append(result_text)
232
+
233
+ if not formatted_results:
234
+ return "No results found for this query."
235
+
236
+ header = f"Found {data.get('meta', {}).get('count', len(results))} total results (showing {len(results)}):\n\n"
237
+ return header + "\n\n".join(formatted_results)
238
+
239
+
240
+ @mcp.tool()
241
+ def fulltext_search(query: str, n: int = 3) -> str:
242
+ """Perform a full-text search using SQLite FTS5 with BM25 ranking.
243
+
244
+ Args:
245
+ query: Search query string (can use FTS5 syntax like AND, OR, NOT).
246
+ n: Number of results to return (default 3).
247
+
248
+ Returns:
249
+ Formatted results with source, BM25 score, and text snippet.
250
+ """
251
+ db = libsql.connect(os.environ["litdb"])
252
+
253
+ results = db.execute(
254
+ """select
255
+ sources.source, sources.text, snippet(fulltext, 1, '', '', '', 16),
256
+ sources.extra, bm25(fulltext)
257
+ from fulltext
258
+ inner join sources on fulltext.source = sources.source
259
+ where fulltext.text match ? order by rank limit ?""",
260
+ (query, n),
261
+ ).fetchall()
262
+
263
+ if not results:
264
+ return f"No results found for query: {query}"
265
+
266
+ formatted_results = []
267
+ for i, (source, text, snippet, extra, score) in enumerate(results, 1):
268
+ try:
269
+ extra_data = json.loads(extra) if extra else {}
270
+ title = extra_data.get("title") or extra_data.get(
271
+ "display_name", "No title"
272
+ )
273
+
274
+ # Get authors (limit to first 3)
275
+ authors = []
276
+ if extra_data.get("authorships"):
277
+ authors = [
278
+ a.get("author", {}).get("display_name", "Unknown")
279
+ for a in extra_data["authorships"][:3]
280
+ ]
281
+ if len(extra_data["authorships"]) > 3:
282
+ authors.append("et al.")
283
+
284
+ year = extra_data.get("publication_year", "")
285
+
286
+ result_text = f"{i}. {title}"
287
+ if authors:
288
+ result_text += f"\n Authors: {', '.join(authors)}"
289
+ if year:
290
+ result_text += f"\n Year: {year}"
291
+ result_text += f"\n Source: {source}"
292
+ result_text += f"\n BM25 Score: {abs(score):.3f}"
293
+ result_text += f"\n Snippet: {snippet}"
294
+
295
+ formatted_results.append(result_text)
296
+ except Exception as e:
297
+ formatted_results.append(
298
+ f"{i}. {source}\n Snippet: {snippet}\n Error: {str(e)}"
299
+ )
300
+
301
+ return "\n\n".join(formatted_results)
302
+
303
+
304
+ @mcp.tool()
305
+ def find_similar(source: str, n: int = 3) -> str:
306
+ """Find articles similar to a given source using vector similarity.
307
+
308
+ Args:
309
+ source: The source identifier (DOI, URL, or path) to find similar articles for.
310
+ n: Number of similar articles to return (default 3).
311
+
312
+ Returns:
313
+ Formatted list of similar articles with metadata.
314
+ """
315
+ db = libsql.connect(os.environ["litdb"])
316
+
317
+ # Get the embedding for the source
318
+ try:
319
+ result = db.execute(
320
+ """select embedding from sources where source = ?""", (source,)
321
+ ).fetchone()
322
+
323
+ if not result:
324
+ return f"Source not found: {source}"
325
+
326
+ (emb,) = result
327
+ except Exception as e:
328
+ return f"Error retrieving source embedding: {str(e)}"
329
+
330
+ # Find similar sources (we get n+1 because the first is always the source itself)
331
+ allrows = db.execute(
332
+ """select sources.source, sources.text, sources.extra
333
+ from vector_top_k('embedding_idx', ?, ?)
334
+ join sources on sources.rowid = id""",
335
+ (emb, n + 1),
336
+ ).fetchall()
337
+
338
+ # Skip the first result (the source itself)
339
+ rows = allrows[1:]
340
+
341
+ if not rows:
342
+ return f"No similar articles found for: {source}"
343
+
344
+ formatted_results = []
345
+ for i, (sim_source, text, extra) in enumerate(rows, 1):
346
+ try:
347
+ extra_data = json.loads(extra) if extra else {}
348
+ title = extra_data.get("title") or extra_data.get(
349
+ "display_name", "No title"
350
+ )
351
+
352
+ # Get authors (limit to first 3)
353
+ authors = []
354
+ if extra_data.get("authorships"):
355
+ authors = [
356
+ a.get("author", {}).get("display_name", "Unknown")
357
+ for a in extra_data["authorships"][:3]
358
+ ]
359
+ if len(extra_data["authorships"]) > 3:
360
+ authors.append("et al.")
361
+
362
+ year = extra_data.get("publication_year", "")
363
+ citation = extra_data.get("citation", "")
364
+
365
+ result_text = f"{i}. {title}"
366
+ if authors:
367
+ result_text += f"\n Authors: {', '.join(authors)}"
368
+ if year:
369
+ result_text += f"\n Year: {year}"
370
+ result_text += f"\n Source: {sim_source}"
371
+ if citation:
372
+ result_text += f"\n Citation: {citation}"
373
+
374
+ formatted_results.append(result_text)
375
+ except Exception as e:
376
+ formatted_results.append(f"{i}. {sim_source}\n Error: {str(e)}")
377
+
378
+ return f"Articles similar to {source}:\n\n" + "\n\n".join(formatted_results)
379
+
380
+
381
+ @mcp.tool()
382
+ def get_source_details(source: str) -> str:
383
+ """Get complete details for a specific source.
384
+
385
+ Args:
386
+ source: The source identifier (DOI, URL, or path).
387
+
388
+ Returns:
389
+ Complete source information including full text and metadata.
390
+ """
391
+ db = libsql.connect(os.environ["litdb"])
392
+
393
+ result = db.execute(
394
+ """select source, text, extra from sources where source = ?""",
395
+ (source,),
396
+ ).fetchone()
397
+
398
+ if not result:
399
+ return f"Source not found: {source}"
400
+
401
+ source_id, text, extra = result
402
+
403
+ try:
404
+ extra_data = json.loads(extra) if extra else {}
405
+
406
+ title = extra_data.get("title") or extra_data.get("display_name", "No title")
407
+
408
+ # Get full author list
409
+ authors = []
410
+ if extra_data.get("authorships"):
411
+ authors = [
412
+ a.get("author", {}).get("display_name", "Unknown")
413
+ for a in extra_data["authorships"]
414
+ ]
415
+
416
+ year = extra_data.get("publication_year", "")
417
+ doi = extra_data.get("doi", "")
418
+ citation = extra_data.get("citation", "")
419
+ abstract = extra_data.get("abstract", "")
420
+ venue = ""
421
+ if extra_data.get("host_venue"):
422
+ venue = extra_data["host_venue"].get("display_name", "")
423
+ elif extra_data.get("primary_location", {}).get("source"):
424
+ venue = extra_data["primary_location"]["source"].get("display_name", "")
425
+
426
+ cited_by_count = extra_data.get("cited_by_count", 0)
427
+ referenced_works_count = extra_data.get("referenced_works_count", 0)
428
+
429
+ output = f"Title: {title}\n"
430
+ if authors:
431
+ output += f"Authors: {', '.join(authors)}\n"
432
+ if year:
433
+ output += f"Year: {year}\n"
434
+ if venue:
435
+ output += f"Venue: {venue}\n"
436
+ if doi:
437
+ output += f"DOI: {doi}\n"
438
+ output += f"Source: {source_id}\n"
439
+ output += f"Citations: {cited_by_count}\n"
440
+ output += f"References: {referenced_works_count}\n"
441
+ if citation:
442
+ output += f"\nFormatted Citation:\n{citation}\n"
443
+ if abstract:
444
+ output += f"\nAbstract:\n{abstract}\n"
445
+ else:
446
+ # Use first 1000 chars of text if no abstract
447
+ text_preview = text[:1000] + "..." if len(text) > 1000 else text
448
+ output += f"\nText Preview:\n{text_preview}\n"
449
+
450
+ return output
451
+ except Exception as e:
452
+ return f"Error formatting source details: {str(e)}"
453
+
454
+
455
+ @mcp.tool()
456
+ def get_citation(source: str) -> str:
457
+ """Generate a formatted citation string for a source.
458
+
459
+ Args:
460
+ source: The source identifier (DOI, URL, or path).
461
+
462
+ Returns:
463
+ Formatted citation string.
464
+ """
465
+ db = libsql.connect(os.environ["litdb"])
466
+
467
+ result = db.execute(
468
+ """select json_extract(extra, '$.citation') from sources where source = ?""",
469
+ (source,),
470
+ ).fetchone()
471
+
472
+ if not result:
473
+ return f"Source not found: {source}"
474
+
475
+ (citation,) = result
476
+
477
+ if not citation:
478
+ return f"No citation available for: {source}"
479
+
480
+ return citation
481
+
482
+
483
+ @mcp.tool()
484
+ def get_bibtex(source: str) -> str:
485
+ """Generate a BibTeX entry for a source.
486
+
487
+ Args:
488
+ source: The source identifier (DOI, URL, or path).
489
+
490
+ Returns:
491
+ BibTeX formatted entry.
492
+ """
493
+ db = libsql.connect(os.environ["litdb"])
494
+
495
+ result = db.execute(
496
+ """select extra from sources where source = ?""", (source,)
497
+ ).fetchone()
498
+
499
+ if not result:
500
+ return f"Source not found: {source}"
501
+
502
+ (extra,) = result
503
+
504
+ if not extra:
505
+ return f"No metadata available for BibTeX generation: {source}"
506
+
507
+ try:
508
+ extra_data = json.loads(extra)
509
+ bibtex = dump_bibtex(extra_data)
510
+ return bibtex
511
+ except Exception as e:
512
+ return f"Error generating BibTeX: {str(e)}"
513
+
514
+
515
+ @mcp.tool()
516
+ def list_tags() -> str:
517
+ """List all defined tags in the database.
518
+
519
+ Returns:
520
+ List of all tags.
521
+ """
522
+ db = libsql.connect(os.environ["litdb"])
523
+
524
+ results = db.execute("select tag from tags").fetchall()
525
+
526
+ if not results:
527
+ return "No tags defined in the database."
528
+
529
+ tags = [tag for (tag,) in results]
530
+ return "Defined tags:\n" + "\n".join(f"- {tag}" for tag in tags)
531
+
532
+
533
+ @mcp.tool()
534
+ def get_tagged_articles(tag: str) -> str:
535
+ """Get all articles with a specific tag.
536
+
537
+ Args:
538
+ tag: The tag name to search for.
539
+
540
+ Returns:
541
+ Formatted list of articles with the specified tag.
542
+ """
543
+ db = libsql.connect(os.environ["litdb"])
544
+
545
+ results = db.execute(
546
+ """select
547
+ sources.source, sources.text, sources.extra
548
+ from sources
549
+ inner join source_tag on source_tag.source_id = sources.rowid
550
+ inner join tags on source_tag.tag_id = tags.rowid
551
+ where tags.tag = ?""",
552
+ (tag,),
553
+ ).fetchall()
554
+
555
+ if not results:
556
+ return f"No articles found with tag: {tag}"
557
+
558
+ formatted_results = []
559
+ for i, (source, text, extra) in enumerate(results, 1):
560
+ try:
561
+ extra_data = json.loads(extra) if extra else {}
562
+ title = extra_data.get("title") or extra_data.get(
563
+ "display_name", "No title"
564
+ )
565
+
566
+ # Get authors (limit to first 3)
567
+ authors = []
568
+ if extra_data.get("authorships"):
569
+ authors = [
570
+ a.get("author", {}).get("display_name", "Unknown")
571
+ for a in extra_data["authorships"][:3]
572
+ ]
573
+ if len(extra_data["authorships"]) > 3:
574
+ authors.append("et al.")
575
+
576
+ year = extra_data.get("publication_year", "")
577
+ citation = extra_data.get("citation", "")
578
+
579
+ result_text = f"{i}. {title}"
580
+ if authors:
581
+ result_text += f"\n Authors: {', '.join(authors)}"
582
+ if year:
583
+ result_text += f"\n Year: {year}"
584
+ result_text += f"\n Source: {source}"
585
+ if citation:
586
+ result_text += f"\n Citation: {citation}"
587
+
588
+ formatted_results.append(result_text)
589
+ except Exception as e:
590
+ formatted_results.append(f"{i}. {source}\n Error: {str(e)}")
591
+
592
+ return f"Articles tagged with '{tag}' ({len(results)} found):\n\n" + "\n\n".join(
593
+ formatted_results
594
+ )
595
+
596
+
597
+ @mcp.tool()
598
+ def generate_nsf_coa(orcid: str, email: str = None) -> str:
599
+ """Generate NSF Collaborators and Other Affiliations (COA) Table 4.
600
+
601
+ Creates an Excel file with co-authors from publications in the last 4 years.
602
+
603
+ Args:
604
+ orcid: The ORCID identifier (with or without https://orcid.org/ prefix).
605
+ email: Optional email for OpenAlex API polite pool (recommended for better rate limits).
606
+
607
+ Returns:
608
+ Status message with the filename of the generated Excel file.
609
+ """
610
+ try:
611
+ get_coa(orcid, email)
612
+ # The get_coa function prints the filename, so we extract it from the pattern
613
+ import datetime
614
+
615
+ orcid_clean = orcid.replace("https://orcid.org/", "")
616
+ today = datetime.date.today().strftime("%Y-%m-%d.xlsx")
617
+ filename = f"{orcid_clean}-{today}"
618
+
619
+ return f"Successfully generated NSF COA file: {filename}\n\nThe file contains:\n- Table 4: Unique co-authors with their affiliations and last active dates\n- All authors sheet: Complete list of all co-authors from each publication\n\nThis includes all co-authors from publications in the last 4 years."
620
+ except Exception as e:
621
+ return f"Error generating NSF COA file: {str(e)}"
622
+
623
+
624
+ def main():
625
+ """Install, uninstall, or run the server.
626
+
627
+ This is the cli. If you call it with install or uninstall as an argument, it
628
+ will do that in the Claude Desktop. With no arguments it just runs the
629
+ server.
630
+ """
631
+ if platform.system() == "Darwin":
632
+ cfgfile = "~/Library/Application Support/Claude/claude_desktop_config.json"
633
+ elif platform.system() == "Windows":
634
+ cfgfile = r"%APPDATA%\Claude\claude_desktop_config.json"
635
+ else:
636
+ raise Exception(
637
+ "Only Mac and Windows are supported for the claude-light mcp server"
638
+ )
639
+
640
+ cfgfile = os.path.expandvars(cfgfile)
641
+ cfgfile = os.path.expanduser(cfgfile)
642
+
643
+ if os.path.exists(cfgfile):
644
+ with open(cfgfile, "r") as f:
645
+ cfg = json.loads(f.read())
646
+ else:
647
+ cfg = {}
648
+
649
+ # Called with no arguments
650
+ if len(sys.argv) == 1:
651
+ mcp.run(transport="stdio")
652
+
653
+ elif sys.argv[1] == "install":
654
+ db = sys.argv[2]
655
+
656
+ setup = {
657
+ "command": shutil.which("litdb_mcp"),
658
+ "env": {"litdb": db, "LITDB_ROOT": os.path.dirname(os.path.abspath(db))},
659
+ }
660
+
661
+ if "mcpServers" not in cfg:
662
+ cfg["mcpServers"] = {}
663
+
664
+ cfg["mcpServers"]["litdb"] = setup
665
+ with open(cfgfile, "w") as f:
666
+ f.write(json.dumps(cfg, indent=4))
667
+
668
+ print(
669
+ f"\n\nInstalled litdb. Here is your current {cfgfile}."
670
+ " Please restart Claude Desktop."
671
+ )
672
+ print(json.dumps(cfg, indent=4))
673
+
674
+ elif sys.argv[1] == "uninstall":
675
+ if "mcpServers" not in cfg:
676
+ cfg["mcpServers"] = {}
677
+
678
+ if "litdb" in cfg["mcpServers"]:
679
+ del cfg["mcpServers"]["litdb"]
680
+ with open(cfgfile, "w") as f:
681
+ f.write(json.dumps(cfg, indent=4))
682
+
683
+ print(f"Uninstalled litdb. Here is your current {cfgfile}.")
684
+ print(json.dumps(cfg, indent=4))
685
+
686
+ else:
687
+ print(
688
+ "I am not sure what you are trying to do. Please use install or uninstall."
689
+ )
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: litdb
3
- Version: 2.1.9
3
+ Version: 2.2.0
4
4
  Summary: A literature database tool with GPT integration.
5
5
  Author-email: John Kitchin <jkitchin@andrew.cmu.edu>
6
6
  Maintainer-email: John Kitchin <jkitchin@andrew.cmu.edu>
@@ -1,168 +0,0 @@
1
- """An MCP server for litdb.
2
-
3
- Provides Claude-Desktop tools to interact with litdb. This is mostly a proof of
4
- concept to retrieve information from litdb, and it does not currently support
5
- modifying the litdb.
6
-
7
- There is a cli, litdb_mcp, that runs the server. The cli is installed as a
8
- script.
9
-
10
- You can install the server using:
11
-
12
- > litdb_mcp install /path/to/litdb.libsql
13
-
14
- and uninstall it with
15
-
16
- > litdb_mcp uninstall
17
-
18
- This should work on Windows, but is untested there.
19
-
20
- The mcp server provides three tools:
21
-
22
- about: Just describes the server.
23
-
24
- vsearch: Performs a vector search from a query. The query is determined by
25
- Claude.
26
-
27
- openalex: Performs a keyword search from a query. the query is determined by
28
- Claude.
29
-
30
- """
31
-
32
- from mcp.server.fastmcp import FastMCP
33
- import requests
34
- import json
35
- import platform
36
- import os
37
- import shutil
38
- import sys
39
-
40
- from sentence_transformers import SentenceTransformer
41
- import numpy as np
42
- import libsql
43
-
44
-
45
- # Initialize FastMCP server
46
- mcp = FastMCP("litdb")
47
-
48
-
49
- # Note I added _litdb here because Claude Desktop had trouble with other
50
- # functions named about...
51
- @mcp.tool()
52
- def about_litdb():
53
- """Describe litdb."""
54
- return f"""Litdb is a database of scientific literature.
55
-
56
- The MCP server has three tools, this one, a vector search tool, and an
57
- OpenAlex search integration.
58
-
59
- Using the db at {os.environ["litdb"]}.
60
- """
61
-
62
-
63
- @mcp.tool()
64
- def vsearch(query: str, n: int = 3) -> str:
65
- """Do a vector search in your litdb.
66
-
67
- QUERY: string, natural language query.
68
- N: int, number of results to return.
69
- """
70
- db = libsql.connect(os.environ["litdb"])
71
-
72
- model = SentenceTransformer("all-MiniLM-L6-v2")
73
- emb = model.encode([query]).astype(np.float32).tobytes()
74
-
75
- c = db.execute(
76
- """select sources.source, sources.text,
77
- sources.extra, vector_distance_cos(?, embedding)
78
- from vector_top_k('embedding_idx', ?, ?)
79
- join sources on sources.rowid = id""",
80
- (emb, emb, n),
81
- )
82
-
83
- results = c.fetchall()
84
-
85
- return str(results)
86
-
87
-
88
- @mcp.tool()
89
- def openalex(query: str, n: int = 5):
90
- """Run a simple keyword query in OpenAlex.
91
-
92
- Args:
93
- query: string, natural language query.
94
- n: int, number of results to return.
95
- """
96
- params = {"filter": f"default.search:{query}", "per_page": n}
97
-
98
- resp = requests.get("https://api.openalex.org/works", params)
99
- data = resp.json()
100
- return data
101
-
102
-
103
- def main():
104
- """Install, uninstall, or run the server.
105
-
106
- This is the cli. If you call it with install or uninstall as an argument, it
107
- will do that in the Claude Desktop. With no arguments it just runs the
108
- server.
109
- """
110
- if platform.system() == "Darwin":
111
- cfgfile = "~/Library/Application Support/Claude/claude_desktop_config.json"
112
- elif platform.system() == "Windows":
113
- cfgfile = r"%APPDATA%\Claude\claude_desktop_config.json"
114
- else:
115
- raise Exception(
116
- "Only Mac and Windows are supported for the claude-light mcp server"
117
- )
118
-
119
- cfgfile = os.path.expandvars(cfgfile)
120
- cfgfile = os.path.expanduser(cfgfile)
121
-
122
- if os.path.exists(cfgfile):
123
- with open(cfgfile, "r") as f:
124
- cfg = json.loads(f.read())
125
- else:
126
- cfg = {}
127
-
128
- # Called with no arguments
129
- if len(sys.argv) == 1:
130
- mcp.run(transport="stdio")
131
-
132
- elif sys.argv[1] == "install":
133
- db = sys.argv[2]
134
-
135
- setup = {
136
- "command": shutil.which("litdb_mcp"),
137
- "env": {"litdb": db, "LITDB_ROOT": os.path.dirname(os.path.abspath(db))},
138
- }
139
-
140
- if "mcpServers" not in cfg:
141
- cfg["mcpServers"] = {}
142
-
143
- cfg["mcpServers"]["litdb"] = setup
144
- with open(cfgfile, "w") as f:
145
- f.write(json.dumps(cfg, indent=4))
146
-
147
- print(
148
- f"\n\nInstalled litdb. Here is your current {cfgfile}."
149
- " Please restart Claude Desktop."
150
- )
151
- print(json.dumps(cfg, indent=4))
152
-
153
- elif sys.argv[1] == "uninstall":
154
- if "mcpServers" not in cfg:
155
- cfg["mcpServers"] = {}
156
-
157
- if "litdb" in cfg["mcpServers"]:
158
- del cfg["mcpServers"]["litdb"]
159
- with open(cfgfile, "w") as f:
160
- f.write(json.dumps(cfg, indent=4))
161
-
162
- print(f"Uninstalled litdb. Here is your current {cfgfile}.")
163
- print(json.dumps(cfg, indent=4))
164
-
165
- else:
166
- print(
167
- "I am not sure what you are trying to do. Please use install or uninstall."
168
- )
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes