litdb 2.2.2__tar.gz → 2.2.3__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 (46) hide show
  1. {litdb-2.2.2/src/litdb.egg-info → litdb-2.2.3}/PKG-INFO +92 -6
  2. {litdb-2.2.2 → litdb-2.2.3}/README.org +91 -5
  3. {litdb-2.2.2 → litdb-2.2.3}/pyproject.toml +1 -1
  4. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/install.py +8 -2
  5. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/mcp_server.py +50 -18
  6. {litdb-2.2.2 → litdb-2.2.3/src/litdb.egg-info}/PKG-INFO +92 -6
  7. {litdb-2.2.2 → litdb-2.2.3}/LICENSE +0 -0
  8. {litdb-2.2.2 → litdb-2.2.3}/setup.cfg +0 -0
  9. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/__init__.py +0 -0
  10. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/app.py +0 -0
  11. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/audio.py +0 -0
  12. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/bibtex.py +0 -0
  13. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/chat.py +0 -0
  14. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/cli.py +0 -0
  15. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/coa.py +0 -0
  16. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/__init__.py +0 -0
  17. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/data_processing.py +0 -0
  18. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/export.py +0 -0
  19. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/filters.py +0 -0
  20. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/manage.py +0 -0
  21. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/openalex_commands.py +0 -0
  22. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/research_commands.py +0 -0
  23. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/review.py +0 -0
  24. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/search.py +0 -0
  25. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/tags.py +0 -0
  26. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/utilities.py +0 -0
  27. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/crawl.py +0 -0
  28. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/db.py +0 -0
  29. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/doe_collaborators.py +0 -0
  30. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/extract.py +0 -0
  31. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/gpt.py +0 -0
  32. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/images.py +0 -0
  33. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/lab.py +0 -0
  34. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/lsearch.py +0 -0
  35. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/openalex.py +0 -0
  36. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/pdf.py +0 -0
  37. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/research.py +0 -0
  38. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/server.py +0 -0
  39. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/summary.py +0 -0
  40. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/utils.py +0 -0
  41. {litdb-2.2.2 → litdb-2.2.3}/src/litdb/youtube.py +0 -0
  42. {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/SOURCES.txt +0 -0
  43. {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/dependency_links.txt +0 -0
  44. {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/entry_points.txt +0 -0
  45. {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/requires.txt +0 -0
  46. {litdb-2.2.2 → litdb-2.2.3}/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.2.2
3
+ Version: 2.2.3
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>
@@ -112,6 +112,9 @@ Dynamic: license-file
112
112
  <img src="https://github.com/jkitchin/litdb/actions/workflows/build.yml/badge.svg" alt="Build Status">
113
113
  </a>
114
114
  <img src="https://img.shields.io/badge/tests-133_passed,_66_skipped-brightgreen" alt="Tests">
115
+ <a href="https://doi.org/10.5281/zenodo.23514948">
116
+ <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23514948.svg" alt="DOI">
117
+ </a>
115
118
  #+END_HTML
116
119
 
117
120
  * litdb concept
@@ -158,7 +161,13 @@ source .venv/bin/activate
158
161
  uv pip install litdb
159
162
  #+END_SRC
160
163
 
161
- You have to activate that virtual env to use litdb, which may be annoying.
164
+ You have to activate that virtual env to use litdb, which may be annoying. An alternative is to install litdb as a uv tool, which puts ~litdb~ and ~litdb_mcp~ on your PATH in their own environment:
165
+
166
+ #+BEGIN_SRC sh
167
+ uv tool install litdb
168
+ #+END_SRC
169
+
170
+ This is also the easiest way to make the MCP server available to AI agents. See [[*Using litdb with AI agents (skill and MCP server)]].
162
171
 
163
172
  ** Recent additions
164
173
 
@@ -811,16 +820,93 @@ litdb schema paper.pdf '{"title": ["str", None], "year": ["int", 2024]}'
811
820
 
812
821
  The schema command first converts the document to markdown using Docling, then uses an LLM with structured output to extract the requested fields. The LLM model used is configured in the ~[llm]~ section of your ~litdb.toml~ file.
813
822
 
814
- ** Claude Desktop + MCP
823
+ ** Using litdb with AI agents (skill and MCP server)
824
+
825
+ litdb comes with two things for AI coding agents such as Claude Code, VS Code (GitHub Copilot), Cursor, Codex, OpenCode and Gemini CLI:
826
+
827
+ - An *agent skill* ([[./skills/litdb/SKILL.md][skills/litdb/SKILL.md]]) that teaches the agent how to use the litdb CLI: adding papers, searching, filters, tags, exporting BibTeX, and so on.
828
+ - An *MCP server* (~litdb_mcp~) that gives the agent direct, read-only tools for your database: ~vsearch~, ~fulltext_search~, ~find_similar~, ~openalex~, ~get_source_details~, ~get_citation~, ~get_bibtex~, ~list_tags~, ~get_tagged_articles~ and ~generate_nsf_coa~.
829
+
830
+ The easiest way to install both is [[https://github.com/jkitchin/knowhow][knowhow]], which needs nothing installed besides [[https://github.com/astral-sh/uv][uv]]. The skill follows the [[https://agentskills.io/specification][Agent Skills specification]], so it also works with ~npx skills~.
831
+
832
+ *** Install the skill
815
833
 
816
834
  #+BEGIN_SRC sh
817
- litdb_mcp install /path/to/litdb.libsql
835
+ # See what litdb offers
836
+ uvx knowhow add jkitchin/litdb --list
837
+
838
+ # Install the skill in the current project
839
+ uvx knowhow add jkitchin/litdb --skill litdb
840
+
841
+ # or for your user, in every project
842
+ uvx knowhow add jkitchin/litdb --skill litdb -g
818
843
  #+END_SRC
819
844
 
820
- Then, restart Claude Desktop.
845
+ The skill is copied to ~.agents/skills/litdb~ (read by VS Code, Codex, OpenCode, Gemini CLI, Cursor and Copilot) and linked into ~.claude/skills/litdb~ for Claude Code. Then ask your agent things like "add the references of 10.1021/jp047349j to my litdb" or "make a bibtex file of everything tagged thesis".
846
+
847
+ Keep it up to date with ~uvx knowhow check~ and ~uvx knowhow upgrade~, and remove it with ~uvx knowhow remove litdb~.
848
+
849
+ If you work from a clone of this repository, ~litdb install claude-skill~ also copies the skill to ~~/.claude/skills/litdb~.
850
+
851
+ *** Install the MCP server
852
+
853
+ The MCP server runs the ~litdb_mcp~ command, so first make sure it is on your PATH (~uv tool install litdb~ does this). The server is defined in [[./mcp/litdb.json][mcp/litdb.json]], and knowhow translates it into each agent's config format:
854
+
855
+ #+BEGIN_SRC sh
856
+ # Claude Code, in this project (writes .mcp.json)
857
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code
858
+
859
+ # Claude Code for all your projects
860
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code -g
861
+
862
+ # Several agents at once
863
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code -a vscode -a cursor -a codex
864
+ #+END_SRC
821
865
 
822
- Now in the Claude Desktop app you can use prompts like "Search my litdb for references on alloy segregation" or "Search OpenAlex for articles on alloy segregation."
866
+ knowhow shows you the server config and asks for confirmation before installing it (add ~-y~ to skip the prompt).
867
+
868
+ The server needs to know which database to use. It looks for:
869
+
870
+ 1. the ~litdb~ environment variable, the path to a ~litdb.libsql~ file;
871
+ 2. a ~litdb.toml~ in the agent's working directory or one of its parents;
872
+ 3. the ~LITDB_ROOT~ environment variable, the directory that contains ~litdb.toml~.
873
+
874
+ The installed config passes ~LITDB_ROOT~ through from your environment, so set it in your shell profile before starting the agent:
875
+
876
+ #+BEGIN_SRC sh
877
+ export LITDB_ROOT=~/litdb # the directory with litdb.toml and litdb.libsql
878
+ #+END_SRC
879
+
880
+ To check it works in Claude Code, run ~/mcp~ and look for ~litdb~, or ask "what is in my litdb about alloy segregation?". Remove the server with ~uvx knowhow remove --mcp litdb~.
881
+
882
+ If you prefer to configure an agent by hand, this is the config (Claude Code ~.mcp.json~ format):
883
+
884
+ #+BEGIN_SRC json
885
+ {
886
+ "mcpServers": {
887
+ "litdb": {
888
+ "command": "litdb_mcp",
889
+ "env": {"LITDB_ROOT": "/path/to/your/litdb"}
890
+ }
891
+ }
892
+ }
893
+ #+END_SRC
894
+
895
+ or with the Claude Code CLI:
896
+
897
+ #+BEGIN_SRC sh
898
+ claude mcp add litdb --scope user -e LITDB_ROOT=/path/to/your/litdb -- litdb_mcp
899
+ #+END_SRC
900
+
901
+ *** Claude Desktop
902
+
903
+ Claude Desktop is not supported by knowhow. Instead, run this from your litdb directory (the one with ~litdb.toml~), or pass ~--db /path/to/litdb.libsql~:
904
+
905
+ #+BEGIN_SRC sh
906
+ litdb install mcp-server
907
+ #+END_SRC
823
908
 
909
+ Then restart Claude Desktop. Now you can use prompts like "Search my litdb for references on alloy segregation" or "Search OpenAlex for articles on alloy segregation." Uninstall it with ~litdb install uninstall-mcp~.
824
910
 
825
911
  * Adding local files
826
912
 
@@ -7,6 +7,9 @@
7
7
  <img src="https://github.com/jkitchin/litdb/actions/workflows/build.yml/badge.svg" alt="Build Status">
8
8
  </a>
9
9
  <img src="https://img.shields.io/badge/tests-133_passed,_66_skipped-brightgreen" alt="Tests">
10
+ <a href="https://doi.org/10.5281/zenodo.23514948">
11
+ <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23514948.svg" alt="DOI">
12
+ </a>
10
13
  #+END_HTML
11
14
 
12
15
  * litdb concept
@@ -53,7 +56,13 @@ source .venv/bin/activate
53
56
  uv pip install litdb
54
57
  #+END_SRC
55
58
 
56
- You have to activate that virtual env to use litdb, which may be annoying.
59
+ You have to activate that virtual env to use litdb, which may be annoying. An alternative is to install litdb as a uv tool, which puts ~litdb~ and ~litdb_mcp~ on your PATH in their own environment:
60
+
61
+ #+BEGIN_SRC sh
62
+ uv tool install litdb
63
+ #+END_SRC
64
+
65
+ This is also the easiest way to make the MCP server available to AI agents. See [[*Using litdb with AI agents (skill and MCP server)]].
57
66
 
58
67
  ** Recent additions
59
68
 
@@ -706,16 +715,93 @@ litdb schema paper.pdf '{"title": ["str", None], "year": ["int", 2024]}'
706
715
 
707
716
  The schema command first converts the document to markdown using Docling, then uses an LLM with structured output to extract the requested fields. The LLM model used is configured in the ~[llm]~ section of your ~litdb.toml~ file.
708
717
 
709
- ** Claude Desktop + MCP
718
+ ** Using litdb with AI agents (skill and MCP server)
719
+
720
+ litdb comes with two things for AI coding agents such as Claude Code, VS Code (GitHub Copilot), Cursor, Codex, OpenCode and Gemini CLI:
721
+
722
+ - An *agent skill* ([[./skills/litdb/SKILL.md][skills/litdb/SKILL.md]]) that teaches the agent how to use the litdb CLI: adding papers, searching, filters, tags, exporting BibTeX, and so on.
723
+ - An *MCP server* (~litdb_mcp~) that gives the agent direct, read-only tools for your database: ~vsearch~, ~fulltext_search~, ~find_similar~, ~openalex~, ~get_source_details~, ~get_citation~, ~get_bibtex~, ~list_tags~, ~get_tagged_articles~ and ~generate_nsf_coa~.
724
+
725
+ The easiest way to install both is [[https://github.com/jkitchin/knowhow][knowhow]], which needs nothing installed besides [[https://github.com/astral-sh/uv][uv]]. The skill follows the [[https://agentskills.io/specification][Agent Skills specification]], so it also works with ~npx skills~.
726
+
727
+ *** Install the skill
710
728
 
711
729
  #+BEGIN_SRC sh
712
- litdb_mcp install /path/to/litdb.libsql
730
+ # See what litdb offers
731
+ uvx knowhow add jkitchin/litdb --list
732
+
733
+ # Install the skill in the current project
734
+ uvx knowhow add jkitchin/litdb --skill litdb
735
+
736
+ # or for your user, in every project
737
+ uvx knowhow add jkitchin/litdb --skill litdb -g
713
738
  #+END_SRC
714
739
 
715
- Then, restart Claude Desktop.
740
+ The skill is copied to ~.agents/skills/litdb~ (read by VS Code, Codex, OpenCode, Gemini CLI, Cursor and Copilot) and linked into ~.claude/skills/litdb~ for Claude Code. Then ask your agent things like "add the references of 10.1021/jp047349j to my litdb" or "make a bibtex file of everything tagged thesis".
741
+
742
+ Keep it up to date with ~uvx knowhow check~ and ~uvx knowhow upgrade~, and remove it with ~uvx knowhow remove litdb~.
743
+
744
+ If you work from a clone of this repository, ~litdb install claude-skill~ also copies the skill to ~~/.claude/skills/litdb~.
745
+
746
+ *** Install the MCP server
747
+
748
+ The MCP server runs the ~litdb_mcp~ command, so first make sure it is on your PATH (~uv tool install litdb~ does this). The server is defined in [[./mcp/litdb.json][mcp/litdb.json]], and knowhow translates it into each agent's config format:
749
+
750
+ #+BEGIN_SRC sh
751
+ # Claude Code, in this project (writes .mcp.json)
752
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code
753
+
754
+ # Claude Code for all your projects
755
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code -g
756
+
757
+ # Several agents at once
758
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code -a vscode -a cursor -a codex
759
+ #+END_SRC
716
760
 
717
- Now in the Claude Desktop app you can use prompts like "Search my litdb for references on alloy segregation" or "Search OpenAlex for articles on alloy segregation."
761
+ knowhow shows you the server config and asks for confirmation before installing it (add ~-y~ to skip the prompt).
762
+
763
+ The server needs to know which database to use. It looks for:
764
+
765
+ 1. the ~litdb~ environment variable, the path to a ~litdb.libsql~ file;
766
+ 2. a ~litdb.toml~ in the agent's working directory or one of its parents;
767
+ 3. the ~LITDB_ROOT~ environment variable, the directory that contains ~litdb.toml~.
768
+
769
+ The installed config passes ~LITDB_ROOT~ through from your environment, so set it in your shell profile before starting the agent:
770
+
771
+ #+BEGIN_SRC sh
772
+ export LITDB_ROOT=~/litdb # the directory with litdb.toml and litdb.libsql
773
+ #+END_SRC
774
+
775
+ To check it works in Claude Code, run ~/mcp~ and look for ~litdb~, or ask "what is in my litdb about alloy segregation?". Remove the server with ~uvx knowhow remove --mcp litdb~.
776
+
777
+ If you prefer to configure an agent by hand, this is the config (Claude Code ~.mcp.json~ format):
778
+
779
+ #+BEGIN_SRC json
780
+ {
781
+ "mcpServers": {
782
+ "litdb": {
783
+ "command": "litdb_mcp",
784
+ "env": {"LITDB_ROOT": "/path/to/your/litdb"}
785
+ }
786
+ }
787
+ }
788
+ #+END_SRC
789
+
790
+ or with the Claude Code CLI:
791
+
792
+ #+BEGIN_SRC sh
793
+ claude mcp add litdb --scope user -e LITDB_ROOT=/path/to/your/litdb -- litdb_mcp
794
+ #+END_SRC
795
+
796
+ *** Claude Desktop
797
+
798
+ Claude Desktop is not supported by knowhow. Instead, run this from your litdb directory (the one with ~litdb.toml~), or pass ~--db /path/to/litdb.libsql~:
799
+
800
+ #+BEGIN_SRC sh
801
+ litdb install mcp-server
802
+ #+END_SRC
718
803
 
804
+ Then restart Claude Desktop. Now you can use prompts like "Search my litdb for references on alloy segregation" or "Search OpenAlex for articles on alloy segregation." Uninstall it with ~litdb install uninstall-mcp~.
719
805
 
720
806
  * Adding local files
721
807
 
@@ -7,7 +7,7 @@ where = ["src"]
7
7
 
8
8
  [project]
9
9
  name = "litdb"
10
- version = "2.2.2"
10
+ version = "2.2.3"
11
11
  authors = [
12
12
  {name = "John Kitchin", email = "jkitchin@andrew.cmu.edu"},
13
13
  ]
@@ -25,18 +25,24 @@ def install():
25
25
  def install_claude_skill():
26
26
  """Install the litdb skill for Claude Code.
27
27
 
28
- Copies SKILL.md from the litdb repository to ~/.claude/skills/litdb/
28
+ Copies skills/litdb/SKILL.md from the litdb repository to
29
+ ~/.claude/skills/litdb/. This needs a source checkout of litdb; otherwise use
30
+ knowhow: uvx knowhow add jkitchin/litdb --skill litdb -g
29
31
  """
30
32
  # Find the SKILL.md file in the package
31
33
  try:
32
34
  import litdb
33
35
 
34
36
  litdb_dir = Path(litdb.__file__).parent.parent.parent
35
- skill_source = litdb_dir / "SKILL.md"
37
+ skill_source = litdb_dir / "skills" / "litdb" / "SKILL.md"
36
38
 
37
39
  if not skill_source.exists():
38
40
  richprint("[red]Error: SKILL.md not found in litdb repository[/red]")
39
41
  richprint(f"[yellow]Looked in: {skill_source}[/yellow]")
42
+ richprint(
43
+ "[yellow]Install it with knowhow instead: "
44
+ "uvx knowhow add jkitchin/litdb --skill litdb -g[/yellow]"
45
+ )
40
46
  raise click.Abort()
41
47
 
42
48
  # Create target directory
@@ -7,7 +7,7 @@ modifying the litdb.
7
7
  There is a cli, litdb_mcp, that runs the server. The cli is installed as a
8
8
  script.
9
9
 
10
- You can install the server using:
10
+ You can install the server in Claude Desktop using:
11
11
 
12
12
  > litdb install mcp-server
13
13
 
@@ -15,6 +15,15 @@ and uninstall it with
15
15
 
16
16
  > litdb install uninstall-mcp
17
17
 
18
+ For other agents (Claude Code, VS Code, Cursor, Codex, ...) use knowhow, which
19
+ reads mcp/litdb.json from the litdb repository:
20
+
21
+ > uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code
22
+
23
+ The database is the `litdb` environment variable if it is set (Claude Desktop
24
+ install), otherwise litdb.libsql next to the litdb.toml found from the working
25
+ directory or LITDB_ROOT.
26
+
18
27
  This should work on Windows, but is untested there.
19
28
 
20
29
  The mcp server provides the following tools:
@@ -59,6 +68,7 @@ All tools return formatted, readable text with complete information.
59
68
 
60
69
  from mcp.server.fastmcp import FastMCP
61
70
  import requests
71
+ import contextlib
62
72
  import json
63
73
  import platform
64
74
  import os
@@ -77,6 +87,29 @@ from .coa import get_coa
77
87
  mcp = FastMCP("litdb")
78
88
 
79
89
 
90
+ def get_db_path():
91
+ """Return the path to the litdb database.
92
+
93
+ Uses the litdb environment variable if it is set, otherwise the
94
+ litdb.libsql next to the litdb.toml found by get_config.
95
+ """
96
+ if os.environ.get("litdb"):
97
+ return os.environ["litdb"]
98
+
99
+ from .utils import get_config
100
+
101
+ # stdout is the MCP stdio transport, so keep get_config messages off it
102
+ try:
103
+ with contextlib.redirect_stdout(sys.stderr):
104
+ config = get_config()
105
+ except SystemExit:
106
+ raise RuntimeError(
107
+ "No litdb.toml found. Set LITDB_ROOT to the directory containing"
108
+ " litdb.toml, or set litdb to the path of litdb.libsql."
109
+ )
110
+ return os.path.join(config["root"], "litdb.libsql")
111
+
112
+
80
113
  # Note I added _litdb here because Claude Desktop had trouble with other
81
114
  # functions named about...
82
115
  @mcp.tool()
@@ -87,7 +120,7 @@ def about_litdb():
87
120
  The MCP server has three tools, this one, a vector search tool, and an
88
121
  OpenAlex search integration.
89
122
 
90
- Using the db at {os.environ["litdb"]}.
123
+ Using the db at {get_db_path()}.
91
124
  """
92
125
 
93
126
 
@@ -98,7 +131,7 @@ def vsearch(query: str, n: int = 3) -> str:
98
131
  QUERY: string, natural language query.
99
132
  N: int, number of results to return.
100
133
  """
101
- db = libsql.connect(os.environ["litdb"])
134
+ db = libsql.connect(get_db_path())
102
135
 
103
136
  model = SentenceTransformer("all-MiniLM-L6-v2")
104
137
  emb = model.encode([query]).astype(np.float32).tobytes()
@@ -252,7 +285,7 @@ def fulltext_search(query: str, n: int = 3) -> str:
252
285
  Returns:
253
286
  Formatted results with source, BM25 score, and text snippet.
254
287
  """
255
- db = libsql.connect(os.environ["litdb"])
288
+ db = libsql.connect(get_db_path())
256
289
 
257
290
  results = db.execute(
258
291
  """select
@@ -316,7 +349,7 @@ def find_similar(source: str, n: int = 3) -> str:
316
349
  Returns:
317
350
  Formatted list of similar articles with metadata.
318
351
  """
319
- db = libsql.connect(os.environ["litdb"])
352
+ db = libsql.connect(get_db_path())
320
353
 
321
354
  # Get the embedding for the source
322
355
  try:
@@ -392,7 +425,7 @@ def get_source_details(source: str) -> str:
392
425
  Returns:
393
426
  Complete source information including full text and metadata.
394
427
  """
395
- db = libsql.connect(os.environ["litdb"])
428
+ db = libsql.connect(get_db_path())
396
429
 
397
430
  result = db.execute(
398
431
  """select source, text, extra from sources where source = ?""",
@@ -464,7 +497,7 @@ def get_citation(source: str) -> str:
464
497
  Returns:
465
498
  Formatted citation string.
466
499
  """
467
- db = libsql.connect(os.environ["litdb"])
500
+ db = libsql.connect(get_db_path())
468
501
 
469
502
  result = db.execute(
470
503
  """select json_extract(extra, '$.citation') from sources where source = ?""",
@@ -492,7 +525,7 @@ def get_bibtex(source: str) -> str:
492
525
  Returns:
493
526
  BibTeX formatted entry.
494
527
  """
495
- db = libsql.connect(os.environ["litdb"])
528
+ db = libsql.connect(get_db_path())
496
529
 
497
530
  result = db.execute(
498
531
  """select extra from sources where source = ?""", (source,)
@@ -521,7 +554,7 @@ def list_tags() -> str:
521
554
  Returns:
522
555
  List of all tags.
523
556
  """
524
- db = libsql.connect(os.environ["litdb"])
557
+ db = libsql.connect(get_db_path())
525
558
 
526
559
  results = db.execute("select tag from tags").fetchall()
527
560
 
@@ -542,7 +575,7 @@ def get_tagged_articles(tag: str) -> str:
542
575
  Returns:
543
576
  Formatted list of articles with the specified tag.
544
577
  """
545
- db = libsql.connect(os.environ["litdb"])
578
+ db = libsql.connect(get_db_path())
546
579
 
547
580
  results = db.execute(
548
581
  """select
@@ -638,14 +671,17 @@ def main():
638
671
  will do that in the Claude Desktop. With no arguments it just runs the
639
672
  server.
640
673
  """
674
+ # Called with no arguments
675
+ if len(sys.argv) == 1:
676
+ mcp.run(transport="stdio")
677
+ return
678
+
641
679
  if platform.system() == "Darwin":
642
680
  cfgfile = "~/Library/Application Support/Claude/claude_desktop_config.json"
643
681
  elif platform.system() == "Windows":
644
682
  cfgfile = r"%APPDATA%\Claude\claude_desktop_config.json"
645
683
  else:
646
- raise Exception(
647
- "Only Mac and Windows are supported for the claude-light mcp server"
648
- )
684
+ raise Exception("Claude Desktop install is only supported on Mac and Windows")
649
685
 
650
686
  cfgfile = os.path.expandvars(cfgfile)
651
687
  cfgfile = os.path.expanduser(cfgfile)
@@ -656,11 +692,7 @@ def main():
656
692
  else:
657
693
  cfg = {}
658
694
 
659
- # Called with no arguments
660
- if len(sys.argv) == 1:
661
- mcp.run(transport="stdio")
662
-
663
- elif sys.argv[1] == "install":
695
+ if sys.argv[1] == "install":
664
696
  db = sys.argv[2]
665
697
 
666
698
  setup = {
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: litdb
3
- Version: 2.2.2
3
+ Version: 2.2.3
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>
@@ -112,6 +112,9 @@ Dynamic: license-file
112
112
  <img src="https://github.com/jkitchin/litdb/actions/workflows/build.yml/badge.svg" alt="Build Status">
113
113
  </a>
114
114
  <img src="https://img.shields.io/badge/tests-133_passed,_66_skipped-brightgreen" alt="Tests">
115
+ <a href="https://doi.org/10.5281/zenodo.23514948">
116
+ <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.23514948.svg" alt="DOI">
117
+ </a>
115
118
  #+END_HTML
116
119
 
117
120
  * litdb concept
@@ -158,7 +161,13 @@ source .venv/bin/activate
158
161
  uv pip install litdb
159
162
  #+END_SRC
160
163
 
161
- You have to activate that virtual env to use litdb, which may be annoying.
164
+ You have to activate that virtual env to use litdb, which may be annoying. An alternative is to install litdb as a uv tool, which puts ~litdb~ and ~litdb_mcp~ on your PATH in their own environment:
165
+
166
+ #+BEGIN_SRC sh
167
+ uv tool install litdb
168
+ #+END_SRC
169
+
170
+ This is also the easiest way to make the MCP server available to AI agents. See [[*Using litdb with AI agents (skill and MCP server)]].
162
171
 
163
172
  ** Recent additions
164
173
 
@@ -811,16 +820,93 @@ litdb schema paper.pdf '{"title": ["str", None], "year": ["int", 2024]}'
811
820
 
812
821
  The schema command first converts the document to markdown using Docling, then uses an LLM with structured output to extract the requested fields. The LLM model used is configured in the ~[llm]~ section of your ~litdb.toml~ file.
813
822
 
814
- ** Claude Desktop + MCP
823
+ ** Using litdb with AI agents (skill and MCP server)
824
+
825
+ litdb comes with two things for AI coding agents such as Claude Code, VS Code (GitHub Copilot), Cursor, Codex, OpenCode and Gemini CLI:
826
+
827
+ - An *agent skill* ([[./skills/litdb/SKILL.md][skills/litdb/SKILL.md]]) that teaches the agent how to use the litdb CLI: adding papers, searching, filters, tags, exporting BibTeX, and so on.
828
+ - An *MCP server* (~litdb_mcp~) that gives the agent direct, read-only tools for your database: ~vsearch~, ~fulltext_search~, ~find_similar~, ~openalex~, ~get_source_details~, ~get_citation~, ~get_bibtex~, ~list_tags~, ~get_tagged_articles~ and ~generate_nsf_coa~.
829
+
830
+ The easiest way to install both is [[https://github.com/jkitchin/knowhow][knowhow]], which needs nothing installed besides [[https://github.com/astral-sh/uv][uv]]. The skill follows the [[https://agentskills.io/specification][Agent Skills specification]], so it also works with ~npx skills~.
831
+
832
+ *** Install the skill
815
833
 
816
834
  #+BEGIN_SRC sh
817
- litdb_mcp install /path/to/litdb.libsql
835
+ # See what litdb offers
836
+ uvx knowhow add jkitchin/litdb --list
837
+
838
+ # Install the skill in the current project
839
+ uvx knowhow add jkitchin/litdb --skill litdb
840
+
841
+ # or for your user, in every project
842
+ uvx knowhow add jkitchin/litdb --skill litdb -g
818
843
  #+END_SRC
819
844
 
820
- Then, restart Claude Desktop.
845
+ The skill is copied to ~.agents/skills/litdb~ (read by VS Code, Codex, OpenCode, Gemini CLI, Cursor and Copilot) and linked into ~.claude/skills/litdb~ for Claude Code. Then ask your agent things like "add the references of 10.1021/jp047349j to my litdb" or "make a bibtex file of everything tagged thesis".
846
+
847
+ Keep it up to date with ~uvx knowhow check~ and ~uvx knowhow upgrade~, and remove it with ~uvx knowhow remove litdb~.
848
+
849
+ If you work from a clone of this repository, ~litdb install claude-skill~ also copies the skill to ~~/.claude/skills/litdb~.
850
+
851
+ *** Install the MCP server
852
+
853
+ The MCP server runs the ~litdb_mcp~ command, so first make sure it is on your PATH (~uv tool install litdb~ does this). The server is defined in [[./mcp/litdb.json][mcp/litdb.json]], and knowhow translates it into each agent's config format:
854
+
855
+ #+BEGIN_SRC sh
856
+ # Claude Code, in this project (writes .mcp.json)
857
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code
858
+
859
+ # Claude Code for all your projects
860
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code -g
861
+
862
+ # Several agents at once
863
+ uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code -a vscode -a cursor -a codex
864
+ #+END_SRC
821
865
 
822
- Now in the Claude Desktop app you can use prompts like "Search my litdb for references on alloy segregation" or "Search OpenAlex for articles on alloy segregation."
866
+ knowhow shows you the server config and asks for confirmation before installing it (add ~-y~ to skip the prompt).
867
+
868
+ The server needs to know which database to use. It looks for:
869
+
870
+ 1. the ~litdb~ environment variable, the path to a ~litdb.libsql~ file;
871
+ 2. a ~litdb.toml~ in the agent's working directory or one of its parents;
872
+ 3. the ~LITDB_ROOT~ environment variable, the directory that contains ~litdb.toml~.
873
+
874
+ The installed config passes ~LITDB_ROOT~ through from your environment, so set it in your shell profile before starting the agent:
875
+
876
+ #+BEGIN_SRC sh
877
+ export LITDB_ROOT=~/litdb # the directory with litdb.toml and litdb.libsql
878
+ #+END_SRC
879
+
880
+ To check it works in Claude Code, run ~/mcp~ and look for ~litdb~, or ask "what is in my litdb about alloy segregation?". Remove the server with ~uvx knowhow remove --mcp litdb~.
881
+
882
+ If you prefer to configure an agent by hand, this is the config (Claude Code ~.mcp.json~ format):
883
+
884
+ #+BEGIN_SRC json
885
+ {
886
+ "mcpServers": {
887
+ "litdb": {
888
+ "command": "litdb_mcp",
889
+ "env": {"LITDB_ROOT": "/path/to/your/litdb"}
890
+ }
891
+ }
892
+ }
893
+ #+END_SRC
894
+
895
+ or with the Claude Code CLI:
896
+
897
+ #+BEGIN_SRC sh
898
+ claude mcp add litdb --scope user -e LITDB_ROOT=/path/to/your/litdb -- litdb_mcp
899
+ #+END_SRC
900
+
901
+ *** Claude Desktop
902
+
903
+ Claude Desktop is not supported by knowhow. Instead, run this from your litdb directory (the one with ~litdb.toml~), or pass ~--db /path/to/litdb.libsql~:
904
+
905
+ #+BEGIN_SRC sh
906
+ litdb install mcp-server
907
+ #+END_SRC
823
908
 
909
+ Then restart Claude Desktop. Now you can use prompts like "Search my litdb for references on alloy segregation" or "Search OpenAlex for articles on alloy segregation." Uninstall it with ~litdb install uninstall-mcp~.
824
910
 
825
911
  * Adding local files
826
912
 
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