research-master 0.1.40

MCP server for searching and downloading academic papers from multiple research sources
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259

# Installation

This guide covers all methods for installing Research Master.

## Quick Install (macOS with Homebrew)

```bash
# Add the custom tap
brew tap hongkongkiwi/research-master

# Install research-master
brew install research-master

# Start the MCP server
research-master serve --stdio
```

## Packages & Images Summary

| Package/Image | Where | Architectures |
|---|---|---|
| Release binaries (`.gz`, `.zip`) | GitHub Releases | Linux (x86_64, arm64), macOS (x86_64, arm64), Windows (x86_64) |
| Homebrew | Homebrew tap | macOS (x86_64, arm64) |
| `.deb` | GitHub Releases | Linux (amd64, arm64) |
| `.rpm` | GitHub Releases | Linux (x86_64, aarch64) |
| `.apk` | GitHub Releases | Alpine (x86_64, aarch64) |
| `cargo install` | crates.io | Any supported Rust target |
| Docker image | GHCR | linux/amd64, linux/arm64 |
| Docker image (OCR) | GHCR (`-ocr`) | linux/amd64, linux/arm64 |

## GitHub Releases (Binaries)

Download prebuilt binaries from the [GitHub Releases page](https://github.com/hongkongkiwi/research-master/releases). Assets include:

- **Linux (glibc)**: `research-master-x86_64-unknown-linux-gnu.gz`, `research-master-aarch64-unknown-linux-gnu.gz`
- **macOS**: `research-master-x86_64-apple-darwin.gz`, `research-master-aarch64-apple-darwin.gz`
- **Windows**: `research-master-windows.zip`

After downloading:

```bash
# Linux/macOS example
gunzip research-master-<target>.gz
chmod +x research-master-<target>
./research-master-<target> --version
```

## Homebrew (macOS)

```bash
# Add the custom tap
brew tap hongkongkiwi/research-master

# Install research-master
brew install research-master
```

## Linux (Debian/Ubuntu) - DEB Package

```bash
# Download .deb package from GitHub Releases
wget https://github.com/hongkongkiwi/research-master/releases/download/vx.x.x/research-master_x.x.x_amd64.deb
# Or arm64:
# wget https://github.com/hongkongkiwi/research-master/releases/download/vx.x.x/research-master_x.x.x_arm64.deb

# Install the package
sudo dpkg -i research-master_x.x.x_amd64.deb

# Install dependencies if needed
sudo apt-get install -f
```

## Linux (Alpine) - APK Package

```bash
# Download .apk package from GitHub Releases (see asset names/paths)
# Example (x86_64):
# wget https://github.com/hongkongkiwi/research-master/releases/download/vx.x.x/x86_64/research-master-x.x.x-r0.apk

# Install the package
sudo apk add --allow-untrusted research-master-x.x.x-r0.apk
```

## Linux (RedHat/Fedora) - RPM Package

```bash
# Download .rpm package from GitHub Releases
wget https://github.com/hongkongkiwi/research-master/releases/download/vx.x.x/research-master-x.x.x-1.x86_64.rpm
# Or arm64:
# wget https://github.com/hongkongkiwi/research-master/releases/download/vx.x.x/research-master-x.x.x-1.aarch64.rpm

# Install the package
sudo dnf install research-master-x.x.x-1.x86_64.rpm
```

## Crates.io

```bash
cargo install research-master
```

## From Source

```bash
git clone https://github.com/hongkongkiwi/research-master
cd research-master
cargo install --path .
```

## Compile-Time Feature Flags

Individual research sources can be disabled at compile time using Cargo features. By default, all sources are included except Google Scholar (requires `GOOGLE_SCHOLAR_ENABLED=true`).

### Available Features

| Feature | Description |
|---------|-------------|
| `arxiv` | Enable arXiv source |
| `pubmed` | Enable PubMed source |
| `biorxiv` | Enable bioRxiv/medRxiv source |
| `semantic` | Enable Semantic Scholar source |
| `openalex` | Enable OpenAlex source |
| `crossref` | Enable CrossRef source |
| `iacr` | Enable IACR ePrint source |
| `pmc` | Enable PMC source |
| `hal` | Enable HAL source |
| `dblp` | Enable DBLP source |
| `ssrn` | Enable SSRN source |
| `dimensions` | Enable Dimensions source |
| `ieee_xplore` | Enable IEEE Xplore source |
| `europe_pmc` | Enable EuropePMC source |
| `core_repo` | Enable CORE source |
| `zenodo` | Enable Zenodo source |
| `unpaywall` | Enable Unpaywall source |
| `mdpi` | Enable MDPI source |
| `jstor` | Enable JSTOR source |
| `scispace` | Enable SciSpace source |
| `acm` | Enable ACM Digital Library source |
| `connected_papers` | Enable Connected Papers source |
| `doaj` | Enable DOAJ source |
| `worldwidescience` | Enable WorldWideScience source |
| `osf` | Enable OSF Preprints source |
| `base` | Enable BASE source |
| `springer` | Enable Springer source |
| `google_scholar` | Enable Google Scholar source (disabled by default) |

### Feature Groups

| Group | Description |
|-------|-------------|
| `core` | arxiv, pubmed, semantic |
| `preprints` | arxiv, biorxiv |
| `full` | All sources (default) |

### Build Examples

```bash
# Build with all sources (default)
cargo build --release

# Build with only core sources (smaller binary)
cargo build --release --no-default-features --features core

# Build with specific sources
cargo build --release --no-default-features --features arxiv,semantic,openalex

# Build with all sources except dblp
cargo build --release --features -dblp

# Install from source with only core sources
cargo install --path . --no-default-features --features core

# Build with Google Scholar enabled (requires environment variable at runtime)
cargo build --release --features google_scholar
```

**Note:** Feature flags affect which sources are **compiled into the binary**. This is different from the `RESEARCH_MASTER_ENABLED_SOURCES` environment variable, which filters sources at **runtime**. You can use both together for maximum control.

## Dependencies for PDF Extraction

PDF text extraction requires native poppler libraries:

**macOS:**
```bash
brew install poppler
```

**Ubuntu/Debian:**
```bash
sudo apt-get install libpoppler-cpp-dev
```

**Arch Linux:**
```bash
sudo pacman -S poppler
```

**Windows:**
Download and install from [poppler-windows](https://github.com/oschwartz10612/poppler-windows)

## Docker

### Basic Usage

```bash
# Build image
docker build -t research-master .

# Run with stdio mode
docker run --rm -i research-master serve --stdio

# Or use pre-built image (includes Poppler for PDF text extraction)
docker run --rm -i ghcr.io/hongkongkiwi/research-master serve --stdio
```

### OCR Variant (for scanned PDFs)

```bash
# OCR variant (adds Tesseract for scanned PDFs)
docker run --rm -i ghcr.io/hongkongkiwi/research-master-ocr serve --stdio

# Build OCR image with extra languages (e.g., English + German)
docker build -f Dockerfile.ocr -t research-master-ocr --build-arg OCR_LANGS="eng deu" .
```

### With Persistent Configuration

```bash
docker run --rm -i \
  -v ~/.config/research-master:/root/.config/research-master \
  -v ./downloads:/downloads \
  ghcr.io/hongkongkiwi/research-master serve --stdio
```

## Verifying Installation

```bash
# Check version
research-master --version

# Show all environment variables
research-master --env

# Search for papers (test)
research-master search "transformer architecture" --max-results 1
```

## Next Steps

- [Configure API Keys](sources.md#source-specific-configuration) for rate-limited sources
- [Set up your MCP client](mcp-clients.md) (Claude Desktop, Zed, etc.)
- [Configure environment variables](configuration.md)

## Related Documentation

- [Sources](sources.md) - Supported research sources and API requirements
- [Usage](usage.md) - CLI commands and options
- [Configuration](configuration.md) - Environment variables and config file
- [MCP Clients](mcp-clients.md) - Configuration for MCP clients