Metadata-Version: 2.5
Name: analog-mcp
Version: 0.10.0
Summary: Model Context Protocol server for Analog — Analog lets any AI understand websites as code, from any MCP client.
Project-URL: Homepage, https://getanalog.io
Project-URL: Documentation, https://getanalog.io/docs/mcp/
Project-URL: Changelog, https://getanalog.io/docs/mcp-changelog/
Author-email: Marcus Campbell <marcus@getanalog.io>
License: MIT
License-File: LICENSE
Keywords: ai-agents,deterministic,llm-tools,mcp,mcp-server,structured-data,web-extraction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: analog-sdk<0.20.0,>=0.18.1
Requires-Dist: mcp<3,>=2.0
Requires-Dist: typing-extensions>=4.4
Description-Content-Type: text/markdown

# analog-mcp

A Model Context Protocol server for [Analog](https://getanalog.io) —
**Analog lets any AI understand websites as code** — usable from Claude
Desktop, Cursor, and anything else that speaks MCP. The perception layer for
LLMs: webpages in, structured records out. Deterministic, zero-shot, honest.
The extraction pipeline contains no LLMs.

Pages are fetched on your machine by default. The SDK uses a local headless
browser, which visits as an unauthenticated user by default. For structured
extraction, the SDK sends the URL and rendered page content to Analog. Results
return to the SDK and are saved locally unless disabled. Authenticated content
is sent only when you explicitly provide it through `html=` or a custom
fetcher. `mode="local"` is the Markdown-only path that sends nothing.

This server is Analog for MCP clients. Agents with shell access can
use the [`analog` command-line app](https://pypi.org/project/analog-sdk/)
directly — the same extraction and saved-result workflow as shell
commands, no configuration required.

The headline tool is `analog(url)`. Point it at a webpage; get back a bounded
receipt with section shapes, representative records, completeness disclosures,
and a handle for the saved result. Its JSON text fallback never exceeds 16,384
characters; structured content carries the same receipt.

## Tools

- **`analog(url, pages=N)`** — extract a page; returns a bounded orientation
  receipt plus a `handle`. Pass `pages=N` (max 50) to follow the site's own
  next-page links and merge up to N pages into one result (each page costs one
  extraction; the sweep is disclosed on the response).
- **`assess(url)`** — check which tool fits a page for your task: the page's
  measured markdown size plus task-keyed guidance (working with the data →
  analog; one quick question → read it directly; a platform data feed spotted
  → worth knowing), so you route a page without spending an extraction. No sign-in required.
- **`analog_history(limit=N)`** — list saved results, newest first, as cheap
  metadata (handle, url, when saved, size) to recover a handle you no longer
  have in context.
- **`analog_open(handle)`** — return a previous result in full, no re-fetch.
- **`analog_export(handle, fmt)`** — re-emit it as `json` / `csv` / `yaml` / `md`.
- **`analog_section(handle, index)`** — pull one section's records.
- **`analog_collection(handle, index)`** — query compatible physical sections
  as one identity-deduplicated records view while retaining their provenance.
- **`analog_find(handle, pattern, field=)`** — search a result's records across
  sections; pass `field=` to scope the search to one field.
- **`analog_describe(handle)`** — a token-cheap preview of a saved result
  (section shapes plus sample records) for orienting without pulling the full JSON.
- **`analog_feedback(...)`** — report a page that extracted poorly
  (reason labels are enumerated in the tool's schema) or send a
  free-form feature request.

Every `analog` result is saved locally, so the `analog_*` tools re-slice it
without re-fetching or re-rendering the page.

JSON-shaped tools expose navigable MCP structured content and an equivalent
text fallback. Format exports, previews, and feedback confirmations remain
text-only.

## Install

The server reads the credential stored by the `analog` CLI (it ships
with `analog-sdk`), so install both tools:

<!-- BEGIN GENERATED: onboarding mcp-install-full -->

```bash example=runnable scenario=onboarding-mcp-install-full
uv tool install analog-sdk
uv tool install analog-mcp
```
<!-- END GENERATED: onboarding mcp-install-full -->

Prefer pip? `pip install analog-mcp` in one environment puts both
executables on PATH. `uvx analog-mcp` runs the server one-off, but
signing in still needs the CLI installed.

## Sign in

Connect a new account:

<!-- BEGIN GENERATED: onboarding new-user-auth -->

```bash example=runnable scenario=onboarding-new-user-auth-default
analog signup
```
<!-- END GENERATED: onboarding new-user-auth -->

Or connect an existing account:

<!-- BEGIN GENERATED: onboarding existing-user-auth -->

```bash example=runnable scenario=onboarding-existing-user-auth-default
analog login
```
<!-- END GENERATED: onboarding existing-user-auth -->

This opens your browser, signs you in, and stores the key in the
CLI's local credential store — `analog-mcp` reads it from there, so no
key ever lands in an MCP config file.

Analog renders pages with a built-in headless browser that downloads on
first use (~150 MB, one-time). To fetch it ahead of time so the first
`analog` tool call doesn't pause:

<!-- BEGIN GENERATED: onboarding browser-preinstall -->

```bash example=runnable scenario=onboarding-browser-preinstall-default
analog browser install
```
<!-- END GENERATED: onboarding browser-preinstall -->

## Configure your MCP client

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

<!-- BEGIN GENERATED: onboarding mcp-config -->

```json example=config schema=mcp-client
{
  "mcpServers": {
    "analog": {
      "command": "analog-mcp"
    }
  }
}
```
<!-- END GENERATED: onboarding mcp-config -->

Restart Claude Desktop. The `analog` tool will appear in the tool list.
No `env` block is needed — `analog-mcp` reads the credential you stored
during sign-in.

### Cursor / other MCP clients

Same idea — the server command is `analog-mcp` and it speaks stdio.
Refer to your client's MCP configuration docs for the exact file
location.

## Usage

Once configured, just ask the agent things like:

> Extract the speakers from <https://example-conference.com/2026>

The agent calls `analog(url=…)` under the hood. The tool returns
a bounded receipt with representative records and a saved-result handle.
The agent can answer from that receipt or use the handle to request the
complete result, one section, a search, or another format without fetching
the page again.

Full documentation: https://getanalog.io/docs

## What this version ships

`analog-mcp` exposes the extraction tool `analog(url)`, a local routing
check `assess(url)`, and the `analog_*` re-slice tools, over the stdio
transport.

## License

MIT — see [LICENSE](./LICENSE).

## Links

- Homepage: <https://getanalog.io>
- Command-line app and Python SDK: [`analog-sdk` on PyPI](https://pypi.org/project/analog-sdk/)
