Metadata-Version: 2.3
Name: local-research-library-mcp
Version: 0.2.0
Summary: An MCP server that gives AI agents read-only access to a local research library (PDF, Markdown, BibTeX, RIS, ENW, XML).
Keywords: mcp,research,papers,library,pdf,bibtex,academic,agent
Author: LHY
Author-email: LHY <hongyuanlu9@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: mcp[cli]>=2.0.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/luhongyuan/local-research-library-mcp
Project-URL: Repository, https://github.com/luhongyuan/local-research-library-mcp
Project-URL: Issues, https://github.com/luhongyuan/local-research-library-mcp/issues
Project-URL: Documentation, https://github.com/luhongyuan/local-research-library-mcp#readme
Provides-Extra: dev
Description-Content-Type: text/markdown

# Local Research Library MCP

[![PyPI version](https://img.shields.io/pypi/v/local-research-library-mcp)](https://pypi.org/project/local-research-library-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

> 让 AI Agent 安全地访问你的本地科研资料库。

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI agents read-only access to your local research library. Search papers, fetch metadata, and find specific passages — all without leaving your machine.

## Features

- **4 Tools**: `list_collections`, `search_papers`, `get_paper`, `search_in_paper`
- **2 Resources**: `research://library` (overview), `research://papers/{paper_id}` (metadata)
- **6 File Formats**: PDF, Markdown, BibTeX, RIS, EndNote, XML
- **Auto-Index**: Detects new/changed files automatically (every 30s)
- **Smart Scoring**: Title > Keywords > Abstract > Author > Body relevance ranking
- **SQLite + FTS5**: Fast full-text search with graceful LIKE fallback
- **Read-Only**: Never modifies your files
- **Path-Safe**: Paper IDs validated, all reads stay inside library root

## Installation

### From PyPI

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

### From Source

```bash
git clone https://github.com/luhongyuan/local-research-library-mcp.git
cd local-research-library-mcp
pip install -e .
```

## Quick Start

### 1. Configure MCP Client

Add to your MCP client configuration (e.g., Cursor, Claude Desktop, Trae):

```json
{
  "mcpServers": {
    "research-library": {
      "command": "local-research-library-mcp",
      "args": ["serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "/path/to/your/papers",
        "RESEARCH_LIBRARY_DB": "/path/to/your/papers/.index/library.db"
      }
    }
  }
}
```

Or if installed from source:

```json
{
  "mcpServers": {
    "research-library": {
      "command": "python",
      "args": ["-m", "local_research_library_mcp", "serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "/path/to/your/papers",
        "RESEARCH_LIBRARY_DB": "/path/to/your/papers/.index/library.db"
      }
    }
  }
}
```

### 2. Start Using

The server auto-indexes on startup and checks for changes every 30 seconds. Just ask your AI agent:

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

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `RESEARCH_LIBRARY_ROOT` | `./research-library` | Root directory of your paper library |
| `RESEARCH_LIBRARY_DB` | `./research-library/.index/library.db` | SQLite index location |
| `RESEARCH_LIBRARY_LOG_LEVEL` | `INFO` | Log level (DEBUG, INFO, WARNING, ERROR) |

## CLI Commands

```bash
# Start the MCP server (default)
local-research-library-mcp serve

# Manually index the library
local-research-library-mcp index

# Force re-index all files (after parser upgrades)
local-research-library-mcp index --force

# Show library status
local-research-library-mcp status
local-research-library-mcp status --json
```

## Search Scoring

When you search, results are ranked by relevance:

| Match Location | Score |
|---------------|-------|
| Title (exact) | +100 |
| Title (contains) | +80 |
| Title (token) | +50 |
| Keywords | +35~45 |
| Abstract | +30~40 |
| Author | +20~30 |
| Collection name | +20 |
| Body (FTS) | +10~40 |

## Supported Formats

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

## Architecture

```
MCP Client (Agent)
    │ stdio
    ▼
MCP Server
    │
    ├── Service Layer (search, fetch, collections)
    │       │
    │       ▼
    ├── Storage (SQLite + FTS5)
    │       │
    │       ▼
    └── Indexer / Parsers
            │
            ▼
        Local File System
```

## Development

```bash
# Clone and install dev dependencies
git clone https://github.com/luhongyuan/local-research-library-mcp.git
cd local-research-library-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=local_research_library_mcp
```

## Publishing to PyPI

```bash
# Build
python -m build

# Upload
python -m twine upload dist/*
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Acknowledgments

Built with:
- [MCP](https://modelcontextprotocol.io) - Model Context Protocol
- [PyMuPDF](https://pymupdf.readthedocs.io/) - PDF processing
- [Pydantic](https://docs.pydantic.dev/) - Data validation
- [SQLite](https://www.sqlite.org/) - Embedded database with FTS5
