# TinyRAG

[![CI](https://github.com/spacecat398/TinyRAG-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/spacecat398/TinyRAG-MCP/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
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:

```bash
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.

```json
{
  "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`:

```ini
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

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

Interactive mode:

```bash
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

```text
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.