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.
- {litdb-2.2.2/src/litdb.egg-info → litdb-2.2.3}/PKG-INFO +92 -6
- {litdb-2.2.2 → litdb-2.2.3}/README.org +91 -5
- {litdb-2.2.2 → litdb-2.2.3}/pyproject.toml +1 -1
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/install.py +8 -2
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/mcp_server.py +50 -18
- {litdb-2.2.2 → litdb-2.2.3/src/litdb.egg-info}/PKG-INFO +92 -6
- {litdb-2.2.2 → litdb-2.2.3}/LICENSE +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/setup.cfg +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/__init__.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/app.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/audio.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/bibtex.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/chat.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/cli.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/coa.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/__init__.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/data_processing.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/export.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/filters.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/manage.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/openalex_commands.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/research_commands.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/review.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/search.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/tags.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/commands/utilities.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/crawl.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/db.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/doe_collaborators.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/extract.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/gpt.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/images.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/lab.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/lsearch.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/openalex.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/pdf.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/research.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/server.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/summary.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/utils.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb/youtube.py +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/SOURCES.txt +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/dependency_links.txt +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/entry_points.txt +0 -0
- {litdb-2.2.2 → litdb-2.2.3}/src/litdb.egg-info/requires.txt +0 -0
- {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.
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
|
@@ -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
|
|
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 {
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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(
|
|
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
|
-
|
|
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.
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|