Typed Python SDK + MCP server for internet access across Western + Indian platforms. Built on Agent-Reach's capability layer.
Agent-Reach is a capability layer: it installs, health-checks, and routes the
best current backend per platform (Jina Reader, yt-dlp, gh, Exa, twitter-cli,
OpenCLI, ...). By design it has no programmatic API — it expects an agent
with shell access reading SKILL.md. agentknows fills that gap and retargets the
platform set at the English-speaking + Indian internet:
| Agent-Reach gives you | agentknows adds |
|---|---|
| Installer + doctor + backend routing | One typed facade: Reach().read(url) / .search(q, platform=...) |
| Per-platform CLIs, each with its own output format | One ReachResult JSON shape for everything |
| Shell-only usage | MCP server — Claude Desktop, Cursor, any MCP client, no shell needed |
| Fix prescriptions inside doctor text | Machine-readable errors: every failure carries a runnable .fix |
| Chinese-platform focus (xiaohongshu, bilibili...) | Indian channels: NSE/BSE stocks, ValuePickr, Indian news pack |
| — | Graceful degradation: missing tool → Jina Reader fallback + setup hint |
uv venv && uv pip install -e .
# optional upstream tools: gh (GitHub), mcporter+exa (web search), twitter-cli, OpenCLI
# `agentknows doctor` tells you exactly what's missing and how to fix it.from agentknows import Reach
reach = Reach()
# read anything
reach.read("https://www.youtube.com/watch?v=...") # metadata + transcript
reach.read("https://github.com/owner/repo/issues/1") # issue + comments via gh
reach.read("https://news.ycombinator.com/item?id=1") # story + comment tree
reach.read("https://forum.valuepickr.com/t/x/3872") # forum topic + posts
reach.read("https://any-blog.com/post") # Markdown via Jina Reader
reach.read("RELIANCE", platform="stocks") # NSE quote (auto .NS/.BO suffix)
# search
reach.search("llm eval frameworks") # Exa semantic web search
reach.search("react hooks", platform="github", kind="code")
reach.search("smallcap IT", platform="discourse") # ValuePickr
reach.search("TCS", platform="stocks") # symbol lookup
# trending
reach.hot("hackernews") # HN front page
reach.hot("news", region="india") # ET/Mint/Hindu/TOI/Moneycontrol
reach.hot("discourse", period="weekly") # top ValuePickr threads
# cross-platform research: one query → parallel fan-out → merged bundle
reach.research("UPI transaction limits", region="india")
reach.research("vector db pricing", report=True) # + Claude-written synthesis
reach.doctor() # structured health reportEvery call returns a ReachResult:
ReachResult(ok=True, platform="stocks", backend="yfinance", kind="document",
content="# Reliance Industries...", meta={"price": 1275.9, "currency": "INR", ...})Failures raise ReachError subclasses (SetupRequired, UpstreamFailure,
UnsupportedOperation) whose .fix is a runnable prescription.
agentknows read https://news.ycombinator.com/item?id=39000000
agentknows read RELIANCE -p stocks
agentknows search "vector databases" -n 5
agentknows search "Tata Motors" -p discourse
agentknows hot news --region india
agentknows hot hackernews
agentknows research "ONDC adoption" --region india # merged research bundle
agentknows research "rust web frameworks" --report # + Claude synthesis (needs key)
agentknows doctor
agentknows read <url> --json # machine outputresearch fans one query out in parallel across web (Exa), Hacker News, news,
YouTube, ValuePickr, and Twitter/Reddit when configured, and merges everything
into one Markdown bundle with per-source coverage notes. --report adds a
Claude-written synthesis (install agentknows[research], set ANTHROPIC_API_KEY
or ant auth login; refusal fallbacks are enabled by default).
uv pip install "agentknows[ui]"
agentknows ui # opens http://127.0.0.1:8787A local one-page console over the same engine: pick a verb (research / search /
read / hot), type a query, watch the research fan-out complete source-by-source
live (SSE), and read the rendered bundle. doctor lives in the nav. Local-first
on purpose — the strongest backends (yt-dlp, gh, cookies, OpenCLI) are on your
machine, so the console runs next to them.
agentknows-mcp # stdioClaude Desktop / Cursor config:
{"mcpServers": {"agentknows": {"command": "agentknows-mcp"}}}Tools: reach_read, reach_search, reach_hot, reach_research, reach_doctor, reach_platforms. (reach_research returns the raw bundle — the calling model does its own synthesis.)
| Platform | read | search | hot | Needs |
|---|---|---|---|---|
| web (any URL) | Jina Reader | Exa via mcporter | — | nothing / mcporter |
| youtube | metadata + transcript | ytsearch | — | yt-dlp (bundled) |
| github | repo / issue / PR | repos, code, issues, prs | — | gh CLI |
| hackernews | story + comments | Algolia | front page | nothing |
| stocks (NSE/BSE/US) | live quote | symbol lookup | — | nothing (yfinance bundled) |
| news (IN + Western) | — | keyword filter | fresh headlines | nothing |
| discourse (ValuePickr + any forum) | topic + posts | forum search | top threads | nothing |
| rss | feed entries | — | — | nothing |
| tweet | search | — | twitter-cli + cookies (burner account!) | |
| reddit / facebook / instagram | via OpenCLI | via OpenCLI | — | OpenCLI + logged-in browser |
8 of 11 platforms are zero-config. Chinese channels (bilibili, xiaohongshu, v2ex, xueqiu, xiaoyuzhou) are intentionally out of scope; their URLs still read fine through the Jina Reader catch-all.
News pack sources — India: Economic Times, LiveMint, The Hindu, Times of India,
Moneycontrol. Western: BBC, The Guardian, TechCrunch, The Verge, Ars Technica.
Edit adapters/news.py:FEEDS to customize.
Login-gated platforms follow Agent-Reach's boundaries: agentknows never automates logins or reads browser cookies; credentials are injected into child processes only and never logged. Use burner accounts — cookie-based API access risks bans.
src/agentknows/
├── client.py # Reach facade
├── router.py # URL → platform (native hosts + agent-reach's can_handle)
├── doctor.py # structured health report
├── models.py # ReachResult / Item envelope
├── errors.py # errors with .fix prescriptions
├── proc.py # upstream CLI runner
├── mcp_server.py # FastMCP server
├── cli.py # human CLI
└── adapters/ # one per platform, normalizing upstream output
├── stocks.py # NSE/BSE/US via yfinance
├── hackernews.py # Algolia public API
├── discourse.py # ValuePickr default; works on any Discourse forum
├── news.py # curated IN + Western RSS pack
└── ...