# Literature Evidence MCP

Small, versioned evidence from your local papers—without loading the whole library
into an AI conversation. Optional modules connect Zotero, writing projects,
fixed-commit source code and experiment records.

[中文说明](README.zh-CN.md) · [Configuration](docs/configuration.md) ·
[Tools](docs/tools.md) · [Release guide](docs/releasing.md)

**Status:** 0.5.0a1, an unreleased alpha candidate. Python 3.11+, macOS and Linux.
Windows is not supported in this release (POSIX file locking/process management).
No hosted account or API key is needed for local file access.

## What it does

- Search local names and cached full text; retrieve text with PDF page numbers and
  SHA-256 hashes. Use original page images for equations and figures with Poppler.
- Return compact indexes and bounded excerpts: 4,000 text characters by default,
  at most 12,000 per read. Explicit continuations preserve the evidence version.
- Read live Zotero metadata in one configured collection and its descendants.
- Optionally read allowlisted writing files, save agreed review notes, inspect
  code at a fixed commit and exchange experiment plans/results.

The server does not modify papers, Zotero data, manuscript text or source code.
MCP calls never launch an experiment. Enabled write tools save notes/plans only.
Search is lexical, PDFs have no OCR, and conversation history is managed by your
client. A cache avoids repeated extraction, not accumulated tool-result history.

## Try the bundled example

```sh
git clone https://github.com/phy-zhangzl/literature-evidence-mcp.git
cd literature-evidence-mcp
```

From this source checkout, with [uv](https://docs.astral.sh/uv/) installed:

```sh
uv sync --locked
uv run --locked literature-mcp --config config.example.json doctor
uv run --locked literature-mcp --config config.example.json serve
```

`serve` defaults to stdio and waits for an MCP client. The example uses only the
synthetic document in `examples/papers` and writes its cache to `.state/cache`.
It does not use a personal Zotero library, a tunnel or an existing service config.

## Install and configure

Build a wheel from a reviewed source checkout, or use a wheel attached to a future
GitHub release. This candidate has **not** been uploaded to PyPI; do not assume the
package name on a registry belongs to this project.

```sh
uv build
python3 -m venv .venv-runtime
.venv-runtime/bin/python -m pip install dist/local_literature_mcp-0.5.0a1-py3-none-any.whl
mkdir -p "$HOME/Papers"
.venv-runtime/bin/literature-mcp init --papers "$HOME/Papers"
.venv-runtime/bin/literature-mcp doctor
```

`init` creates `~/.config/literature-mcp/config.json` and never overwrites an existing
file. `XDG_CONFIG_HOME`, `LITERATURE_MCP_CONFIG` or the global `--config` argument
can select another location. Relative paths are relative to the config file.
Use a separate config, cache, experiment store and runtime environment for each
installation. [Migration from the local predecessor](docs/migration.md).

Configure your MCP client with this stdio server entry, substituting **absolute**
paths for your runtime and config:

```json
{
  "mcpServers": {
    "literature-product": {
      "command": "/absolute/path/to/.venv-runtime/bin/literature-mcp",
      "args": ["--config", "/absolute/path/to/config.json", "serve"]
    }
  }
}
```

Client configuration formats vary; this is a common stdio entry, not an automatic
client installer. Optional local HTTP: add `--transport streamable-http` after
`serve`. It listens on `127.0.0.1`, at `/mcp`, with the configured port. It has no
public authentication layer; do not expose it directly to the Internet.

## Optional capabilities

| Configuration | Tools made available |
| --- | --- |
| Only `papers_dir` | Library status, file listing, search, fetch, page images |
| `zotero_collection` | Collection/item discovery and metadata sections |
| `project_dir` | Writing context and append-only feedback |
| `code_repository` | Fixed-commit code listing, search, reads and version context |
| `experiments_dir` | Experiment index, artifact discovery and evidence reads |
| Code repository + experiment store | Save agreed experiment plans |

Poppler is optional for text and required for page images. Install with
`brew install poppler` on macOS or your distribution's `poppler-utils` package on
Linux. Git is needed only for code tools. Zotero requires its desktop local API to
be enabled. See [configuration](docs/configuration.md) and [data boundaries](SECURITY.md).

The optional [foamCase adapter](docs/adapters.md) is for existing scientific
workflows. File-only users need neither it nor a simulation environment.

## Development and release

```sh
uv run --locked pytest -q
uv run --locked python scripts/smoke_test.py
uv run --locked python scripts/smoke_test.py --transport http
uv build
uv run --locked python scripts/check_release.py
```

Tests use synthetic fixtures and temporary stores. See [CONTRIBUTING.md](CONTRIBUTING.md).
CI checks macOS/Linux with Python 3.11–3.13; a configured workflow is not a claim that
remote CI has already run. The tag workflow creates a **draft** GitHub prerelease;
it does not publish to PyPI. See [release guide](docs/releasing.md).

## License

[MIT](LICENSE). Papers and research data remain under their own licenses and are
not included in this repository.