retrieval-mcp

Current release: 0.4.4, 31 tools. Platform architecture: ../overview.md.

The package currently declares mcp>=1.2.0,<2: the 31-tool server still uses the official SDK v1 FastMCP API, while SDK v2 removed that import path. The upper bound makes a normal install resolve a compatible SDK without client-side --with mcp<2 workarounds.

An MCP server for the Retrieval academic-paper API - semantic paper search, document matching, ACE journal memory, and index inventory. Self-contained: it talks to the backend over HTTP only (just mcp + httpx), so it installs anywhere with uvx / pip - no repo checkout, no GPU, no models.

By default it targets the compute box on the lab LAN (http://10.100.100.111:8000), which trusts LAN callers so no key is needed. Off-LAN, point RETRIEVAL_API_URL at the public gateway (https://retrieval.rnarket.com) and set RETRIEVAL_API_KEY (sk-...).

Tools

Every tool's full docstring (purpose + each argument with its default + an example) is what your LLM sees - call them by name. Summary:

Paper retrieval

Tool What it does
search_papers Semantic hybrid search over the live top-venue corpus (filters: venue, year, title_only)
search_within_paper Every matching passage inside one paper
get_paper_markdown Return one paper's complete Markdown, or Range-stream it to a caller-local file/directory
download_paper_pdf Range-stream the original PDF to a caller-local path with validated resume and atomic publication
download_papers Download pdf, markdown, or both for 1-10 paper IDs with two bounded concurrent transfers
match_document / match_paper Content-nearest papers to a passage / to a paper
list_conferences / corpus_stats Venue registry / corpus size

Journal work-memory (scoped to the current project by default)

Tool What it does
journal_record Record a work note (memory) or a file's current content (doc, latest-wins)
journal_search Search memory - keyword (FTS5, no embedding) or hybrid/dense/sparse
journal_recent List recent entries
journal_index_dir Batch-index a local dir's files into the journal (latest-wins per file)

Code KB (source stays local - only chunks are uploaded)

Tool What it does
index_code AST-chunk a repo locally (40+ languages) and index it, scoped to you
search_code Semantic code search with path:line citations
index_inventory Your indexed-file tree: user -> host -> project -> dir -> file

Public Code (admin-managed shared source corpus)

Tool What it does
list_public_code_sources List configured sources, active revisions, coverage, profiles, and update state
add_public_code_source Register an HTTPS Git upstream using server-side proxy/credential profile references
check_public_code_updates Queue remote revision checks for selected sources or domains
index_public_code_sources Queue bare mirror refresh, AST chunking, shared GPU embedding, and atomic promotion
set_public_code_update_policy Change manual/scheduled update policy without exposing credentials
public_code_job_status Poll durable source/file/chunk progress for checks and indexing
search_public_code Flat domain or exact-repository hybrid/dense/keyword search with full code citations

ACE playbook (accumulated, curated lessons per project)

Tool What it does
ace_context_aware / ace_playbook Retrieve relevant / list all curated bullets
ace_enhance_prompt / ace_smart_generate Attach playbook lessons to a prompt (no LLM call)
ace_smart_reflect Curate a transferable lesson into the playbook (grow-and-refine dedup)

Code KB language coverage

index_code chunks 40+ languages structurally via tree-sitter (chonkie CodeChunker): Python, TypeScript/TSX/JS/JSX (React), Java, Kotlin (incl. Jetpack Compose .kt/.kts), Swift, Go, Rust, C/C++, C#, Ruby, PHP, Lua, Scala, Dart, R, Julia, Elixir, Erlang, Haskell, OCaml, SQL, GraphQL, Protobuf, HTML, CSS/SCSS (Tailwind = CSS classes), Vue, Svelte, shell, PowerShell, Dockerfile, Terraform/HCL, CMake, YAML/JSON/TOML/XML, and more. Grammarless config/text files fall back to line-window chunks; docs (.md) and binaries are skipped (docs belong in the journal via journal_index_dir).

Install

Claude Code

# LAN (no key):
claude mcp add retrieval -- uvx --from retrieval-mcp==0.4.4 retrieval-mcp
# Off-LAN (public gateway + key):
claude mcp add retrieval \
  --env RETRIEVAL_API_URL=https://retrieval.rnarket.com \
  --env RETRIEVAL_API_KEY=sk-... \
  -- uvx --from retrieval-mcp==0.4.4 retrieval-mcp

Claude Desktop / any MCP client

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "retrieval": {
      "command": "uvx",
      "args": ["--from", "retrieval-mcp==0.4.4", "retrieval-mcp"],
      "env": {
        "RETRIEVAL_API_URL": "https://retrieval.rnarket.com",
        "RETRIEVAL_API_KEY": "sk-..."
      }
    }
  }
}

No uv? pip install retrieval-mcp then use "command": "retrieval-mcp".

Automatic code-index refresh

index_code(...) returns a local job ID before repository walking, hashing, AST chunking, upload, GPU embedding, or Qdrant upsert completes. Poll that same ID with index_code_status() through the preparing, backend queue, and terminal phases. A second index request for the same scope reuses the active job instead of starting another scan.

With auto_refresh=True, the client then keeps one filesystem watcher for that absolute repository path. Ordinary file events hash and chunk only the touched paths; ignore-rule changes trigger a full reconcile. search_code() never waits for the watcher or indexing: it returns the last completed snapshot and reports freshness separately.

Git repositories continue to honor Git's ignore rules by default. Any directory, including non-Git projects, can add scope-relative patterns to .retrievalignore; callers can add temporary patterns with exclude_globs=["generated/**", "private.py"]. Explicit delete_code() cancels/fences stale refresh work and removes vectors, inventory, and the saved refresh policy.

Config (env)

Var Default Notes
RETRIEVAL_API_URL http://10.100.100.111:8000 LAN compute box (no key). Off-LAN, set to https://retrieval.rnarket.com.
RETRIEVAL_API_KEY - sk-... key for the gateway (create under /auth/keys). Required off-LAN.
Journal/code scope current absolute directory path The client derives scope from the directory you run or pass to each tool, so projects do not leak into each other.

Paper artifact transport

  • get_paper_markdown(..., save_path=None) returns the complete JSON-backed Markdown to the MCP caller. With save_path, it instead uses the raw GET /api/papers/{paper_id}/markdown file route, so large Markdown is not buffered as JSON by the gateway or MCP process.
  • Markdown files and PDFs use HTTP Range with validated Content-Range. If the connection closes after writing a valid prefix, the next request resumes from the exact local byte offset. Completed files are published atomically and are not overwritten unless overwrite=True.
  • download_papers accepts at most 10 paper IDs, preflights all destination names, disambiguates sanitized filename collisions with a stable digest, and reuses the single-artifact Range paths with at most two concurrent transfers. Errors are reported per paper/artifact.
  • The separate authenticated HTTP POST /api/papers/download-batch endpoint serves a one-shot ZIP for browser/API clients. It is capped at 10 papers and 1 GiB of source artifacts, allows at most two concurrent archive builds, and intentionally rejects Range because each generated archive is a new file.

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.11)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Ironbox4pip from gravatar.com Ironbox4pip

License

MIT

Requires

Python >=3.10

Tags

ace code-search llm mcp model-context-protocol papers retrieval search

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

retrieval_mcp-0.4.4.tar.gz (53.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

retrieval_mcp-0.4.4-py3-none-any.whl (53.3 kB view details)

Uploaded Python 3

File details

Details for the file retrieval_mcp-0.4.4.tar.gz.

File metadata

  • Download URL: retrieval_mcp-0.4.4.tar.gz
  • Upload date:
  • Size: 53.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for retrieval_mcp-0.4.4.tar.gz
Algorithm Hash digest
SHA256 e66f65518f6c5ea7e8b25f298fc0827c9157120c542c14276625dbb045c6f2b1
MD5 1c5eb3c99041e9f12767ab8a93190193
BLAKE2b-256 1e42d2822bbd7cecb1fb2a40a3a0d4b6d62cd969d581169e87f5cbff2d151cc7

See more details on using hashes here.

File details

Details for the file retrieval_mcp-0.4.4-py3-none-any.whl.

File metadata

  • Download URL: retrieval_mcp-0.4.4-py3-none-any.whl
  • Upload date:
  • Size: 53.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for retrieval_mcp-0.4.4-py3-none-any.whl
Algorithm Hash digest
SHA256 7498d28fa42f4eaf138b422eb14ef11506889dc7c9ec3686eaf6978526a323ee
MD5 d1dca7be9c915961928505b4e5d4eed2
BLAKE2b-256 a70692d9ea20c31424dac3ed2069f16b05fd810cad341de32e766db6a6a513f2

See more details on using hashes here.

Release history Release notifications | RSS feed

0.4.11

2 files

0.4.10

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

This release

0.4.4 This release

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.2

1 file

0.3.1

2 files

0.3.0

2 files

0.2.37

2 files

0.2.36

2 files

0.2.35

2 files

0.2.34

2 files

0.2.33

2 files

0.2.32

2 files

0.2.31

2 files

0.2.30

2 files

0.2.29

2 files

0.2.28

2 files

0.2.27

2 files

0.2.26

2 files

0.2.25

2 files

0.2.24

2 files

0.2.23

2 files

0.2.22

2 files

0.2.21

2 files

0.2.20

2 files

0.2.19

2 files

0.2.18

2 files

0.2.17

2 files

0.2.16

2 files

0.2.15

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page