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 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jkitchin/litdb --skill litdb技能说明
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-gfor all projects, repeat-afor more agents). Remove it withuvx knowhow remove --mcp litdb. - Claude Desktop:
litdb install mcp-server(uses the database in the current litdb project, or--db PATH), andlitdb 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 locationvsearch(query, n=3): Vector search in the database. Returns formatted summaries with title, authors, year, DOI, similarity score, and full abstractopenalex(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 scoresfind_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 informationget_citation(source): Generate a formatted citation string for a sourceget_bibtex(source): Generate a BibTeX entry for a source (for LaTeX/bibliography managers)
ORGANIZATION TOOLS:
list_tags(): List all defined tags in the databaseget_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:
- Run commands to help them: Don't just show command examples - actually execute them when appropriate
- Check status: Use
litdb aboutto see database info - Search for them: Run
litdb vsearch "query"or other search commands - Get help: Use
litdb --helporlitdb SUBCOMMAND --helpto see all options - Verify setup: Check for
litdb.tomlfiles, runlitdb initif needed
Examples of what you can do:
litdb about- Show database statisticslitdb vsearch "machine learning" -n 5- Perform vector searchlitdb list-filters- Show active filterslitdb list-tags- Show all tagslitdb sql "SELECT COUNT(*) FROM sources"- Run SQL querieslitdb 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