PaperMind — Research-Paper RAG, as an MCP Server and a Web App

Give any AI assistant a searchable, citable library of research papers. PaperMind indexes PDFs into PostgreSQL + pgvector and exposes them through the Model Context Protocol (MCP), so Claude Desktop (or any MCP client) can search your papers and answer with (paper, page) citations. The same retrieval also powers a FastAPI web app.

Highlights

• MCP server with all three primitives. 3 tools, 2 resources and 1 prompt. Typed Pydantic outputs, so every tool publishes an output schema. Tool annotations mark which tools are read-only.
• Hybrid retrieval, tuned by measurement. Semantic search (pgvector) plus Postgres full-text search, fused with Reciprocal Rank Fusion. The fusion weight was chosen on a 36-question labeled eval with a decision rule fixed before the run: 78% hit@1, 97% recall@5, 0.841 MRR (see Evals).
• Security enforced in code, not in the prompt. add_paper can only read from inbox/; path traversal, symlink escapes and fake PDFs are refused. HTTP mode requires a bearer token and refuses to start on a network address without one.
• Tested. 59 unit, protocol and HTTP tests plus live retrieval evals. CI runs lint and tests on Python 3.12 and 3.14, builds the Docker image, and checks that the container rejects unauthenticated requests.
• Runs two ways. Over stdio for desktop clients, or over Streamable HTTP in a multi-stage, non-root Docker image (836 MB, down from 978 MB) with the embedding model built in.

Architecture

flowchart LR
    subgraph Clients
        CD["Claude Desktop/ any MCP client"]
        B["Browser"]
    end
    CD -- "stdio, or Streamable HTTP+ bearer token" --> M["MCP serverapp/mcp_server.pytools · resources · prompt"]
    B --> F["FastAPI appapp/main.py"]
    M --> H["Hybrid searchapp/hybrid_search.py"]
    F --> H
    H --> S["Semanticfastembed bge-small"]
    H --> K["KeywordPostgres full-text (GIN)"]
    S --> V[("PostgreSQL + pgvectorlocal Docker or Neon")]
    K --> V
    I["inbox/ PDFs"] -- "add_paper:validate → copy → chunk → embed" --> V

The MCP client’s own model does the reasoning. PaperMind’s job is retrieval you can trust: find the right passages and return them with their source paper, page and relevance score.

MCP server

Use it in Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude:

{
  "mcpServers": {
    "papermind": {
      "command": "/ABSOLUTE/PATH/TO/papermind/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/papermind/app/mcp_server.py"]
    }
  }
}

Logs go to stderr, because stdout carries the protocol. On macOS they appear in ~/Library/Logs/Claude/mcp-server-papermind.log.

Inspect it

npx @modelcontextprotocol/inspector .venv/bin/python app/mcp_server.py

Serve it over HTTP (Docker)

echo "PAPERMIND_TOKEN=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" >> .env
docker build -t papermind-mcp .
docker run --rm --env-file .env -p 127.0.0.1:8765:8765 \
  -v "$PWD/data:/app/data" -v "$PWD/inbox:/app/inbox" papermind-mcp

python scripts/smoke_http.py      # sends the token from .env

Clients authenticate with Authorization: Bearer . Without Docker, python app/mcp_server.py --http serves on 127.0.0.1:8765; it won’t bind to a network address unless a token is set.

The server only accepts requests addressed to localhost and, when a browser sends an Origin, only from localhost pages. If you serve it under a domain, add it with PAPERMIND_ALLOWED_HOSTS and PAPERMIND_ALLOWED_ORIGINS.

Search: how it works and how it was tuned

search_papers runs two searches over the same chunks and merges them:

1. Semantic: the query is embedded (bge-small-en-v1.5) and matched against pgvector by cosine similarity. Finds passages with the same meaning.
2. Keyword: Postgres full-text search over a generated tsvector column with a GIN index. Finds passages with the same words. Queries are reduced to alphanumeric OR-terms, so user input can’t inject query operators.
3. Reciprocal Rank Fusion: each list votes weight / (60 + rank) per chunk; chunks ranked well by both win. Ranks are fused rather than raw scores, which aren’t on comparable scales. If full-text search is unavailable, search falls back to semantic-only instead of failing.

Evals

scripts/eval_retrieval.py runs labeled questions (evals/) through every method and reports hit@1 (was the #1 result from the right paper?), recall@5 and MRR. Full output: evals/results.md.

What the numbers showed:

• Equal-weight fusion was slightly worse than semantic alone, so keyword search is a light tiebreaker (weight 0.5), not an equal partner. The weight was picked by a rule fixed before the run (best MRR; within 0.02, higher recall@5 wins), not by trying values until a test passed.
• The embedding model handles exact terms well on its own: 10/10 on queries like “PagedAttention” or “RAG-Sequence versus RAG-Token”.
• Most remaining misses are long-document bias: T5 (67 pages, covers nearly every topic) wins many plain-English questions under any weight. Tracked in #9.

python scripts/explain_search.py "" shows both rankings and the fused result for any query.

Security

Scope: MCP authorization makes the server an OAuth resource server. A shared secret suits a self-hosted tool; full OAuth means swapping in a TokenVerifier that validates JWTs from an authorization server (Auth0, Keycloak). Nothing else changes.

Bugs found by testing

• No DNS-rebinding protection in Docker: the MCP SDK enables Origin checks only when the server binds a loopback address, and the image binds 0.0.0.0, so a request from any website’s origin was accepted (with a valid token). Found by pointing skillbench’s mcp-server-hardening probe at the container; fixed by configuring the checks for every bind address, with tests and a CI check.
• Path traversal in the web /upload endpoint: a crafted filename could write outside data/. Found while writing the security tests; fixed with a regression test.
• Dead connections after Neon auto-suspends: a server idle for hours failed its next search with AdminShutdown: terminating connection due to administrator command, because the pool reused a connection the database had killed. Found in a long-running container’s logs, reproduced by restarting Postgres between two queries, and fixed with pool_pre_ping + pool_recycle (#13).

Tests

pip install -r requirements-dev.txt
ruff check app tests scripts
pytest -v                      # 59 fast tests, no database needed
pytest -m integration -v       # retrieval checks against the real vector store
python scripts/eval_retrieval.py

The fast suite connects a real in-process MCP client to the server, and sends real HTTP requests through the SDK’s auth middleware. The database and embedder are replaced with fakes, so it checks the protocol surface, input validation, fusion logic and security boundaries without needing any infrastructure.

Web app

docker compose up -d                       # local Postgres + pgvector
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                       # defaults are fully local
python -m app.embed_store                  # index the PDFs in data/
uvicorn app.main:app --reload              # http://localhost:8000

Configuration

Secrets live only in a git-ignored .env. The committed .env.example documents every setting.

Project structure

app/
├── mcp_server.py      # MCP server: tools, resources, prompt; stdio + HTTP
├── hybrid_search.py   # semantic + keyword search fused with RRF
├── keyword_search.py  # Postgres full-text search (tsvector + GIN)
├── auth.py            # bearer-token verifier for HTTP mode
├── http_security.py   # Origin/Host checks against DNS rebinding
├── retrieval_metrics.py
├── embed_store.py     # pgvector storage, ingestion, connection pooling
├── pdf_loader.py      # PDF -> per-page documents with citation metadata
├── embeddings.py      # fastembed adapter
├── ingest.py          # chunking
├── main.py, rag.py    # FastAPI web app
└── config.py          # provider/DB selection from env vars
evals/                 # labeled questions + latest results
scripts/               # eval, search explainer, HTTP smoke test
tests/                 # protocol, security, auth, fusion, metrics, API tests
Dockerfile             # multi-stage, non-root MCP server image
.github/workflows/     # CI: lint + tests (3.12, 3.14) + Docker build, auth and Origin checks

Roadmap

• [x] End-to-end RAG with citations, plus a web UI
• [x] MCP server: tools, resources, prompt, typed outputs, annotations
• [x] Security boundary, tests and CI
• [x] Streamable HTTP transport + multi-stage Docker image
• [x] Hybrid retrieval with a labeled eval set and measured tuning
• [x] Bearer-token auth for HTTP mode
• [x] DNS-rebinding protection (Origin/Host checks) for every bind address
• [x] Off deprecated langchain-community (verified identical text and vectors)
• [ ] Long-document bias: per-paper diversity or length normalization (#9)
• [ ] Full OAuth via a JWT TokenVerifier

Contact

Nemili Enoch Das, MS Computer Science @ George Washington University. Open to full-time and early-career software engineering roles in AI infrastructure, backend and ML systems.

• Email: [email protected]
• GitHub: @Enoch-Nemili
• LinkedIn: enoch-nemili

Contributing

See CONTRIBUTING.md for setup and conventions, CHANGELOG.md for release history, and SECURITY.md to report a vulnerability.

License

MIT. See LICENSE.