# EndNote MCP Service

This project provides an automated service for reading EndNote `.enl` libraries and exposing their contents via the MCP (Modular Command Protocol) interface. It enables structured, programmatic access to bibliographic data and PDF full texts for downstream LLMs or automation clients.

## Features
- **Automatic EndNote Library Parsing**: Reads `.enl` (SQLite) files and associated `.Data` folders.
- **MCP Tool Interface**: Exposes all functions as MCP tools for easy integration with LLMs or workflow engines.
- **List All References**: Enumerate all bibliographic entries with metadata.
- **Fuzzy Search**: Search references by (partial) title or keywords, supporting both English and Chinese.
- **PDF Full Text Extraction**: Retrieve and extract the full text of attached PDF files by paper title.
- **Backup Mode & Manual Refresh**: Optionally operate on a `.enl.backup` file for safer access, with both automatic and manual refresh support.

## Typical Usage
- List all papers: `list_papers()`
- Fuzzy search: `search_papers('distillation')`
- Extract full text: `read_paper('Paper Title')`
- Manually refresh backup: `refresh_backup()`

## Application Scenarios
- LLM-based literature review and knowledge extraction
- Automated research assistants
- Academic data mining and analysis

## Requirements
- Python 3.10+
- EndNote `.enl` file and corresponding `.Data` folder
- MCP/fastmcp runtime environment

This service is currently run against EndNote 21; other versions have not been compatibility-tested.

## Installation
1. Install [uv](https://github.com/astral-sh/uv) if you don't have it:
   ```bash
   pip install uv
   # or see https://github.com/astral-sh/uv for other installation methods
   ```
2. Install dependencies using uv (recommended):
   ```bash
   uv pip install -r requirements.txt
   ```
   The main dependencies are:
   - fastmcp>=2.8.1
   - pypdf>=5.6.0

   A requirements.txt file is provided for compatibility, but uv is the recommended tool for dependency management.

## Configuration
You need to provide the path to your EndNote `.enl` file and the corresponding `.Data` folder. Optionally, you can enable detailed logging.

You may also enable backup mode with the `--use-backup` or `-b` option. When enabled, all database operations are performed on a `.enl.backup` file, which is automatically refreshed from the original `.enl` file at startup. You can manually refresh the backup at any time using the `refresh_backup()` MCP tool.

> **Why Backup Mode?**
>
> EndNote software locks the `.enl` file while it is running, preventing other programs from accessing it. This means that when you are viewing or editing references in EndNote, this tool cannot operate on the original `.enl` file. To solve this, backup mode was introduced: all operations are performed on a `.enl.backup` copy. **When you need to refresh the backup, you must first close EndNote** to release the file lock; otherwise, the refresh will fail.

## Running the Server
Start the MCP server with the required arguments:
```bash
python server.py --enl-file <path-to-your.enl> --data-folder <path-to-your.Data> [--enable-log] [--use-backup]
# or using short options:
python server.py -e <path-to-your.enl> -d <path-to-your.Data> -l -b
```
- `--enl-file`, `-e`: Path to the EndNote `.enl` file (required)
- `--data-folder`, `-d`: Path to the EndNote `.Data` folder (required)
- `--enable-log`, `-l`: Enable detailed log output (optional)
- `--use-backup`, `-b`: Use `.enl.backup` for all DB operations (optional, enables backup mode; the backup is auto-refreshed at startup)

When backup mode is enabled, all operations are performed on the `.enl.backup` file. The backup is automatically refreshed from the original `.enl` file at server startup, and you can manually refresh it at any time using the `refresh_backup()` tool.

## MCP Server Configuration

To integrate this service with MCP-compatible clients or orchestration tools, you can define an entry in your `mcp.json` configuration. Example:

```json
{
  "mcpServers": {
    "enl_reader_mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "<path-to-your-clone>",
        "-m",
        "server",
        "-e",
        "E:/EndNoteLib/your_library.enl",
        "-d",
        "E:/EndNoteLib/your_library.Data",
        "-l",
        "-b"
      ]
    }
  }
}
```
- Replace `<path-to-your-clone>` with the actual path where you cloned this repository.
- Adjust the paths to your `.enl` file and `.Data`
- Add `-b` to enable backup mode if desired. When enabled, the service will operate on a `.enl.backup` file and support manual refresh via the `refresh_backup` tool.

## MCP Tools

- `list_papers(offset=0, limit=10)`: List all references with pagination.
- `search_papers(query)`: Fuzzy search references by title or keywords.
- `read_paper(title)`: Get metadata and PDF full text by (fuzzy) title.
- `refresh_backup()`: Manually refresh the `.enl.backup` file (only available when backup mode is enabled; has no effect if backup mode is off).

**Note:** The `refresh_backup` tool is only effective when backup mode is enabled. Backup mode is recommended for scenarios requiring read-only or safer access to the EndNote library.