nbrag

English | 简体中文

nbrag is a PyPI package that builds a local text knowledge base and exposes it through an MCP server for LLM-powered retrieval.

nbrag is an agentic RAG system: the LLM actively calls retrieval tools, constructs both semantic vector queries and BM25 lexical queries based on context, and autonomously expands its reading range from retrieved chunks.

This lets it complete extreme multi-hop reasoning tasks across multiple files — far beyond what traditional one-shot RAG can do.

nbrag works with any MCP-compatible agent, including OpenClaw, Codex, Claude Code, Cursor, Trae, Opencode, WorkBuddy, lc-agent, and more.

Use it when you want an MCP client to retrieve evidence from files you control, such as internal documentation, regulations, manuals, notes, local project docs, or Python source code.

nbrag comes with vector search, BM25 search, and hybrid search built in. Through well-crafted prompts and 10+ MCP tools, an AI agent can retrieve the most relevant evidence.

When to use nbrag

nbrag is a good fit when you want to:

• index private or local text that hosted services cannot see
• build a domain-specific knowledge base from your own files
• let an MCP client search both vectorized chunks and stored original text
• keep storage on your own machine

nbrag is text-first. If your source material starts as PDF, Word, images, scans, or web pages, convert it to .md, .txt, or .html before ingestion for the best results.

Install

pip install nbrag

To confirm the package is available:

python -m nbrag --help

Configure the API key

By default, nbrag uses SiliconFlow-compatible embedding and rerank endpoints. Set NBRAG_API_KEY before ingestion or serving.

Linux/macOS:

export NBRAG_API_KEY=sk-xxx

Windows PowerShell:

$env:NBRAG_API_KEY = "sk-xxx"

Quick start

The normal workflow is:

1. prepare a folder of text files
2. ingest it with batch_ingest()
3. describe the collection with set_collection_profile()
4. start the MCP server
5. connect your MCP client

Minimal ingestion example

Create a script such as ingest_my_docs.py:

from nbrag import batch_ingest, set_collection_profile

batch_ingest(
    paths=[
        "D:/docs/company_policies",
        "D:/docs/product_manuals",
    ],
    collection_name="company_knowledge",
    file_extensions=[".md", ".txt", ".html"],
    delete_first=True,
    verbose=True,
)

set_collection_profile(
    "company_knowledge",
    display_name="Company Knowledge Base",
    description="Internal policies and product manuals.",
    aliases=["company docs", "policies", "manuals"],
    tags=["internal", "policy", "manual"],
)

Run it with Python:

python ingest_my_docs.py

A few practical notes:

• collection_name is the stable machine-facing identifier （knowledge base name）
• file_extensions lets you limit which text files are ingested
• delete_first=True If you need to adjust parameters, you can fully rebuild this collection. However, if incremental import is supported, avoid deleting it beforehand.
• verbose=True is useful while you are learning or debugging your ingest flow

Why set_collection_profile() matters

Chroma collection names should stay simple and slug-like, such as company_knowledge.

set_collection_profile() adds the human-facing metadata that helps both people and MCP routing understand what a collection contains:

• display_name
• description
• aliases
• tags

That metadata is stored separately from the vector-store internals and is used to make collection selection easier and clearer.

Python source code uses the same ingestion flow

Python projects do not require a separate ingestion workflow. In practice, you usually only change:

• the folders you ingest
• the file_extensions list, for example ['.py', '.md', '.txt']
• the collection description in set_collection_profile()

Example:

from nbrag import batch_ingest, set_collection_profile

batch_ingest(
    paths=[
        "D:/projects/my_framework/src",
        "D:/projects/my_framework/docs",
    ],
    collection_name="my_framework",
    file_extensions=[".py", ".md", ".txt"],
    delete_first=True,
    verbose=True,
)

set_collection_profile(
    "my_framework",
    display_name="My Framework Source And Docs",
    description="Python source and documentation for my_framework.",
    aliases=["my_framework", "framework source", "framework docs"],
    tags=["python", "source", "docs"],
)

Import a GitHub project into an nbrag knowledge base

nbrag.contrib.ingest_github_proj downloads a GitHub repository as a ZIP archive and ingests it directly:

from nbrag.contrib.ingest_github_proj import ingest_github_proj

ingest_github_proj(
    "https://github.com/owner/repo",
    collection_name="repo",
    relative_paths=["src", "docs"],
    branch="main",
    delete_first=True,
    verbose=True,
)

Why use ingest_github_proj

You can use the ingest-github-proj skill in nbrag/.agents/skills/ingest-github-proj/SKILL.md to have the AI generate GitHub ingestion scripts for you.

It lets you vectorize both the source code and the documentation of a GitHub project into one knowledge base, so the LLM can help you write code with grounded, hallucination-free context. An LLM paired with the nbrag MCP server outperforms one paired with context-only MCP servers like Context7.

Start the MCP server

stdio mode

Use stdio when one client owns one server process.

python -m nbrag

HTTP mode

Use HTTP mode when multiple clients or many IDE windows should share one local server process.

python -m nbrag --transport streamable-http --port 9101

Configure MCP clients

stdio configuration

Point the client at the Python environment where nbrag is installed.

Example:

{
  "mcpServers": {
    "nbrag": {
      "command": "python",
      "args": ["-m", "nbrag"],
      "env": {
        "NBRAG_API_KEY": "sk-xxx"
      }
    }
  }
}

If your client does not use the same interpreter as your shell, replace python with the full interpreter path.

HTTP configuration

First start the shared local server:

python -m nbrag --transport streamable-http --port 9101

Then point the client to:

{
  "mcpServers": {
    "nbrag": {
      "url": "http://localhost:9101/mcp"
    }
  }
}

MCP capabilities overview

After the server starts, nbrag exposes a set of retrieval-oriented MCP tools. For human readers, the easiest way to think about them is by capability:

How this differs from naive RAG

Naive RAG is usually a fixed one-shot pipeline: retrieve top-k chunks once and place them into the prompt.

nbrag is different in two practical ways:

• you prepare and control the knowledge base yourself
• retrieval is exposed through MCP tools, so the client can search, refine, inspect original text, and fetch more context when needed

Configuration reference

Configuration priority:

CLI arguments > environment variables > YAML config > defaults

Environment variables

YAML config

nbrag automatically looks for:

1. ./nbrag_config.yaml
2. ./nbrag_config.yml
3. ~/.config/nbrag/config.yaml
4. ~/.config/nbrag/config.yml

Example:

embedding:
  api_key: ${NBRAG_API_KEY}
  base_url: https://api.siliconflow.cn/v1
  model: BAAI/bge-m3

rerank:
  model: BAAI/bge-reranker-v2-m3

storage:
  db_path: ./rag_db

chunking:
  chunk_size: 1000
  chunk_overlap: 150

CLI

python -m nbrag --help
python -m nbrag --transport stdio
python -m nbrag --transport streamable-http --port 9101
python -m nbrag --api-key sk-xxx
python -m nbrag --db-path /data/rag
python -m nbrag --config ./nbrag_config.yaml

Development

git clone https://github.com/ydf0509/nbrag.git
cd nbrag
pip install -e ".[dev]"

python -m nbrag
python -m nbrag --transport streamable-http --port 9101

License

MIT