TinyRAG

CI License: MIT

Your agent already has an LLM. TinyRAG gives it a private knowledge base through MCP.

No Docker. No vector database. No mandatory API key. Add your .txt documents to data/raw/; TinyRAG automatically chunks and indexes them, then exposes the relevant source text to your agent through MCP.

Zero RAG configuration: the defaults work out of the box, with optional semantic retrieval when you need it.

You do not need to install or configure anything yourself. Give this repository to an agent with terminal access, and it can set up TinyRAG for you.

Give this repository to your agent and tell it:

Install TinyRAG, add my text documents, run its evaluation, and configure it as a local stdio MCP server. Do not commit secrets or private documents.

Repository: https://github.com/spacecat398/TinyRAG-MCP

---

你的 Agent 已经拥有 LLM，TinyRAG 通过 MCP 为它提供一个私有知识库。

无需 Docker，无需向量数据库，也不强制要求 API Key。把 .txt 文档放入 data/raw/，TinyRAG 会自动切块并建立索引，再通过 MCP 把相关原文提供给你的 Agent。

RAG 零配置：默认设置开箱即用，需要时再开启语义检索。

你不需要亲自安装或配置任何东西。把这个仓库交给拥有终端权限的 Agent，它会替你完成 TinyRAG 的安装和接入。

把这个仓库地址发给你的 Agent，并告诉它：

安装 TinyRAG，添加我的文本文档，运行项目评估，并将它配置为本地 stdio MCP 服务器。不要提交密钥或私人文档。

仓库地址：https://github.com/spacecat398/TinyRAG-MCP

---

Agent Instructions

This section is written for AI agents that install, configure, or operate TinyRAG.

Objective

Install TinyRAG as a local MCP server and expose the user's UTF-8 .txt documents as searchable knowledge. Prefer the smallest working configuration. Do not add Docker, a vector database, or an LLM dependency unless the user explicitly requests one.

Requirements

• Python 3.12 or newer
• uv preferred; pip is supported
• Git
• A host that can launch local stdio MCP servers

Install

git clone https://github.com/spacecat398/TinyRAG-MCP.git
cd TinyRAG-MCP
uv sync
uv run python -m unittest discover -s tests -v
uv run python scripts/eval.py

Expected test result: all unit tests pass. Expected evaluation result: 3 passed, 0 failed.

If uv is unavailable:

python -m venv .venv
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
python scripts/eval.py

Activate .venv first when required by the operating system.

Add Knowledge

1. Put UTF-8 .txt files in data/raw/.
2. Run a query or restart the MCP server.
3. TinyRAG automatically rebuilds data/processed/ when source file names, modification times, or chunk settings change.

Do not commit private documents unless the user explicitly approves it. The included sample documents may be removed.

Configure MCP

Use the following local stdio server definition. Replace cwd with the absolute repository path on the current machine.

{
  "mcpServers": {
    "tinyrag": {
      "command": "uv",
      "args": ["run", "python", "rag_app/mcp_server.py"],
      "cwd": "/absolute/path/to/TinyRAG-MCP"
    }
  }
}

Windows paths may use forward slashes, for example C:/Users/name/TinyRAG-MCP.

Configuration file names and locations vary by MCP host. Adapt the object to the host's schema without changing the command, arguments, or working directory. TinyRAG uses stdio; do not configure it as an HTTP server.

Available Tools

Tool	Purpose
query_knowledge_base(question)	Retrieve relevant context and return a lightweight grounded answer or excerpt
search_relevant_chunks(question, top_k=3)	Return source chunks for the calling agent to reason over
list_documents()	List indexed source documents

For agentic workflows, prefer search_relevant_chunks when the calling agent should produce the final answer itself.

Retrieval Modes

TinyRAG works without an API key:

• Default: local keyword retrieval
• Optional: semantic retrieval through an OpenAI-compatible Embedding API
• Fallback: keyword retrieval when the Embedding API is unavailable

To enable semantic retrieval, create .env from .env.example:

TINYRAG_ENABLE_REMOTE_EMBEDDINGS=true
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small

Never commit .env. Remote embeddings stay disabled unless TINYRAG_ENABLE_REMOTE_EMBEDDINGS=true is set explicitly. When enabled, document chunks and queries are sent to the configured API endpoint. Inform the user before enabling a remote endpoint for private data.

Direct Query

uv run python scripts/query.py "What does the knowledge base say about RAG?"

Interactive mode:

uv run python scripts/query.py

Operational Constraints

• Supported source format: .txt only
• Transport: local MCP stdio only
• Generation: lightweight rule/excerpt generation, not a general-purpose LLM
• Storage: JSON cache under data/processed/
• Default chunk size: 500 characters
• Default overlap: 80 characters
• Default retrieval count: 3 chunks

The calling agent is expected to handle general reasoning and answer generation. TinyRAG focuses on loading, caching, and retrieving local context.

Safety Rules

• Never expose or commit .env.
• Never commit .venv/ or data/processed/.
• Treat files in data/raw/ as potentially private.
• Do not silently enable a remote Embedding API.
• Do not delete user documents when rebuilding the cache.
• Keep paths relative to the repository except for the MCP host's required absolute cwd.

Important Files

rag_app/mcp_server.py   MCP stdio entry point
rag_app/pipeline.py     retrieval pipeline
rag_app/retriever.py    keyword and embedding retrieval
rag_app/cache.py        automatic local cache
data/raw/               user source documents
data/processed/         generated cache, ignored by Git
scripts/eval.py         smoke evaluation
scripts/query.py        command-line query tool
.env.example            optional embedding configuration
CHANGELOG.md            release notes and upgrade changes
LICENSE                 MIT license terms

Completion Check

Before reporting installation complete, verify all of the following:

1. uv run python -m unittest discover -s tests -v and uv run python scripts/eval.py pass.
2. data/raw/ contains the intended documents.
3. The MCP configuration uses an absolute and existing cwd.
4. The MCP host can see query_knowledge_base, search_relevant_chunks, and list_documents.
5. No secret or private generated file is staged in Git.