Metadata-Version: 2.4
Name: inocli
Version: 0.4.0
Summary: Unofficial Inoreader client
Author-email: aryadovoy <ryav.omsk@gmail.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic[email]>=2.0.0
Requires-Dist: typing-extensions>=4.5.0; python_version < '3.11'
Provides-Extra: mcp
Requires-Dist: mcp[cli]<2.0.0,>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Unofficial Inoreader Client

An async Python client for the Inoreader API that provides easy access to your RSS feeds, subscriptions, and content management.

## Features

- **Async/await support**: built with aiohttp for efficient async operations
- **Type safety**: full type hints and Pydantic models for data validation
- **Easy authentication**: automatic API key management
- **Tag management**: read, star, like, and organize your articles
- **Custom tags**: create and manage your own tags

## Installation

Install the base client with `pip`:

```shell
pip install inocli
```

Or with `uv`:

```shell
uv add inocli
```

## Quick Start

### 1. Setup Configuration

Run the interactive configuration command:

```shell
inocli-configure
```

It uses existing `INOREADER_*` environment variables as defaults, asks for
missing values, and creates
`${XDG_CONFIG_HOME:-~/.config}/inocli/config.toml` with restricted permissions.
An existing file is never overwritten.

The resulting file has this format:

```toml
[inoreader]
app_id = "your_app_id"
app_key = "your_app_key"
email = "your_email@example.com"
password = "your_password"
```

If you create the file manually, restrict access because it contains your
password:

```shell
chmod 700 ~/.config/inocli
chmod 600 ~/.config/inocli/config.toml
```

Environment variables are also supported:

```env
INOREADER_APP_ID=your_app_id
INOREADER_APP_KEY=your_app_key
INOREADER_EMAIL=your_email@example.com
INOREADER_PASSWORD=your_password
```

Configuration priority is: explicit Python arguments, environment variables,
a local `.env` file, then the user TOML file.

### 2. Basic Usage

```python
import asyncio
from inocli import InoreaderClient, InoreaderConfig

async def main():
    # Load configuration from environment variables
    config = InoreaderConfig.get()

    # Create client (automatically handles authentication)
    client = await InoreaderClient.create(config)

    try:
        # Get user information
        user_info = await client.get_user_info()
        print(f"Welcome, {user_info.user_name}!")

        # Get all subscriptions
        subscriptions = await client.get_subscriptions()
        print(f"You have {len(subscriptions.subscriptions)} subscriptions")

        # Get one page of content (oldest first by default)
        content = await client.get_content()
        print(f"Found {len(content.items)} items")

        # Or stream items lazily without loading everything into memory
        async for item in client.iter_content(max_pages=2):
            print(item.title)

    finally:
        await client.close()

# Run the example
asyncio.run(main())
```

### Content Pagination

`get_content()` fetches one page by default. Pass `max_pages=N` to fetch at
most `N` pages. In the Python API, `max_pages=0` and `max_pages=None` both
request the entire stream, which may consume substantial time and memory.
Negative values are invalid.

For lazy processing, use `iter_content()`. It yields articles as pages arrive
instead of collecting all fetched articles in memory, and accepts the same
`max_pages` limit.

## Inoreader API Documentation

For more details on the Inoreader API, refer to the official documentation: [Inoreader API Documentation](https://www.inoreader.com/developers/)

## MCP Server

The library includes an [MCP](https://modelcontextprotocol.io/) server that exposes Inoreader operations as tools for LLMs.

### Installation

Install the MCP extra with `pip`:

```shell
pip install "inocli[mcp]"
```

Or with `uv`:

```shell
uv add "inocli[mcp]"
```

### Configuration

When the user TOML file is configured, add only the command to your Claude
Desktop or VS Code MCP config:

```json
{
  "mcpServers": {
    "inocli": {
      "command": "inocli-mcp"
    }
  }
}
```

> **Note:** Authentication currently uses the legacy ClientLogin flow, which requires
> storing your raw password. Migration to OAuth 2.0 is planned.

### Available Tools

| Tool                | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `get_user_info`     | Get the authenticated user profile                              |
| `get_subscriptions` | List all RSS feed subscriptions                                 |
| `get_tags`          | List all tags with unread/article counts                        |
| `get_content`       | Fetch articles with optional filtering (`max_pages` defaults to `1`; `0` fetches the entire stream; negative values are invalid) |
| `edit_tag`          | Add or remove tags (read, starred, custom labels) from articles |

## License

This project is licensed under the MIT License.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
