agentknows

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

Install

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.

SDK

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 report

Every 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.

CLI

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 output

research 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).

Web console

uv pip install "agentknows[ui]"
agentknows ui          # opens http://127.0.0.1:8787

A 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.

MCP server

agentknows-mcp     # stdio

Claude 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 support

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
twitter	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.

Layout

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
    └── ...