alto-connector

Alto Connector

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

あなた自身の資料についてインタビューし、コース、小説、研究プロジェクトなどをもとに、インタラクティブでフィルター可能な「リキッドグラス」Alto タイムラインを作成する Claude コネクターです。色分けされた幕の帯に並ぶガラスのカード、エンティティチップ、経路付きの接続線、独自のスキーマを使った詳細ページ、ハイライトとメモ、モバイルレイアウト、そして共有できる自己完結型のオフラインファイルを作成します。

唯一のルール（§0）： Alto は閉じたナレッジコンテナーです。あなたが提供したものをつなぎ、整理します。事実、出来事、所蔵品、説明を作り出すことはありません。メモが少なければ、意図どおりタイムラインも簡素になります。コネクターはこのルールをサーバー側で適用します。資料と明示的な同意が記録されるまで、作成ツールはロックされたままです。

インストール

お使いのコンピューターに対応するファイルを最新リリースからダウンロードし、Claude Desktop で Settings → Extensions → Advanced settings → Install Extension… に進んで選択してください。Claude Desktop を再起動すると、Extensions に Alto が表示されます。

macOS、Apple Silicon	Alto-macos-arm64.mcpb
macOS、Intel	Alto-macos-x64.mcpb
Windows、64-bit	Alto-windows-x64.mcpb

ほかにインストールするものはありません。 各バンドルには専用の Python が含まれているため、サイズは約 50MB です。Claude Desktop には Node は同梱されていますが Python はなく、標準の macOS に入っている Python は 3.9 で、このサーバーには古すぎます。

Claude Desktop を使わない場合

Alto は通常の MCP サーバーなので、Claude Code、Cline、Zed、Continue、ご自身のスクリプトなど、どの MCP クライアントからでも実行できます。ダウンロードもバンドルも不要です。

クライアントの 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 のユーザーは Python をインストールする必要がありません。

タイムラインは ~/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. 年表は次の 2 つの方法で利用できます。
   • オフラインファイル（常に利用可能）：自己完結型の HTML ファイルです。ダブルクリックで開き、友人に送ることができ、サーバーなしでいつまでも使えます。
   • ウェブページ（無料で、設定は自動です — 「公開」を参照）：https://<your-site>.web.app/pv/<key>/ にあるページです。あなたの Google アカウントだけが開けます。ホームページに一覧表示され、ハイライト、メモ、レポートがデバイス間で同期されます。誰かに見せるには、ホームページから共有リンクを作成します。
5. いつでも戻ってこられます。get_timeline を使えば、チャットをまたいで下書きを再開できます。

公開 — あなた専用のプライベートサイトを自動で設定

すべての年表はプライベートです。年表は、あなたの Google アカウント内にある無料の Firebase プロジェクト（Spark プラン、カード不要）を使った、あなた自身の Alto サイトに公開されます。当社のアカウントを使うことはありません。サイトの URL は https://<your-project>.web.app/pv/<key>/ で、公開した Google アカウントだけが開けます。公開設定にはできません。

あなたが設定することはありません。 Alto を初めて使うとき、Claude は set_up_site を呼び出し、インタビューの進行中にバックグラウンドで次の処理を行います。

1. Alto 専用フォルダーに、公式の Node と Firebase CLI をダウンロードします（チェックサムで固定。システム全体へのインストールはなく、管理者パスワードも不要です）。
2. Google のページを開きます。許可をクリックすると、あなたのアカウントで操作できるようになります。
3. Firebase プロジェクト、ウェブアプリ、Firestore、Google サインインを作成します。
4. firestore.rules にあるサイトとユーザーごとのセキュリティルールをデプロイし、外部から匿名でデータを読み取れないことを確認します。
5. 新しいサイトを開きます。Google で続行をクリックすると、このコンピューター上の Alto にあなたのアカウントでサインインし、下書きがあればアカウントに移します。

以降、プロジェクトはあなたのアカウントに保存され（プロジェクトの保存先：自動）、サインインしたどのコンピューターからも同じプロジェクトを使えます。publish_timeline を使えば、ファイルをアップロードせずに年表をサイトに公開できます。

共有には共有リンクを使います。 年表を誰かに見せるには、ホームページのメニューから「共有リンクを作成」を選びます。これは /s/<key>/ にある、そのページのスナップショットです。インストールや Alto アカウントがなくても、リンクを知っている人なら誰でも閲覧できます。リンクはいつでも同じ場所から無効にできます。

すでに Firebase プロジェクトをお持ちですか？ 拡張機能の詳細設定にサイト、プロジェクト ID、必要に応じてウェブ設定を入力してください。または、チェックアウトから ALTO_FIREBASE_SITE、ALTO_FIREBASE_PROJECT、ALTO_FIREBASE_CONFIG を設定してください。このコンピューターに Firebase CLI がない場合、set_up_site は Alto 専用の CLI をインストールし、新しいプロジェクトを作る代わりに、そのプロジェクトの設定（Firestore、サインイン、ルール）を完了します。自分の CLI を使う場合は、ALTO_FIREBASE_BIN で指定します。

共有リンクを作成する前に、知っておくべきことが 2 つあります。共有リンクはリンクを持つ人なら誰でも閲覧できます。キーを推測することはできませんが、アクセス制御はされていないため、役目を終えたらリンクを無効にしてください。また、メモを同期するためにサインインした閲覧者は、あなたの Firebase プロジェクト内にアカウントを作成します。セキュリティルールにより、アプリを通じてその人のメモを読むことはできませんが、プロジェクトの所有者であるあなたは、Firebase コンソールでメモを見ることができます。

既存の作業を移行する

set_up_site は最後の手順として、ローカルフォルダーにあるものをすべてアカウントにコピーします。手動で行うには（たとえば、別のフォルダーから行う場合）：

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

コピーは行いますが、削除はしません。また、アカウントにすでにあるものはスキップします。

複数のサイトと、自動的に始まるチャット

ユーザーは、利用する Google アカウントごとに Alto サイトを持つことができます。すべてのタイムラインツールでは、任意の account（luke-alto のようなサイト名、そのアドレス、または Google メールアドレス）を指定できます。呼び出し間で情報は記憶されないため、1 つのコネクタプロセスで複数のチャットに対応できます。

• get_interview_guide は、このコンピューターでサインインしているすべてのアカウントと、それぞれにある内容を一覧表示します。そのため、独立して開かれたチャット（タイムラインの Edit timeline ボタンからではないチャット）でも、ユーザーが名前を指定したタイムラインを見つけられます。account="all" を指定して list_projects を呼び出しても、同じことをその場で実行できます。
• connect_account(site) を使うと、ユーザーがすでに持っているサイトを、そのアドレスだけで追加できます。Alto はサイトの公開 Web 設定（/__/firebase/init.json）を読み取り、ユーザーはサイト独自のサインインページで「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/ — 参照ビルドからコンテンツを除いて抽出した、3 つのページテンプレートです。元になった抽出フィクスチャは公開していません。著者自身の文章が含まれているためです。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 サイトにも）保存します。