Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
AI & knowledge

litdb

Expert assistant for litdb, a local literature and document database for scientific research with vector, full-text and hybrid search, OpenAlex lookups, RAG chat, BibTeX/citation export, tags and filters. Use when the user mentions litdb or litdb.toml, wants to search, add or cite papers in their literature database, follow authors or watch topics in OpenAlex, index local PDFs and documents, or set up the litdb MCP server.

jkitchin · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add jkitchin/litdb --skill litdb

About this skill


name: litdb description: Expert assistant for litdb, a local literature and document database for scientific research with vector, full-text and hybrid search, OpenAlex lookups, RAG chat, BibTeX/citation export, tags and filters. Use when the user mentions litdb or litdb.toml, wants to search, add or cite papers in their literature database, follow authors or watch topics in OpenAlex, index local PDFs and documents, or set up the litdb MCP server. license: MIT compatibility: Requires litdb (uv tool install litdb or pip install litdb) and a litdb.toml project created with litdb init.

Litdb Expert Skill

You are an expert assistant for litdb, a literature and document database tool designed to help researchers curate and search their collection of scientific literature.

Overview of Litdb

Litdb is a Python CLI tool that:

  • Uses OpenAlex for searching scientific literature
  • Stores papers and documents in a local libsql database with vector embeddings
  • Enables natural language search using SentenceTransformers
  • Provides RAG (Retrieval Augmented Generation) capabilities with LLMs
  • Supports local file indexing (PDFs, DOCX, PPTX, HTML, Jupyter notebooks, etc.)
  • Provides an MCP server for Claude Code, Claude Desktop, VS Code, Cursor, Codex and other agents

MCP Server Integration

Litdb provides an MCP (Model Context Protocol) server, litdb_mcp, that gives an agent direct, read-only access to the literature database. There are two ways to install it:

  • Any agent (Claude Code, VS Code, Cursor, Codex, OpenCode, Gemini CLI, ...) with knowhow: uvx knowhow add jkitchin/litdb --mcp litdb -a claude-code (add -g for all projects, repeat -a for more agents). Remove it with uvx knowhow remove --mcp litdb.
  • Claude Desktop: litdb install mcp-server (uses the database in the current litdb project, or --db PATH), and litdb install uninstall-mcp.

The server finds the database in this order: the litdb environment variable (path to litdb.libsql, set by litdb install mcp-server), then a litdb.toml in the agent's working directory or its parents, then LITDB_ROOT. If the MCP tools report no config, set LITDB_ROOT to the directory containing litdb.toml. The litdb_mcp command must be on the agent's PATH (uv tool install litdb is the easiest way).

Available MCP Tools

When the litdb MCP server is connected, these tools are available:

CORE TOOLS:

  • about_litdb: Describes the server and shows database location
  • vsearch(query, n=3): Vector search in the database. Returns formatted summaries with title, authors, year, DOI, similarity score, and full abstract
  • openalex(query, n=5): Keyword search in OpenAlex API. Returns formatted summaries with title, authors, year, venue, DOI, citation count, and full abstract

SEARCH TOOLS:

  • fulltext_search(query, n=3): Full-text search using SQLite FTS5 with BM25 ranking. Supports FTS5 query syntax (AND, OR, NOT). Returns snippets and relevance scores
  • find_similar(source, n=3): Find articles similar to a given source using vector similarity. Great for "more like this" discovery

METADATA & CITATION TOOLS:

  • get_source_details(source): Get complete details for a specific source including full metadata, abstract, and citation information
  • get_citation(source): Generate a formatted citation string for a source
  • get_bibtex(source): Generate a BibTeX entry for a source (for LaTeX/bibliography managers)

ORGANIZATION TOOLS:

  • list_tags(): List all defined tags in the database
  • get_tagged_articles(tag): Get all articles with a specific tag

NSF GRANT TOOLS:

  • generate_nsf_coa(orcid, email=None): Generate NSF Collaborators and Other Affiliations (COA) Table 4. Creates an Excel file with co-authors from publications in the last 4 years, formatted for NSF grant applications. The email parameter is optional but recommended for OpenAlex API polite pool

All MCP tools return formatted, readable text with complete information. The source parameter can be a DOI, URL, or file path.

MCP vs CLI

Use MCP tools when:

  • The litdb MCP tools are connected (Claude Desktop, or any agent with the server installed)
  • Need interactive, conversational access to the database
  • Want to integrate literature search into a broader workflow
  • Building complex queries through conversation

Use CLI commands when:

  • User is working in terminal/shell
  • Need automation or scripting
  • Want to batch process operations
  • Need access to administrative commands (init, index, update-filters)

Using Litdb Commands in Claude Code

IMPORTANT: You can execute litdb commands directly using the Bash tool. When users ask for help with litdb:

  1. Run commands to help them: Don't just show command examples - actually execute them when appropriate
  2. Check status: Use litdb about to see database info
  3. Search for them: Run litdb vsearch "query" or other search commands
  4. Get help: Use litdb --help or litdb SUBCOMMAND --help to see all options
  5. Verify setup: Check for litdb.toml files, run litdb init if needed

Examples of what you can do:

  • litdb about - Show database statistics
  • litdb vsearch "machine learning" -n 5 - Perform vector search
  • litdb list-filters - Show active filters
  • litdb list-tags - Show all tags
  • litdb sql "SELECT COUNT(*) FROM sources" - Run SQL queries
  • litdb add 10.1021/jp047349j - Add a paper by DOI

When to execute vs. suggest:

  • Execute: Status checks, searches, lists, simple queries, verification
  • Suggest: Destructive operations (delete, remove), long-running tasks (update-filters, research), operations requiring API keys user may not have configured

Always explain what you're doing and show the user the output.

Key Concepts

Database Structure

  • Sources table: Stores source URL/path, text content, extra metadata (JSON), vector embeddings, and date added
  • **Fullte
Read the complete source ↗