Metadata-Version: 2.5
Name: analog-mcp
Version: 0.11.0
Summary: Model Context Protocol server for Analog, a web interface built for AIs.
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.21.0,>=0.20.0
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. Analog is a web interface
built for AIs. It converts webpages into the things they contain — products,
articles, events, and other records — so AIs can query, compare, export, and use
them directly. The extraction pipeline contains no LLMs.

For URL acquisition, pages are rendered in a browser on your machine by default. The built-in
browser starts a fresh session and does not use your browser profile, cookies,
or saved credentials. For structured extraction, the rendered page content and
its URL are sent to Analog. Results return to the SDK and are saved locally
unless disabled. Signed-in page content is sent only when you explicitly supply it.
`mode="local"` converts the page
to Markdown on your machine and sends nothing to Analog.

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.

`analog` and `analog_describe` accept `guidance: true` to add at most one
available next action. Guidance is off by default and changes no evidence
or capture settings. The receipt includes advice only when it fits after
the selected evidence; necessary recovery remains visible either way.

## 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 and field metadata) when page orientation is useful.
- **`analog_feedback(...)`** — report a page that extracted poorly
  (reason labels are enumerated in the tool's schema) or send a
  free-form feature request.

When saving succeeds, the `analog_*` tools re-slice the saved result
without re-fetching or re-rendering the page. A failed save leaves the
bounded receipt available and reports that no saved handle can be used.

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/)
