{
  "markdown": "# Alto Connector\n\nmcp-name: io.github.lukebmandel-debug/alto-connector\n\nA Claude connector that interviews you about **your own materials** — a course,\na novel, a research project — and builds you an interactive, filterable\n\"liquid-glass\" **Alto timeline**: glass cards on colored act bands, entity\nchips, routed connection lines, detail pages with your own schema, highlights\nand notes, mobile layout, and a self-contained offline file you can share.\n\n**The one rule (§0):** Alto is a closed knowledge container. It connects and\norganizes what *you* provide — it never invents facts, events, holdings, or\ndescriptions. Sparse notes make a sparse timeline, on purpose. The connector\nenforces this server-side: authoring tools stay locked until your materials\nand explicit consent are recorded.\n\n## Install\n\nDownload the file for your computer from the\n[latest release](../../releases/latest), then in Claude Desktop go to\n**Settings → Extensions → Advanced settings → Install Extension…** and choose\nit. Restart Claude Desktop and Alto appears under Extensions.\n\n| | |\n|---|---|\n| macOS, Apple Silicon | `Alto-macos-arm64.mcpb` |\n| macOS, Intel | `Alto-macos-x64.mcpb` |\n| Windows, 64-bit | `Alto-windows-x64.mcpb` |\n\n**Nothing else to install.** Each bundle carries its own Python, which is why\nit is around 50MB. Claude Desktop ships Node but not Python, and stock macOS\nstill has 3.9 — too old for this server.\n\n### Without Claude Desktop\n\nAlto is a plain MCP server, so any MCP client can run it — Claude Code, Cline,\nZed, Continue, your own script. No download, no bundle.\n\nAdd this to your client's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"alto\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\",\n               \"git+https://github.com/lukebmandel-debug/alto-connector\",\n               \"alto-connector\"]\n    }\n  }\n}\n```\n\nRequires [uv](https://docs.astral.sh/uv/getting-started/installation/)\n(`curl -LsSf https://astral.sh/uv/install.sh | sh`). `uvx` fetches and runs\nAlto in a throwaway environment each time, so there is nothing to install or\nupdate.\n\nPrefer a permanent install? Then `alto-connector` is on your `PATH` and the\nconfig is simply `{\"command\": \"alto-connector\"}`:\n\n```bash\npip install git+https://github.com/lukebmandel-debug/alto-connector\nalto-connector --help      # check it works; without --help it waits for a\n                           # client to speak to it, which looks like a hang\n```\n\nEverything works the same way — the interview, the build, the offline file —\nbecause the bundle and this are the same server; the bundle just carries its\nown Python so Claude Desktop users need not install one.\n\nTimelines land in `~/Documents/Alto`. Each is a single self-contained HTML\nfile you open in any browser — no server, no account, no internet. Shareable\nweb links are optional (see Publishing below); without them, that file is the\nfinished product.\n\nThen tell your client: *\"I want to build a timeline in Alto — interview me.\"*\n\n### From a checkout\n\n`bash setup.sh` — **macOS and Claude Desktop only**; it registers the\nconnector by writing `claude_desktop_config.json`. For any other client, use\none of the two methods above pointed at your checkout.\n\n## Using it — what a new user actually does\n\n1. Open a chat and say something like *\"I want to build a timeline in Alto —\n   interview me.\"*\n2. Claude calls `get_interview_guide` and runs a short warm interview:\n   - **Flow 1** — name the project container and what it's for.\n   - **Flow 2 §A** — *the materials gate*: you hand over your actual materials\n     (upload files or paste text into the chat), and explicitly agree that\n     Alto builds only from them.\n   - **§B–§I** — title, what the axis means, your acts/eras, your entities\n     (characters, doctrines, teams…), node schema (e.g. Facts·Issue·Holding·\n     Rule for law), relationship vocabulary for the lines, extra filter axes,\n     persona, presentation.\n3. Claude authors nodes **verbatim from your materials**, wires connections,\n   runs a layout preview, builds (a verifier gates every build), and\n   publishes.\n4. You get your timeline two ways:\n   - **Offline file** (always): one self-contained HTML — double-click to\n     open, send to a friend, works forever with no server.\n   - **Web links** (optional, still free): if Firebase publishing is\n     configured, `https://<your-site>.web.app/t/<timeline>/` plus a homepage\n     listing all your published timelines, a reports page, and cross-device\n     sync of highlights/notes/reports.\n5. Come back any time — drafts resume across chats via `get_timeline`.\n\n## Publishing (optional web links + cross-device sync)\n\nTimelines are private by default and the offline file always works. To publish\nshareable links — and to get highlights, notes and reports syncing between your\ndesktop and your phone — you host them on **your own** free Firebase project\n(Spark plan, no card).\n\n**You host what you share.** Everyone who authors a timeline publishes to their\nown project, so the people you send a link to read it from your site and their\nnotes live in your Firestore. That means you can revoke a link at any time\n(`publish_timeline(timeline_id, visibility=\"private\")` deletes the page from\nyour site), and it means nobody's data flows through anyone else's project.\nReading a shared timeline needs no install and no Alto account — just the link.\n\n1. [console.firebase.google.com](https://console.firebase.google.com) → create\n   a project → Hosting → add a site (e.g. `my-alto`).\n2. Enable **Firestore** and **Authentication → Google** in that project, and\n   deploy the per-user rules in `firestore.rules` (`firebase deploy --only\n   firestore:rules`). Do this *before* publishing: a Firestore left in test\n   mode is world-readable and world-writable for 30 days.\n3. `npm i -g firebase-tools && firebase login`\n4. Open Alto's settings in Claude Desktop (**Settings → Extensions → Alto**)\n   and fill in **Firebase Hosting site**, **Firebase project id** and\n   **Firebase web config**. From a checkout instead, set `ALTO_FIREBASE_SITE`,\n   `ALTO_FIREBASE_PROJECT` and `ALTO_FIREBASE_CONFIG` in the environment.\n\n   The web config comes from Firebase console → Project\n   settings → Your apps → SDK setup and configuration. It is spliced into\n   `alto-cloud.js` at publish time. Leave it unset and sync is simply off:\n   highlights stay in the browser's local storage on each device.\n   `ALTO_FIREBASE_BIN` overrides the path to the `firebase` CLI if it is not on\n   your `PATH`.\n\nTwo things worth knowing before you share a link. Published means **public to\nanyone who has the URL** — the address carries a random tail so it cannot be\nguessed, but it is not access-controlled. And a reader who signs in to sync\ntheir notes gets an account in *your* Firebase project: the security rules stop\nyou reading their notes through the app, but you own the project and can see\nthem in the Firebase console.\n\n## Repo layout\n\n- `engine/` — the three page templates, extracted content-free from the\n  reference build. The extraction fixtures they were derived from are not\n  published: they contain the author's own writing. `test_roundtrip.py` skips\n  without them.\n- `alto/build/` — brief model, height estimator, layout resolver (a port of\n  the engine's own), block generators, verifier, offline bundler.\n- `alto/mcp_server.py` — the 14 MCP tools + interview prompt.\n- `alto/build/sanitize.py` — makes user content inert before it reaches a page.\n  Load-bearing: the engine renders detail sections straight into `innerHTML`.\n- `alto/publish_static.py` — free-tier static publishing via the Firebase CLI.\n- `packaging/` — the .mcpb bundles, the download page and the registry entry.\n  See `packaging/README.md`.\n- `alto/web.py`, `alto/auth/` — a full remote-server variant (streamable HTTP\n  + OAuth 2.1), not used by the local install; kept for a future hosted\n  deployment.\n\n## Development\n\n```bash\n.venv/bin/python -m pytest tests/        # incl. the golden round-trip\npython3 -m alto.build samples/contracts_brief.json --bundle   # CLI build\n```\n\n## Privacy\n\nSee `alto/privacy.html`. Short version: your source documents stay in your\nClaude conversation; the connector stores only what it builds, locally in\n`~/Documents/Alto` (and, if you publish, on your own Firebase site).\n",
  "bytes": 8282,
  "sha": "16f281b11d391a84967c4fc60b8e2bc1cc8ed0d0b76a3cc7e791133ba6a4c7b6",
  "repo_slug": "lukebmandel-debug/alto-connector",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lukebmandel_debug_alto_connect_57e8ad51/readme"
}