<p align="center">
  <h1 align="center">Local Research Library MCP</h1>
  <p align="center">让 AI Agent 安全访问你的本地科研资料库 | Give AI agents read-only access to your local research library</p>
</p>

<p align="center">
  <a href="https://pypi.org/project/local-research-library-mcp/"><img src="https://img.shields.io/pypi/v/local-research-library-mcp" alt="PyPI"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python"></a>
</p>

<p align="center">
  <a href="#中文">中文</a> | <a href="#english">English</a>
</p>

---

# 中文

## 简介

你是否遇到过这些情况：

- AI 助手不知道你电脑上有哪些论文
- 记得看过某篇论文，但想不起文件名
- 想在一篇长论文里快速定位某个概念

**Local Research Library MCP** 就是为了解决这些问题而生的。它是一个本地 MCP 服务器，让 Cursor、Claude、Codex、Trae 等 AI Agent 能够直接浏览和搜索你电脑上的论文资料库。所有数据都留在本地，不会上传到任何地方。

### 工作原理

```
你的论文文件夹（PDF、BibTeX、Markdown ...）
        │
        ▼ 启动时自动扫描，每 30 秒检测新增文件
   ┌──────────┐
   │ 索引引擎  │  提取标题、作者、关键词、摘要、全文
   └────┬─────┘
        ▼
   ┌──────────┐
   │ SQLite   │  本地数据库 + 全文搜索
   └────┬─────┘
        ▼
   ┌──────────┐
   │ MCP 服务  │  通过 stdio 协议暴露给 AI 客户端
   └──────────┘
```

### 核心能力

| 能力 | 说明 |
|------|------|
| **浏览资料库** | 列出所有论文分类及每个分类的论文数量 |
| **全文搜索** | 跨所有论文搜索关键词，按相关度排序 |
| **论文详情** | 获取任意论文的标题、作者、年份、摘要、关键词 |
| **论文内搜索** | 在单篇论文中定位特定内容，返回匹配段落和页码 |

### 支持格式

| 格式 | 扩展名 | 可提取的元数据 |
|------|--------|---------------|
| PDF | `.pdf` | 标题、作者、年份、关键词、摘要、全文 |
| BibTeX | `.bib` | 标题、作者、年份、期刊、DOI、摘要 |
| RIS | `.ris` | 标题、作者、年份、期刊、DOI、摘要 |
| EndNote | `.enw` | 标题、作者、年份、期刊、DOI、摘要 |
| Markdown | `.md` `.markdown` | 标题、全文 |
| XML | `.xml` | 标题、作者、年份、DOI、摘要 |

### 安全特性

- 🔒 **只读**：不会修改、删除或上传你的任何文件
- 🚀 **自动索引**：启动时自动扫描，每 30 秒检测新增文件，放入新论文即可搜索
- 🔍 **智能排序**：标题 > 关键词 > 摘要 > 作者 > 正文，多维度加权
- 🛡️ **路径安全**：所有访问都限制在配置的论文文件夹内，防止越权读取

## 安装与配置

需要 Python 3.11+。以下两种方式任选其一，按步骤操作即可。

### 方式一：uvx（推荐）

无需手动安装，`uvx` 会自动下载并运行。

**第 1 步：安装 uv（如果没有）**

```bash
pip install uv
```

**第 2 步：添加 MCP 配置**

在你的 MCP 客户端配置中加入：

```json
{
  "mcpServers": {
    "research-library": {
      "command": "uvx",
      "args": ["local-research-library-mcp", "serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<替换为你的论文文件夹路径>",
        "RESEARCH_LIBRARY_DB": "<替换为索引数据库路径>"
      }
    }
  }
}
```

### 方式二：pip 安装

**第 1 步：安装**

```bash
pip install local-research-library-mcp
```

**第 2 步：添加 MCP 配置**

在你的 MCP 客户端配置中加入：

```json
{
  "mcpServers": {
    "research-library": {
      "command": "local-research-library-mcp",
      "args": ["serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<替换为你的论文文件夹路径>",
        "RESEARCH_LIBRARY_DB": "<替换为索引数据库路径>"
      }
    }
  }
}
```

### ⚠️ 路径说明

> **请务必将配置中的 `<替换为...>` 替换为你电脑上的实际路径！**

| 系统 | `RESEARCH_LIBRARY_ROOT` 示例 | `RESEARCH_LIBRARY_DB` 示例 |
|------|---------------------------|--------------------------|
| Windows | `D:\\papers` | `D:\\papers\\.index\\library.db` |
| macOS / Linux | `/Users/yourname/papers` | `/Users/yourname/papers/.index/library.db` |

`RESEARCH_LIBRARY_DB` 建议放在论文文件夹内的 `.index` 目录下。

## 使用

配置完成后，重启 AI 客户端，直接用自然语言问：

- "帮我找关于 graph neural network 的论文"
- "我有哪些论文分类？"
- "在这篇论文里搜一下 attention mechanism"

## 工具

| 工具 | 说明 |
|------|------|
| `list_collections` | 列出所有文件夹分类及论文数量 |
| `search_papers` | 搜索论文（标题、关键词、摘要、正文） |
| `get_paper` | 获取论文详细信息 |
| `search_in_paper` | 在单篇论文内搜索 |

## 搜索排序

| 匹配位置 | 分数 |
|---------|------|
| 标题 | +50~100 |
| 关键词 | +35~45 |
| 摘要 | +30~40 |
| 作者 | +20~30 |
| 正文 | +10~40 |

## 命令行

```bash
local-research-library-mcp serve          # 启动服务器
local-research-library-mcp index          # 手动索引
local-research-library-mcp index --force  # 强制重新索引
local-research-library-mcp status         # 查看状态
```

## 环境变量

| 变量 | 说明 |
|------|------|
| `RESEARCH_LIBRARY_ROOT` | 论文文件夹路径 |
| `RESEARCH_LIBRARY_DB` | 索引数据库路径 |
| `RESEARCH_LIBRARY_LOG_LEVEL` | 日志级别（默认 INFO） |

---

# English

## Introduction

Ever run into these problems?

- Your AI assistant doesn't know what papers you have on disk
- You remember reading a paper but can't recall the filename
- You want to quickly locate a concept inside a long paper

**Local Research Library MCP** solves all of these. It is a local MCP server that lets Cursor, Claude, Codex, Trae, and other AI Agents browse and search your research paper library directly. All data stays on your machine — nothing is uploaded.

### How It Works

```
Your papers folder (PDF, BibTeX, Markdown, ...)
        │
        ▼ Scans on startup, checks for new files every 30s
   ┌──────────┐
   │ Indexer   │  Extracts title, authors, keywords, abstract, full text
   └────┬─────┘
        ▼
   ┌──────────┐
   │ SQLite    │  Local database + full-text search (FTS5)
   └────┬─────┘
        ▼
   ┌──────────┐
   │ MCP Server│  Exposes tools to AI clients via stdio protocol
   └──────────┘
```

### Core Capabilities

| Capability | Description |
|-----------|-------------|
| **Browse library** | List all paper collections with counts |
| **Full-text search** | Search across all papers, ranked by relevance |
| **Paper details** | Get title, authors, year, abstract, keywords for any paper |
| **In-paper search** | Find specific content within a paper, with page numbers and snippets |

### Supported Formats

| Format | Extensions | Extractable Metadata |
|--------|-----------|---------------------|
| PDF | `.pdf` | title, authors, year, keywords, abstract, full text |
| BibTeX | `.bib` | title, authors, year, journal, DOI, abstract |
| RIS | `.ris` | title, authors, year, journal, DOI, abstract |
| EndNote | `.enw` | title, authors, year, journal, DOI, abstract |
| Markdown | `.md` `.markdown` | title, full text |
| XML | `.xml` | title, authors, year, DOI, abstract |

### Security

- 🔒 **Read-only**: Never modifies, deletes, or uploads your files
- 🚀 **Auto-index**: Scans on startup, detects new files every 30 seconds
- 🔍 **Smart ranking**: Title > keywords > abstract > author > body, multi-dimensional scoring
- 🛡️ **Path-safe**: All access is confined to the configured papers folder

## Installation & Configuration

Requires Python 3.11+. Choose one of the two options below and follow the steps.

### Option 1: uvx (Recommended)

No manual install needed — `uvx` downloads and runs automatically.

**Step 1: Install uv (if you don't have it)**

```bash
pip install uv
```

**Step 2: Add MCP configuration**

Add the following to your MCP client config:

```json
{
  "mcpServers": {
    "research-library": {
      "command": "uvx",
      "args": ["local-research-library-mcp", "serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<replace with your papers folder path>",
        "RESEARCH_LIBRARY_DB": "<replace with your index database path>"
      }
    }
  }
}
```

### Option 2: pip install

**Step 1: Install**

```bash
pip install local-research-library-mcp
```

**Step 2: Add MCP configuration**

Add the following to your MCP client config:

```json
{
  "mcpServers": {
    "research-library": {
      "command": "local-research-library-mcp",
      "args": ["serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<replace with your papers folder path>",
        "RESEARCH_LIBRARY_DB": "<replace with your index database path>"
      }
    }
  }
}
```

### ⚠️ Path Instructions

> **You MUST replace the `<replace with ...>` placeholders above with actual paths on your computer!**

| System | `RESEARCH_LIBRARY_ROOT` example | `RESEARCH_LIBRARY_DB` example |
|--------|-------------------------------|------------------------------|
| Windows | `D:\\papers` | `D:\\papers\\.index\\library.db` |
| macOS / Linux | `/Users/yourname/papers` | `/Users/yourname/papers/.index/library.db` |

`RESEARCH_LIBRARY_DB` should be placed inside your papers folder under `.index`.

## Usage

After configuration, restart your AI client and ask in natural language:

- "Find papers about graph neural networks"
- "What collections do I have?"
- "Search for 'attention mechanism' in this paper"

## Tools

| Tool | Description |
|------|-------------|
| `list_collections` | List all folders with paper counts |
| `search_papers` | Search papers (title, keywords, abstract, body) |
| `get_paper` | Get paper details |
| `search_in_paper` | Search within a single paper |

## Search Ranking

| Match Location | Score |
|---------------|-------|
| Title | +50~100 |
| Keywords | +35~45 |
| Abstract | +30~40 |
| Author | +20~30 |
| Body | +10~40 |

## CLI

```bash
local-research-library-mcp serve          # Start server
local-research-library-mcp index          # Manual index
local-research-library-mcp index --force  # Force re-index
local-research-library-mcp status         # Show status
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `RESEARCH_LIBRARY_ROOT` | Papers folder path |
| `RESEARCH_LIBRARY_DB` | Index database path |
| `RESEARCH_LIBRARY_LOG_LEVEL` | Log level (default INFO) |

---

## License

[MIT](LICENSE) © [Hongyuan Lu](https://github.com/Hongyuan-Lu)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) · Contact: hongyuanlu9@gmail.com