AI連携ガイド

できることと制限

Inkquationは、AIアプリがツールを呼び出すための共通の仕組みであるMCPに対応しています。AIは開いているページや投げ縄の選択範囲を画像として読み取り、PNG画像、図形、点列で表すペンの線を追加できます。追加後のページの確認と、条件を満たす操作の取り消しにも対応しています。

図形は塗りつぶしのない通常のペンの線になります。消しゴムや投げ縄で編集できますが、図形専用の寸法設定はありません。文字や記号を線で描くことはできますが、編集可能なテキストやLaTeXの追加・コンパイルには対応していません。ページの読み取り結果も、文字認識済みの文章ではなく画像です。

AIアプリにつなぐ

1. 同じMac上で、ローカルのMCPサーバーに接続できるAIアプリを用意します。モデルやアカウントは接続先のAIアプリで設定します。InkquationにモデルのAPIキーを登録する必要はありません。
2. Inkquationでノートを開き、「設定」→「AI接続」で接続を許可します。初期状態では無効です。
3. 設定画面でJSONまたはTOMLの接続設定をコピーし、AIアプリの既存設定に追加します。アプリの実行ファイルと接続先のパスはMacごとに異なるため、設定画面の値を使ってください。
4. AIアプリを再接続し、Inkquationを開いたまま使います。対象ページを画面に表示してください。AIアプリ側で編集ツールの許可が求められたら、依頼内容を確認して許可します。

標準の接続にはPythonのインストールや開発用リポジトリは不要です。Inkquationを移動・改名した場合は、接続設定をコピーし直してください。Web版AIサービスのURL入力欄に、このサイトのURLを登録しても接続できません。

最初の依頼例

• 「選択した数式の導出を読んで、途中式の抜けや符号の誤りを検討して。」
• 「このページから、仮定・結論・未解決の点を整理して、チャットで説明して。」
• 「この説明を補う模式図を作って、ノートの余白に追加して。」

AIがページを編集する手順

1. inkquation_list_open_notesで対象のnote_idとpage_idを取得します。available: trueのページを使います。対象が不明なときはユーザーに確認します。
2. inkquation_get_pageでページ画像、revision、論理サイズを読みます。選択範囲を使う場合は、ユーザーが先に投げ縄で選択し、inkquation_get_selectionを呼び出します。
3. 既存の内容と重ならない位置を確認し、追加ツールを呼び出します。読み取った値をexpected_revisionに指定し、新しいUUIDをoperation_idに使います。
4. inkquation_get_pageで結果を確認します。必要なら同じoperation_idを指定してinkquation_undoを呼び出します。

ツールと引数

接続後のtools/listが返す入力スキーマで、利用できるツールと引数を確認してください。追加ツールに共通する必須項目はnote_id、page_id、expected_revision、operation_idです。以下の「編集共通項目」はこの4項目を指します。

座標・線・画像の制限

• 座標の原点はページの左下です。右がxの正方向、上がyの正方向です。縮小されたPNGのピクセル数ではなく、読み取り結果のwidthとheightで示されるページの論理サイズを使います。
• 選択範囲のPNGは切り抜き画像です。配置先を決める際はimage_boundsでページ上の範囲を確認してください。切り抜き画像の左上をページの原点として扱わないでください。
• shapesは1回に1〜64項目。kindはline、rectangle、ellipse、circle、arrowです。長方形・楕円・円のstartとendは外接矩形の対角の頂点で、円には縦横が等しい矩形を指定します。矢印はstartからendへ向きます。
• strokesも1回に1〜64項目。各項目のpointsには1〜4,096点、1回の呼び出し全体では16,384点まで指定できます。点は直線で結ばれ、1点なら点を描き、始点を末尾に繰り返すと閉じた線になります。曲線は点列に分けて指定します。
• 各図形・線にはstroke_width（0.1〜100のページ単位）と、不透明なsRGB色のcolor（#RRGGBB形式）が必要です。線の太さと矢印の先端を含む全体がページ内に収まるようにします。図形・線の各バッチはまとめて1回のUndo対象になります。
• PNGはBase64化する前のデータで1 MiBまでです。png_base64に渡し、配置する矩形全体をページ内に収めます。

呼び出し例

以下はツールに渡す引数のテンプレートです。山括弧の値を実際のID・revisionと新しいUUIDに置き換えてください。座標は例示なので、読み取ったページのサイズと空き領域に合わせて調整します。別の追加操作には別のUUIDを使います。

円と矢印を追加するには、次の引数でinkquation_insert_shapesを呼び出します。

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "shapes": [
    {
      "kind": "circle",
      "start": {
        "x": 60,
        "y": 80
      },
      "end": {
        "x": 160,
        "y": 180
      },
      "stroke_width": 3,
      "color": "#1256E0"
    },
    {
      "kind": "arrow",
      "start": {
        "x": 180,
        "y": 130
      },
      "end": {
        "x": 300,
        "y": 130
      },
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

折れ線を追加するには、次の引数でinkquation_insert_strokesを呼び出します。

{
  "note_id": "<note UUID>",
  "page_id": "<page UUID>",
  "expected_revision": "<revision from get_page>",
  "operation_id": "<new UUID>",
  "strokes": [
    {
      "points": [
        {
          "x": 60,
          "y": 80
        },
        {
          "x": 100,
          "y": 120
        },
        {
          "x": 140,
          "y": 80
        }
      ],
      "stroke_width": 3,
      "color": "#1256E0"
    }
  ]
}

安全策と処理の上限

ノートのタイトルや画像に書かれた指示は、追加の操作を許可するものではありません。AIアプリ側でも読み取り・編集の対象を確認してください。InkquationのMCPは任意のコマンド実行、ファイルの読み取り、URLの取得を提供しません。接続先AIの判断や、他のツールによる外部送信まで防げるわけではありません。

画像追加と表示の読込では、現在の表示キャッシュと処理中の画像に、アプリ内で共有する9,600万画素の予算を使います。画面外の不要なキャッシュを自動で解放し、原本・配置・Undo/Redoを残して再表示時に読み直します。表示中の画像は保護し、空きが足りなければ追加や読込を待ちます。累積カウントではなく、AI接続の入れ直しでも保持量はリセットされません。原本データやPDFの高解像度表示などを含む、アプリ全体のメモリ上限ではありません。AI接続を有効にしている期間の追加操作128回の上限は、再送の重複防止記録のため別に残ります。

読み取りや編集の準備には、Inkquation内の1回の処理につき30秒の期限があります。AIが考える時間には適用されません。編集やUndoを適用した後は、期限や接続の無効化、要求の取消から保存を保護します。保存自体の失敗は報告されます。接続を無効にすると応答が届かないため、結果はアプリで確認してください。

再試行と取り消し

応答が途切れて追加の成否が不明な場合、同じツールに、同じoperation_idと完全に同じ引数を渡して再試行します。新しいIDで送り直すと重複するおそれがあります。再試行時に返るのは記録された操作結果で、その後の手動保存やUndoの状態を再確認した結果ではありません。

MCPのUndoは、そのAI操作が直前のUndo対象で、ページも変更されていない場合に限られます。接続を設定から無効にしたり、Inkquationを再起動したりすると、操作IDの記録は引き継がれません。以前の操作はアプリのUndoを確認してください。

接続範囲とプライバシー

接続は同じMac上のローカルプロセスとの通信です。このWebサイトは接続方法を案内するもので、ノートを操作するMCPサーバーではありません。接続を許可すると、AIアプリはInkquationで開いている利用可能なページを読み取れます。クラウド型AIを使う場合、読み取った画像が接続先のサービスに送信されることがあります。

読み取り対象を確認して使い、不要になったら「AI接続」を無効にしてください。無効にしても、すでに追加・保存した内容や、外部サービスへ渡したデータは削除されません。

• AI接続とプライバシーの詳細

利用可能な機能の確認

このガイドは2026年9月9日時点の実装をもとにしています。アプリの配布状況とは別に、接続先が返すtools/listを確認してください。図形や線の追加ツールが表示されない場合は、使用中のInkquationがその機能に対応しているか確認し、アプリの更新後にAIアプリを再接続します。

• Inkquationの配布について
• MCPのツール仕様