<!-- markdownlint-disable MD033 MD041 -->
<p align="center">
  <img src="packages/extension/src/assets/skimlet-logo.svg" alt="Skimlet logo" width="128">
</p>

<h1 align="center">Skimlet</h1>
<!-- markdownlint-enable MD033 MD041 -->

Skimlet provides a local Model Context Protocol (MCP) server and HTTP search API
for agents doing research. It reads search engine results pages (SERPs) and
extracts page content in batches using your Chrome profile. Google is the first
supported source; Brave, Bing, and Reddit are planned.

Search and extraction times depend on the sites, browser, and network. Google
may rate-limit requests, so a batch can contain failed searches.

Requires Node.js 22+ and Chrome 125+.

## Architecture

![Skimlet architecture diagram](assets/skimlet-architecture-v1.png)

## Setup

Choose one way to start the MCP server. Both use the separate Chrome
extension described below.

### Local checkout

```sh
npm ci
npm run check
npm test
npm run build
```

For MCP clients that use `mcpServers` JSON, provide an absolute path to your
checkout:

```json
{
  "mcpServers": {
    "skimlet": {
      "command": "node",
      "args": ["/absolute/path/to/skimlet-final/packages/skimlet/dist/mcp/mcp.js"]
    }
  }
}
```

### Published npm package

Run the published package with `npx`. No global install is required:

```json
{
  "mcpServers": {
    "skimlet": {
      "command": "npx",
      "args": ["-y", "@bhoomabrsr/skimlet"]
    }
  }
}
```

The batch tools and HTTP API require version 0.3.0 or newer. Version 0.2.1 has
the older MCP `search` tool. If 0.3.0 is not published yet, build this checkout.

### Chrome extension

Install [Skimlet from the Chrome Web Store](https://chromewebstore.google.com/detail/skimlet/fiipfignceankihmkhfjldmniofechoh)
in the Chrome profile you want to use. If you lack Store access, clone
this repository, run `npm ci && npm run build:extension`, and load
`packages/extension/dist/` through **Load unpacked** in `chrome://extensions`.
The relay accepts both extension IDs.

Start an MCP client, then select the Skimlet icon on a web page to attach that
tab. Select it again to detach. The relay stays online when an MCP client
exits. If the relay restarts, select the icon to reconnect. Skimlet closes
the tabs it creates when each search finishes or is cancelled.

## MCP batch tools

The MCP server exposes the batch API as three tools. `batch_search` submits
queries without waiting for the searches to finish:

```json
{
  "queries": ["TypeScript Playwright"],
  "includeContent": true,
  "format": "markdown",
  "maxContentBytes": 20000
}
```

Content extraction is off by default. The submission returns an `id` and
`accessToken`. Pass both to `batch_search_status`; use the `skip` value from its
`next` URL to read subsequent results. Pass the same credentials to
`batch_search_cancel` to cancel a batch. The MCP server sends the bearer token
in the API request header; it does not put the token in the URL.

## Local search API

The built relay also serves the [search API](packages/api/README.md) on
`127.0.0.1:19989`. This source checkout builds the API into the relay.

Single searches return Google listings without opening linked pages. A batch
accepts up to 50 queries and returns a polling URL and bearer token without
waiting for the searches to finish. Only batches support `includeContent`,
which opens linked pages asynchronously. Jobs and results are stored in SQLite.
The Workmatic worker resumes queued searches after a relay restart. The only
supported provider is `SKIMLET_BROWSER_PROVIDER=extension`.

## Scope and security

The extension requests `activeTab`, `debugger`, and `tabGroups`. It has no
all-URL host permissions, content scripts, toolbar injection, or credential
storage. The relay listens on loopback and checks the extension's `Origin`
header against the Store ID and the unpacked build's manifest-derived ID.
Loopback is not an authentication boundary: processes run by other users on
this machine can also reach the relay. Non-browser clients can supply an
`Origin` header. Use Skimlet on a trusted machine with trusted MCP clients.
Browser requests can include your profile cookies, and clients receive
extracted page content.

Skimlet owns its extension, relay, and browser connector. The `version` field
at `/version` reports the package version. The API uses Playwright Core for
searches. The relay also keeps a compatible Chrome DevTools Protocol (CDP)
command interface for browser interactions.

A real browser can help with some bot checks, but it cannot guarantee that
you will avoid CAPTCHAs.

## Acknowledgements

Skimlet builds on the work of [Playwriter](https://github.com/remorses/playwriter)
and its maintainer, Tommaso De Rossi. Playwriter's extension and CDP design
helped shape Skimlet's protocol. The current search flow has no Playwriter
runtime dependency.