rag-ai-scientist

Installable toolkit for local RAG indexing + MCP serving in scientific workflows.

rag-ai-scientist gives you:

• a CLI to initialize and build a local vector database from your papers and notes,
• an MCP server entrypoint for any MCP-compatible AI client,
• packaged skills under rag_ai_scientist/skills/ (workflow checklists—no Git clone needed),
• a challenge harness (reference profile: whest) — the example RAG → skill → validate → score loop,
• Overleaf Git sync tools (same credentials as your Overleaf MCP) for pushing LaTeX bundles.

On PyPI, this README contains the complete install and MCP setup workflow. Additional examples are included in the source distribution.

End-user workflow (pip only — no clone required)

You install from PyPI, create any folder for your project, put your research materials there, index once, then connect an MCP-compatible AI client.

The workflow is: install → add files under references/ → init-references → setup-rag → configure any MCP client → update notes and rebuild as needed.

Minimal command sequence (after pip install rag-ai-scientist):

mkdir -p ~/my-ai-scientist/references
cd ~/my-ai-scientist
# Add your own .md / .pdf files under references/

rag-ai-scientist init-references --project-root . --references-dir ./references
rag-ai-scientist setup-rag --project-root . --force
rag-ai-scientist mcp --project-root .    # configure this command in your MCP client

• query_analysis_knowledge answers from your indexed files.
• get_skill loads packaged skills (e.g. cms-higgs-opendata, whest-estimation-challenge) without indexing anything extra.

You update your AI scientist by editing files under references/ (and configs/references.yaml if paths change), then setup-rag --force again.

Installation

From PyPI (recommended)

python -m pip install rag-ai-scientist

Pinned example:

python -m pip install rag-ai-scientist==0.1.9

PyPI project page: rag-ai-scientist

Verify

rag-ai-scientist --help
python -c "import rag_ai_scientist; print(rag_ai_scientist.__version__)"

From source (maintainers / contributors only)

git clone https://github.com/uzzielperez/rag-ai-scientist.git
cd rag-ai-scientist
git checkout dev   # or your working branch
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e .

Isolation tip: use a dedicated venv (e.g. ~/venvs/rag-ai-scientist) instead of mixing with heavy analysis stacks.

CLI commands

Common flags: --project-root, --force (rebuild index), --references-dir (with init-references).

Challenge harness (WHEST as the example loop)

# From a whest-starterkit checkout:
rag-ai-scientist harness run --project-root . --profile whest --dry-run
rag-ai-scientist harness run --project-root . --profile whest --until-stage validate

MCP tools: harness_list_profiles, harness_run. Skills: challenge-harness, whest-estimation-challenge.

Overleaf (built-in + companion MCP)

export OVERLEAF_PROJECTS_CONFIG="$HOME/.config/overleaf-mcp/projects.json"
rag-ai-scientist overleaf list-projects
rag-ai-scientist overleaf sync --bundle-dir output/overleaf_bundle --dry-run

MCP tools: overleaf_list_projects, overleaf_status, overleaf_list_files, overleaf_read_file, overleaf_sync_bundle. Skill: overleaf-paper-sync.

Keep the Node Overleaf MCP for section-level edits; use these Python tools for list/read/bundle push.

Connect an MCP client

The server uses standard MCP over stdio. In VS Code with GitHub Copilot, add this to .vscode/mcp.json (use absolute paths):

{
  "servers": {
    "rag-ai-scientist": {
      "type": "stdio",
      "command": "/absolute/path/to/venv/bin/rag-ai-scientist",
      "args": ["mcp", "--project-root", "/absolute/path/to/my-ai-scientist"]
    }
  }
}

Other MCP clients use the same command and arguments, though their configuration file/schema may differ. For clients using an mcpServers object (including Cursor, Cline, and Claude Desktop), use:

{
  "mcpServers": {
    "rag-ai-scientist": {
      "command": "/absolute/path/to/venv/bin/rag-ai-scientist",
      "args": ["mcp", "--project-root", "/absolute/path/to/my-ai-scientist"]
    }
  }
}

See Getting started for setup details and the optional .rag-ai-scientist/.env file for LLM keys. Existing projects with an index under .cursor/rag_db continue to work without moving it.

Packaged skills and examples

• Skills ship inside the installed package. Access via MCP get_skill:
  • cms-higgs-opendata — CMS Run-1 Higgs open-data replication
  • whest-estimation-challenge — ARC WhiteBox Estimation Challenge 2026 (use with whest-starterkit)
  • challenge-harness — generic harness / example-loop skill
  • overleaf-paper-sync — Overleaf Git sync + MCP tools
• Additional get_skill, client configuration, and whest challenge examples are included in docs/examples/README.md in the source distribution.

Whest challenge quick start (combined workflow)

git clone https://github.com/AIcrowd/whest-starterkit.git && cd whest-starterkit
uv sync
pip install rag-ai-scientist
bash scripts/setup_rag_references.sh   # symlinks docs into references/
rag-ai-scientist init-references --project-root . --references-dir ./references --force
rag-ai-scientist setup-rag --project-root . --force

Then configure any MCP-compatible client with --project-root set to your whest-starterkit folder and ask:

Use the whest-estimation-challenge skill. Start from mean propagation and improve the estimator.

Running agents beside a separate lab environment

If training runs use a different conda/venv than rag-ai-scientist:

1. Install rag-ai-scientist in its own small venv.
2. Keep --project-root pointed at your research folder.
3. Run heavy jobs via explicit wrappers (conda run, scripts) from the agent — see Runbook for patterns.

Repository layout (when developing from source)

rag_ai_scientist/
  cli.py                  # CLI entrypoint
  mcp_server.py           # MCP server (RAG + skills + harness + Overleaf)
  harness/                # Challenge loops (whest reference profile)
  overleaf/               # Git-based Overleaf client
  skills/                 # Packaged skills (ship in wheel)
rag/
  index_documents.py      # Indexer used by setup-rag
configs/
  references.example.yaml # Example only — users run init-references instead
  overleaf.example.yaml   # Overleaf sync template
docs/
  GETTING_STARTED.md      # Primary user guide (pip-only path)
  examples/               # Maintainer docs / optional narratives

Browse on GitHub: docs/.

Development & PyPI releases

Contributor workflow and release steps: DEV_README.md.

License

• Open-source: AGPL-3.0-or-later (LICENSE)
• Commercial: see LICENSE-COMMERCIAL.md

Security notes

• Never commit secrets (.env, API keys).
• Treat .rag-ai-scientist/rag_db (or your configured data directory) as sensitive if your indexed PDFs are sensitive. Legacy .cursor/rag_db indexes are also supported.