Metadata-Version: 2.4
Name: resilient-read
Version: 0.1.0
Summary: MCP server for resilient chunked reads of large files
Project-URL: Homepage, https://github.com/jayluxferro/resilient-read
Project-URL: Issues, https://github.com/jayluxferro/resilient-read/issues
Author-email: Justice Owusu Agyemang <jay@sperixlabs.org>
License: MIT
License-File: LICENSE
Keywords: agents,chunked-read,context-window,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: mcp>=1.0.0
Requires-Dist: starlette>=0.37.2
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# resilient-read

MCP server that lets coding agents read very large files safely in **small, resumable chunks**.

## Why this exists

When context windows are small, naive full-file reads are brittle and expensive. `resilient-read` provides deterministic pagination with cursor-based continuation and drift detection.

## Tools

- `rr.stat` - get file metadata (`size`, `mtime_ns`, optional `sha256`)
- `rr.read_bytes` - read byte windows with `offset`, `max_bytes`, `next_offset`, `eof`
- `rr.read_lines` - read line-numbered slices for code/log analysis
- `rr.read_tail` - read only the latest lines from append-only files
- `rr.search_then_page` - search with contextual excerpts and `next_from_line`
- `rr.make_cursor` - mint resumable cursor token
- `rr.read_next` - read next chunk from cursor (fails if file changed)

## Install

```bash
uv sync
```

Run with stdio (default):

```bash
uv run resilient-read
```

## MCP config (stdio)

```json
{
  "mcpServers": {
    "resilient-read": {
      "command": "uvx",
      "args": ["resilient-read"],
      "env": {
        "RR_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}
```

## Example workflows

### Cursor-based file pagination

1. Call `rr.stat(path="large.log")`
2. Call `rr.make_cursor(path="large.log", offset=0, max_bytes=65536)`
3. Loop on `rr.read_next(cursor=...)` until `eof=true`

### Targeted search pagination

1. Call `rr.search_then_page(path="server.log", query="timeout", max_matches=3)`
2. Follow with `rr.search_then_page(..., from_line=<next_from_line>)`

Each response is small and composable, so you can process huge files while staying inside small model contexts.

## Project housekeeping

- Release notes and version history: `CHANGELOG.md`
- Manual semver tagging flow: `docs/RELEASE.md`
- JSON-RPC examples: `examples/`
