Skip to main content
Glama

Folio

License: MIT Backend CI Console CI Release

Turn a folder of documents into a search tool for Claude, Cursor and any other MCP client: hybrid vector + Chinese BM25 retrieval, a reranker, and auto-merged passages, one Folio_<folder> tool per folder.

Documentation · 繁體中文 · Roadmap · Changelog

The Search Playground: an answer with citations, and each result's vector, BM25, fusion and rerank scores

Folio is an open-source retrieval-augmented generation (RAG) server for the Model Context Protocol. Each folder becomes a Folio_<folder> tool with three modes, search, list and read. It is an OAuth 2.1 resource server: it verifies tokens offline and never issues them, and pairs with MCP Gate as the authorization server. Folio was called Agentic RAG up to v1.1.0; the database names (agentic_rag) and the storage layout keep the old name, and nothing needs migrating.

What's new

1.4.1: folders belong to the person, not to one token, so every personal access token and OAuth sign-in of one MCP Gate user sees the same folders; signing out ends the console session on the server; answers come in the question's language. See the CHANGELOG, and the ROADMAP for what comes next (1.5: a Docker image, backups, and OCR and speech through an OpenAI-compatible API).

Removed in 1.5: the built-in OCR, the built-in speech-to-text (FireRedASR, docling-whisper) and the /v1 media endpoints. 1.4.x keeps them working and warns in the log; /v1 responses carry a Deprecation header. Move to an OpenAI-compatible vision model for scanned PDFs and images and an OpenAI-compatible transcription endpoint for audio, for example both served by Forgeyard. See what replaces them.

Related MCP server: RAG3 MCP Server

Key features

  • Hierarchical chunks that merge back. Small leaves for precise matching, large parents for context, never across a section; several hits in one passage come back as the whole passage.

  • Hybrid search, tuned for Chinese. Dense vectors (pgvector) and BM25 fused with Reciprocal Rank Fusion; Chinese is word-segmented first (CKIP, jieba or bigram).

  • Cross-encoder reranking (mxbai-rerank-base-v2, bge-reranker-v2-m3), and MCP search says when nothing relevant was found.

  • Contextual retrieval. An LLM writes a short context line for each chunk at index time; re-indexing an edited file only redoes the chunks that changed. Files indexed by an older chunking pipeline or another embedding model are marked for re-indexing.

  • Per-person folders. You only see the folders of your MCP Gate account, over MCP, REST and the console alike.

  • Many formats. PDF, Office (including legacy and RTF), OpenDocument, HTML and MHTML, Markdown, EPUB, email, images with OCR, and audio.

  • Measured, not guessed. A public 205-question golden set and an evaluation harness; the console scores your own folders on Recall@k, MRR and nDCG@k.

  • A console at /admin: folders and files, a Search Playground with the per-signal trace, index jobs, query analytics and knowledge gaps, evaluation, live settings, health and an audit log.

  • Local GPU, CPU or cloud. AMD ROCm, NVIDIA CUDA or CPU for in-process models, or every model behind an OpenAI-compatible API with no torch at all.

Installation

You need:

  • Python 3.12 and uv;

  • PostgreSQL with the pgvector extension;

  • OpenAI-compatible endpoints for the embedding, LLM and reranker models (vLLM, Ollama, Forgeyard or a cloud provider);

  • LibreOffice (soffice) for legacy Office files and RTF.

git clone https://github.com/xianhong1208/folio-rag.git
cd folio-rag

# Local models need the `local` extra, and torch comes from a dependency group:
# always pass one of rocm-r714 | cuda | cpu with it (cuda = CUDA 13.0, NVIDIA driver 580+).
# All-cloud: plain `uv sync`.
uv sync --extra local --group cuda

cp .env.example .env         # set DATABASE_URL (PostgreSQL + pgvector)
# edit config/config.yaml: rag.embedding / rag.llm / rag.rerank endpoints,
#                          auth.issuer / auth.audience, server.port

uv run python main.py        # creates the schema and runs migrations on start

Folio listens on http://0.0.0.0:5039: the MCP endpoint is /mcp and the console is /admin. Run it as the user that owns .venv: NLTK 3.10.4+ refuses data files owned or writable by another account, and long plain-text paragraphs then fail to split (chown -R <service user> .venv).

Quick start

Folio authenticates through MCP Gate. Register Folio there first: MCP Gate only issues tokens for audiences it knows.

1. Register the server in MCP Gate. Services → Register Service, with this server's host, port and path (/mcp). The audience defaults to the MCP URL, for example http://127.0.0.1:5039/mcp.

2. Point Folio at MCP Gate in config/config.yaml:

auth:
  enabled: true
  issuer:   "http://localhost:4568"          # MCP Gate base URL (RS256 JWKS issuer)
  audience: "http://127.0.0.1:5039/mcp"      # must equal the audience registered in MCP Gate

3. Create a folder and add documents, in the console (Library → New Folder → Upload Files, signed in with a personal access token from MCP Gate) or over REST:

curl -X POST http://127.0.0.1:5039/api/folders/ \
  -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"name":"product-docs"}'

4. Connect a client. An OAuth-capable client needs nothing up front:

claude mcp add --transport http folio http://127.0.0.1:5039/mcp

On first use the client registers with MCP Gate and shows the consent screen; then the Folio_product-docs tool appears. For scripts, pass a personal access token as a bearer header.

5. Ask.

Folio_product-docs  mode="search"  query="how do I rotate the signing key?"

You get the matching passages, merged where they belong together, each with a relevance score and its source file and heading.

Deployment options

Profile

Models

Install

local (default)

Anything goes. The shipped config calls self-hosted embedding, LLM and reranker endpoints, and runs CKIP segmentation, Docling parsing with OCR and FireRedASR speech-to-text in-process

uv sync --extra local --group rocm-r714 | cuda | cpu

hybrid

The same, for a mix of self-hosted and cloud endpoints; API keys written literally in config.yaml are warned about

as local

cloud

Every role is an HTTP endpoint and keys must be ${ENV} references; no torch and no model downloads

uv sync

Set it with rag.profile; see Cloud profile. Keep the console and the unauthenticated /v1 media endpoints on a trusted network or behind a reverse proxy with HTTPS; /mcp and /api/rag/* need a valid token. A Docker image and compose file are planned for 1.5.

Documentation

How it works

the pipeline, retrieval in detail (BM25, segmentation, reranking, latency, relevance cutoff), measuring retrieval, every feature in detail

Configuration

every setting you are likely to touch, and the cloud profile

Authentication

folder ownership by MCP Gate user, and the token revocation feed

Console

signing in, the two permission tiers, each page, re-indexing after an upgrade or an embedding model change

API reference

MCP, REST, console and health endpoints

PostgreSQL operations

connection budget and database upkeep

Development

architecture, checks, CI and releasing

Retrieval evaluation

the golden set, the harness and the baselines

Contributing

Issues and pull requests are welcome. Branch off dev and open the pull request into dev. Code and comments are in English; the console is English only by decision. Run the checks in docs/development.md first: uv run pytest, uvx ruff check ., and npm test plus npm run build in frontend/ when you change the console.

Licence

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to connect local knowledge bases, preview and index selected directories, search for traceable snippets with source metadata, and read indexed document versions through MCP tools.
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to index and retrieve local documents through semantic, BM25, or hybrid search, with tools for chunk reads and page images accessible from MCP clients such as Codex and ChatGPT web.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables querying a folder of company documents over MCP and retrieving matching passages with file:line citations for Claude to answer from. Supports keyword and multilingual hybrid search over an incrementally indexed SQLite knowledge base.
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP clients to search a folder of markdown notes and read individual notes through two read-only tools, using hybrid dense-vector and BM25 retrieval.
      2
      MIT