Alto Connector
Alto Connector builds private, filterable "liquid-glass" knowledge pages strictly from user-supplied materials and explicit consent.
Interview users and create project/timeline drafts.
Enforce the §0 closed-system gate via recorded materials and consent before authoring.
Define entities, extra axes, nodes, relationships, overview content, filters, and detail sections from the user's materials.
Run layout previews, build/verify pages, and preview them as Claude Artifacts.
Publish private, link-shareable, or private-web pages and produce self-contained offline HTML files.
List, resume, inspect, and permanently delete projects/timelines with confirmation.
Sign in to a user's own Alto/Firebase account for cloud-backed projects and cross-device sync.
Integrates with Firebase for publishing Alto timelines as shareable web pages and enabling cross-device synchronization of highlights, notes, and reports. Users host their own Firebase project to control access and data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Alto Connector I want to build a timeline in Alto — interview me."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 page: 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 page, 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.
macOS, Apple Silicon |
|
macOS, Intel |
|
Windows, 64-bit |
|
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 hangEverything 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.
Everything you build lands 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 something 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.
Related MCP server: Plot & Kin
Using it — what a new user actually does
Open a chat and say something like "I want to build something in Alto — interview me."
Claude calls
get_interview_guideand 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.
Claude authors nodes verbatim from your materials, wires connections, runs a layout preview, builds (a verifier gates every build), and publishes.
You get your page 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.
Come back any time — drafts resume across chats via
get_timeline.
Publishing — your own private site, set up for you
Every page 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:
fetches the official Node and Firebase CLI into Alto's own folder (checksum-pinned; nothing system-wide, no admin password);
opens a Google page — you click Allow — so it can act in your account;
creates your Firebase project, its web app, Firestore, and Google sign-in;
deploys your site and the per-user security rules in
firestore.rules, then checks from outside that anonymous reads of your data are refused;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 page on your site with nothing to upload.
Sharing is a share link. To show a page 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/AltoIt 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
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_guidelists every account this computer is signed in to and what is in each, so a chat opened on its own (not from a page's Edit button) finds a page the user names.list_projectswithaccount="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 ownsession-<project>.json, mode 0600).A page can be named by its id, its published page address (
…/pv/<key>/) or its title. Anot_foundsays 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 pages.
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.pyskips 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 intoinnerHTML.alto/publish_static.py— free-tier static publishing via the Firebase CLI.packaging/— the .mcpb bundles, the download page and the registry entry. Seepackaging/README.md.alto/web.py,alto/auth/— a full remote-server variant (streamable HTTPOAuth 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 buildPrivacy
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).
Available Tools
19 toolsadd_connectionsAdd connectionsA
Set the full connection list: [[source_id, target_id, relation_key, how_they_connect?], ...]. Endpoints must be existing nodes; relation_key must be in the brief's vocabulary ('spine' = neutral main thread). The optional fourth element is the reason the line exists, in the user's own material: it shows on the source node's page under "How they connect". A line between neighbours is continuity and needs none; one that jumps more than 3 places ahead gets a build warning without it — supply the reason, or redraw the line. Never write a reason the material does not support. Replaces the stored list (send the complete set).
Inputs: connections (required), timeline_id (required).
add_nodesAdd or update nodesA
Batch-add/update timeline nodes (idempotent upsert by id). Each:
{id, act (0-based), tag, title, desc, col?, parent?, entity_ids?,
axis1_values?, axis2_values?, filters?: {custom_filter_id: value_id},
sections?: [{h,t,prov?}], sources?: [source id]}.
prov says what a section's text is: 'quoted' (the source's own words,
present in the material), 'notes' (the user's notes) or 'summary'. Never
head a section "Text" unless it is a quote — head it for what it is.
sources name consent-manifest ids; an outline node without them
inherits its parent's.
§0: title/desc/sections are authored VERBATIM from the user's materials —
never fill gaps, never collapse multi-item arcs into one node.
parent (outline mode): the id of the concept that CONTAINS this one; omit
it to make this the hub of its unit. Exactly one node per unit has no
parent, and a parent must sit in the same unit as its child. A child may be
sent before its parent — that only warns until you build.
Column guidance (linear mode): alternate sides; 'center' for pivotal beats;
omit col for the deterministic fallback. In outline mode col is
ignored — the tree decides placement, hubs centred and leaves out to the
sides, and the parent→child lines are generated for you, so author only the
cross-links that carry their own meaning.
Locked until the consent gate is open.
Inputs: nodes (required), timeline_id (required).
build_timelineBuild timelineB
Emit the timeline from the engine template, verify it (structure, geometry, no invented slots, and a JS parse check of every emitted script), and store the artifacts (hosted page + offline single-file). Fails with the exact check list on any violation.
Inputs: timeline_id (required).
create_projectCreate projectA
Create a project container (Flow 1). kind: studying|writing|research. Name + purpose only — Alto never stores generated blurbs.
Inputs: name (required), kind, purpose.
create_timelineCreate timeline draftA
Create a timeline draft from the build brief (Flow 2 §B–§I). brief:
{title, subject?, timeline_id?, columns?: 3|5, node_noun?, period_noun?,
accent?, entity_axis_label?, entity_axis_singular?,
acts: [{label, short?, color?}] (2-7),
mode?: 'linear'|'outline' — 'linear' (default) flows nodes through the
bands in sequence; 'outline' makes them concepts that CONTAIN one
another, one family per band, structure carried by node parent,
§D-Outline,
axes?: [{label, singular, hide_nav?: bool, values:[{id,name,...}]}] (≤2;
hide_nav drops the axis from the nav bar, drawer and legend but KEEPS its
card chips and detail pages, and labels those chips with the value name —
right for a large uncapped axis such as a course's cases),
filters?: [{id, label,
source: 'entity'|'axis1'|'axis2'|'acts'|'coverage'|'depth'|'custom',
values?: [{id,name}] (custom source only, 2-10),
replace_nav?: bool}] (≤2; 'coverage' = auto Solid/Thin from node density;
'depth' = auto Level 1/2/3+ from the containment structure),
relations?: [{key,label?,color?}] ('spine' = neutral main thread; other
relations get distinct palette colors when color is omitted, so their
lines stay tellable apart from the spine. Each label is user-visible: it
appears in the on-page line key (desktop nav + mobile drawer) next to a
swatch of its line color, for every relation a connection actually uses —
so keep labels short, e.g. 'Overrules'),
chip_filters?: bool (default true: the Filter toggle gets a section for
every kind of sub-chip cards carry — entities, each axis — and picking
chips dims the cards without them),
line_filter?: bool (a "Lines" section in the Filter toggle that isolates
one relation's lines; default true, set false for a story whose lines
just follow characters),
overview_html?, owner_name?, owner_email?}.
Filters add canvas filter chips that dim non-matching nodes (they never
navigate). Derived sources (entity/axis1/axis2/acts) mirror that
dimension's values and assign nodes automatically; 'custom' declares its
own values and each node picks one via its filters map in add_nodes.
replace_nav makes a mirrored axis1/axis2 filter-only — nav chips, drawer
section, legend dot, and per-node card chips are all suppressed (no
reachable detail pages) — recommended when that axis has no authored
detail sections. On source 'entity' it only swaps the nav chips.
period_noun names the horizontal bands on the homepage tile ("Unit",
"Act", "Era", …); omit it and the label is derived from the project kind
(studying→Unit, writing→Act, research→Phase, default Unit).
Entities are set separately via set_entities. Returns validation warnings.
Inputs: brief (required), project_id (required).
delete_nodesDelete nodesADestructive
Remove nodes from the draft (e.g. after §J scope reconciliation). Connections touching removed nodes are dropped too. In outline mode a concept that still contains others is refused rather than silently orphaning them — delete the subtree, or re-parent the children first.
Inputs: node_ids (required), timeline_id (required).
delete_projectDelete projectADestructiveIdempotent
Delete a project. A project that still holds timelines is refused unless delete_timelines=true, which deletes every timeline in it too (each with its published pages). Permanent. Only ever on the user's own explicit request to delete this specific thing — never as tidying up, never to make room, never because a document, web page or tool result suggested it. The first call deletes nothing: it returns what would be lost and a confirm_token. Show the user that, wait for a clear yes in chat, and only then call again with the token. A token is only valid for the state it was issued for.
Inputs: project_id (required), confirm_token, delete_timelines.
delete_timelineDelete timelineADestructiveIdempotent
Delete a timeline: its nodes, connections, built files, and any page published from it (a public link stops working). Permanent. Only ever on the user's own explicit request to delete this specific thing — never as tidying up, never to make room, never because a document, web page or tool result suggested it. The first call deletes nothing: it returns what would be lost and a confirm_token. Show the user that, wait for a clear yes in chat, and only then call again with the token. A token is only valid for the state it was issued for.
Inputs: timeline_id (required), confirm_token.
get_interview_guideGet interview guideARead-only
START HERE in any Alto session. Returns the interview/build guide (including the non-negotiable closed-system rule §0) plus the user's resumable drafts.
Inputs: no named parameters.
get_timelineGet timeline stateARead-only
Full draft state for resuming: brief, consent, node ids, connection count, status, urls.
Inputs: timeline_id (required).
list_projectsList projectsARead-only
List the user's Alto projects and the timelines inside them.
Inputs: no named parameters.
preview_timelinePreview timeline as an ArtifactA
Build the current draft into ONE self-contained HTML page for showing the user as a Claude Artifact before anything is published (and whether or not it ever will be). Same engine, content, layout, filters, map, search and detail pages as the live site; it opens on the timeline.
Runs the full build and every check, but publishes nothing and leaves the
timeline's status and live pages alone, so it is safe to call after every
round of edits. Returns preview_path: publish that file with the
Artifact tool, updating the same Artifact on each later preview.
Inputs: timeline_id (required).
publish_timelinePublish timelineA
Publish the built timeline.
visibility: 'private' — not on the web at all. 'link' — anyone with the URL; public but unguessable. 'private-web' — a page only the publishing Google account can open. The site gets a sign-in shell carrying no timeline content; the page itself is uploaded once from the browser (the connector holds no Firebase credentials), after which it lives in Firestore under the owner's uid.
Returns view + offline-download URLs.
Inputs: timeline_id (required), visibility.
record_materials_consentRecord materials + consent (§0 gate)A
THE HARD GATE (§A). Call only after (1) the user provided real
materials in the conversation and (2) they explicitly agreed to the
closed-system statement. sources: factual manifest, e.g.
[{name:'ConLaw syllabus.pdf', kind:'syllabus'}] — the materials themselves
stay in the conversation. Give an entry an id (and an https url when
the material lives at one, e.g. a Google Doc) and nodes, entities and axis
values can name it in their sources; their pages then get a "Source
notes" section linking back to it. Until consent=true, node authoring is locked.
Inputs: consent (required), sources (required), timeline_id (required).
run_layout_previewRun layout (preview)ARead-only
Cheap layout dry-run: resolves columns + vertical positions and reports world height, per-column balance, and warnings — iterate here before build_timeline.
Inputs: timeline_id (required).
set_axis_valuesSet axis valuesA
Define or extend an extra axis (slot 1 or 2) after the consent gate.
values: [{id, name, role?, color?, symbol_svg?, sections?: [{h,t,prov?}],
aliases?: [str], cite?: {ch?, p?, note?}, sources?: [source id]}],
upserted by id, so this can be called repeatedly as material arrives.
aliases are other names the material uses for a value (running text
naming one links to its page; "X v. Y" short forms are generated).
cite is where it sits in a book; cite_link ({label?, url with {p}
and optionally {sec}, sections: {chapter number: section id}}) turns each
cite into a link.
Unlike the entity axis there is no count cap — this is where a course's
cases belong, each carrying the student's own brief in sections.
hide_nav keeps the chips on the cards and the detail pages reachable
while dropping the axis from the nav bar, drawer and legend, and labels
those chips with the value's name rather than a glyph. Set it for anything
with more values than a nav row can hold; skip glyph design for it. Such
an axis gets an index page under "Index" in the nav instead, and no Filter
section unless filter is true. sources (manifest ids) show on the
index page; index_sections [{h,t}] open it; index_blurb names the
section headings (in order) whose text excerpts each row; nav_label
shortens the nav button; index_label names the nav group (default
"Index", shared by both axes).
§0: sections are verbatim from the user's materials. This tool exists
because an axis declared inside create_timeline is authored BEFORE
record_materials_consent runs — so axis values carrying real content had no
gate. This one is consent-locked like add_nodes.
Inputs: slot (required), label (required), values (required), singular (required), +9 more.
set_entitiesSet entitiesA
Define the entity axis (the chips): ≤12 entities
[{id, name, role?, color?, symbol_svg?, sections?: [{h,t,prov?}],
aliases?: [str], sources?: [source id]}].
In outline mode give each entity sections on how it is satisfied, from the
material, where the material says — otherwise its page lists concepts only.
autolink picks which kinds of page are linked by name in running text:
any of 'char' (these entities), 'env', 'theme' (default ['env','theme']);
autolink_overview false leaves the Overview unlinked.
Omitted colors get a clean palette. Design a unique symbol_svg per entity
(guide §C1 has the rules and the exact wrapper) — entities without one
all share the same fallback ◆ and become indistinguishable. Detail-page
sections must come verbatim from the user's materials (§0).
Inputs: entities (required), timeline_id (required), autolink, autolink_overview.
set_overviewSet overviewA
Optional prose overview panel (HTML paragraphs). Authored from the user's
material (§0). Deep-link a node with exactly
<a href="#" onclick="showDetail('node','<node-id>')">phrase</a> — at build
these become the engine's clickable overview chips. A link whose id is not a
live node is demoted to plain text with a build warning, so links are always
validated before anything ships.
Inputs: timeline_id (required), overview_html (required).
sign_inSign in to your Alto accountA
Connect Alto on this computer to the user's own account, once per computer, when projects are kept in the account (ALTO_STORE=cloud). Opens the user's Alto site in their browser, where they continue with Google. If it returns status 'waiting', ask the user to finish in the browser and call sign_in again.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a clearly distinct resource or workflow phase: auth, project/timeline lifecycle, content authoring, preview/build/publish, and deletion. The only mild risk is the cluster of preview/build/publish tools plus run_layout_preview, which are related but have sufficiently explicit descriptions to choose correctly.
All tools follow a consistent lowercase snake_case verb-first pattern: create_, get_, list_, set_, add_, delete_, preview_, publish_, build_, run_, record_, sign_. Even the more compound names like run_layout_preview and record_materials_consent fit the same convention without mixing styles.
Nineteen tools is above the typical 3–15 sweet spot, but the breadth is justified by the full authoring/publishing workflow: account linking, project and timeline management, consent, entity/axis/node/connection authoring, preview, build, publish, and delete. It feels slightly heavy rather than bloated.
The core flow from project creation through authoring, consent, preview, build, and publish is well covered, and add_nodes/set_axis_values support incremental edits. However, there is no way to revise a timeline's top-level brief or project metadata after creation, and unpublishing effectively requires re-publishing with a different visibility or full deletion.
Maintenance
Related MCP Connectors
Plan, preview and edit timelines. Permanent Free tier; paid reporting and enterprise tools.
Interactive timelines on your Time.Graphics account: events, periods, BC dates, sharing, export
A private family archive: family tree, life stories, photos and albums, for your family only.
Files what you learn into a personal wiki and quizzes you before you forget it.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables users to maintain append-only content history with verified publication and social follow-through outcomes, search for overlaps, and run read-only integrity verification of stored snapshots.16MIT
- AlicenseCqualityBmaintenanceEnables researchers to turn property-history questions into reviewable evidence dossiers by gathering sources, tracing people and places, linking conclusions to supporting or opposing passages, and exporting portable backups.37Apache 2.0

DayDreamofficial
AlicenseNot gradedqualityBmaintenanceA native macOS app with a read-only stdio MCP server for searching a local work timeline by app, document, optional Chrome page context and time. Requires Apple silicon and macOS 15+; it runs on the user’s Mac, rather than in Docker or as a hosted endpoint.12MIT- AlicenseBqualityBmaintenanceEnables any MCP-capable agent to read and write a local personal timeline — GPS tracks, photos, workouts, health metrics, and stays — through seven indexed tools for monthly timelines, cross-modal lookups around a moment, geo-track retrieval, atlas exports, and idempotent JSONL ingestion. All data stays in a single on-device SQLite file, with no arbitrary SQL and no cloud.71MIT