MCP ツールリファレンス

VMark は AI アシスタントに 7 つの複合 MCP ツール を公開します：session、workspace、document、workflow、selection、browser、coherence。これらは合わせて、エディタの読み書きのバックボーン、ファイル／ウィンドウのライフサイクル、CST セーフなワークフロー編集、選択範囲を対象とするピンポイント編集、制限付きのブラウザナビゲーション、そしてワークスペース整合性レイヤーの読み取り専用ビューをカバーします。

以前の 12 ツール／76 アクションのサーフェスは整理されました — ドキュメント内のフォーマットツール（太字、見出し、テーブルなど）は、AI エージェントがすでに Markdown のラウンドトリップで簡単にこなせる作業を重複していたためです。完全な根拠は MCP プルーニングプランを参照してください。

推奨ワークフロー

session.get_state を 1 回呼び出して、開いているウィンドウ、タブ、タブごとの {filePath, dirty, revision, kind} を確認します。
Markdown の場合：document.read → 推論 → document.write（安全な並行性のために expected_revision を渡す）。
GitHub Actions YAML（kind: "yaml-workflow"）の場合：コメントとアンカーを保持する CST セーフな編集には workflow.apply_patch、actionlint 診断には workflow.validate。
ファイル操作（開く、保存、閉じる、タブ切り替え）は workspace にあります。

Mermaid ダイアグラム

MCP 経由で AI を使用して Mermaid を生成する場合は、mermaid-validator MCP サーバーのインストールを検討してください — ダイアグラムがドキュメントに到達する前に、同じ Mermaid v11 パーサーで構文エラーをキャッチします。

`session`

ワンショットの状況把握。1 回の呼び出しですべてのウィンドウ、すべてのタブ、サーバーの機能を発見します。

`get_state`

引数なし。

返り値 {windows, capabilities}：

json

{
  "windows": [
    {
      "label": "main",
      "focused": true,
      "tabs": [
        {
          "id": "tab-1",
          "filePath": "/path/to/notes.md",
          "title": "notes",
          "dirty": false,
          "revision": "<revision-token>",
          "kind": "markdown"
        },
        {
          "id": "tab-2",
          "filePath": "/repo/.github/workflows/ci.yml",
          "title": "ci",
          "dirty": true,
          "revision": "<revision-token>",
          "kind": "yaml-workflow"
        }
      ]
    }
  ],
  "capabilities": {
    "version": "<vmark-mcp-server version>",
    "supportedKinds": ["markdown", "yaml-workflow"],
    "mcpProtocol": "<mcp-protocol-version>"
  }
}

kind の判別子は、そのタブで document.write（markdown 用）と workflow.apply_patch（yaml-workflow 用）のどちらを使うべきかを示します。

`workspace`

ファイルとウィンドウのライフサイクル。ドキュメント内のことは扱いません。

`new`

新しい無題のタブを作成します。

パラメーター	タイプ	必須	説明
`kind`	string	いいえ	`"markdown"`（デフォルト）または `"yaml-workflow"`
`windowLabel`	string	いいえ	対象ウィンドウ；デフォルトはフォーカス中

{tabId} を返します。

`open`

ディスクからファイルを開きます。

パラメーター	タイプ	必須
`filePath`	string	はい
`windowLabel`	string	いいえ

{tabId} を返します。

`save`

タブを既存のパスに保存します。

パラメーター	タイプ	必須
`tabId`	string	いいえ（デフォルトはフォーカス中のタブ）

{filePath, revision} を返します。

`save_as`

タブを新しいパスに保存します。

パラメーター	タイプ	必須
`tabId`	string	いいえ
`filePath`	string	はい

{revision} を返します。

`close`

タブを閉じます。force なしで未保存の作業を破棄することを拒否します。

パラメーター	タイプ	必須
`tabId`	string	はい
`force`	boolean	いいえ

成功時は {closed: true}、タブがダーティで force が指定されていない場合は {closed: false, reason: "DIRTY"} を返します。

`switch_tab`

タブをアクティブにします。

パラメーター	タイプ	必須
`tabId`	string	はい

`focus_window`

ウィンドウにフォーカスします。

パラメーター	タイプ	必須
`windowLabel`	string	はい

`document`

読み取り、書き込み、変換。サーフェスのバックボーンです。

`read`

パラメーター	タイプ	必須
`tabId`	string	いいえ（デフォルトはフォーカス中のタブ）

{content, revision, filePath, kind, dirty} を返します。書き込み前には必ず読み取ります — revision トークンは次の write に同伴される必要があります。

`write`

ドキュメント全体のコンテンツを置き換えます。

パラメーター	タイプ	必須	説明
`tabId`	string	いいえ	対象タブ（デフォルトはフォーカス中）
`content`	string	はい	新しい全コンテンツ
`expected_revision`	string	いいえ	直近の読み取りからのリビジョントークン

expected_revision が指定されていてその読み取り以降にドキュメントが変更されている場合、レスポンスは現在のリビジョンを含む STALE 構造化エラーエンベロープになります；再読み取りしてリトライしてください。

json

// 成功
{ "revision": "<new-revision-after-write>" }

// stale
{ "error": "STALE", "message": "Document has changed since the last read", "current_revision": "<current-revision>" }

`transform`

決定的な書き換えを適用します。現在は CJK 固有の変換（全角 ↔ ASCII 句読点変換、CJK ↔ ラテン間のスペース調整）をサポートします。

パラメーター	タイプ	必須	説明
`tabId`	string	いいえ	対象タブ
`kind`	string	はい	`"cjk-format"`、`"cjk-spacing"`、または `"cjk-punctuation"`
`expected_revision`	string	いいえ	並行制御トークン

cjk-format はユーザーの CJK フォーマット設定をエンドツーエンドで適用します。cjk-spacing は CJK 文字と隣接するラテン／数字の間に単一スペースを挿入します。cjk-punctuation は CJK 文字に隣接する ASCII 句読点を全角形式に変換します。

{revision} を返します。

`workflow`

GitHub Actions ワークフロー YAML 用の actionlint 検証と CST セーフな外科的編集。kind が "yaml-workflow" のタブでのみ利用可能です。

document.read ／ document.write はすべてのタブで動作 — ワークフロー YAML を含む

workflow ツールは読み書きのバックボーンの代替では ありません。ワークフロータブでは以下が可能です：

document.read で生の YAML テキスト（すべてのコメント付き）を取得
document.write で全体を置き換え（送信した文字列はそのまま保存される — コメントを含めれば保持される）
部分的な編集でコメント、アンカー、キー順が確実に保持されることを サーバー自身に保証 させたい場合は workflow.apply_patch

1 つのフィールドを変更しつつ他はそのままにしたい場合は apply_patch を使ってください（サーバーは変更しないコメントを落とすことができません）。全体を書き直したり、新しいワークフローをゼロから生成したりする場合は document.write を使ってください。

`apply_patch`

IRPatch オブジェクトの配列を適用します。パッチは VMark の CST 認識ミューテーターを通じてディスパッチされ、コメント、アンカー、キー順を保持します。YAML ファイルへの生の document.write ではこれらが失われます。

パラメーター	タイプ	必須
`tabId`	string	いいえ
`patches`	IRPatch[]	はい
`expected_revision`	string	いいえ

IRPatch は判別共用体（kind フィールド）です。サポートされる種類：

`kind`	効果
`workflow.set`	トップレベルフィールドを設定（`{path, value}`）— `name`、`env.X` など
`job.set`	ジョブ上のフィールドを設定（`{jobId, path, value}`）
`step.set`	ステップ上のフィールドを設定（`{jobId, stepIndex, path, value}`）
`with.set`	ステップの `with:` ブロック内のキーを設定（`{jobId, stepIndex, key, value}`）
`with.remove`	ステップの `with:` ブロックからキーを削除
`needs.add` ／ `needs.remove`	`needs:` からジョブ ID を追加または削除
`trigger.setFilters`	トリガーのフィルター配列を置き換え — branches、paths、types など（`{event, filter, value: string[]}`）

成功時は {revision}、失敗時は構造化された STALE ／ INVALID_PATCH ／ NOT_WORKFLOW エラーエンベロープを返します。

`validate`

ワークフロー YAML に対して actionlint を実行します。

パラメーター	タイプ	必須
`tabId`	string	いいえ

{ok, diagnostics, binaryAvailable} を返します。各診断は {line, col, message, severity} を持ちます。binaryAvailable: false は actionlint がローカルにインストールされていないことを意味します；Homebrew または上流のリリースからインストールしてください。

`coherence`

ワークスペース整合性レイヤーの読み取り専用ビュー — どの派生ドキュメントが、その生成元となった上流に対して古くなっているかを示します。どちらのアクションもドキュメント、台帳、エディタ状態を一切変更しません；両方とも Rust バックエンドがワークスペースごとのカーネルから直接応答するため、エディタウィンドウが前面になくても動作します。

さらに 2 つの読み取り専用アクションがセマンティックレイヤーを公開します：

claims — 現在のカノン設定：{claim, entryId, statement, maturity, invalidAt, visible}。セマンティックチェックの制約になるのは established の設定だけです。visible はデフォルトコンテキストを反映します。
contexts — コンテキストの集合（暗黙の default は常に存在します）：{id, name, parent, enforcement, visibleClaims, errors}。

変更を伴うアクションが 1 つ、委任によってゲートされます：

resolve — 明示的に委任されたエージェントとして、活きている古くなったエッジを解決します：{workspace_root, txf, input, resolution: "accept-newer" | "waive", reason? (required for waive)}。認可は fail-closed です：ワークスペースの所有者が 認証済みのブリッジ ID に対して、その解決の種類をカバーする有効で失効していない委任を（アプリ内で、内訳から）付与している必要があり、かつエッジが活きていなければなりません。委任による解決はすべて、その付与に紐づけて監査ログに記録されます。設定とコンテキストの変更が公開されることは決してありません — カノンは人間の管理下にとどまります。

すべてのアクションで workspace_root（照会するワークスペースの絶対パス）が必要です。session.get_state（開いているタブの filePath）または workspace ツールから取得できます。パスが欠落している、絶対パスでない、またはディレクトリでない場合は、平文の文字列エラーで拒否されます。

`status`

1 つのワークスペースのカーネル状態カウンター。

パラメーター	タイプ	必須	説明
`workspace_root`	string	はい	照会するワークスペースの絶対パス

返り値：

json

{
  "initialized": true,
  "objects": 12,
  "open_items": 2,
  "quarantined": 0,
  "writer": "0198c0de-0000-7000-8000-000000000001"
}

フィールド	意味
`initialized`	ワークスペースにまだ整合性台帳がない（`.vmark/` ディレクトリがない）場合は `false`。その場合、`objects` 以外のカウンターはすべて 0 です。
`objects`	追跡中のオブジェクト（整合性 ID を持つファイル）。
`open_items`	現存する非フレッシュなエッジ — 現在の内訳の件数。
`quarantined`	直近の読み取りで隔離された不正な台帳行。
`writer`	このインストールのライター ID（UUID）。

`edges`

内訳そのもの：上流が動いたすべての現存依存エッジ。先にスキャンと照合を実行するため、結果は呼び出し時点のディスク上のファイルを反映します。

パラメーター	タイプ	必須	説明
`workspace_root`	string	はい	照会するワークスペースの絶対パス

返り値は配列 — すべて整合している場合は空です：

json

[
  {
    "txf": "0198c0de-0000-7000-8000-00000000000a",
    "input": 0,
    "upstream": "0198c0de-0000-7000-8000-00000000000b",
    "upstream_path": "characters/elena.md",
    "pinned": "rev-a1b2c3",
    "downstream": "0198c0de-0000-7000-8000-00000000000c",
    "downstream_path": "scenes/chapter-3.md",
    "downstream_rev": "rev-d4e5f6",
    "state": "version-stale"
  }
]

フィールド	意味
`txf` ／ `input`	このエッジを識別する変換エントリと入力スロット（アプリ内の解決アクションに渡します）。
`upstream` ／ `upstream_path`	下流が依存するオブジェクトと、その最後に確認されたパス。
`pinned`	下流の生成元となった上流のリビジョン。
`downstream` ／ `downstream_path` ／ `downstream_rev`	派生オブジェクト、そのパス、および現在のリビジョン。
`state`	`"version-stale"`、`"stale-valid"`、`"stale-contradicted"`、`"stale-unknown"`、`"waived"`、`"diverged"`、`"diverged-multi-head"`、または `"unpinnable"`。

エッジの解決（新しい版の受け入れ／免除）は、VMark の内訳ビューで人間が行う操作です — 意図的に MCP には公開されていません。

エラー

2 種類のエラー形状が現れます：

ドメインエラー — success: false を設定し、JSON エンコードされたエンベロープを error で返します：

json

{ "error": "STALE", "message": "...", "current_revision": "<current-revision>" }

引数形状エラー — 必須引数の不足／不正（例: content フィールドなしの document.write）の場合、error は問題を説明する平文の文字列です。構造化エンベロープはドメインレベルの条件のために予約されています。

コード	表面化形式	意味
`STALE`	エンベロープ	`expected_revision` が一致しなかった；再読み取りしてリトライ
`INVALID_PATCH`	エンベロープ	`workflow.apply_patch` が不正な `patches` 配列を受信
`INVALID_TAB`	エンベロープ	`tabId` を解決できなかった
`INVALID_PATH`	エンベロープ	`workspace.open` が読み取れない `filePath` を受信
`NOT_WORKFLOW`	エンベロープ	非 YAML ワークフロータブで `workflow.*` が呼ばれた
`READ_ONLY`	エンベロープ	読み取り専用ドキュメントへのミューテーションが試行された
`INTERNAL`	エンベロープ	ハンドラーで予期しないエラー
（平文文字列）	文字列	必須引数の欠落または型違い

MCP ツールリファレンス ​

session ​

get_state ​

workspace ​

new ​

open ​

save ​

save_as ​

close ​

switch_tab ​

focus_window ​

document ​

read ​

write ​

transform ​

workflow ​

apply_patch ​

validate ​

coherence ​

status ​

edges ​

エラー ​

MCP ツールリファレンス

`session`

`get_state`

`workspace`

`new`

`open`

`save`

`save_as`

`close`

`switch_tab`

`focus_window`

`document`

`read`

`write`

`transform`

`workflow`

`apply_patch`

`validate`

`coherence`

`status`

`edges`

エラー