Skip to main content
Glama
ccam80

Zotero Chunk RAG

by ccam80
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

DeepZotero

Semantic search over a Zotero library. PDFs are extracted (text, tables, figures), chunked, embedded, and stored in ChromaDB. An MCP server exposes the index to Claude Code (or any MCP client) as 10 tools for semantic and exact-word search over text, tables and figures, context expansion, citation graph lookup, indexing, and cost tracking.

What it extracts

  • Text — section-aware chunks with overlap, classified by document section (abstract, methods, results, etc.)

  • Tables — vision-based extraction via Claude Haiku 4.5. Each table is rendered to PNG and transcribed to structured markdown (headers, rows, footnotes). Table extraction is vision-only: with vision disabled, or without an Anthropic key, no tables are extracted.

  • Figures — detected with captions, extracted as PNGs, searchable by caption text.

Related MCP server: archilles

Requirements

  • Python 3.10+

  • A Gemini API key for embeddings (unless using embedding_provider: "local")

  • An Anthropic API key for vision-based table extraction (optional but recommended)

  • Zotero 8 with PDFs in storage/. Citation keys are read from Zotero's native citationKey field, which earlier versions do not have — on Zotero 7 every citation key comes back empty.

  • Tesseract-OCR — only needed to OCR scanned / image-only PDF pages. Install Tesseract with the language data you need, then set the TESSDATA_PREFIX environment variable to its tessdata directory (e.g. C:\Program Files\Tesseract-OCR\tessdata). PyMuPDF locates the OCR data via that variable; without it, scanned pages are skipped ("OCR disabled because Tesseract language data not found."). Text-based PDFs do not need Tesseract.

Install as a Claude Code plugin

Requires uv on PATH. The repo is its own marketplace:

/plugin marketplace add ccam80/deep-zotero
/plugin install deep-zotero

The server launches through uvx, which fetches the pinned deep-zotero wheel from PyPI and caches it.

In the environment Claude Code starts from, set DEEP_ZOTERO_DATA_DIR (the Zotero data directory holding zotero.sqlite and storage/), DEEP_ZOTERO_CHROMA_PATH (where the index lives), GEMINI_API_KEY (embeddings) and ANTHROPIC_API_KEY (vision table extraction during indexing).

Index the library once before searching: deep-zotero-index -v.

/deep-zotero:install walks a coding agent through the whole setup: variables, Tesseract, and the first index.

Setup

1. Configuration

The four environment variables above are the whole configuration. Every other setting has a sensible default.

To override more than those four, write a JSON config and point DEEP_ZOTERO_CONFIG at it (or pass --config PATH to the CLI):

{
    "zotero_data_dir": "~/Zotero",
    "chroma_db_path": "~/.local/share/deep-zotero/chroma",
    "gemini_api_key": "YOUR_GEMINI_KEY",
    "anthropic_api_key": "YOUR_ANTHROPIC_KEY"
}

A config file takes precedence over the environment wherever both supply a setting. See Configuration reference for every field.

2. API keys

Gemini (required for default embeddings): Get a key at aistudio.google.com/app/apikey. Set it as gemini_api_key in config or GEMINI_API_KEY env var. If you don't want to use Gemini, set "embedding_provider": "local" to use ChromaDB's built-in all-MiniLM-L6-v2 model (no API key needed, lower quality).

Anthropic (required for vision table extraction): Get a key at console.anthropic.com. Set it as anthropic_api_key in config or ANTHROPIC_API_KEY env var. Table extraction is vision-only — without this key, text and figures are still indexed but no tables are extracted. Vision extraction uses the Anthropic Batch API with Claude Haiku 4.5 — cost is roughly $0.016 per table, with prompt caching reducing cost on large batches.

To disable vision extraction entirely:

{
    "vision_enabled": false
}

3. Index your library

deep-zotero-index -v

To test with a subset first:

deep-zotero-index --limit 10 -v

This reads the Zotero SQLite database (read-only, safe while Zotero is open), extracts text/tables/figures from each PDF, chunks the text, embeds via Gemini, and stores everything in ChromaDB.

CLI options:

Flag

Description

--force

Delete and rebuild index for all matching items

--limit N

Only index N items

--item-key KEY

Index a single Zotero item

--title PATTERN

Regex filter on title (case-insensitive)

--no-vision

Skip vision table extraction for this run

--config PATH

Use a different config file

-v

Debug logging

The indexer is incremental — it only processes items not already in the index. Use --force after changing chunk_size, embedding_dimensions, or ocr_language.

You can also trigger indexing from the MCP client via the index_library tool.

4. Check it works

Call get_index_stats from Claude Code. It should report the documents and chunks just indexed.

If the tools are missing, the server did not start: confirm uv is on PATH and that the environment variables are visible to Claude Code's process.

For scanned-page OCR, TESSDATA_PREFIX (see Requirements) must be set in that same environment.

Configuration reference

Zotero

Field

Default

Description

zotero_data_dir

~/Zotero

Path to Zotero's data directory (contains zotero.sqlite and storage/). Falls back to DEEP_ZOTERO_DATA_DIR env var

chroma_db_path

~/.local/share/deep-zotero/chroma

Where the ChromaDB index is stored on disk. Falls back to DEEP_ZOTERO_CHROMA_PATH env var

Embedding

Field

Default

Description

embedding_provider

"gemini"

"gemini" for Gemini API, "local" for ChromaDB's built-in all-MiniLM-L6-v2 (no key needed)

embedding_model

"gemini-embedding-001"

Gemini model name (only used when provider is "gemini")

embedding_dimensions

768

Output vector dimensions. gemini-embedding-001 supports 64-3072. Changing requires --force re-index

gemini_api_key

null

Falls back to GEMINI_API_KEY env var

embedding_timeout

120.0

Timeout in seconds for embedding API calls

embedding_max_retries

3

Max retries for failed embedding calls

embedding_rate_limit_backoff

30.0

Seconds to wait before retrying after an HTTP 429 (per-minute quota)

Chunking

Field

Default

Description

chunk_size

400

Target chunk size in tokens (~4 chars/token). Changing requires --force re-index

chunk_overlap

100

Overlap between consecutive chunks in tokens

Vision

Field

Default

Description

vision_enabled

true

Enable vision table extraction during indexing

vision_model

"claude-haiku-4-5-20251001"

Anthropic model for table transcription

anthropic_api_key

null

Falls back to ANTHROPIC_API_KEY env var

Reranking

Field

Default

Description

rerank_enabled

true

Enable composite score reranking

rerank_alpha

0.7

Similarity exponent (0-1). Lower = more metadata influence

rerank_section_weights

null

Override default section weights

rerank_journal_weights

null

Override default journal quartile weights

oversample_multiplier

3

Oversample factor before reranking

oversample_topic_factor

5

Additional factor for search_topic

OCR

Field

Default

Description

ocr_language

"eng"

Tesseract language code for scanned pages ("fra", "deu", etc.). Changing requires --force re-index

OpenAlex

Field

Default

Description

openalex_email

null

Email for OpenAlex polite pool (10 req/s vs 1 req/s). Falls back to OPENALEX_EMAIL env var

MCP tools

Semantic search

search_papers — Passage-level semantic search. Returns matching text with surrounding context, reranked by composite score (similarity × section weight × journal weight). Supports required_terms for combining semantic search with exact word matching — each term must appear as a whole word in the passage.

Parameters: query (optional when required_terms is given), top_k (1-50), context_chunks (0-3), year_min, year_max, author, tag, collection, chunk_types (text/figure/table), sections, journal_quartiles, section_weights, journal_weights, required_terms (words that must appear as whole words), terms_operator (AND/OR).

search_topic — Paper-level topic search, deduplicated by document. Groups chunks by paper, scores by average and best composite relevance.

Parameters: query, num_papers (1-50), year_min, year_max, author, tag, collection, chunk_types, sections, journal_quartiles, section_weights, journal_weights.

Filtering

search_papers(query="baroreflex sensitivity", author="Olufsen", journal_quartiles=["Q1"])
search_papers(required_terms=["SDNN"], sections=["results"], year_min=1991, year_max=1995)

Parameter

Applied

Match

year_min, year_max, chunk_types, sections, journal_quartiles

during retrieval

exact

author, tag, collection

after retrieval

case-insensitive substring

section_weights, journal_weights

during reranking, so only with query

reorders, excludes nothing

Valid sections: abstract, introduction, background, methods, results, discussion, conclusion, references, appendix, preamble, table, figure, unknown.

Valid journal_quartiles: Q1, Q2, Q3, Q4, and unknown for journals with no quartile.

Tables and figures

search_papers covers text, tables and figures. Every result names its chunk_type; narrow with chunk_types:

search_papers("impedance measurement", chunk_types=["table"])

Table results add table_index, caption, num_rows and num_cols, with the table markdown in passage. Figure results add figure_index, caption and image_path (the extracted PNG), with the caption in passage.

Table and figure chunks carry section values of table and figure rather than the section they appeared in. Both weigh 1.0 in reranking.

Exact word matching

required_terms lists words that must appear in the passage as whole words, case-insensitively — heart matches Heart but not hearth. terms_operator is AND (default) or OR.

Terms constrain the search itself, so a passage containing a rare acronym is found even when semantic similarity would not rank it:

search_papers("autonomic regulation", required_terms=["SDNN"])

Omit query to retrieve every matching passage in the index, unranked, with no embedding call:

search_papers(required_terms=["propranolol", "SDNN"], terms_operator="AND")

At least one of query or required_terms is required. section_weights and journal_weights affect ranking only and are ignored when query is omitted. No phrase search, no stemming.

Context expansion

get_passage_context — Expand context around a passage from search_papers. For table results, pass table_page and table_index to find body text citing the table.

Parameters: doc_id, chunk_index, window (1-5), table_page, table_index.

Citation graph (OpenAlex)

Requires the document to have a DOI in Zotero.

find_citing_papers — Papers that cite a given document. Parameters: doc_id, limit (1-100).

find_references — Papers a document cites. Parameters: doc_id, limit (1-100).

get_citation_count — Citation and reference counts. Parameters: doc_id.

Index management

index_library — Trigger indexing from the MCP client. Parameters: force_reindex, limit, item_key, title_pattern, no_vision.

get_index_stats — Document/chunk/table/figure counts, section coverage, journal coverage. Counts cover the entire collection. The result is cached in index_stats.sqlite next to the Chroma database and refreshed at the end of every indexing run; pass refresh: true to force a recount.

get_reranking_config — Current reranking weights and valid override values.

get_vision_costs — Vision API batch usage and cost summary. Parameters: last_n (recent entries to show).

Reranking

Search results are scored:

composite_score = similarity^alpha * section_weight * journal_weight

Default section weights:

Section

Weight

results

1.0

conclusion

1.0

table

0.9

methods

0.85

abstract

0.75

background

0.7

unknown

0.7

discussion

0.65

introduction

0.5

preamble

0.3

appendix

0.3

references

0.1

Default journal weights: Q1=1.0, Q2=0.85, Q3=0.65, Q4=0.45.

Override per-call via section_weights and journal_weights parameters. Set a section to 0 to exclude it. Disable reranking entirely with "rerank_enabled": false.

Shared filter parameters

Parameter

Type

Description

author

string

Case-insensitive substring match against author names

tag

string

Case-insensitive substring match against Zotero tags

collection

string

Case-insensitive substring match against collection names

year_min / year_max

int

Publication year range

section_weights

dict

Override section weights for this call

journal_weights

dict

Override journal quartile weights

required_terms

list

Exact whole-word matches required in passage (search_papers only)

Research agent skill

examples/zotero-research/SKILL.md is a ready-made Claude Code skill that wraps these tools into a spawnable research agent — it takes a high-level research question, runs the appropriate searches, and returns consolidated findings with citation keys. Copy it into .claude/skills/ (or your global skills directory) to use it.

Development

Debug viewer

tools/debug_viewer.py is a PyQt6 browser for inspecting the ChromaDB index — view papers, tables (rendered markdown vs PDF), figures, and individual chunks.

.venv/Scripts/python.exe tools/debug_viewer.py

Tests

.venv/Scripts/python.exe -m pytest

Tests that make real Anthropic API calls are marked vision_api and excluded by default; run them with -m vision_api.

tests/stress_test_real_library.py is the end-to-end quality gate: it pulls 10 papers from the live Zotero library, runs the full extraction → index → search pipeline into a temp ChromaDB, and asserts on extraction and retrieval quality. It writes STRESS_TEST_REPORT.md and _stress_test_debug.db.

.venv/Scripts/python.exe tests/stress_test_real_library.py

--vision-only re-runs just the vision extraction against an existing _stress_test_debug.db, optionally narrowed to one paper with --paper KEY.

Releasing

python tools/release.py --bump patch (or an explicit X.Y.Z) rewrites the version in pyproject.toml and plugin/.claude-plugin/plugin.json, including the pinned package the plugin launches, then commits and tags. It refuses a dirty tree, a non-main branch, and an existing tag.

Pushing the tag runs .github/workflows/publish.yml, which re-checks that tag, both manifests and the pin agree before publishing to PyPI.

Available Tools

4 tools
get_index_statsB

Get statistics about the indexed collection.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.2/5.0
Behavior2/5

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. The description only states what the tool does ('Get statistics') without explaining what kind of statistics are returned, whether this is a read-only operation, if there are rate limits, or how the data is formatted. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior and output characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's appropriately sized and front-loaded, making it easy to understand at a glance. Every part of the sentence earns its place by conveying essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has no parameters, an output schema exists (which should cover return values), and the description is concise, the description is somewhat complete for its simplicity. However, it lacks context about what 'statistics' entail and how this tool fits with its siblings, leaving room for improvement in guiding the agent on usage and output interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the schema description coverage is 100% (as there are no parameters to describe). The description doesn't need to add parameter semantics beyond what the schema provides. According to the rules, with 0 parameters, the baseline score is 4, as there's no parameter information to compensate for or enhance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get statistics') and the target resource ('about the indexed collection'), which provides a specific verb+resource combination. However, it doesn't differentiate this tool from its siblings (get_passage_context, search_papers, search_topic), which all appear to operate on similar data but serve different purposes. The purpose is clear but lacks sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings or alternatives. It doesn't mention prerequisites, context for usage, or exclusions. While the tool has no parameters, which might imply straightforward usage, there's no explicit instruction on when this statistical information is needed compared to other tools that search or retrieve content.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_passage_contextA

Expand context around a specific passage.

Use after search_papers to get more context.

Args: doc_id: Document ID from search results chunk_index: Chunk index from search results window: Chunks before/after to include (1-5)

ParametersJSON Schema
NameRequiredDescriptionDefault
doc_idYes
chunk_indexYes
windowNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

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 implies this is a read operation ('Expand context'), which is useful, but lacks details on permissions, rate limits, or what happens if inputs are invalid. The description doesn't contradict annotations, but it's minimal given the lack of structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with the core purpose stated first, followed by usage guidance and parameter details. Every sentence earns its place by providing essential information without redundancy, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (3 parameters, no annotations, but with an output schema), the description is mostly complete. It covers purpose, usage, and parameter semantics well. However, it could benefit from more behavioral context (e.g., error handling or output format hints), though the output schema mitigates some of this need.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning beyond the input schema, which has 0% schema description coverage. It explains each parameter: 'doc_id: Document ID from search results,' 'chunk_index: Chunk index from search results,' and 'window: Chunks before/after to include (1-5).' This clarifies the purpose and constraints of all parameters, fully compensating for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Expand context around a specific passage.' This specifies the verb ('Expand context') and resource ('a specific passage'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'search_papers' or 'search_topic' beyond mentioning it should be used 'after search_papers.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: 'Use after search_papers to get more context.' This gives a specific sequence and purpose. However, it doesn't explicitly state when NOT to use it or mention alternatives like 'search_topic' or 'get_index_stats,' which could help further distinguish its role.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_papersA

Semantic search over research paper chunks.

Returns relevant passages with surrounding context.

Args: query: Natural language search query top_k: Number of results (1-50) context_chunks: Adjacent chunks to include (0-3) year_min: Minimum publication year filter year_max: Maximum publication year filter

Returns: List of results with passage text, context, and metadata

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
top_kNo
context_chunksNo
year_minNo
year_maxNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format ('List of results with passage text, context, and metadata') and mentions 'relevant passages with surrounding context,' which adds value beyond basic functionality. However, it lacks details on permissions, rate limits, or error handling that would be helpful for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by clear sections for Args and Returns. Every sentence earns its place by providing essential information without redundancy, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (5 parameters, no annotations, but with an output schema), the description is largely complete. It explains parameters thoroughly and notes the return format, though it could benefit from more behavioral context (e.g., performance hints or limitations). The output schema reduces the need to detail return values, but some gaps remain in usage guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate. It provides detailed semantics for all 5 parameters: 'query' as a natural language search query, 'top_k' with range (1-50), 'context_chunks' with range (0-3), and 'year_min/year_max' as publication year filters. This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Semantic search over research paper chunks' which specifies the verb (search), resource (research paper chunks), and method (semantic). It distinguishes from siblings like 'get_index_stats' (statistics), 'get_passage_context' (context retrieval), and 'search_topic' (topic-based search) by focusing on semantic search over chunks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'search_topic' or other siblings. It mentions what the tool does but lacks explicit when/when-not instructions or prerequisites, leaving the agent to infer usage from context alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_topicA

Find the most relevant papers for a topic, deduplicated by document.

Searches across all chunks, then groups by paper. Each paper is scored by both its average chunk relevance (overall topical fit) and its best single chunk (strongest individual passage). Results are sorted by average score.

Args: query: Natural language topic description num_papers: Number of distinct papers to return (1-50) year_min: Minimum publication year filter year_max: Maximum publication year filter

Returns: List of per-paper results with scores and best passage

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
num_papersNo
year_minNo
year_maxNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses key behavioral traits: deduplication by document, scoring methodology (average and best chunk relevance), sorting by average score, and filtering by year. However, it doesn't mention rate limits, authentication needs, error conditions, or pagination behavior for large result sets.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and appropriately sized. It begins with the core purpose, explains the deduplication and scoring methodology, lists parameters with clear semantics, and describes the return format. Every sentence adds value with zero wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters with 0% schema coverage and no annotations, the description does an excellent job explaining parameter semantics and tool behavior. The presence of an output schema means return values don't need explanation. However, for a search tool with scoring complexity, it could benefit from mentioning performance characteristics or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

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 provides clear semantic meaning for all 4 parameters: 'query' as natural language topic, 'num_papers' as count of distinct papers with range, and year filters as publication year bounds. This adds substantial value beyond the bare schema, though it doesn't explain null handling for year parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Find the most relevant papers for a topic, deduplicated by document.' It specifies the verb 'find' and resource 'papers', and distinguishes from sibling 'search_papers' by emphasizing deduplication and scoring methodology (average vs best chunk).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: for finding papers by topic with deduplication and scoring. However, it doesn't explicitly state when NOT to use it or directly compare with sibling 'search_papers', which might be an alternative for paper searches without the specific scoring/deduplication approach described here.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedget_index_stats
    • First observedget_passage_context
    • First observedsearch_papers
    • First observedsearch_topic
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation4/5

The tools are mostly distinct in purpose: get_index_stats provides collection statistics, search_papers finds specific passages, search_topic finds relevant papers by topic, and get_passage_context expands context around a passage. However, search_papers and search_topic both involve semantic search over paper content, which could cause some confusion about when to use each, though their descriptions clarify the difference (passage-level vs. paper-level results).

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with clear verb_noun structures: get_index_stats, get_passage_context, search_papers, and search_topic. The naming is predictable and readable, with no mixing of conventions or stylistic deviations.

Tool Count4/5

With 4 tools, the count is reasonable for a RAG-focused server, covering key operations like searching, context expansion, and statistics. It might be slightly thin for broader document management tasks (e.g., no indexing or update tools), but it's well-scoped for its apparent purpose of querying and exploring a research paper collection.

Completeness3/5

The toolset covers core retrieval and exploration functions (search, context expansion, stats) but has notable gaps for a full RAG or document management system. There are no tools for indexing, updating, or deleting documents, and operations like filtering by metadata beyond year are limited. This could lead to dead ends for agents needing to modify or fully manage the collection.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mcp-zotero

    nealcaren
    A
    license
    C
    quality
    D
    maintenance
    Enables interaction with Zotero libraries for searching, managing collections, items, tags, and attachments, plus optional semantic search across PDFs via local embeddings.
    38
    2
    MIT

  • archilles

    kasssandr
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables semantic search over local Calibre libraries via MCP, allowing AI assistants to query books, annotations, and export bibliographies while keeping data private.
    8
    MIT

  • zotero-fulltext-mcp

    matthiaskloft
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables searching and reading full text of papers in a Zotero library by converting PDF attachments to Markdown and exposing a full-text search index to LLM tools.
    MIT

  • research-mcp

    lduda79
    F
    license
    A
    quality
    B
    maintenance
    Enables semantic search across personal PDF paper collections with page-level citations, allowing users to query their library from any MCP-capable client.
    9
    -