alto-connector

Alto Connector

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

一款 Claude 连接器，会采访你，了解你自己的资料——课程、小说、研究项目——并据此构建可交互、可筛选的「液态玻璃」Alto 时间线：彩色幕段上的玻璃卡片、实体标签、带路由的连接线、采用你自定义架构的详情页、亮点和笔记、移动端布局，以及可供分享的独立离线文件。

唯一规则（§0）： Alto 是一个封闭的知识容器。它只连接和整理你提供的内容，绝不捏造事实、事件、持有物或描述。笔记稀疏，时间线自然也会稀疏。连接器会在服务端强制执行此规则：记录好你的资料并获得明确同意之前，创作工具始终处于锁定状态。

安装

从最新版本下载适用于你电脑的文件，然后在 Claude Desktop 中前往 Settings → Extensions → Advanced settings → Install Extension… 并选择该文件。重启 Claude Desktop，Alto 就会显示在 Extensions 下。

macOS，Apple Silicon	Alto-macos-arm64.mcpb
macOS，Intel	Alto-macos-x64.mcpb
Windows，64 位	Alto-windows-x64.mcpb

无需安装其他内容。 每个安装包都自带 Python，因此大小约为 50 MB。Claude Desktop 自带 Node，但不带 Python；而原版 macOS 仍附带 3.9 版，对此服务来说太旧了。

不使用 Claude Desktop

Alto 是一个纯 MCP 服务，因此任何 MCP 客户端都能运行它——Claude Code、Cline、Zed、Continue，或你自己的脚本。无需下载，也无需安装包。

将以下内容添加到客户端的 MCP 配置中：

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

需要安装 uv （curl -LsSf https://astral.sh/uv/install.sh | sh）。每次运行时，uvx 都会在临时环境中获取并运行 Alto，因此无需安装或更新任何内容。

更喜欢永久安装？这样一来，alto-connector 就会位于你的 PATH 中，配置只需写成 {"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

所有功能都保持不变——采访、构建、离线文件——因为安装包和此版本其实是同一个服务；安装包只是自带 Python，这样 Claude Desktop 用户就不必自行安装。

时间线保存在 ~/Documents/Alto 中。每条时间线都是一个独立的 HTML 文件，可在任意浏览器中打开——无需服务、账户或互联网。可分享的网页链接是可选的（见下文的“发布”）；没有链接时，该文件就是最终成品。

然后告诉客户端：“我想在 Alto 中创建一条时间线——采访我吧。”

从检出目录运行

bash setup.sh——仅限 macOS 和 Claude Desktop；它会通过写入 claude_desktop_config.json 注册连接器。对于其他客户端，请使用上述两种方法之一，并将目标指向你的检出目录。

使用方式——新用户实际会做什么

1. 打开聊天并说类似 “我想在 Alto 中构建一条时间线——采访我吧。”
2. Claude 调用 get_interview_guide，并进行一段简短的暖场访谈：
   • Flow 1 — 命名项目容器，并说明它的用途。
   • Flow 2 §A — 材料关卡：你交出自己的实际材料（上传文件或将文本粘贴到聊天中），并明确同意 Alto 仅根据这些材料构建。
   • §B–§I — 标题、轴的含义、你的阶段／时代、实体（角色、学说、团队……）、节点架构（例如法律领域的 Facts·Issue·Holding·Rule）、连线的关系词汇、额外筛选轴、角色设定、呈现方式。
3. Claude 逐字依据你的材料编写节点、连接节点、运行布局预览、构建（每次构建都会经过验证器把关），然后发布。
4. 你可以通过两种方式获得时间线：
   • 离线文件（始终提供）：一个独立的 HTML 文件——双击即可打开、可以发送给朋友，无需服务器，永久可用。
   • 网页（免费，已为你设置——参见“发布”）：页面位于 https://<your-site>.web.app/pv/<key>/，只有你的 Google 账号可以打开；页面会列在你的主页上，并支持跨设备同步高亮、笔记和报告。若要向他人展示，请从主页创建分享链接。
5. 随时回来——草稿会通过 get_timeline 在不同聊天间恢复。

发布——为你设置的专属私人网站

每条时间线都是私密的。它会放在你自己的 Alto 网站上——这是你自己的 Google 账号中的免费 Firebase 项目（Spark 套餐，无需银行卡），绝不是我们的项目——网址为 https://<your-project>.web.app/pv/<key>/，只有发布它的 Google 账号可以打开。没有公开选项。

你无需进行任何设置。 首次使用 Alto 时，Claude 会调用 set_up_site，该程序会在访谈进行期间于后台运行：

1. 将官方 Node 和 Firebase CLI 下载到 Alto 自己的文件夹中 （固定校验和；不安装到系统范围内，无需管理员密码）；
2. 打开 Google 页面——你点击 Allow——这样它就能在你的账号中操作；
3. 创建你的 Firebase 项目、其 Web 应用、Firestore 和 Google 登录；
4. 部署你的网站以及 firestore.rules 中的每用户安全规则， 然后从外部检查匿名读取你的数据是否会被拒绝；
5. 打开你的新网站——你点击 Continue with Google——这样这台电脑上的 Alto 就会以你的身份登录，并将任何草稿移入你的账号。

从此以后，你的项目都保存在你的账号中（Keep projects in: auto），因此你登录的每台电脑都会看到相同的项目，而 publish_timeline 无需上传任何内容，就能将时间线发布到你的网站上。

通过分享链接进行分享。 若要向他人展示时间线，请使用主页上该时间线菜单中的“Create share link”。它是该单个页面在 /s/<key>/ 的快照，任何拥有链接的人都可以阅读，无需安装软件或拥有 Alto 账号；你可以随时在同一位置撤销链接。

已经有 Firebase 项目？ 填写扩展程序的 Advanced 设置（网站、项目 ID，以及可选的 Web 配置）——或者在检出版本中设置 ALTO_FIREBASE_SITE、ALTO_FIREBASE_PROJECT、ALTO_FIREBASE_CONFIG。 如果这台电脑上没有 Firebase CLI，set_up_site 会安装 Alto 自己的 CLI，并完成该项目的设置（Firestore、登录、安全规则），而不是新建项目。ALTO_FIREBASE_BIN 可指定你自己的 CLI。

分享链接前有两件事值得了解。分享链接任何拥有它的人都可以读取——无法猜出密钥，但它并不受访问控制，因此完成用途后请撤销链接。此外，登录以同步笔记的读者会在你的 Firebase 项目中获得一个账号：安全规则会阻止你通过应用读取他们的笔记，但项目归你所有，你可以在 Firebase 控制台中查看这些笔记。

在现有作品之间迁移

set_up_site 会在最后一步将本地文件夹中的所有内容复制到你的账户中。手动执行（例如从另一个文件夹复制）：

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

它只复制，不会删除，并且会跳过账户中已有的内容。

使用多个站点，以及自行启动的聊天

用户可以为自己使用的每个 Google 账户各自拥有一个 Alto 站点。每个时间线工具都接受可选的 account（站点名称，例如 luke-alto、站点地址或 Google 邮箱），且调用之间不会保留任何信息——一个连接器进程可以为多个聊天提供服务。

• get_interview_guide 会列出此电脑已登录的所有账户及其内容，因此，独立打开的聊天（不是从时间线的 Edit timeline 按钮打开）可以找到用户指定的时间线。使用 account="all" 调用 list_projects 也可以随时获取相同信息。
• connect_account(site) 只需提供站点地址，即可添加用户已有的站点：Alto 会读取该站点公开的 Web 配置（/__/firebase/init.json），用户则在站点自己的登录页面上点击 Continue with Google。账户信息保存在 ~/.config/alto/accounts.json 中（不含令牌；每次登录会单独保存为 session-<project>.json，权限模式为 0600）。
• 可以通过时间线的 ID、已发布页面地址（…/pv/<key>/）或标题来指定时间线。not_found 会说明它在哪里：其他账户（found_in_accounts），或者没有草稿的主页（published_without_draft）。
• import_timeline(published_key) 可以还原通过文件夹连接器发布页面的草稿：现在发布时会在页面旁边保存一份压缩的草稿副本（users/{uid}/alto_snapshots/{key}）。
• 发布到已连接的账户时，页面会直接写入该账户，不会重新部署站点：部署需要通过此 Google 账户登录 Firebase CLI，而这台电脑可能并未登录。对于 Alto 不认识站点地址的登录，绝不会猜测地址（项目的默认站点可能属于其他人）；只有从账户自己的已发布时间线中才能得知站点。

仓库布局

• engine/ — 三个页面模板，从参考构建中提取并移除了内容。用于生成这些模板的提取测试文件未公开：其中包含作者自己的文字。没有这些文件时，test_roundtrip.py 会跳过。
• alto/build/ — 简报模型、高度估算器、布局解析器（移植自 engine 自身）、区块生成器、验证器、离线打包器。
• alto/mcp_server.py — 29 个 MCP 工具和采访提示词。
• alto/build/sanitize.py — 在用户内容进入页面前将其处理为惰性内容。此步骤至关重要：engine 会将详细部分直接渲染到 innerHTML 中。
• alto/publish_static.py — 通过 Firebase CLI 发布静态内容，适用于免费套餐。
• packaging/ — .mcpb 包、下载页面和注册表条目。参见 packaging/README.md。
• alto/web.py、alto/auth/ — 完整的远程服务版本（可流式传输的 HTTP + OAuth 2.1），本地安装不会使用；保留以供未来托管部署使用。

开发

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

隐私

参见 alto/privacy.html。简而言之：源文档保留在你的 Claude 对话中；连接器只会在本地 ~/Documents/Alto 中存储其生成的内容（如果你发布了内容，也会存储在你自己的 Firebase 站点上）。