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,
• a vendored Overleaf Node MCP server (overleaf install-node-server) so anyone can run the full read/write/commit/push toolset.

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.10

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
# Anyone can install the companion Node MCP server straight from the wheel:
rag-ai-scientist overleaf install-node-server --dest ~/.config/overleaf-mcp
npm install --prefix ~/.config/overleaf-mcp

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.

Overleaf Node MCP pickup (no separate download)

The full read/write/commit/push server ships inside the wheel as rag_ai_scientist/overleaf/node/ (overleaf-mcp-server.js + overleaf-git-client.js, needs @modelcontextprotocol/sdk). After pip install rag-ai-scientist:

rag-ai-scientist overleaf install-node-server --dest ~/.config/overleaf-mcp
npm install --prefix ~/.config/overleaf-mcp

Then point any MCP client at it:

{
  "mcpServers": {
    "overleaf": {
      "command": "node",
      "args": ["/Users/YOU/.config/overleaf-mcp/overleaf-mcp-server.js"],
      "env": {"OVERLEAF_PROJECTS_CONFIG": "/Users/YOU/.config/overleaf-mcp/projects.json"}
    }
  }
}

Tools: list_files, read_file, write_file, get_sections, get_section_content, status_summary, list_projects, delete_file, commit_changes, push_changes, git_status, upload_file.

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.