@shubhamcodess/tiny-browse 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +31 -0
- package/LICENSE +21 -0
- package/README.md +146 -2
- package/dist/cli.js +5923 -0
- package/dist/index.d.ts +279 -0
- package/dist/index.js +5106 -0
- package/package.json +74 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/). Before 1.0, breaking changes bump the minor version.
|
|
4
|
+
|
|
5
|
+
## [Unreleased]
|
|
6
|
+
|
|
7
|
+
## [0.1.0] - 2026-11-08
|
|
8
|
+
|
|
9
|
+
First release.
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- MCP server with `web_search` and `web_fetch`, over stdio (`tiny-browse mcp`) and HTTP (`tiny-browse serve --http`), plus a JSON API.
|
|
14
|
+
- Library API: `webSearch`, `webFetch`, `createClient`, `doctor`, `TinyBrowseError` and TypeScript types.
|
|
15
|
+
- Google search in the installed Chrome with DuckDuckGo and Bing fallbacks; results parsed three independent ways and merged by vote.
|
|
16
|
+
- Page reading over plain HTTP or in Chrome, whichever works, remembered per site.
|
|
17
|
+
- Clean Markdown extraction keeping headings, code, tables, lists and quotes.
|
|
18
|
+
- Hard `max_tokens` limit, `focus` for relevant sections, `cursor` to continue long pages, and a model-agnostic token counter.
|
|
19
|
+
- Strict, shared request budgets for search engines and escalating pauses after CAPTCHAs.
|
|
20
|
+
- No-Chrome mode (`--no-chrome`, `mode: "http"`).
|
|
21
|
+
- Image bytes for vision models (`return_images`).
|
|
22
|
+
- Disk cache for pages and search results.
|
|
23
|
+
- `tiny-browse login`, `doctor`, `init` and `config <client>`.
|
|
24
|
+
|
|
25
|
+
### Security
|
|
26
|
+
|
|
27
|
+
- Local and private network addresses refused, including requests made by pages inside Chrome.
|
|
28
|
+
- Pages read in a cookie-less browser context.
|
|
29
|
+
|
|
30
|
+
[Unreleased]: https://github.com/shubhamcodess/tiny-browse/compare/v0.1.0...HEAD
|
|
31
|
+
[0.1.0]: https://github.com/shubhamcodess/tiny-browse/releases/tag/v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Shubham Prakash
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,147 @@
|
|
|
1
|
-
#
|
|
1
|
+
# tiny-browse
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<img src="assets/logo-256.png" alt="tiny-browse logo" width="120" align="right">
|
|
4
|
+
|
|
5
|
+
### Give any AI agent the web, in 126 kB.
|
|
6
|
+
|
|
7
|
+
tiny-browse searches **Google in the Chrome you already have**, reads the best results and returns **clean Markdown** that fits a **hard token budget**. One **zero-dependency** package: an **MCP server** for any agent and a **Node.js library** for your own code. No bundled browser, no API keys.
|
|
8
|
+
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
[](https://github.com/shubhamcodess/tiny-browse/actions/workflows/ci.yml)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
|
|
13
|
+
[](https://www.npmjs.com/package/@shubhamcodess/tiny-browse)
|
|
14
|
+
[](https://www.npmjs.com/package/@shubhamcodess/tiny-browse)
|
|
15
|
+
[](https://www.npmjs.com/package/@shubhamcodess/tiny-browse)
|
|
16
|
+
|
|
17
|
+
- **Any agent, any model.** MCP over stdio or HTTP, plus a JSON API. No LLM inside.
|
|
18
|
+
- **Tiny on disk.** A 126 kB download with zero runtime dependencies, using your installed Chrome, Edge, Brave or Chromium instead of downloading a browser of its own.
|
|
19
|
+
- **Answers, not HTML.** Main content only, with headings, code, tables and lists kept, inside a hard `max_tokens` limit.
|
|
20
|
+
- **Careful by default.** Strict search rate limits, no access to private networks, pages read without your cookies.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
Requires Node.js 22+ and Chrome, Chromium, Edge or Brave (or use the no-Chrome mode).
|
|
25
|
+
|
|
26
|
+
**From npm**
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install -g @shubhamcodess/tiny-browse
|
|
30
|
+
tiny-browse doctor
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Agents can also run it without installing: `npx -y @shubhamcodess/tiny-browse mcp`.
|
|
34
|
+
|
|
35
|
+
**From the latest GitHub release**
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm install -g https://github.com/shubhamcodess/tiny-browse/releases/latest/download/tiny-browse.tgz
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
**From source**
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
git clone https://github.com/shubhamcodess/tiny-browse.git
|
|
45
|
+
cd tiny-browse
|
|
46
|
+
npm ci && npm run build
|
|
47
|
+
npm link # or run: node dist/cli.js
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Use cases
|
|
51
|
+
|
|
52
|
+
**Web search for your own local agents.** An agent running on a local model has no web access. Add tiny-browse as an MCP server and it can search and read pages, with no API keys and no cloud service.
|
|
53
|
+
|
|
54
|
+
**Answers grounded in sources.** Every page comes back with its URL and only its relevant sections, so an assistant can answer from current pages and cite them instead of relying on what the model remembers.
|
|
55
|
+
|
|
56
|
+
**Current docs for coding agents.** Libraries change after a model's training cutoff. `web_fetch` with `focus` pulls just the part of the documentation the agent needs, as clean Markdown with code blocks intact.
|
|
57
|
+
|
|
58
|
+
## Connect to an agent
|
|
59
|
+
|
|
60
|
+
**Claude Code**
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
claude mcp add tiny-browse -- npx -y @shubhamcodess/tiny-browse mcp
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**VS Code (GitHub Copilot)**: `.vscode/mcp.json`
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"servers": {
|
|
71
|
+
"tiny-browse": { "type": "stdio", "command": "npx", "args": ["-y", "@shubhamcodess/tiny-browse", "mcp"] }
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**Cursor, Claude Desktop and most other clients**
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"mcpServers": {
|
|
81
|
+
"tiny-browse": { "command": "npx", "args": ["-y", "@shubhamcodess/tiny-browse", "mcp"] }
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`tiny-browse config <client>` prints the setup for `claude-code`, `claude-desktop`, `cursor`, `vscode`, `codex` or `generic`. To share one warm Chrome between several agents, run `tiny-browse serve --http 7777` and connect to `http://127.0.0.1:7777/mcp`.
|
|
87
|
+
|
|
88
|
+
The agent gets two tools: **`web_search`** (search and read the top results) and **`web_fetch`** (read URLs, optionally narrowed with `focus` or continued with `cursor`). Parameters: [TOOLS.md](docs/TOOLS.md).
|
|
89
|
+
|
|
90
|
+
## Use as a dependency
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
npm install @shubhamcodess/tiny-browse
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
import { webSearch, webFetch } from "@shubhamcodess/tiny-browse";
|
|
98
|
+
|
|
99
|
+
const { results, pages, markdown } = await webSearch({ query: "node.js stream backpressure", read: 2 });
|
|
100
|
+
for (const r of results) console.log(r.rank, r.title, r.url);
|
|
101
|
+
|
|
102
|
+
const docs = await webFetch({ urls: ["https://go.dev/doc/effective_go"], focus: "goroutines", max_tokens: 2000 });
|
|
103
|
+
console.log(docs.pages[0].markdown);
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Each call starts what it needs and shuts it down before returning, so short-lived CLIs exit straight away. Use `createClient()` to reuse one Chrome across calls, `mode: "http"` to skip Chrome entirely, and `TinyBrowseError.code` to handle failures. Full API: [LIBRARY.md](docs/LIBRARY.md).
|
|
107
|
+
|
|
108
|
+
## How it works
|
|
109
|
+
|
|
110
|
+
1. **Search.** Google's results page is loaded in your Chrome and read three independent ways (layout, accessibility tree, selectors), merged by vote, so a page redesign rarely breaks it. If Google is blocked or over its rate budget, DuckDuckGo and Bing are tried.
|
|
111
|
+
2. **Read.** Each page is fetched over plain HTTP and rendered with scripts off, which is fast; pages that need JavaScript get a full Chrome load. The faster way is remembered per site.
|
|
112
|
+
3. **Extract.** The main content is found by how the page is laid out, not by class names. Menus, ads, cookie banners and hidden text are dropped.
|
|
113
|
+
4. **Fit.** The page is split into sections by heading and packed into `max_tokens`, keeping the sections most relevant to the query.
|
|
114
|
+
|
|
115
|
+
## Limitations
|
|
116
|
+
|
|
117
|
+
- Search engines may block automated browsers, depending on your network. Running `tiny-browse login` once usually helps with Google. Reading pages is not affected.
|
|
118
|
+
- Sites that refuse automated access with a bot check are reported as `blocked`, never bypassed.
|
|
119
|
+
- No PDF support yet.
|
|
120
|
+
- Tested on macOS and Linux. Windows is untested.
|
|
121
|
+
|
|
122
|
+
## Troubleshooting
|
|
123
|
+
|
|
124
|
+
| Problem | Fix |
|
|
125
|
+
|---|---|
|
|
126
|
+
| `chrome_not_found` | Install Chrome, or set `--browser-path` / `TINY_BROWSE_CHROME` |
|
|
127
|
+
| Google keeps showing CAPTCHAs | Run `tiny-browse login`. Searches use the other engines meanwhile; `tiny-browse doctor` shows pauses and budgets |
|
|
128
|
+
| Chrome won't start on Ubuntu 24.04 | `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0` |
|
|
129
|
+
| `port … is already in use` | Another `tiny-browse serve` is running: stop it or choose another port |
|
|
130
|
+
| A page comes back thin | Use `render: "browser"`; the site may need JavaScript or block automation |
|
|
131
|
+
|
|
132
|
+
## Documentation
|
|
133
|
+
|
|
134
|
+
| | |
|
|
135
|
+
|---|---|
|
|
136
|
+
| [Configuration](docs/CONFIGURATION.md) | Settings, rate limits, environment variables, flags |
|
|
137
|
+
| [MCP tools and server](docs/TOOLS.md) | Tool parameters, output, HTTP server |
|
|
138
|
+
| [Library API](docs/LIBRARY.md) | Functions, options, errors, lifecycle |
|
|
139
|
+
| [Design notes](docs/DESIGN.md) | Architecture and findings |
|
|
140
|
+
| [Contributing](CONTRIBUTING.md) | Development setup and releases |
|
|
141
|
+
| [Security](SECURITY.md) | Reporting vulnerabilities, threat model |
|
|
142
|
+
| [Code of Conduct](CODE_OF_CONDUCT.md) | |
|
|
143
|
+
| [Changelog](CHANGELOG.md) | |
|
|
144
|
+
|
|
145
|
+
## License
|
|
146
|
+
|
|
147
|
+
[MIT](LICENSE) © Shubham Prakash
|