io.github.lukebmandel-debug/alto-connector

Alto Connector

mcp-name: io.github.lukebmandel-debug/alto-connector

A Claude connector that interviews you about your own materials — a course, a novel, a research project — and builds you an interactive, filterable "liquid-glass" Alto timeline: glass cards on colored act bands, entity chips, routed connection lines, detail pages with your own schema, highlights and notes, mobile layout, and a self-contained offline file you can share.

The one rule (§0): Alto is a closed knowledge container. It connects and organizes what you provide — it never invents facts, events, holdings, or descriptions. Sparse notes make a sparse timeline, on purpose. The connector enforces this server-side: authoring tools stay locked until your materials and explicit consent are recorded.

Install

Download the file for your computer from the latest release, then in Claude Desktop go to Settings → Extensions → Advanced settings → Install Extension… and choose it. Restart Claude Desktop and Alto appears under Extensions.

Nothing else to install. Each bundle carries its own Python, which is why it is around 50MB. Claude Desktop ships Node but not Python, and stock macOS still has 3.9 — too old for this server.

Without Claude Desktop

Alto is a plain MCP server, so any MCP client can run it — Claude Code, Cline, Zed, Continue, your own script. No download, no bundle.

Add this to your client's MCP config:

{
  "mcpServers": {
    "alto": {
      "command": "uvx",
      "args": ["--from",
               "git+https://github.com/lukebmandel-debug/alto-connector",
               "alto-connector"]
    }
  }
}

Requires uv (curl -LsSf https://astral.sh/uv/install.sh | sh). uvx fetches and runs Alto in a throwaway environment each time, so there is nothing to install or update.

Prefer a permanent install? Then alto-connector is on your PATH and the config is simply {"command": "alto-connector"}:

pip install git+https://github.com/lukebmandel-debug/alto-connector
alto-connector --help      # check it works; without --help it waits for a
                           # client to speak to it, which looks like a hang

Everything works the same way — the interview, the build, the offline file — because the bundle and this are the same server; the bundle just carries its own Python so Claude Desktop users need not install one.

Timelines land in ~/Documents/Alto. Each is a single self-contained HTML file you open in any browser — no server, no account, no internet. Shareable web links are optional (see Publishing below); without them, that file is the finished product.

Then tell your client: "I want to build a timeline in Alto — interview me."

From a checkout

bash setup.sh — macOS and Claude Desktop only; it registers the connector by writing claude_desktop_config.json. For any other client, use one of the two methods above pointed at your checkout.

Using it — what a new user actually does

1. Open a chat and say something like "I want to build a timeline in Alto — interview me."
2. Claude calls get_interview_guide and runs a short warm interview:
   • Flow 1 — name the project container and what it's for.
   • Flow 2 §A — the materials gate: you hand over your actual materials (upload files or paste text into the chat), and explicitly agree that Alto builds only from them.
   • §B–§I — title, what the axis means, your acts/eras, your entities (characters, doctrines, teams…), node schema (e.g. Facts·Issue·Holding· Rule for law), relationship vocabulary for the lines, extra filter axes, persona, presentation.
3. Claude authors nodes verbatim from your materials, wires connections, runs a layout preview, builds (a verifier gates every build), and publishes.
4. You get your timeline two ways:
   • Offline file (always): one self-contained HTML — double-click to open, send to a friend, works forever with no server.
   • Web page (free, set up for you — see Publishing): a page at https://<your-site>.web.app/pv/<key>/ that only your Google account can open, listed on your homepage, with cross-device sync of highlights/notes/reports. To show it to someone, create a share link from your homepage.
5. Come back any time — drafts resume across chats via get_timeline.

Publishing — your own private site, set up for you

Every timeline is private. It goes on your own Alto site — a free Firebase project (Spark plan, no card) in your Google account, never one of ours — at https://<your-project>.web.app/pv/<key>/, which opens only for the Google account that published it. There is no public option.

You set nothing up. The first time you use Alto, Claude calls set_up_site, which runs in the background while the interview goes on:

1. fetches the official Node and Firebase CLI into Alto's own folder (checksum-pinned; nothing system-wide, no admin password);
2. opens a Google page — you click Allow — so it can act in your account;
3. creates your Firebase project, its web app, Firestore, and Google sign-in;
4. deploys your site and the per-user security rules in firestore.rules, then checks from outside that anonymous reads of your data are refused;
5. opens your new site — you click Continue with Google — so Alto on this computer is signed in as you, and moves any drafts into your account.

From then on your projects live in your account (Keep projects in: auto), so every computer you sign in on sees the same ones, and publish_timeline puts a timeline on your site with nothing to upload.

Sharing is a share link. To show a timeline to someone, use "Create share link" in its menu on your homepage. It is a snapshot of that one page at /s/<key>/, readable by anyone with the link without an install or an Alto account, and you can revoke it from the same place at any time.

Already have a Firebase project? Fill in the extension's Advanced settings (site, project id, and optionally the web config) — or, from a checkout, ALTO_FIREBASE_SITE, ALTO_FIREBASE_PROJECT, ALTO_FIREBASE_CONFIG. If this computer has no Firebase CLI, set_up_site installs Alto's own and finishes setting up that project (Firestore, sign-in, rules) instead of making a new one. ALTO_FIREBASE_BIN points at a CLI of your own.

Two things worth knowing before you share a link. A share link is readable by anyone who has it — the key cannot be guessed, but it is not access-controlled, so revoke it when it has done its job. And a reader who signs in to sync their notes gets an account in your Firebase project: the security rules stop you reading their notes through the app, but you own the project and can see them in the Firebase console.

Moving existing work across

set_up_site copies whatever is in the local folder into your account as its last step. To do it by hand (for example from another folder):

alto-connector migrate --from ~/Documents/Alto

It copies, never deletes, and skips anything already in your account.

More than one site, and chats that start on their own

A person can have an Alto site for each Google account they use. Every timeline tool takes an optional account (a site name like luke-alto, its address, or the Google email), and nothing is remembered between calls — one connector process can serve several chats.

• get_interview_guide lists every account this computer is signed in to and what is in each, so a chat opened on its own (not from a timeline's Edit timeline button) finds a timeline the user names. list_projects with account="all" does the same on demand.
• connect_account(site) adds a site the user already has, from its address alone: Alto reads the site's public web config (/__/firebase/init.json), and the user clicks Continue with Google on the site's own sign-in page. Accounts are kept in ~/.config/alto/accounts.json (no tokens; each sign-in is its own session-<project>.json, mode 0600).
• A timeline can be named by its id, its published page address (…/pv/<key>/) or its title. A not_found says where it is: another account (found_in_accounts), or the homepage with no draft behind it (published_without_draft).
• import_timeline(published_key) restores a draft whose page was published from a folder-backed connector: that publish now keeps a compressed copy of the draft beside the page (users/{uid}/alto_snapshots/{key}).
• Publishing into a connected account writes the page straight into it and does not redeploy the site: deploying needs the Firebase CLI logged in as that Google account, which this computer may not be. A sign-in whose site address Alto does not know is never given a guessed one (a project's default site can be somebody else's); the site is learned from the account's own published timelines.

Repo layout

• engine/ — the three page templates, extracted content-free from the reference build. The extraction fixtures they were derived from are not published: they contain the author's own writing. test_roundtrip.py skips without them.
• alto/build/ — brief model, height estimator, layout resolver (a port of the engine's own), block generators, verifier, offline bundler.
• alto/mcp_server.py — the 29 MCP tools + interview prompt.
• alto/build/sanitize.py — makes user content inert before it reaches a page. Load-bearing: the engine renders detail sections straight into innerHTML.
• alto/publish_static.py — free-tier static publishing via the Firebase CLI.
• packaging/ — the .mcpb bundles, the download page and the registry entry. See packaging/README.md.
• alto/web.py, alto/auth/ — a full remote-server variant (streamable HTTP
  • OAuth 2.1), not used by the local install; kept for a future hosted deployment.

Development

.venv/bin/python -m pytest tests/        # incl. the golden round-trip
python3 -m alto.build samples/contracts_brief.json --bundle   # CLI build

Privacy

See alto/privacy.html. Short version: your source documents stay in your Claude conversation; the connector stores only what it builds, locally in ~/Documents/Alto (and, if you publish, on your own Firebase site).