Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ crate-type = ["cdylib", "rlib"]

[features]
default = []
cli = ["dep:clap", "dep:comfy-table", "dep:dialoguer", "dep:dirs"]
cli = ["dep:clap", "dep:comfy-table", "dep:dialoguer", "dep:dirs", "dep:toml", "dep:webbrowser"]
python = ["dep:pyo3", "dep:pythonize"]

[dependencies]
Expand All @@ -34,6 +34,8 @@ clap = { version = "4", features = ["derive"], optional = true }
comfy-table = { version = "7", optional = true }
dialoguer = { version = "0.11", optional = true }
dirs = { version = "6", optional = true }
toml = { version = "0.8", optional = true }
webbrowser = { version = "1", optional = true }

# Python bindings (optional)
pyo3 = { version = "0.23", features = ["extension-module"], optional = true }
Expand Down
58 changes: 45 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,35 @@ It also works standalone: as a CLI tool, a Python library, or a Rust crate.

| Mode | What it does | Guide |
|------|-------------|-------|
| **MCP server** (`scix serve`) | Expose SciX tools to Claude, Cursor, Zed, etc. | [docs/mcp-server.md](docs/mcp-server.md) |
| **MCP server** (`scix serve`) | Expose SciX tools to Claude, Cursor, Zed, Gemini CLI, Codex CLI, Windsurf | [docs/mcp-server.md](docs/mcp-server.md) |
| **Chat REPL** (`scix chat`) | Built-in tool-use loop against any model (Anthropic, OpenAI, Gemini, Ollama) — no MCP host needed | below |
| **CLI** (`scix`) | Command-line tool for your terminal | [docs/cli.md](docs/cli.md) |
| **Python library** (`scix_client`) | Native Python module — `pip install scix-client` | [docs/python.md](docs/python.md) |
| **Rust library** (`scix_client`) | Async Rust crate — `cargo add scix-client` | [docs/rust.md](docs/rust.md) |

One binary (`scix`) does everything. Python bindings are auto-generated from the Rust types — zero extra maintenance.

## Install

```bash
# One-line installer (no Rust toolchain required)
curl -sSf https://raw.githubusercontent.com/yipihey/scix-client/main/install.sh | sh

# From PyPI (also gives you the Python module)
pip install scix-client # or: uvx scix-client, pipx install scix-client

# From crates.io (compiles locally)
cargo install scix-client --features cli
# or, prebuilt binary via cargo-binstall:
cargo binstall scix-client
```

Verify your setup at any time with:

```bash
scix doctor
```

## Prerequisites

You need a SciX / ADS API token. Get one (free) at:
Expand All @@ -30,25 +52,18 @@ export ADS_API_TOKEN="your-token-here"

## Quick Start: MCP

Give your AI assistant access to the entire SciX database.

### Install

```bash
cargo install scix-client --features cli
# or: cargo binstall scix-client
```
Give your AI assistant access to the entire SciX database. (Install with any method from [Install](#install) above.)

### Automatic setup (recommended)

```bash
scix setup
```

This detects your installed editors (Claude Code, Claude Desktop, Cursor, Zed), prompts for your API token, validates it, and writes the correct config for each one. Run it once and you're done.
This detects your installed editors (Claude Code, Claude Desktop, Cursor, Zed, Gemini CLI, Codex CLI, Windsurf), prompts for your API token (offering to open the token page in your browser), validates it, and writes the correct config for each one. Run it once and you're done.

Options:
- `scix setup claude-code` — configure only Claude Code
- `scix setup claude-code` — configure only one editor
- `scix setup --yes` — non-interactive (uses env token, configures all detected editors)
- `scix setup --skip-validation` — skip token validation

Expand Down Expand Up @@ -84,11 +99,28 @@ See [docs/mcp-server.md](docs/mcp-server.md) for Cursor, Zed, full tool referenc

---

## Quick Start: CLI
## Quick Start: Chat REPL

Drive scix from any tool-use-capable LLM, with no MCP host required. Set one provider's API key and go.

```bash
cargo install scix-client --features cli
export ANTHROPIC_API_KEY="sk-ant-..." # or OPENAI_API_KEY, GEMINI_API_KEY, OLLAMA_HOST
export SCIX_API_TOKEN="your-ads-token"
scix chat # auto-detects provider

# Or pick explicitly:
scix chat --provider openai --model gpt-5
scix chat --provider gemini --model gemini-2.5-pro
scix chat --provider ollama --model llama3.1:70b
```

Inside the REPL, just ask questions. The model uses the same SciX tools the MCP server exposes (search, export, metrics, libraries, citation/reference networks, object name resolution, paper details).

---

## Quick Start: CLI

```bash
scix search 'first_author:"Perlmutter" supernova' --sort "citation_count desc"
scix export 1999ApJ...517..565P --format bibtex
scix cites 1999ApJ...517..565P --rows 50
Expand Down
81 changes: 81 additions & 0 deletions docs/chat.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# Chat REPL Guide

[Back to README](../README.md)

`scix chat` is a built-in tool-use REPL that drives any tool-use-capable LLM
against the SciX tool set — no MCP host required. Set one provider's API key
and a SciX API token, and go.

## Quick Start

```bash
export SCIX_API_TOKEN="your-ads-token"
export ANTHROPIC_API_KEY="sk-ant-..."

scix chat
```

Inside the REPL you'll see a `>` prompt. Type a question; press Enter. The
model has access to the full SciX tool set; tool calls and results are
printed inline as they happen.

```
> Find the three most-cited papers by Vera Rubin on galaxy rotation curves
[tool] scix_search({"query":"author:\"Rubin, V\" title:\"rotation curve\"","sort":"citation_count desc","rows":3})

The three most-cited papers by Vera Rubin on galaxy rotation curves are:
1. ...
> exit
```

## Providers

Provider is selected with `--provider`, or auto-detected from the first env
var present in this order: `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` →
`GEMINI_API_KEY` → `OLLAMA_HOST`.

| Provider | Env var | Default model | Notes |
|--------------|--------------------------------|-----------------------|-------|
| `anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` | |
| `openai` | `OPENAI_API_KEY` | `gpt-5` | Optional `OPENAI_BASE_URL` for compatible APIs |
| `gemini` | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | `gemini-2.5-pro` | |
| `ollama` | `OLLAMA_HOST` (default `http://localhost:11434`) | `llama3.1:8b` | Uses Ollama's OpenAI-compatible `/v1` endpoint |

Override the model with `--model`:

```bash
scix chat --provider openai --model gpt-5
scix chat --provider gemini --model gemini-2.5-flash
scix chat --provider ollama --model llama3.1:70b
```

## Options

```
scix chat [OPTIONS]

--provider <P> anthropic | openai | gemini | ollama
--model <NAME> Override the default model
--max-turns <N> Maximum tool-call iterations per user message (default 25)
```

## How It Compares to MCP

| Aspect | `scix serve` (MCP) | `scix chat` |
|-------------------|--------------------------------|-----------------------------------|
| Host required | Yes (Claude Code, Cursor, ...) | No — direct API call |
| Bring your own key | Host's key | Yours (one of four providers) |
| Streaming | Host-dependent | Not yet |
| Best for | Daily use in an IDE/editor | Scripting, CI, headless servers, models without an MCP host |

Both modes share the same tool implementations, so behavior is identical.

## Troubleshooting

- **"No LLM provider detected"** — set one of `ANTHROPIC_API_KEY`,
`OPENAI_API_KEY`, `GEMINI_API_KEY`, or `OLLAMA_HOST`, or pass `--provider`.
- **"401 unauthorized"** — your provider key is missing or wrong.
- **"Authentication required"** — your SciX API token is missing
(`SCIX_API_TOKEN`).
- **Tool calls failing repeatedly** — increase `--max-turns`, or run
`scix doctor` to verify connectivity.
11 changes: 10 additions & 1 deletion docs/mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,13 @@ Once connected, you can ask your AI assistant things like:
## Installation

```bash
# From crates.io (recommended)
# One-line installer (prebuilt binary, no Rust toolchain)
curl -sSf https://raw.githubusercontent.com/yipihey/scix-client/main/install.sh | sh

# From PyPI
pip install scix-client # or: uvx scix-client, pipx install scix-client

# From crates.io
cargo install scix-client --features cli

# Pre-built binary (via cargo-binstall — no compile needed)
Expand Down Expand Up @@ -55,6 +61,9 @@ scix setup claude-code # Configure only Claude Code
scix setup claude-desktop # Configure only Claude Desktop
scix setup cursor # Configure only Cursor
scix setup zed # Configure only Zed
scix setup gemini-cli # Configure only Gemini CLI
scix setup codex-cli # Configure only Codex CLI (OpenAI)
scix setup windsurf # Configure only Windsurf (Codeium)

Flags:
--skip-validation Don't test the API token
Expand Down
145 changes: 145 additions & 0 deletions install.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
#!/bin/sh
# scix-client installer
#
# Downloads the latest prebuilt `scix` binary for your platform from
# https://github.com/yipihey/scix-client/releases and installs it to
# ~/.local/bin (or $SCIX_INSTALL_DIR if set).
#
# Usage:
# curl -sSf https://raw.githubusercontent.com/yipihey/scix-client/main/install.sh | sh
#
# Environment:
# SCIX_INSTALL_DIR Install directory (default: $HOME/.local/bin)
# SCIX_VERSION Version to install (default: latest)
# GITHUB_TOKEN Optional, for higher rate limits on api.github.com
#
# Exit codes:
# 1 usage / unsupported platform
# 2 download failed
# 3 install failed

set -eu

REPO="yipihey/scix-client"
INSTALL_DIR="${SCIX_INSTALL_DIR:-$HOME/.local/bin}"
VERSION="${SCIX_VERSION:-latest}"

err() { printf 'error: %s\n' "$*" >&2; exit "${2:-1}"; }
info() { printf '%s\n' "$*"; }

need_cmd() {
if ! command -v "$1" >/dev/null 2>&1; then
err "missing required command: $1"
fi
}

# Pick curl or wget for downloads.
if command -v curl >/dev/null 2>&1; then
DL='curl -fsSL'
DL_OUT='curl -fsSL -o'
elif command -v wget >/dev/null 2>&1; then
DL='wget -qO-'
DL_OUT='wget -qO'
else
err "need curl or wget"
fi

need_cmd uname
need_cmd tar
need_cmd mkdir
need_cmd chmod
need_cmd mv

# Detect platform target triple matching the release artifact names.
detect_target() {
os="$(uname -s)"
arch="$(uname -m)"
case "$os" in
Linux)
case "$arch" in
x86_64|amd64) echo "x86_64-unknown-linux-gnu" ;;
aarch64|arm64) echo "aarch64-unknown-linux-gnu" ;;
*) err "unsupported linux arch: $arch" ;;
esac
;;
Darwin)
case "$arch" in
x86_64) echo "x86_64-apple-darwin" ;;
arm64) echo "aarch64-apple-darwin" ;;
*) err "unsupported macos arch: $arch" ;;
esac
;;
MINGW*|MSYS*|CYGWIN*)
err "windows: please download from https://github.com/$REPO/releases" 1
;;
*)
err "unsupported OS: $os"
;;
esac
}

resolve_version() {
if [ "$VERSION" = "latest" ]; then
api_url="https://api.github.com/repos/$REPO/releases/latest"
if [ -n "${GITHUB_TOKEN:-}" ]; then
tag=$($DL -H "Authorization: Bearer $GITHUB_TOKEN" "$api_url" 2>/dev/null \
| sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
else
tag=$($DL "$api_url" 2>/dev/null \
| sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p' | head -n1)
fi
[ -n "$tag" ] || err "could not resolve latest release tag" 2
echo "$tag"
elif [ "${VERSION#v}" = "$VERSION" ]; then
echo "v$VERSION"
else
echo "$VERSION"
fi
}

TARGET="$(detect_target)"
TAG="$(resolve_version)"
VER="${TAG#v}"
ARCHIVE="scix-v${VER}-${TARGET}.tar.gz"
URL="https://github.com/$REPO/releases/download/$TAG/$ARCHIVE"

info "scix-client installer"
info " repo: $REPO"
info " version: $TAG"
info " target: $TARGET"
info " prefix: $INSTALL_DIR"
info ""

TMP=$(mktemp -d 2>/dev/null || mktemp -d -t scix)
trap 'rm -rf "$TMP"' EXIT INT TERM

info "Downloading $ARCHIVE..."
$DL_OUT "$TMP/$ARCHIVE" "$URL" || err "download failed: $URL" 2

info "Extracting..."
tar -xzf "$TMP/$ARCHIVE" -C "$TMP" || err "extract failed" 2

[ -f "$TMP/scix" ] || err "archive did not contain expected binary 'scix'" 2

mkdir -p "$INSTALL_DIR" || err "cannot create $INSTALL_DIR" 3
chmod +x "$TMP/scix"
mv "$TMP/scix" "$INSTALL_DIR/scix" || err "cannot install to $INSTALL_DIR" 3

info ""
info "Installed: $INSTALL_DIR/scix"

# Friendly PATH check.
case ":$PATH:" in
*":$INSTALL_DIR:"*)
info ""
info "Next: scix setup"
;;
*)
info ""
info "Warning: $INSTALL_DIR is not on your PATH."
info "Add this to your shell profile (.bashrc / .zshrc):"
info " export PATH=\"\$HOME/.local/bin:\$PATH\""
info ""
info "Then run: scix setup"
;;
esac
Loading
Loading