newsclip 0.7.0__tar.gz

newsclip-0.7.0/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.artifacts
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+bench
+docs
+tests
+*.sqlite3
+*.jsonl
+__pycache__

newsclip-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13']
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --extra mcp --extra signin
+      - run: uv run --locked patchright install --with-deps chromium
+      - run: make check
+      - run: make check-mcp check-standalone

newsclip-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,145 @@
+name: Release
+on:
+  push:
+    tags: ['v*.*.*']
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  released:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      done: ${{ steps.check.outputs.done }}
+    steps:
+      - id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          done=false
+          if [ "$GITHUB_REF_TYPE" = tag ] && gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            done=true
+          fi
+          echo "done=$done" >> "$GITHUB_OUTPUT"
+
+  ci:
+    needs: released
+    if: needs.released.outputs.done != 'true'
+    uses: ./.github/workflows/ci.yml
+    permissions:
+      contents: read
+
+  images:
+    needs: ci
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990
+      - uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f
+      - name: Identify immutable candidates
+        id: version
+        run: |
+          version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "$GITHUB_REF_TYPE" = tag ]; then
+            test "$GITHUB_REF_NAME" = "v$version"
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "candidate=candidate-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT" >> "$GITHUB_OUTPUT"
+      - name: Build standalone server candidate
+        id: server
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8
+        with:
+          context: .
+          target: server
+          platforms: linux/amd64
+          push: true
+          tags: ghcr.io/${{ github.repository_owner }}/newsclip-mcp:${{ steps.version.outputs.candidate }}
+          build-args: |
+            VCS_REF=${{ github.sha }}
+            IMAGE_VERSION=${{ steps.version.outputs.version }}
+          provenance: mode=max
+          sbom: true
+          cache-from: type=gha,scope=newsclip
+          cache-to: type=gha,mode=max,scope=newsclip
+      - name: Build sign-in browser candidate
+        id: login
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8
+        with:
+          context: .
+          target: login
+          platforms: linux/amd64
+          push: true
+          tags: ghcr.io/${{ github.repository_owner }}/newsclip-login-browser:${{ steps.version.outputs.candidate }}
+          build-args: |
+            VCS_REF=${{ github.sha }}
+            IMAGE_VERSION=${{ steps.version.outputs.version }}
+          provenance: mode=max
+          sbom: true
+          cache-from: type=gha,scope=newsclip
+          cache-to: type=gha,mode=max,scope=newsclip
+      - name: Exercise shipped images without external network access
+        env:
+          SERVER_IMAGE: ghcr.io/${{ github.repository_owner }}/newsclip-mcp@${{ steps.server.outputs.digest }}
+          LOGIN_IMAGE: ghcr.io/${{ github.repository_owner }}/newsclip-login-browser@${{ steps.login.outputs.digest }}
+        run: |
+          docker pull "$SERVER_IMAGE"
+          docker pull "$LOGIN_IMAGE"
+          docker run --rm --init --network none --read-only --tmpfs /tmp:rw,exec,mode=1777,size=1g \
+            -v "$PWD/scripts/smoke_standalone.py:/acceptance.py:ro" \
+            --entrypoint python "$SERVER_IMAGE" /acceptance.py
+          timeout 300 docker run --rm --init --network none --read-only --tmpfs /tmp:rw,exec,mode=1777,size=1g --shm-size=256m \
+            -v "$PWD/scripts/standalone_e2e.py:/acceptance.py:ro" \
+            --entrypoint python "$LOGIN_IMAGE" /acceptance.py
+      - name: Build source and wheel distributions
+        run: uv build --no-sources
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: distributions
+          path: dist/*
+          retention-days: 7
+      - name: Promote tested digests
+        if: github.ref_type == 'tag'
+        env:
+          REGISTRY: ghcr.io/${{ github.repository_owner }}
+          VERSION: ${{ steps.version.outputs.version }}
+          SERVER_DIGEST: ${{ steps.server.outputs.digest }}
+          LOGIN_DIGEST: ${{ steps.login.outputs.digest }}
+        run: |
+          bash scripts/promote_image.sh "$REGISTRY/newsclip-mcp" "$SERVER_DIGEST" "$VERSION"
+          bash scripts/promote_image.sh "$REGISTRY/newsclip-login-browser" "$LOGIN_DIGEST" "$VERSION"
+          docker buildx imagetools create --prefer-index=false --tag "$REGISTRY/newsclip-mcp:latest" "$REGISTRY/newsclip-mcp@$SERVER_DIGEST"
+          docker buildx imagetools create --prefer-index=false --tag "$REGISTRY/newsclip-login-browser:latest" "$REGISTRY/newsclip-login-browser@$LOGIN_DIGEST"
+
+  github-release:
+    needs: images
+    if: github.event_name == 'push' && github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: distributions
+          path: dist
+      - env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" --verify-tag --title "$TAG" --generate-notes

newsclip-0.7.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.pyc
+.venv/
+bench/results/
+bench/output/
+tmp/
+*.egg-info/
+dist/
+.newsclip/
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+*-cookies.json
+cookies.json
+.claude/
+.artifacts/
+local/
+.env
+*.token

newsclip-0.7.0/AGENTS.md

@@ -0,0 +1,34 @@
+# Working on Newsclip
+
+Newsclip searches, retrieves and privately archives news through CLI, Python and
+MCP interfaces. Only identity-matched, independently assessed FULL content may
+be returned as an article or enter the SQLite archive.
+
+Read README.md, ARCHITECTURE.md and docs/DEVELOPMENT.md. AGENTS.md is the only
+agent instruction file; do not add CLAUDE.md or GEMINI.md.
+
+## Boundaries
+
+- This source is published. Never write personal, account, household, host or
+  network details into public code, comments, docs, fixtures or artifacts.
+- Use synthetic fixtures and example domains. Never copy real article bodies,
+  cookies, screenshots, incidents or profiles into a test or issue.
+- Preserve complete user isolation across authorization, sessions, profiles,
+  archive, exports, diagnostics and asynchronous callbacks.
+- Sign-in is driven by the person through signin-window. Reader tools cannot
+  collect credentials or automate credential submission.
+- A successful sign-in is not proof of entitlement to an arbitrary article.
+  Preserve provider assessment and atomic verified-session publication.
+- Keep provider drift local. Shared fixes require a shared reproducer.
+- SQLite is archive authority. Use consistent backup/restore operations.
+
+## Verify and contribute
+
+Use `uv sync --locked --extra mcp --extra signin`, install the Patchright
+Chromium, then run `make check` and `make check-mcp`. Add synthetic browser and
+user-isolation acceptance for changes to those paths. Live checks are explicit
+private operator actions; never put credentials or live content in public CI.
+
+Follow CONTRIBUTING.md: changes land in the maintained source and are exported
+as releases. Never rewrite a public release tag or merge directly into a release
+mirror. Preserve the MIT license and third-party notices.

newsclip-0.7.0/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture
+
+All interfaces use one synchronous `NewsclipService`. Providers own publisher
+URL identity, discovery, assessment and extraction details. Shared code owns
+network budgets, browser leases, session storage and the SQLite archive.
+
+```text
+CLI / Python client / MCP
+          |
+authenticated user application
+          |
+    NewsclipService
+     |     |     |
+ providers |   SQLite archive
+       verified session + retained browser profile
+```
+
+## User boundary
+
+The standalone server loads a bounded user registry containing token hashes.
+Each registered user has an independent mounted application at `/users/USER`.
+Authentication checks that application's user token; a path or request field
+cannot select another user's authority. Token rotation is checked on subsequent
+requests. New users require a restart to create their mounted application.
+
+Composition resolves every user's data and state roots independently, without
+changing process-wide environment variables. Sessions, profiles, leases,
+incidents, search cursors, archives and server exports use those roots.
+Callbacks preserve the construction user's context when invoked from a worker.
+The host administrator remains trusted.
+
+## Human sign-in
+
+The authenticated `connect` operation creates a short-lived relay link for one
+provider and user. A separate private browser service validates the target and
+opens a restricted signin-window. The person drives the publisher's page.
+Top-level navigation is limited to the provider and required identity hosts;
+resource requests and DNS resolution have explicit allowlists. Browser policy
+blocks local files, downloads, password storage and general browser controls.
+
+After the person signs in, Newsclip visits the configured verification article
+and applies the provider's existing full-content checks. It closes Chromium
+before publishing the new profile-bound session. Publication is atomic and
+compares the generation present when the window opened, so an obsolete window
+cannot overwrite a newer session. Failed candidates are discarded without
+replacing existing verified authority.
+
+Retained browser state and portable session authority are distinct. A profile
+alone is not permission to read an article. Browser readers use the profile
+associated with the active verified session and serialize access with leases.
+
+## Retrieval and persistence
+
+An owned URL is fetched with the applicable user's session, extracted, and
+assessed. Requested, final, canonical and extracted article identity must agree.
+Negative authentication, challenge and paywall signals take precedence over
+plausible prose. Only independently accepted FULL content becomes an Article.
+A verified session does not establish entitlement to every article.
+
+`get` returns accepted content transiently. `save` commits immutable raw-fetch
+evidence and an extraction revision in SQLite; Markdown is a derived export.
+Re-extraction reads stored bytes, and archive search does not contact providers.
+Backups use SQLite's consistent backup path rather than copying live WAL files.
+
+## Installation-specific integrations
+
+The core has a small optional integration boundary for installations maintaining
+additional operator capabilities. The standalone distribution contains no such
+integration, deployment accounts or credential automation. Provider session
+verification remains usable without an automated acquisition adapter.

newsclip-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+Newsclip welcomes focused bug reports, synthetic regression cases, provider
+improvements and documentation fixes. Read [the architecture](ARCHITECTURE.md)
+and [development guide](docs/DEVELOPMENT.md) before changing provider behavior.
+
+Never include credentials, cookies, browser profiles, account details, real
+article bodies, screenshots of signed-in pages, or deployment information in an
+issue, pull request, test fixture or log attachment. Use invented data and
+example domains. Share security reports privately; see [SECURITY.md](SECURITY.md).
+
+## How changes land
+
+This repository is a release mirror of the maintained source. Pull requests are
+reviewed here and re-applied to the maintained source; they are not merged into
+the mirror. Accepted changes arrive in a subsequent release, with contributor
+credit in its release notes. This keeps every public release reproducible from
+the same source without maintaining a separate implementation.
+
+Explain the problem, expected behavior and a minimal reproducer. Run `make check`
+and, for protocol changes, `make check-mcp`. Public tests use synthetic data and
+must work without publisher accounts or private services. Provider-specific
+selectors and access checks belong in that provider's adapter or definition.
+
+Contributions are accepted under the MIT license. Preserve third-party notices.

newsclip-0.7.0/Dockerfile

@@ -0,0 +1,65 @@
+# syntax=docker/dockerfile:1.7
+FROM ghcr.io/astral-sh/uv:0.13.5@sha256:32a7bb39b496babbd997b0a39a4d66c126bdaf5661b302bf6f06abda8deca6ff AS uv
+FROM node:24.22.1-bookworm-slim@sha256:55fb5f5a527ea2c5c4a95f963e48ef90aa38c7b346054fdc8ee9957a2b55d205 AS browser-node
+FROM python:3.12.14-slim-trixie@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f AS base
+COPY --from=browser-node /usr/local/bin/node /usr/local/bin/browser-node
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 UV_LINK_MODE=copy \
+    PATH=/app/.venv/bin:$PATH PLAYWRIGHT_BROWSERS_PATH=/opt/chromium \
+    HOME=/tmp/newsclip-home NEWSCLIP_STATE_HOME=/state NEWSCLIP_DATA_HOME=/data \
+    PLAYWRIGHT_NODEJS_PATH=/usr/local/bin/browser-node
+COPY --from=uv /uv /uvx /usr/local/bin/
+RUN apt-get update && apt-get upgrade -y --no-install-recommends \
+ && apt-get install -y --no-install-recommends ca-certificates curl dumb-init libxtst6 xvfb \
+ && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY pyproject.toml uv.lock README.md LICENSE ./
+RUN uv sync --locked --no-dev --extra mcp --extra signin --no-install-project \
+ && patchright install --with-deps chromium \
+ && /app/.venv/bin/python -c "from pathlib import Path; import patchright; p = Path(patchright.__file__).parent / 'driver' / 'node'; p.unlink(); p.symlink_to('/usr/local/bin/browser-node')" \
+ && rm -rf /var/lib/apt/lists/* \
+ && groupadd --gid 1000 newsclip \
+ && useradd --uid 1000 --gid 1000 --no-create-home --shell /usr/sbin/nologin newsclip
+COPY src ./src
+RUN uv sync --locked --no-dev --extra mcp --extra signin
+ARG VCS_REF=unknown
+ARG IMAGE_VERSION=development
+LABEL org.opencontainers.image.title="Newsclip" \
+      org.opencontainers.image.description="Private news search, reading and archiving with human sign-in" \
+      org.opencontainers.image.source="https://github.com/benjamin-di/newsclip-mcp" \
+      org.opencontainers.image.revision="${VCS_REF}" \
+      org.opencontainers.image.version="${IMAGE_VERSION}" \
+      org.opencontainers.image.licenses="MIT"
+ENTRYPOINT ["dumb-init", "--"]
+
+FROM base AS login
+ENV NOVNC_DIR=/opt/novnc
+ARG NOVNC_VERSION=1.6.0
+ARG NOVNC_SHA256=5066103959ef4e9b10f37e5a148627360dd8414e4cf8a7db92bdbd022e728aaa
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends x11vnc fonts-noto-cjk \
+ && curl --fail --silent --show-error --location \
+      "https://github.com/novnc/noVNC/archive/refs/tags/v${NOVNC_VERSION}.tar.gz" -o /tmp/novnc.tar.gz \
+ && printf '%s  /tmp/novnc.tar.gz\n' "$NOVNC_SHA256" | sha256sum --check --status \
+ && mkdir -p /opt/novnc \
+ && tar -xzf /tmp/novnc.tar.gz -C /opt/novnc --strip-components=1 \
+      "noVNC-${NOVNC_VERSION}/app" "noVNC-${NOVNC_VERSION}/core" \
+      "noVNC-${NOVNC_VERSION}/vendor" "noVNC-${NOVNC_VERSION}/vnc.html" \
+      "noVNC-${NOVNC_VERSION}/LICENSE.txt" "noVNC-${NOVNC_VERSION}/AUTHORS" \
+      "noVNC-${NOVNC_VERSION}/docs/LICENSE.MPL-2.0" \
+      "noVNC-${NOVNC_VERSION}/docs/LICENSE.OFL-1.1" \
+      "noVNC-${NOVNC_VERSION}/docs/LICENSE.BSD-3-Clause" \
+      "noVNC-${NOVNC_VERSION}/docs/LICENSE.BSD-2-Clause" \
+ && python -m signin_window.browser install-policy \
+ && rm -rf /tmp/novnc.tar.gz /var/lib/apt/lists/*
+USER 1000:1000
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=2m --start-interval=2s --retries=3 \
+ CMD ["curl", "--fail", "--silent", "http://127.0.0.1:8080/health"]
+CMD ["newsclip", "signin-service", "--host", "0.0.0.0"]
+
+FROM base AS server
+USER 1000:1000
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=2m --start-interval=2s --retries=3 \
+ CMD ["curl", "--fail", "--silent", "http://127.0.0.1:8000/health"]
+CMD ["newsclip", "serve", "--host", "0.0.0.0"]

newsclip-0.7.0/Dockerfile.dockerignore

@@ -0,0 +1,39 @@
+.git
+.venv
+__pycache__
+*.pyc
+local
+.env
+.artifacts
+.work
+tmp
+dist
+.github/
+publish/
+.gitattributes
+private/
+deploy/
+bench/
+src/newsclip/local_extensions.py
+src/newsclip/identity*
+src/newsclip/identity/
+src/newsclip/identity_targets/
+src/newsclip/identity_definitions/
+src/newsclip/providers/*_auth.py
+src/newsclip/login.py
+src/newsclip/secret_reference.py
+src/newsclip/credential_readiness.py
+src/newsclip/agent_run_vision.py
+src/newsclip/vision_cli.py
+src/newsclip/vision_planning.py
+src/newsclip/hcaptcha.py
+src/newsclip/ops_server.py
+src/newsclip/repair_policy.py
+scripts/live_check.py
+scripts/prepare_auth_repair.py
+scripts/promote_image.sh
+scripts/smoke_image.sh
+scripts/synthetic_route_check.py
+scripts/explain_live_report.py
+tests/fixtures/diagnostics/
+tests/fixtures/identity_snapshot/

newsclip-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 benjamin-di
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

newsclip-0.7.0/Makefile

@@ -0,0 +1,21 @@
+.PHONY: check check-mcp check-standalone check-runtime-lock
+
+# Keep local and CI verification identical. Live providers are always explicit.
+check: check-runtime-lock
+	uv run --locked ruff check .
+	uv run --locked ruff format --check .
+	uv run --locked mypy src/newsclip
+	uv run --locked pytest -q -m "not live"
+	git diff --check
+
+# Keep image dependencies independent of the application's release version.
+check-runtime-lock:
+	@test ! -f deploy/requirements.runtime.txt || { expected=$$(mktemp); trap 'rm -f "$$expected"' EXIT; \
+	uv export --locked --no-dev --extra mcp --no-emit-project --no-header --output-file "$$expected" >/dev/null && \
+	diff -u deploy/requirements.runtime.txt "$$expected"; }
+
+check-mcp:
+	uv run --locked --extra mcp pytest -q -m "not live" tests/test_mcp.py tests/test_mcp_http.py tests/test_drift.py tests/test_serving_recovery_workflow.py
+
+check-standalone:
+	uv run --locked --extra mcp --extra signin pytest -q tests/test_standalone.py tests/test_remote_cli.py

newsclip-0.7.0/NOTICE

@@ -0,0 +1,10 @@
+Newsclip's original code is licensed under the MIT license in LICENSE.
+
+Newsclip depends on separately licensed Python packages and system components.
+Their licenses continue to apply. The login browser image bundles noVNC,
+Chromium, Xvfb and x11vnc; it preserves their upstream license files and package
+copyright notices. The MIT license for Newsclip does not relicense these works.
+
+Publisher names identify compatible services. Newsclip is not affiliated with
+or endorsed by those publishers. Publisher content remains the property of its
+respective rights holders; the software license grants no rights to that content.

newsclip-0.7.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: newsclip
+Version: 0.7.0
+Summary: News search, verified subscription reading and private archiving
+Project-URL: Homepage, https://github.com/benjamin-di/newsclip-mcp
+Project-URL: Documentation, https://github.com/benjamin-di/newsclip-mcp#readme
+Project-URL: Issues, https://github.com/benjamin-di/newsclip-mcp/issues
+Author: benjamin-di
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: click<9,>=8.4
+Requires-Dist: curl-cffi<1,>=0.16.3
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: lxml<7,>=5
+Requires-Dist: patchright<2,>=1.52
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: rich<15,>=14
+Requires-Dist: trafilatura<3,>=2
+Requires-Dist: typer<1,>=0.16
+Provides-Extra: login
+Provides-Extra: mcp
+Requires-Dist: anyio<5,>=4.8; extra == 'mcp'
+Requires-Dist: fastmcp<5,>=4.0.10; extra == 'mcp'
+Requires-Dist: starlette<2,>=1.0.1; extra == 'mcp'
+Requires-Dist: uvicorn<1,>=0.34; extra == 'mcp'
+Provides-Extra: signin
+Requires-Dist: signin-window<0.4,>=0.3.0; extra == 'signin'
+Requires-Dist: uvicorn<1,>=0.34; extra == 'signin'
+Description-Content-Type: text/markdown
+
+# Newsclip
+
+Search, read and privately archive news through a command-line interface,
+Python API, or MCP server. Newsclip uses your existing subscriptions and public
+publisher endpoints. It returns an article only when its identity and full
+content pass the provider's verification checks.
+
+Subscription sign-in uses [signin-window](https://github.com/benjamin-di/signin-window):
+open a short-lived link and sign in on the publisher's page yourself. Newsclip
+keeps the verified session afterwards. It does not need your password in a
+configuration file or an assistant conversation.
+
+- Ten built-in providers: Financial Times, WSJ, Bloomberg, CNBC, Reuters,
+  The Economist, The New York Times, The Guardian, AP News and Axios.
+- Fair federated search with source status, date filters and coverage limits.
+- Separate user tokens, sessions, retained browser profiles and SQLite archives.
+- Transient reading with `get`; durable storage and Markdown export with `save`.
+- Local CLI/Python access and authenticated HTTP/MCP access to the same core.
+- MIT-licensed original code, with synthetic tests and no bundled account data.
+
+## Quick start
+
+The reference server runs on Linux AMD64 with Docker Compose. Python 3.12+ and
+[uv](https://docs.astral.sh/uv/) are used for setup and the CLI. The sign-in
+viewer works in a browser or phone; the browser service itself runs on Linux.
+
+```sh
+git clone https://github.com/benjamin-di/newsclip-mcp.git
+cd newsclip-mcp
+uv sync --locked --extra mcp --extra signin
+uv run python scripts/setup.py --user alice --user bob
+docker compose up -d
+```
+
+Setup writes private token files and configuration without printing secrets.
+Each person uses their own URL and token file:
+
+```sh
+export NEWSCLIP_URL=http://127.0.0.1:8000/users/alice
+export NEWSCLIP_TOKEN_FILE="$PWD/local/tokens/alice.token"
+
+uv run newsclip search "energy markets" --source ap --json
+uv run newsclip auth connect ft
+# Open the returned link, complete sign-in, then check the session.
+uv run newsclip auth status ft --json
+uv run newsclip get 'https://www.ft.com/content/<article-id>'
+uv run newsclip save 'https://www.ft.com/content/<article-id>' --out article.md
+uv run newsclip archive-search "energy" --json
+```
+
+`get` does not archive. `save` commits the verified article and can additionally
+write a Markdown file on the CLI client's machine. Failed, partial and
+unauthorized pages never become archived articles. Use `archive-get ARTICLE_ID`
+to read a saved article without contacting its publisher.
+
+The default deployment is reachable only on the server itself. For phone or
+remote-client access, configure an HTTPS public origin and reverse proxy as
+explained in [deployment](docs/DEPLOYMENT.md).
+
+## Interfaces
+
+For MCP, connect your client to
+`http://127.0.0.1:8000/users/alice/mcp` with Alice's bearer token. The server
+exposes `search`, `get`, `save`, `archive_search`, `archive_get`, `reextract`,
+`session_status`, and `connect`. `connect` returns a human sign-in link; read
+operations never submit credentials.
+
+For Python:
+
+```python
+from pathlib import Path
+from newsclip.client import NewsclipClient
+
+with NewsclipClient(
+    "http://127.0.0.1:8000/users/alice",
+    Path("local/tokens/alice.token").read_text(),
+) as client:
+    response = client.search_many("energy markets", provider_keys=["ap"])
+    for result in response.results:
+        print(result.headline, result.url)
+```
+
+The local CLI and synchronous `NewsclipService` are also available without
+running an HTTP server. `newsclip --user alice ...` selects isolated local
+storage; it is an administrator/local-process option, not remote authorization.
+`newsclip mcp` serves local stdio MCP with the same local user's access.
+
+## Providers and limits
+
+See the [provider matrix](docs/PROVIDERS.md) for authentication, search coverage
+and retrieval behavior. A supported adapter cannot guarantee that a publisher
+will accept every network, account or browser. Articles outside a subscription
+are reported as `not_entitled`. Provider failures remain visible beside healthy
+search results.
+
+Newsclip is for content you are authorized to access. You supply the necessary
+subscriptions and API permissions. It does not purchase access, redistribute
+publisher content, or grant rights to that content through its software license.
+
+## Documentation
+
+- [CLI reference](docs/CLI.md) and [Python/HTTP/MCP API](docs/API.md)
+- [Sign-in and user isolation](docs/AUTHENTICATION.md)
+- [Deployment, configuration, backups and upgrades](docs/DEPLOYMENT.md)
+- [Provider support and extension](docs/PROVIDERS.md)
+- [Architecture](ARCHITECTURE.md), [development](docs/DEVELOPMENT.md) and [roadmap](ROADMAP.md)
+- [Contributing](CONTRIBUTING.md), [security reporting](SECURITY.md) and [third-party notices](NOTICE)
+
+## Development
+
+```sh
+uv sync --locked --extra mcp --extra signin
+uv run patchright install chromium
+make check
+make check-mcp
+```
+
+Offline tests use synthetic content and require no publisher credentials. Live
+provider checks are explicit private operator actions and are never run on a
+contributor's pull request. Public images and release archives are built from
+the public release source.
+
+## License
+
+[MIT](LICENSE) for original code. Dependencies retain their own licenses; see
+[NOTICE](NOTICE). Newsclip is not affiliated with the supported publishers.