pyaireader

Local AI Evidence Reader MCP for AI agents.

pyaireader reads public URLs for AI agents. It is not a human-facing web reader and not a crawler platform. The MVP target is:

public URL -> safety -> HTTP fetch -> extract -> evidence -> quality -> trace -> cache

Fetched page content is untrusted evidence, not instructions.

Documentation

Start here:

• 中文安装与使用教程

• MCP integration guide

• Capability matrix

• PRD

• SPEC

Related MCP server: markdown-for-agents-mcp

Install

Recommended:

git clone https://github.com/PigeonAI-Yang/pyaireader.git
cd pyaireader
uv sync --extra dev --extra extractors

Full install with Scrapling, browser, and PDF support:

uv sync --extra dev --extra extractors --extra browser --extra pdf
uv run playwright install chromium

MCP

Recommended stdio MCP command:

uv --directory J:\PigeonYang\pyaireader run pyaireader-mcp

For local SDK inspection:

uv run mcp dev src/pyaireader/mcp/server.py

The MCP server registers:

• reader_health

• read_url_for_ai

• batch_read_urls_for_ai

• inspect_url

• clear_reader_cache

Codex Desktop / Codex CLI / Claude Code CLI setup examples are in:

docs/mcp-integration.md

CLI

pyaireader read https://example.com --pretty
pyaireader inspect https://example.com --pretty
pyaireader batch urls.txt --jsonl
pyaireader clear-cache --url https://example.com
pyaireader clear-cache --domain example.com

Configuration

Copy .env.example if you want local overrides.

Important defaults:

• Cache: .pyaireader/cache.sqlite3

• Fetch strategy: auto

• Default order: HTTP first; Scrapling/browser are later phases

• Max redirects: 5

• Private network blocking: enabled

Safety Boundary

Allowed:

• http

• https

• public DNS names and public IPs

Blocked:

• file:, data:, javascript:, ftp:

• localhost

• userinfo URLs

• private / loopback / link-local / reserved IPs

• metadata IP 169.254.169.254

• unsafe redirect targets

Tests

Default local test run:

uv run pytest -q

Optional network/browser verification:

$env:PYAIREADER_RUN_NETWORK_TESTS='1'
$env:PYAIREADER_RUN_BROWSER_TESTS='1'
uv run pytest -q tests\test_optional_integration.py