terminal_kb
This server provides a local, offline-first knowledge base interface for searching and retrieving evidence from PDFs and Markdown notes via MCP tools.
search_library: Full-text search across indexed PDF and Markdown documents, with optional limit and citekey filtering.
get_passage: Retrieve an exact indexed passage with citekey, page, and chunk metadata.
get_document: Look up document metadata and index status for a given citekey.
get_page_image: Render a PDF page as an image to visually verify formulas, tables, and figures.
find_evidence: Find relevant passages for a claim, intended to help locate and verify evidence before citing.
index_status: Show the local catalog and indexing status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@terminal_kb search my library for retrieval augmented generation and show cited passages"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Terminal Knowledge Base
A terminal-only local knowledge base for managing PDFs, Markdown notes, and evidence for paper writing. It does not rely on Obsidian or Zotero and can be used directly through the CLI, scripts, and MCP agents.
Features
SQLite FTS5 full-text search, supporting Chinese and English
PDFs parsed page by page, returning
citekey, page numbers, and original text passagesRecursive import of Markdown notes, preserving stable citekeys
BibTeX bibliography files and research draft directories
JSON-RPC over stdio MCP server, connectable to terminal agents such as Codex
Optional LanceDB + Sentence Transformers vector indexes
All indexes and parse results are local, rebuildable files
Related MCP server: loci-mcp
Environment Requirements
Linux/macOS
Python 3.11+
pdftotext,pdfinfo,pdftoppm(installingpoppleris recommended)
Basic full-text search requires no additional Python dependencies. A Python 3.12 virtual environment with uv is recommended.
uv python install 3.12
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e .Optional dependencies:
# 向量检索(CPU 环境)
uv pip install --python .venv/bin/python lancedb sentence-transformers
# 更复杂的 PDF 版面、表格和公式解析
uv pip install --python .venv/bin/python doclingNon-NVIDIA GPUs:
uv pip install --python .venv/bin/python \
torch==2.6.0+cpu \
--index-url https://download.pytorch.org/whl/cpuQuick Start
./kb init
./kb add ~/Books/paper.pdf --title "Paper title" --author "Doe, Jane" --year 2024
./kb add ~/notes/method.md --title "Method notes"
./kb index --all
./kb search "retrieval augmented generation" --limit 5Common commands:
./kb status
./kb doctor
./kb show <citekey> --page 2
./kb passage --citekey <citekey> --page 2
./kb cite <citekey> --page 2
./kb page-image <citekey> 2 --dpi 150The paper citation format is: [@citekey, p. 2].
Importing Existing Directories
kb add adds files one at a time. For batch imports, you can use the shell:
find ~/Books/final -type f \( -iname '*.pdf' -o -iname '*.md' \) -print0 |
while IFS= read -r -d '' file; do
./kb add "$file"
done
./kb index --all --forceMCP Agent Integration
serve-mcp uses stdin/stdout for JSON-RPC transport and requires no additional MCP SDK:
[mcp_servers.terminal_kb]
command = "/absolute/path/to/knowledge-base/kb"
args = ["--root", "/absolute/path/to/knowledge-base", "serve-mcp"]The tools provided include:
search_library: search PDF and Markdown evidenceget_passage: fetch a precise passage with its page numberget_document: view document metadata and statusget_page_image: render PDF pages to verify formulas, tables, and figuresfind_evidence: find evidence by claimindex_status: view indexing status
Vector Retrieval
The vector index is an optional feature, enabled in .kb/config.toml:
enable_vectors = true
embedding_model = "BAAI/bge-small-zh-v1.5"Then rebuild:
./kb index --all --forceThe first run downloads the model from Hugging Face.
Verification
./kb doctor
.venv/bin/python -m unittest discover -s tests -vAvailable Tools
6 toolsfind_evidenceB
Find passages relevant to a claim; verify passages before citing.
Inputs: claim (required), limit.
get_documentC
Retrieve document metadata and index status.
Inputs: citekey (required).
get_page_imageB
Render a PDF page for visual verification of formulas, tables, and figures.
Inputs: page (required), citekey (required), dpi.
get_passageB
Retrieve an exact indexed passage with citekey and page metadata.
Inputs: page, citekey, chunk_id.
index_statusA
Show local catalog and index status.
Inputs: no named parameters.
search_libraryC
Search indexed PDF and Markdown evidence.
Inputs: query (required), limit, citekey.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
get_passage, get_document, get_page_image, and index_status are clearly distinct, but search_library and find_evidence overlap heavily since both search the same evidence set for relevant passages. The descriptions add some differentiation, but an agent could still easily pick the wrong one for a general search.
Most tools follow a clear verb_noun pattern: search_library, get_passage, get_document, get_page_image, find_evidence. The exception is index_status, which is a noun phrase instead of something like get_index_status, but this is only a minor consistency break.
Six tools form a tight, well-scoped set for an evidence-retrieval knowledge base. Each tool maps to a specific step in the workflow of searching, retrieving, and verifying evidence, with no unnecessary bloat.
The core research workflow is covered: search, retrieve passages, inspect page images, check metadata, and monitor index status. Notable gaps are full-document text retrieval and index/database management, but agents can still complete the primary evidence-checking task with the provided tools.
Maintenance
Related MCP Connectors
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Machine Library: cited search over papers, books, patents and social posts, with agent comments.
YouTube transcripts (chunks, phrase search, most replayed moments), PDFs and web pages as Markdown.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables local-first hybrid knowledge retrieval from authorized Markdown and plain-text files, combining full-text and vector search with reranking and traceable source references via a single search tool.1MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP hosts to query locally indexed notes, docs, chat logs, and other files via hybrid vector/BM25 retrieval with section-level citations. Exposes tools, resources, and prompts for searching and asking over the indexed content.-
- FlicenseNot gradedqualityAmaintenanceEnables AI hosts and agents to search, ask, and retrieve cited sections from a locally indexed collection of notes, documents, PDFs, web pages, org files, and chat logs using hybrid vector and BM25 retrieval.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP-compatible hosts to search, ask, and retrieve section-level citations from scattered local notes, docs, PDFs, Word files, web pages, org files, and chat logs using hybrid vector and BM25 retrieval.-