flc1125/mote

Mote — Markdown を入れれば URL が出てくる

Mote は Markdown を不変・列挙不可能・ブラウザで読み取り可能なオンラインページとして公開し、URL を返します。このスキルは、いつどのように Mote を使用するかのみをガイドします。公開プロトコルは CLI / MCP 実装が行うものであり、アップロードロジックを自分で実装してはいけません。

いつ使用するか

以下の意図のいずれかに合致する場合に Mote を使用します。

• 「この Markdown / レポート / ドキュメントを共有したい」「Web ページ / リンクにしてほしい」
• 設計ドキュメント、調査資料、会議録、README をオンラインリンクにするよう明示的に要求された
• あなたが生成したレポートや分析結果を Web ページとして公開するよう要求された

Markdown を読む、編集する、ローカルブラウザでプレビューするだけの場合は、Mote に公開しません。

使用してはいけない場合:

• コンテンツにパスワード、API キー、秘密鍵などの認証情報や企業秘密が含まれている場合 — Mote の URL がアクセス認証情報となります。リンクを知っていれば誰でも読むことができ、現在ユーザー側からの削除エントリは提供されていません。
• 公開済みのコンテンツを修正する必要がある場合 — Mote のドキュメントは不変です。内容を変更するには再公開して新しい URL を取得する必要があります。

公開方法

まずローカル画像が参照されているか確認し、設定済みのツールに応じてパスを選択します。ユーザーが指定したインスタンスを尊重します。既にセルフホストの設定がある場合は、パブリックインスタンス https://mote.pub に強制的に切り替えません。

パス A: MCP ツール（mote MCP サーバーが接続されている場合）

• コンテンツが会話内にあり、ローカル画像がない場合 → publish_markdown を呼び出し、markdown（オプションで name、例：report.md）を渡します。ローカルおよびリモートのこのツールはローカル画像を収集せず、リモート画像の URL のみを保持します。
• ローカル Markdown ファイルの場合 → ローカルの stdio のみが publish_markdown_file を提供し、path を渡します（ローカル画像は自動アップロードされ、内容に基づいて重複排除されます）。リモートでは publish_markdown のみが利用可能であり、ローカルファイルや画像が必要な場合は設定済みの CLI を使用し、パスをリモートツールに渡しません。

パス B: CLI（インストール済みで認証が設定されている場合に利用可能）

1. 既存のファイルをそのまま公開します。会話内容にローカル画像がない場合は、一時ファイルに書き込めます。ローカル画像がある場合は、Markdown と必要な画像を相対パス関係を保った一時ディレクトリに配置してから、CLI またはローカルの publish_markdown_file で公開します。画像は Markdown ファイルがあるディレクトリからの相対パスで解決され、ターミナルのカレントディレクトリからの相対パスではありません。Markdown だけを /tmp に移動しないでください。
2. 実行:

mote <file.md> --json

3. stdout の JSON を解析: { "id": "...", "url": "..." }

CLI は自動的に Markdown および対応する HTML 内のローカル画像参照、パス検証、アップロード、内容の重複排除を処理します。リモート画像は元の URL を保持し、ダウンロードやパッケージ化はされません。画像のみがドキュメントとともにアップロードされ、他のローカル Markdown ファイルへのリンクは自動的に対象ファイルを公開しません。

コンテンツ互換性

• 標準的な Markdown、テーブル、タスクリスト、脚注、GitHub スタイルの Alerts、および言語指定可能なコードハイライトをサポートします。
• 数式には TeX のサブセットをサポート。mermaid コードブロックは6種類の静的チャートのサブセットをサポートし、1記事あたり最大4つのチャートをレンダリングします。無効、非サポート、または予算超過のコンテンツはソースコードとして表示される場合があり、公開が成功したからといってすべての拡張構文がレンダリングされるわけではありません。
• HTML は安全なサブセットのみ許可され、スクリプト、MDX、インタラクティブな埋め込みは実行されません。生の SVG のアップロードや直接埋め込みはサポートされていません。Mote が生成するチャートの SVG は個別にサニタイズされており、表示可能です。
• 複雑な数式やチャートを公開した後は、実際のページの数式、線、ラベル、画像を確認してください。確認なしにレンダリング効果が検証されたと主張しないでください。

詳細な構文や制限については、互換性ドキュメント および オンラインサンプル を参照してください。セルフホストインスタンスのサポート範囲はデプロイバージョンによって異なります。

返された URL の扱い方

• URL をそのままユーザーに返します。切り詰めたり、書き換えたりしないでください。
• 「公開しました: 」のように一言添えるだけで十分です。
• ページには検索エンジンのインデックスを禁止する指示が設定されていますが、これはアクセス制御や絶対に収集されないという保証ではありません。アクセス可能性はインスタンスとストレージの継続的な運用に依存します。
• ユーザーが後で「このページを更新して」と依頼した場合: 保存された Markdown とアップロードされたアセットは不変であり、再公開すると新しい URL が取得されることを説明します。ビューアーの更新により表示効果が変わる可能性があり、リモート画像は元のサイトに依存します。

制限（公開前の自己チェック）

• Markdown ≤ 2 MiB、単一画像 ≤ 10 MiB、アップロードアセット ≤ 50、パッケージ全体 ≤ 20 MiB。1 MiB = 1,048,576 バイト。CLI は内容の重複排除後にカウントし、リモート画像はカウントされません。
• 画像形式: png / jpeg / webp / gif / avif（SVG は非サポート）
• 制限を超えた場合は、どの項目が制限を超えたかをユーザーに正直に伝え、自分で内容を削減しないでください。

よくあるエラー

• ログイン期限切れ: ユーザーを同じインスタンスでインタラクティブログインに導いてください。ユーザーがログイン補助を明示的に要求した場合にのみ、許可された範囲内で続行します。公開失敗を理由にブラウザログインを独自に開始したり、他のクライアントの認証情報を読み取ったり、古いトークンに戻したりしないでください。詳細は認証ドキュメントを参照してください。
• no publish token configured: インスタンスの認証モードを確認してください。静的モードではインスタンス管理者がトークンを提供する必要があります。Access インスタンスでは OAuth ログインまたは明示的なマシンモードが必要であり、Cloudflare 管理 API トークンを公開キーとして使用してはいけません。自分で認証情報を生成しないでください。
• マシンモード: MOTE_AUTH_MODE=service および、それに対応する MOTE_SERVICE_API_URL、MOTE_SERVICE_CLIENT_ID、MOTE_SERVICE_CLIENT_SECRET が明示的に必要です。欠落または無効な場合は停止し、ユーザーログイン状態で代用しないでください。
• タイムアウト、5xx、または結果不明: 自動的に公開を再試行しないでください。不変のドキュメントが既に生成されている可能性があります。まず結果を確認し、ユーザーが再公開するかどうかを決定します。
• asset not found: <path>: Markdown が参照するローカル画像が存在しません。ユーザーに相対パスを確認するよう促してください。
• unsupported image type: SVG などの非サポート形式が参照されています。ユーザーに png または webp に変換してから再試行するよう提案してください。