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.
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.
SQLite FTS5 full-text search, supporting Chinese and English
PDFs parsed page by page, returning citekey, page numbers, and original text passages
Recursive 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: search-docs
Linux/macOS
Python 3.11+
pdftotext, pdfinfo, pdftoppm (installing poppler is 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/cpu./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].
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 --forceserve-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 evidence
get_passage: fetch a precise passage with its page number
get_document: view document metadata and status
get_page_image: render PDF pages to verify formulas, tables, and figures
find_evidence: find evidence by claim
index_status: view indexing status
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.
./kb doctor
.venv/bin/python -m unittest discover -s tests -vFind passages relevant to a claim; verify passages before citing.
| Name | Required | Description | Default |
|---|---|---|---|
| claim | Yes | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral disclosure burden, but it is ambiguous whether 'verify passages before citing' is a tool behavior or an instruction to the agent. It does not disclose what the tool returns, whether it validates passages, mutual performance, or side effects, leaving behavioral understanding uncertain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description fits in one short sentence with two clauses, both contributing: the first states the primary purpose, the second the critical usage warning. It is front-loaded and free of fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, no annotations, and the description does not explain what the returned passages look like, how to interpret them, or what effects 'limit' influences. Given the claim-relevance domain, an expert agent needs more guidance about the result format and ratio with sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It indirectly covers 'claim' by referencing a claim, but it never mentions the 'limit' parameter or its role, relying entirely on the parameter name and default value. This is insufficient for full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Find passages') with a clear scope ('relevant to a claim'), which distinguishes it from siblings like get_document or get_passage. However, it does not explicitly contrast with search_library, so the differentiation is implicit rather than named.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'relevant to a claim' implies the tool is for claim-driven evidence retrieval, and 'verify passages before citing' suggests a downstream verification step. But the description provides no explicit when-to-use vs. alternatives, nor any exclusions among the listed sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve document metadata and index status.
| Name | Required | Description | Default |
|---|---|---|---|
| citekey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Retrieve' implies a read-only action, but the description does not disclose response contents, error behavior if the citekey is unknown, authentication requirements, or exactly what 'index status' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no filler or redundancy. It is concise, though it could be more informative without becoming bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is too thin to give an agent enough context: it lacks return details, failure modes, citekey semantics, and any contrast with deeply related sibling tools like index_status.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description never mentions citekey or what it represents. The only signal is the property name itself, which is insufficient for an agent to know what a valid citekey looks like or where to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Retrieve') and resource ('document metadata and index status'), which clearly separates it from tools like get_passage or get_page_image. It does not, however, explicitly contrast it with sibling index_status or note that this is per-document status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use get_document versus siblings like search_library, get_passage, or index_status. The description only states what it does, not when it should be chosen over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a PDF page for visual verification of formulas, tables, and figures.
| Name | Required | Description | Default |
|---|---|---|---|
| dpi | No | ||
| page | Yes | ||
| citekey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains the intent but does not disclose what the output looks like (image format, inline vs. URL), whether the page is rendered at the given DPI without modification, how out-of-range pages are handled, or any performance implications of rendering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is immediately informative and free of filler. It front-loads the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and cryptic parameters, the description is far from sufficient for an agent to call and interpret results correctly. Missing key details include the meaning of citekey, acceptable page ranges, output format, and error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter-level explanation. Citekey is not mentioned at all, page format and indexing are unspecified, and dpi is left to be inferred from its default value. The description does not compensate for the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Render'), the resource ('a PDF page'), and the use case ('visual verification of formulas, tables, and figures'). This strongly differentiates it from sibling tools like get_passage or get_document, which retrieve text or documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for visual verification' implies this tool is intended when visual inspection of rendered content is needed, distinguishing it from text-based retrieval tools. However, it does not explicitly state when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve an exact indexed passage with citekey and page metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| citekey | No | ||
| chunk_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It signals a read-only operation through 'Retrieve' and indicates exactness, but it does not describe what happens when a passage is not found, whether page or chunk_id is the lookup key, or what the response structure will be. These gaps limit an agent's ability to anticipate the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded, unambiguous sentence with no padding. Every word contributes meaning and the key information is placed at the start.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there are 3 params, no annotations, no output schema, and no sibling disambiguation, the description is too sparse for an agent to invoke this tool confidently. It does not explain which combination of page, citekey, and chunk_id forms a valid call, nor what the passage retrieval semantics are. The missing guidance matters because the schema marks all params as optional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the three undocumented parameters. It mentions 'citekey' and 'page metadata,' but it does not clearly map these to the page, citekey, or chunk_id schema fields, and it never addresses chunk_id. The agent still has to guess how parameters act together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') and resource ('exact indexed passage') with the metadata that is included ('citekey and page'), so an agent can tell it is a deterministic lookup rather than a general search. It doesn't explicitly differentiate it from siblings like get_document or get_page_image, but the focus on an indexed passage is enough to distinguish it broadly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The words 'exact' and 'indexed' imply it should be used when a specific known identifier exists, suggesting a use case: retrieve an already-indexed passage rather than searching. However, it does not explicitly say when this tool should be chosen over search_library, get_document, or get_page_image, nor does it name any alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show local catalog and index status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The verb 'Show' implies a read-only, non-mutating operation, and the phrase 'status' reinforces that no data is changed. However, with no annotations and no additional context, the description does not disclose whether the tool refreshes the catalog, could return stale data, or has any side effects; this is minimal but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no filler, redundant phrasing, or unnecessary details. Every word contributes to the meaning, and it is appropriately sized for a zero-parameter status tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-input status tool, the description is adequate to initiate invocation. However, there is no output schema, and the description does not clarify what values or detail are returned (e.g., index state, last update time, catalog names), leaving some uncertainty about how to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema is trivially complete at 100% coverage. The description does not need to explain parameter meaning, and the absence of parameters is itself a useful signal that invocation requires no arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') with a clear resource ('local catalog and index status'). It is semantically distinct from the sibling tools, which are all retrieval-oriented operations, and it immediately signals this is a status/inspection tool rather than a document/evidence lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance about when to call this tool vs. the identified siblings. The absence of an alternative status tool makes the intended use inferable, but the description never states prerequisites or conditions (e.g., 'use after indexing' or 'use to diagnose search issues').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search indexed PDF and Markdown evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| citekey | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only says 'indexed PDF and Markdown evidence.' It adds the context that only indexed files are searched and scopes the file types, but it does not explain ranking, snippet behavior, or any effects on state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, very short sentence with no filler words, so it is concise. However, it is arguably too short for a tool with three parameters and a potentially ambiguous search behavior, making it under-specified rather than appropriately complete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and an inadequate parameter description, the description fails to explain essential invocation details such as how to form queries, what the returned evidence looks like, or how 'limit' and 'citekey' affect results. For a simple search tool, the minimal context is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about 'query', 'limit', or 'citekey'. The agent is left to guess what each parameter means and which are required beyond the schema's structural hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a search over indexed PDF and Markdown content, giving the agent a specific verb and resource. Though it does not name sibling tools, the 'search' operation is distinct from the get_* retrieval tools and find_evidence appears to be a broader alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like find_evidence or get_document. There are no exclusions, prerequisites, or hints about what makes this the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_evidenceget_documentget_page_imageget_passageindex_statussearch_libraryScored 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.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Open-source Obsidian for MDX - edit local docs with agent assistance
Token-efficient search for coding agents over public and private documentation.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
