Metadata-Version: 2.4
Name: inoreader-mcp
Version: 0.1.0
Summary: MCP server for Inoreader — exposes feeds, articles, and curation tools to AI assistants.
Project-URL: Repository, https://github.com/ibrapk/inoreader-mcp
Project-URL: Issues, https://github.com/ibrapk/inoreader-mcp/issues
Author-email: ibrapk <mcp-inoreader.2phgc@8alias.com>
License: MIT
License-File: LICENSE
Keywords: ai,claude,feeds,inoreader,mcp,rss
Classifier: Development Status :: 3 - Alpha
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 :: Communications
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: markdownify>=0.11
Requires-Dist: mcp>=1.2
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic>=2.5
Provides-Extra: keyring
Requires-Dist: keyring>=24.0; extra == 'keyring'
Description-Content-Type: text/markdown

# inoreader-mcp

MCP server for Inoreader — exposes feeds, articles, and curation tools to AI assistants.

> ⚡ **Vibecoded.** This project was designed and implemented in collaboration
> with an AI coding assistant (Claude). Every architecture decision and code
> change has a paper trail in commit messages and [`CHANGELOG.md`](CHANGELOG.md).
> Read those if you want the *why* behind any piece of the codebase.

> **Status:** v0.1.0. Feature-complete for the v1 scope (read + lightweight
> curation), single-tenant, stdio transport. Not yet published to PyPI / GHCR;
> the release workflow is parked under manual dispatch.

---

## Requirements

- **Python ≥ 3.11**
- **An Inoreader Pro / Supporter / Teams plan.** Free-tier users cannot access the
  Inoreader Developer API (you'll get HTTP 403 on every request).
- A registered Inoreader developer app (AppId + AppKey) — get one at
  <https://www.inoreader.com/all_articles#preferences-developer>.
- [`uv`](https://github.com/astral-sh/uv) recommended for local development.

## Local development setup

```bash
# 1. Clone and enter the repo
git clone https://github.com/ibrapk/inoreader-mcp.git
cd inoreader-mcp

# 2. Install all dependencies (incl. dev + optional keyring extra)
uv sync --all-extras

# 3. Configure your Inoreader credentials
cp .env.example .env
$EDITOR .env   # fill INOREADER_APP_ID and INOREADER_APP_KEY
```

`.env` is gitignored — your credentials never leave your machine.

## Authorize once with `inoreader-mcp auth`

The server uses OAuth 2.0 with a local loopback callback. You authorize once;
tokens are persisted at `~/.config/inoreader-mcp/tokens.json` (mode 0600) and
refreshed automatically thereafter.

**Before the first run**, configure your Inoreader app correctly in the
[developer dashboard](https://www.inoreader.com/all_articles#preferences-developer):

1. **OAuth Redirect URI** must be exactly:
   ```
   http://127.0.0.1:8765/callback
   ```
   (Or any URI you intend to pass via `--redirect-uri`. The browser must be
   redirected to a URL that matches this value exactly — including scheme, host,
   port and path.)

2. **Access type** must be **Read + Write** if you plan to use the curation
   tools (mark read, star, add tag, etc.). If your app is registered as
   **Read only**, the OAuth flow will fail with `invalid_scope — An unsupported
   scope was requested` because we request `scope=read write` to enable
   Zone 2 (mutating) endpoints. You can change this in your app's settings at
   any time and re-run `inoreader-mcp auth`.

Then:

```bash
# Load your env vars (or export them manually)
set -a && source .env && set +a

# Run the OAuth flow
uv run inoreader-mcp auth
```

The server opens your browser, you authorize, and the tokens land on disk.
Re-run `inoreader-mcp auth` any time to re-authorize from scratch.

### `auth` flags

| Flag | Default | Purpose |
|---|---|---|
| `--redirect-uri URL` | `http://127.0.0.1:8765/callback` | Override the loopback URI (must match what's registered in Inoreader) |
| `--timeout SECONDS` | `300` | How long to wait for the browser callback before giving up |
| `--no-browser` | _off_ | Print the authorize URL instead of trying to open a browser |
| `--manual` | _off_ | Headless mode (no local listener, no browser) — see below |

### Authorizing on a headless server (no local browser)

If your server has no GUI (typical SSH-only host, container, CI runner), you can
authorize without ever loading anything in a browser **on the server itself**.
Two equivalent options:

#### Option 1 — Manual paste (`--manual`, recommended)

```bash
uv run inoreader-mcp auth --manual
```

The command prints a long `https://www.inoreader.com/oauth2/auth?...` URL.

1. Open that URL in any browser **on another device** (your laptop, phone, …).
2. Authorize the app on Inoreader's page.
3. Inoreader redirects to `http://127.0.0.1:8765/callback?code=...&state=...`.
   Your browser will likely show a connection-refused page — **that's expected**;
   nothing is listening on your laptop. The URL in the address bar is what we need.
4. Copy that full URL and paste it back into the headless terminal when prompted.

The server validates the `state` (CSRF) and exchanges the code for tokens.

#### Option 2 — SSH port forwarding

If your SSH workflow allows reconnecting with `-L`:

```bash
ssh -L 8765:127.0.0.1:8765 user@your-headless-host
# then, on the server:
uv run inoreader-mcp auth   # default loopback flow
```

The browser on your laptop hits `http://127.0.0.1:8765/callback`, which the SSH
tunnel forwards to the listener running on the server. No `--manual` needed.

## Troubleshooting authorization

| Symptom | Most likely cause | Fix |
|---|---|---|
| `invalid_scope — An unsupported scope was requested` in the redirect URL | Your Inoreader app is registered as **Read only**, but we request `scope=read write` | Change the app's access type to **Read + Write** in the developer dashboard, then re-run `inoreader-mcp auth` |
| `redirect_uri_mismatch` (or similar) on the consent page | The `--redirect-uri` you're passing doesn't match the one registered for the app | Update either side so they're identical, including port and path |
| `403 Forbidden` from the API after authorizing | Your Inoreader plan doesn't include developer API access | Upgrade to Pro / Supporter / Teams |
| Browser shows "connection refused" on `127.0.0.1:8765/callback` | Expected with `--manual` — nothing is supposed to listen on your laptop. | Just copy the URL from the address bar back into the terminal |
| `OAuth state mismatch` after pasting | You pasted a URL from a different `auth` run | Re-run `inoreader-mcp auth --manual` and use the freshly opened authorize URL |

## Read tools (Phase 2)

Once authorized, run the MCP server over stdio:

```bash
set -a && source .env && set +a
uv run inoreader-mcp serve
```

The server registers six read tools plus a `diagnostics` health snapshot.
Wire it up to Claude Code with:

```bash
claude mcp add inoreader -- env INOREADER_APP_ID=$INOREADER_APP_ID \
  INOREADER_APP_KEY=$INOREADER_APP_KEY uv --directory /path/to/inoreader-mcp \
  run inoreader-mcp serve
```

| Tool | What it does |
|---|---|
| `list_subscriptions` | All your feeds with folders, URLs, icon URLs (cached 60 s) |
| `list_folders_and_tags` | Folders, user tags, active searches, system streams + unread counts |
| `get_unread_counts` | Per-feed / per-folder / per-tag unread tallies |
| `list_articles` | Stream contents with metadata + a short preview. Filter by `folder`, `feed`, `tag`, `unread_only`, `starred_only`, `since_seconds`. Returns short article IDs you pass to `get_article`. |
| `get_article` | Full article body as Markdown (capped at `max_chars`). Pass `include_image_urls=True` for vision-capable clients. |
| `search_articles` | Full-text search, optionally scoped to a folder/feed/tag. |
| `diagnostics` | Auth status, Zone 1/2 quota, cache state, version. Run when something seems off. |

## Write tools (Phase 3)

All write tools are gated behind `INOREADER_READ_ONLY=1` — set that env var
to a truthy `1` and the server doesn't register any of them.

| Tool | What it does |
|---|---|
| `mark_read` / `mark_unread` | Toggle read state on a list of `article_ids`. Reversible. |
| `star` / `unstar` | Toggle the starred flag on a list of `article_ids`. |
| `add_tag` / `remove_tag` | Apply or remove a user tag on a list of `article_ids`. Tag name must be 1–64 chars from `[A-Za-z0-9 _\-.]`. |
| `mark_stream_read` | **High blast radius.** Marks every unread article in a stream (`stream_id` or `folder` name) as read. Strongly recommend calling with `dry_run=True` first to preview the count and a sample of titles. Optional `max_age_days` cutoff to leave anything newer untouched. |

Per-article writes batch at 100 IDs per request to fit within Inoreader's
edit-tag limits. After any successful write, the hierarchy cache (unread
counts, folders/tags) is invalidated so the next read reflects the change.

> **Note:** `get_article` returns `is_read`, `is_starred`, and `labels` for
> convenience, but Inoreader's bulk-fetch endpoint doesn't reliably populate
> per-user state on those entries (the response includes a `state_caveat`
> field as a reminder). For authoritative state, use `list_articles`
> (e.g. `list_articles(starred_only=True)`) instead.

## Resources & prompts (Phase 4)

The server exposes three **resources** (browsable Markdown views the user can
attach as context in supporting clients) and four **prompts** (slash-menu
templates with safe-by-default workflows baked in):

| Resource URI | Content |
|---|---|
| `inoreader://subscriptions` | All feeds as a Markdown table (title, folders, URL) |
| `inoreader://folders` | Folder hierarchy with each folder's child feeds + unread counts |
| `inoreader://tags` | User tags with their tagged-unread counts |

| Prompt | Args | What it does |
|---|---|---|
| `catch_up` | _none_ | Summarize my unread from the last ~24 h, grouped by folder; ask before any writes |
| `weekly_roundup` | _none_ | Summarize what I starred in the last ~7 days, grouped by theme |
| `digest` | `folder` | Per-folder digest of today's unread; ask before mass-marking-read |
| `find` | `topic` | Search subscriptions for a topic, surface the most relevant 5–10 |

All prompts that involve writes pre-bake the safety rule: ask before mutating,
prefer `mark_stream_read(dry_run=True)` for stream-level operations.

## Install helper (Phase 5)

Once you've set `INOREADER_APP_ID` / `INOREADER_APP_KEY` in env (or filled them
in interactively), run:

```bash
uv run inoreader-mcp install                    # prints the claude command
uv run inoreader-mcp install --auto-register    # also runs claude mcp add for you
uv run inoreader-mcp install --repo-path .      # use local repo via `uv --directory`
uv run inoreader-mcp install --manual           # force headless paste-URL flow
```

The flow walks you through:
1. Loading credentials (env or prompt)
2. Authorizing if no valid tokens are present (auto-detects headless vs loopback)
3. Printing — or running, with `--auto-register` — the `claude mcp add` command
4. Verifying with a `diagnostics` round-trip

## Docker

```bash
# Build the image
docker build -t inoreader-mcp .

# Authorize once on the host (interactive — needs your browser)
uv run inoreader-mcp auth --manual

# Run the server, mounting your tokens into the container
docker run -i --rm \
  -e INOREADER_APP_ID -e INOREADER_APP_KEY \
  -v "$HOME/.config/inoreader-mcp:/root/.config/inoreader-mcp" \
  inoreader-mcp serve
```

The published image is at `ghcr.io/ibrapk/inoreader-mcp:latest` once we tag a
release.

## CI

`.github/workflows/`:

| Workflow | Trigger | What it runs |
|---|---|---|
| `ci.yml` | PR + push to main | ruff lint + format check, mypy `--strict`, pytest on Linux + macOS × Python 3.11 / 3.12 / 3.13 |
| `release.yml` | manual dispatch only | Parked. Trigger from the Actions tab when you want to publish: pick the tag, optionally tick `publish_pypi` and/or `publish_ghcr`. No auto-trigger on tag — explicit human click only. |
| `integration.yml` | manual `workflow_dispatch` only | Runs the `-m integration` test suite against the live Inoreader API. Never on a schedule — the user notices breakage faster than a nightly cron would. |

### CLI diagnostics

You can also call `diagnostics` outside of an MCP client, useful for one-off checks:

```bash
$ uv run inoreader-mcp diagnostics
{
  "server_version": "0.1.0.dev0",
  "auth": {"status": "ok", "user_name": "<your-username>", "scope": "read write", ...},
  "quota": {"zone1": {"used": 4, "limit": 100, "reset_after": 1543}, ...},
  "cache": {"entries": 0, "ttl_seconds": 60.0}
}
```

### Article content shape

* HTML article bodies are converted to **Markdown** for compactness and to play
  well with how LLMs read text. Tables and complex layouts may degrade — see
  the troubleshooting section below if a specific feed produces poor output.
* By default, `<img>` tags become `[Image: alt-text]` placeholders (URL dropped,
  tracking pixels collapse to nothing). Pass `include_image_urls=True` on
  `get_article` to keep full Markdown image syntax.
* `get_article` truncates at `max_chars` (default 50 000). The response sets
  `truncated: true` and `chars_remaining: N` so the model knows when to refetch.
* Article IDs come in two formats. The tools return the **short** form
  (`344691561`) for compactness; both forms are accepted as inputs to
  `get_article`.

## Configuration

All settings are environment variables.

| Var | Default | Purpose |
|---|---|---|
| `INOREADER_APP_ID` | _(required)_ | Developer AppId |
| `INOREADER_APP_KEY` | _(required)_ | Developer AppKey |
| `INOREADER_READ_ONLY` | `0` | If `1`, hide the write tools (Phase 3+) |
| `INOREADER_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
| `INOREADER_LOG_FORMAT` | `text` | `text` or `json` |
| `INOREADER_DEBUG` | `0` | If `1`, log full request/response (secrets redacted) |
| `INOREADER_USE_KEYRING` | `0` | If `1`, store tokens in the OS keyring instead of the JSON file |

## Development

```bash
uv run pytest         # run the test suite
uv run ruff check .   # lint
uv run ruff format .  # format
uv run mypy src tests # type-check (strict)
```

## Roadmap

| Phase | Scope | Status |
|---|---|---|
| 1 | Project scaffold, OAuth loopback flow, token storage, structured logging | ✅ Complete |
| 2 | Async HTTP client + transport, read tools, `diagnostics` | ✅ Complete |
| 3 | Write tools (`mark_read`, `star`, `add_tag`, `mark_stream_read`) | ✅ Complete |
| 4 | MCP resources + prompts (`catch_up`, `digest`, ...) | ✅ Complete |
| 5 | `inoreader-mcp install` interactive helper, Docker image, GitHub Actions | ✅ Complete |
| 6 | v0.1.0 release prep — `CHANGELOG`, version bump, ready to tag | ✅ Complete |

See [CHANGELOG.md](CHANGELOG.md) for the full v0.1.0 feature list.

## License

MIT — see [LICENSE](LICENSE).
