Local YDB MCP

@astandrik/local-ydb-mcp

Docker ベースの local-ydb デプロイメントを操作するための、非公式の stdio MCP サーバーです。

ウェブサイト：local-ydb-toolkit.ydb-qdrant.tech。

ydb/ydb-mcp との関係

このパッケージは、公式の ydb-platform/ydb-mcp サーバーを補完するものです。既存の YDB エンドポイントに対するアドホック SQL クエリ、クエリの説明、ディレクトリ一覧、パスの検査など、一般的な YDB データベースレベルのツールには ydb/ydb-mcp を使用してください。

エージェントが Docker ベースの local-ydb 環境そのものを操作する必要がある場合は、@astandrik/local-ydb-mcp を使用してください。ホストの前提条件チェック、ルートまたはテナントのブートストラップ、データベースのヘルスチェック診断、動的ノードのライフサイクル管理、GraphShard チェック、ローカルデプロイメント向けのテーブル DDL 生成／検証／適用、認証の強化、ストレージのワークフロー、ダンプ／復元、バージョンアップグレードに対応します。このパッケージの local_ydb_sql ツールは、意図的に ydb/ydb-mcp より対象を限定しており、選択した設定済みの local-ydb プロファイルに対してのみ、管理対象の YQL を実行します。変更を行うツールは、計画を先に提示し、変更を実行する前に confirm: true を必須とします。

MCP クライアントの設定

このパッケージには Node.js 20.19 以降が必要です。

MCP サーバーを起動せずに、インストール済みの CLI を確認します。

local-ydb-mcp --version
local-ydb-mcp --help

または、npm 経由で同じコマンドを実行します。

npx --yes @astandrik/local-ydb-mcp@latest --version
npx --yes @astandrik/local-ydb-mcp@latest --help

各フラグは標準出力に表示され、ツールキットの設定を読み込まずにコード 0 で終了します。 不明な引数、繰り返されたフラグ、フラグの組み合わせが指定された場合は、標準エラー出力に使用方法のエラーを表示してコード 2 で終了します。サポートされているのは、長形式の --version フラグと --help フラグのみです。 通常の MCP stdio 動作では、引数なしで起動してください。MCP クライアントの起動設定に、これらの診断用フラグを追加しないでください。

クライアントが手動でリポジトリをチェックアウトせずにサーバーを実行できるよう、npx を使用します。

{
  "mcpServers": {
    "local-ydb": {
      "command": "npx",
      "args": ["-y", "--prefer-online", "@astandrik/local-ydb-mcp@latest"],
      "env": {
        "LOCAL_YDB_TOOLKIT_CONFIG": "/path/to/local-ydb.config.json"
      }
    }
  }
}

この形式では、MCP サーバーの起動時に npm レジストリを確認するため、MCP クライアントを再起動すると、新たに公開されたバージョンがクライアントに適用されます。

設定ファイルは省略可能です。LOCAL_YDB_TOOLKIT_CONFIG が設定されていない場合、サーバーは現在の作業ディレクトリから local-ydb.config.json を読み込みます。環境変数が存在していても値が空の場合は明示的な指定として扱われ、CONFIG_PATH_NOT_ABSOLUTE が返されます。暗黙的に参照されるファイルが存在しない場合、サーバーは ghcr.io/ydb-platform/local-ydb:stable-26-1-1 を使用するデフォルトのローカルプロファイルを使用します。LOCAL_YDB_TOOLKIT_CONFIG と呼び出しごとの configPath の値は絶対パスであり、1 MiB 以下の読み取り可能な通常の JSON ファイルを指定する必要があります。設定された defaultProfile は、既存の profiles エントリを指定する必要があります。明示的に指定されたファイルが存在しない、読み取れない、サイズが上限を超えている、形式が不正、またはスキーマが無効な場合、サーバーは処理を拒否し、ファイルの内容、パーサーの抜粋、絶対パスを公開することなく、安定したエラーコードを返します。

名前付きのアップストリームデフォルトタグは変更される可能性があります。アップグレードを制御するには、profiles.<name>.image を明示的に設定してください。不変のイメージを取得する場合はダイジェストを使用できますが、local_ydb_upgrade_version はダイジェストで固定されたソースプロファイルを受け付けない点に注意してください。

パッケージ更新によって暗黙のデフォルトが変更されると、以前のデフォルトで作成された既存のスタックは、YDB イメージが混在するのを防ぐため、プロファイル互換性チェックに失敗します。再起動またはブートストラップの前に、スタックの現在のイメージ参照をファイルベースのプロファイルに追加し、意図的にダンプと再構築を行うアップグレードには local_ydb_upgrade_version を使用してください。

公式 MCP Registry のメタデータでは io.github.astandrik/local-ydb-mcp という名前を使用します。一致する npm バージョンの公開後、リポジトリルートにある server.json から公開されます。

MCP の機能

このサーバーは、local-ydb 操作用のツールと静的な MCP プロンプトを公開します。プロンプトテンプレートは、スタックの診断、ルートデータベースのブートストラップ、テナントトポロジーのブートストラップ、データベースの診断、スキーマの生成と適用、バージョンアップグレード、認証の強化、ストレージグループの削減を案内します。プロンプトはワークフローの指示のみを返し、コマンドは実行しません。プロンプトの configPath を指定する場合は、対応するツール引数と同様に、絶対パスで指定する必要があります。

変更を伴うツールは、confirm: true を指定して呼び出さない限り、プランのみを返します。

ツール

このサーバーは 39 個のツールを公開します。この一覧は実行時のツールレジストリから生成されます。更新するには、toolDefinitions を編集して npm run docs:generate を実行してください。

チェック

ツール	モード	説明
local_ydb_inventory	読み取り専用	local-ydb ターゲットプロファイルの Docker インベントリを読み取り専用で取得します。成功すると、ok=true、Docker CLI／デーモンの状態、コンテナ、ボリューム、および実際に存在する設定済みコンテナの inspect データを返します。Docker CLI、デーモン、またはインベントリの取得に失敗すると、理由とともに ok=false を返し、ホストが空であると誤認されないようインベントリ配列は省略されます。SSH ターゲットまたはプローブに失敗した場合は、保守的な Docker 可用性フラグとともに docker-inventory-failed を使用します。
local_ydb_database_status	読み取り専用	設定済みテナントパスの YDB 管理データベース状態を読み取り専用で取得します。コマンド、stdout、stderr、ok フラグを返します。ブートストラップ／再起動のトラブルシューティング前にテナントの状態を確認する際に使用し、スキームへの到達性確認には local_ydb_tenant_check を使用します。
local_ydb_healthcheck	読み取り専用	設定済みテナントまたはルートデータベースの YDB モニタリングヘルスチェックを読み取り専用で実行します。公式 YDB CLI の SelfCheck パスを使用し、selfCheckResult、問題の件数、問題の種類、上限付きの生出力、およびデータベースが正常かどうかを返します。要求した noCache／noMerge オプションが、認識済みの正確な 2 行のレガシーパーサーシグネチャによって拒否された場合は、optionResolution と warnings で報告され、compatibilityFallback は再試行が実際に開始されたかどうかを示します。データベースレベルの診断には local_ydb_status_report の後に使用します。
local_ydb_container_logs	読み取り専用	設定済みの静的またはプライマリ動的 local-ydb コンテナから、最近の Docker ログを読み取ります。ブートストラップ、再起動、または準備状態の確認に失敗した場合に使用します。target はコンテナの役割を選択し、lines は末尾から取得する行数を指定します。
local_ydb_status_report	読み取り専用	迅速な診断のための読み取り専用集約レポートです。local_ydb_inventory、local_ydb_auth_check、local_ydb_tenant_check、local_ydb_nodes_check、local_ydb_healthcheck を実行し、それぞれの結果を返します。各コンポーネントは分離されているため、予期しない失敗が発生しても安全なコンポーネント形式のフォールバックを返し、残りのチェックは続行されます。
local_ydb_tenant_check	読み取り専用	YDB CLI を使用して、設定済みテナントパスに到達できることを確認する読み取り専用チェックです。ブートストラップまたは復元の後、ノードや GraphShard をチェックする前にテナントメタデータを確認するために使用します。
local_ydb_scheme	読み取り専用	stdout／stderr に上限を設けた、読み取り専用の YDB スキーム一覧表示または詳細表示です。rootDatabase パスではルートデータベースを、それ以外ではテナントデータベースを使用します。一覧表示では recursive／long／onePerLine フラグをサポートし、詳細表示では stats をサポートします。互換性のないフラグの組み合わせは拒否されます。
local_ydb_nodes_check	読み取り専用	viewer/json nodelist を通じて動的ノードの登録状態を確認する読み取り専用チェックです。動的ノードの起動、追加、または削除の後に使用します。テナントへの到達性が不明な場合は、先に local_ydb_tenant_check を使用してください。
local_ydb_graphshard_check	読み取り専用	設定済みテナントに対して、viewer/json capabilities と tabletinfo を通じて GraphShard を確認する読み取り専用チェックです。graphShardExists、tablet ID、viewer の状態詳細を返します。テナントのブートストラップ後、GraphShard のサポートやタブレットの可視性が具体的な確認事項である場合に使用します。
local_ydb_auth_check	読み取り専用	匿名 viewer の whoami 状態と、設定済み YDB CLI のテナントアクセスを確認する読み取り専用の認証監査です。rootPasswordFile が設定されている場合は、ルート認証情報を使用します。認証の強化やパスワードのローテーション後に、想定どおりの状態であることを確認するために使用します。
local_ydb_storage_placement	読み取り専用	ReadStoragePool の出力と BSC の物理配置を返す読み取り専用のストレージ検査です。ストレージグループの追加または削減前に、正確なプール構成を確認するために使用します。
local_ydb_storage_leftovers	読み取り専用	local-ydb の残存候補である Docker ボリューム、ダンプ、PDisk／データパスを読み取り専用で検索します。Docker ボリューム名と profile.storageSearchPaths をスキャンし、削除は行いません。削除するパスやボリュームを特定するため、local_ydb_cleanup_storage の前に使用します。
local_ydb_list_versions	読み取り専用	local-ydb コンテナイメージについて、公開されている GHCR または Docker Hub のタグを一覧表示し、数値バージョンタグを新しい順に並べます。local_ydb_upgrade_version の前に使用します。レジストリのページネーションと認証は信頼できるオリジンに制限され、pageSize と maxPages によりページネーションの上限が設定されます。
local_ydb_pull_status	読み取り専用	local_ydb_pull_image によって開始されたバックグラウンドの Docker イメージ取得状況を確認します。既知のジョブでは、バイト数ではなく完了した既知の Docker レイヤーに基づく単調増加の progressPercent を返します。実行中は 0～99、正常に完了すると 100、失敗時は最後に観測された値になります。

スキーマ

ツール	モード	説明
local_ydb_generate_schema	読み取り専用	読み取り専用の構造化 YDB テーブル DDL 生成ツールです。CREATE TABLE、ALTER TABLE、DROP TABLE、セカンダリインデックス用の厳密な JSON 仕様を生成し、公式リファレンスと警告を含む生成スクリプトを返します。また、変更を適用せずに YDB JS SDK を通じて検証することもできます。
local_ydb_apply_schema	計画優先の変更	公式 YDB JS SDK を通じて YDB テーブル DDL を検証または適用します。PRAGMA と CREATE TABLE、ALTER TABLE、DROP TABLE の生の YQL DDL を受け付けます。action=apply は先に検証を行い、confirm=true の場合にのみ実行します。

SQL

ツール	モード	説明
local_ydb_sql	計画優先の変更	Query Service を通じて、設定済みの local-ydb ターゲットに対してマネージド YQL v1 を実行します。query は SnapshotRO を使用し、explain はプラン／AST を返します。execute は必ず先に EXPLAIN を実行し、confirm=true の場合にのみ NoTx 実行を 1 回送信します。

認証

ツール	モード	説明
local_ydb_permissions	計画優先の変更	パスの YDB スキーム権限を確認または変更します。デフォルトの list アクションは読み取り専用です。grant、revoke、set、clear、chown、および継承の変更は、confirm=true でない限りプランを返します。
local_ydb_prepare_auth_config	計画優先の変更	現在の静的ノード設定から、セキュリティを強化した YDB 設定を生成します。local_ydb_write_dynamic_auth_config と local_ydb_apply_auth_hardening の前に使用してください。confirm=true でない場合は、予定されている書き込みのみを返します。
local_ydb_write_dynamic_auth_config	計画優先の変更	認証必須の起動に必要な、text-proto 形式の動的ノード認証トークンファイルを書き込みます。認証強化に使用する SID を選択した後に使用してください。confirm=true でない場合は、予定されているファイル書き込みのみを返します。
local_ydb_apply_auth_hardening	計画優先の変更	設定やコンテナを変更する前に、チェックのみの静的プロファイル全体と、設定済みバインディングとの互換性の事前確認が成功した場合に限り、レビュー済みの強化済み YDB 設定ファイルを適用します。変更不可能な不整合がある場合は、破棄してからブートストラップする必要があります。その後、静的ノードを再起動し、設定済みのすべての動的ノードをインデックス順に再作成して検証します。動的ノードのトークンファイルが設定されていない場合も同様です。メタデータ検証の前に、コンテナの稼働状態が安定していることと IC 登録の両方を確認する必要があります。ロールバックでは、静的設定を復元した後、再起動またはブートストラップによる整合性調整を行います。設定を準備してレビューした後にのみ使用してください。confirm=true でない場合は、事前確認／適用／再作成のプランのみを返します。
local_ydb_set_root_password	計画優先の変更	ALTER USER で実行時の root パスワードを変更し、ホストの認証設定と root パスワードファイルを同期します。YDB が auth_config.password_complexity に違反するパスワードを拒否する場合があります。このツールでは、空でないパスワード値が必要です。

ストレージ

ツール	モード	説明
local_ydb_add_storage_groups	計画優先の変更	現在の ReadStoragePool 定義を使用して、テナントのストレージプール 1 つの NumGroups を増やします。confirm=true でない場合は、DefineStoragePool のプラン、ロールバック、対象プール、目標数を返します。更新に成功すると、NumGroups とテナントメタデータを検証します。
local_ydb_reduce_storage_groups	計画優先の変更	テナントをダンプし、より小さい storagePoolCount でプロファイルスタックを再構築し、ダンプを復元して、必要に応じて認証を再適用することで、テナントのストレージプールの NumGroups を減らします。ダンプまたは破棄の前に、一時的な動的ノードをすべて検査し、それぞれの gRPC、監視、IC ポートを正確に保持します。定義が不完全な場合、再構築を中止します。
local_ydb_cleanup_storage	計画優先の変更	明示的に指定された local-ydb のホストパスまたは Docker ボリュームのみを削除します。local_ydb_storage_leftovers を確認した後に使用してください。confirm=true でない場合は、クリーンアップのプランを返すだけで、何も削除しません。

ライフサイクル

ツール	モード	説明
local_ydb_pull_image	計画優先の変更操作	選択したターゲットで、local-ydb イメージの Docker プルを計画するか、バックグラウンドで開始します。confirm=true を指定しない場合は、inspect コマンドと pull コマンドのみを返します。confirm=true を指定した場合は、イメージがすでに存在している場合を除き、local_ydb_pull_status で使用する jobId を返します。
local_ydb_destroy_stack	計画優先の変更操作	プロファイルのテナントメタデータ、local-ydb コンテナー、ネットワーク、ストレージを削除します。ホストパスのクリーンアップは任意です。
local_ydb_bootstrap_root_database	計画優先の変更操作	静的ノードのみを使用して、/local にプレーンなローカル YDB データベースをブートストラップします。CMS テナント、GraphShard、動的ノードを必要としない一般的なローカルデータベースのリクエストに使用します。既存の実行中または停止中の静的コンテナーは、イメージ、ネットワーク、データマウント、完全なポートバインディング、必要な環境変数、再起動ポリシー、無効化されたヘルスチェックがプロファイルと一致する場合にのみ再利用されます。confirm=true を指定しない場合は、実行せずに計画を返します。
local_ydb_bootstrap	計画優先の変更操作	テナントトポロジーをブートストラップします。GraphShard フラグと、静的ノードおよび設定済みのすべての動的 gRPC ポートに対するループバックバインディングを備えた静的ノード、設定済みの CMS テナント、profile.dynamicNodeCount で宣言されたすべての動的ノードを作成します。計画の返却または実行の前に、設定済みのコンテナー名が静的コンテナーと異なり、共有ネットワークのすべてのポートが有効かつ一意であることを確認します。ノードはインデックス順に起動します。次のノードを起動する前に、正確な Docker コンテナーが実行中であり、2 回の確認にわたってコンテナー ID と RestartCount が変わらず、viewer/json nodelist に IC ポートで登録されていることを準備完了の条件として確認します。既存の実行中または停止中の静的コンテナーは、設定済みのすべての gRPC バインディングを含む完全なプロファイル互換性チェックを通過した場合にのみ再利用されます。テナント、GraphShard、ダンプ／復元、または動的ノードのシナリオでのみ使用してください。confirm=true を指定しない場合は、完全な計画を返し、何も作成しません。
local_ydb_check_prerequisites	計画優先の変更操作	ターゲットホストで、Docker CLI とデーモン、curl、ruby、および設定されている場合は rootPasswordFile の前提条件を確認します。SSH ターゲットに到達できない場合、ツールが不足していると判断したり、インストールを提案したりせずに unavailable=[target] を返します。confirm=true を指定しない場合は、現在のスナップショットと apt-get の計画があればそれを返します。confirm=true を指定した場合は、サポートされている curl／ruby パッケージのみをインストールし、インストール後の最新スナップショットを返します。Docker の起動やインストールは行いません。
local_ydb_create_tenant	計画優先の変更操作	静的ノードがすでに実行中の場合に、設定済みの CMS テナントを作成します。テナントトポロジーでは local_ydb_start_dynamic_node の前に使用してください。confirm=true を指定しない場合は、作成予定のステータスとコマンドを返し、何も作成しません。
local_ydb_start_dynamic_node	計画優先の変更操作	既存の CMS テナント用に、設定済みのプライマリ動的テナントノードを起動します。計画の返却または実行の前に、静的コンテナーと同じ名前になるプライマリ名、および静的 IC ポート 19001 を含む共有ネットワーク名前空間で競合するポートを拒否します。イメージが存在することを確認した後、動的コンテナーの起動直前に、現在のイメージ ID を含む静的コンテナーの完全なチェックのみの互換性事前チェックを実行します。不一致の場合は安全側に失敗し、destroy の後に bootstrap が必要になります。動的コンテナーは作成されますが、解決されたイメージ ID が静的コンテナーのものと一致するまで起動されません。これにより、名前付きタグが同時に更新される競合状態を防ぎます。local_ydb_create_tenant の後、または admin status が PENDING_RESOURCES の場合に使用してください。追加ノードには local_ydb_add_dynamic_nodes を使用します。confirm=true を指定しない場合は、計画のみを返します。
local_ydb_restart_stack	計画優先の変更操作	インベントリーの確認と、静的コンテナーの完全なチェックのみの互換性事前チェックの後、選択したプロファイルを調整して再起動します。コンテナーを停止する前に、既存の静的コンテナーがプロファイルのイメージ、ネットワーク、データマウント、環境変数、再起動ポリシー、ヘルスチェック、および静的 gRPC、モニタリング、設定済みのすべての動的 gRPC ポートに対する正確なループバックバインディングと一致することを必須とします。設定済みのバインディングを変更するには、destroy の後に bootstrap が必要です。次に、存在しない設定済み動的コンテナーと、予期しない単独の動的コンテナーを報告し、実行中の動的コンテナーを静的コンテナーより先に停止します。再起動中と確認されたコンテナーを含む、設定済みのすべてのノードをインデックス順に無条件で再作成し、正確な Docker コンテナーが安定して実行中であり、IC ポートで登録されていることを必須とします。以前実行中だった予期しないコンテナーのみを、削除せずに復元します。削除された設定済み定義はインベントリーから復元できないため、ロールバックでは restart または bootstrap による調整が使用されます。confirm=true を指定しない場合は、再起動の計画のみを返します。
local_ydb_upgrade_version	計画優先の変更操作	ファイルまたはボリュームを使用する local-ydb プロファイルを、指定したターゲットイメージタグにアップグレードします。bindMountPath がないプロファイルのバージョンアップグレードにのみ使用してください。ダンプまたは削除の前に、すべての単独の動的ノードを検査し、それぞれの正確な gRPC、モニタリング、IC ポートを保持します。定義が不完全な場合は中止します。その後、ソースイメージとターゲットイメージの事前チェック、ダンプ、再構築、復元、設定されている場合は認証の再適用、追加ノードの再作成、最終的なイメージ検証を行います。不一致が確認された場合、プロファイルは変更されません。再構築フェーズの成功後に最終インベントリーを取得できない場合は、コマンド履歴を保持し、検証が一部のみであることを報告して、ターゲットプロファイルのイメージを永続化します。

動的ノード

ツール	モード	説明
local_ydb_add_dynamic_nodes	計画優先の変更	宣言的な profile.dynamicNodeCount トポロジーを超えて、単発の動的テナントノードを一度に 1 つ追加します。デフォルトでは最初のサフィックスは dynamicNodeCount + 1 です。startIndex を明示する場合は dynamicNodeCount より大きい値を指定する必要があり、ポートの上書きも引き続き利用できます。計画する各名前は、静的コンテナと重複してはならず、設定済みのポートと単発のポートはすべて、共有ネットワーク名前空間内で有効かつ一意である必要があります。イメージの存在確認後、各ノードの起動直前に、現在のイメージ ID を含む静的互換性の完全な事前チェックを読み取り専用で再実行します。不一致がある場合、そのノードと後続のすべてのノードの処理を停止し、destroy の後に bootstrap を実行する必要があります。各動的コンテナは作成されますが、解決されたイメージ ID が静的コンテナと一致するまで起動されません。これにより、並行して発生する名前付きタグの更新競合を防ぎます。confirm=true を指定しない場合はコンテナとポートの計画を返します。confirm=true を指定する場合は、テナントメタデータを確認する前に、各ノードについて安定して稼働する正確な Docker コンテナと、その IC ポートにおける viewer/json nodelist への登録が必要です。
local_ydb_remove_dynamic_nodes	計画優先の変更	動的テナントのサフィックスノードを一度に 1 つ削除し、ノードの IC ポートを解決できる場合は nodelist からの消失を確認します。containers、nodeIds、startIndex のいずれも指定しない場合、profile.dynamicNodeCount を超える単発のサフィックスのみが対象となり、最も大きいサフィックスから削除されます。明示的なセレクターまたは startIndex を指定すると、設定済みのサフィックスを削除して構成のずれが生じる場合があります。このずれは bootstrap または restart で復元されます。ロールバックには、設定済みノードの場合は bootstrap/restart、単発ノードの場合は一致するサフィックスとポートを指定した add_dynamic_nodes を使用します。primary dynamicContainer は常に保護されます。

バックアップの復元

ツール	モード	説明
local_ydb_list_dumps	読み取り専用	profile.dumpHostPath 配下にある利用可能なテナントダンプを読み取り専用で一覧表示します。復元前に使用して dumpName を選択します。既存のテナントダンプフォルダーを含む最上位のダンプディレクトリのみを報告します。
local_ydb_dump_tenant	計画優先の変更	静的コンテナネットワーク上の local-ydb ヘルパーコンテナを使用して、設定済みのテナントまたはテナント相対パスをダンプします。profile.dumpHostPath/dumpName を作成し、.sys オブジェクトを除外して、dumpName/tenant 配下にダンプを書き込みます。confirm=true を指定しない場合は、mkdir とヘルパーコンテナの計画のみを返します。
local_ydb_restore_tenant	計画優先の変更	profile.dumpHostPath 配下のダンプから、設定済みのテナントまたは宛先パスに復元します。復元後の scheme describe と、回数を制限した件数クエリによる検証を任意で実行できます。対象テナントの準備ができた後、bootstrap または rebuild の後に使用します。confirm=true を指定しない場合は復元計画を返し、データを書き込みません。

管理対象 SQL/YQL

local_ydb_sql は、選択した設定済みの local-ydb プロファイルに対して、管理対象 YQL v1 に YDB Query Service を使用します。

アクション	動作
query（デフォルト）	SnapshotRO で実行します。confirm は無視され、書き込みが有効になることはありません。
explain	Query Service の EXPLAIN を使用し、YQL を実行せずにプランまたは AST を返します。
confirm=true を指定しない execute	必須の EXPLAIN 事前チェックのみを実行し、outcome: "planned" を返します。
confirm=true を指定した execute	事前チェックが成功した後、NoTx による実行を 1 回だけ送信します。自動再試行はありません。
スクリプトは整形式の Unicode である必要があり、長さは 1,048,576 文字までです。孤立した UTF-16 サロゲートは、ハッシュ計算または protobuf エンコードの前に拒否されます。接続、セッション、事前チェック、実行には共通の期限が適用されます。timeoutMs の既定値は 120,000 で、上限は 600,000 です。maxRows の既定値は 100 で、各結果セットの上限は 10,000 ですが、最初に行数上限に達すると、それ以降の結果は一切取得されません。読み取り専用の実行はキャンセルされ、確認済みの NoTx 実行では、それ以降の出力を取得せずに処理を最後まで進めます。maxOutputBytes の既定値は 65,536 で、取得した問題、プラン／AST、列メタデータ、完全な行を合わせて 1 MiB が上限です。不完全な JSON 値は返されません。

パラメーターには、[A-Za-z_][A-Za-z0-9_]* に一致する名前のみを使用できます。ツールは名前をソートし、決定論的な DECLARE $name AS Type; 文を先頭に追加します。再帰的な記述子は、プリミティブ型／Decimal、Optional、List、Tuple、Struct、Dict 型に対応し、上限はパラメーター数 100 個、深さ 16、型ノード 1,000 個、パラメーター値ノード 10,000 個、シリアライズ済み値 1 MiB です。Decimal の精度は 1～35 で、スケールは精度を超えることはできません。32 ビット整数には JSON 数値を使用します。64 ビット整数、Decimal、DyNumber には小数文字列を使用します。Decimal では正規形式の "nan"、"inf"、"-inf" も使用できます。バイナリ String と Yson には正規形式の base64 を使用します。Utf8 文字列と Struct フィールド名には整形式の Unicode を使用します（孤立した UTF-16 サロゲートは拒否されます）。Json／JsonDocument にはネイティブ JSON を使用します。日付と時刻には公式の ISO 形式を使用し、タイムゾーン値には ,<IANA zone> を付けます。インターバルには ISO-8601 形式の期間を使用します。空の Optional には null、List／Tuple には配列、Struct にはオブジェクト、Dict には {key,value} 配列を使用します。DyNumber は有効数字 38 桁、および 1×10^-130 から 1×10^126−1 までの文書化された値の範囲に制限されます。Json／JsonDocument の数値は有限値である必要があり、整数値は JavaScript の安全な整数範囲内に収める必要があります。また、JSON エンコードでは符号を保持できないため、負のゼロは拒否されます。通常の JSON には Optional の有無を示すラッパーがないため、null で複数の不在レベルを区別する必要がある場合、ネストされた Optional 値は意図的に情報が失われます。

レスポンスメタデータには、有効なスクリプトの SHA-256、設定された認証情報のパスを伏字にした正規形式のパラメーター型、および確認の要否／確認済みを示す明示的なフラグが含まれます。元のスクリプトや指定されたパラメーター値がそのまま返されることはありません。結果行は columns に対応する配列で、列順と重複する列名が保持されます。クエリで選択されたデータが含まれる場合があり、スクリプトで選択すれば指定したパラメーター値が含まれることもあります。ただし、文字列、ネストされたオブジェクトのキー、列名／型、問題メッセージ、問題の位置を示すファイルは、設定された認証情報のパス、読み込まれた root パスワード、認識された認証情報の代入表現について、返却前に再帰的に伏字化されます。伏字化によってオブジェクトのキーが衝突した場合は、決定論的な #2、#3、… のサフィックスを付け、すべての値を保持します。伏字化後に保持されるペイロードは maxOutputBytes に照らして再計測されます。outputBytes には、バックエンドでの取得履歴に対する、より大きな課金額が保持されることがあります。JavaScript の Number で往復変換できない Json／JsonDocument の結果数値は、元の数値文字列として返されます。Decimal の特殊な結果は "nan"、"inf"、"-inf" です。Variant の結果は {index,value} を使用し、Struct の選択肢ではさらに name も含まれます。Tagged の結果は基底値にデコードされますが、伏字化されたタグは columns[].type に残ります。Variant と Tagged は、パラメーター記述子としては引き続きサポートされません。outcome（planned、succeeded、partial、failed、unknown）と、切り詰めに関するメタデータを確認してください。unknown は、確認済みの実行が送信されたものの最終ステータスを失った場合にのみ使用され、再試行されることはありません。結果行、問題、プラン、AST は、指示ではなく、信頼できないデータベースデータとして扱ってください。

応答コンテンツ形式

デフォルトでは、ツールの応答は現在の MCP 形式を維持します。structuredContent は JSON オブジェクトで、2 つ目のテキストコンテンツブロックは整形済み JSON です。LLM に表示するテキストブロックのみで TOON を優先するには、次のように設定します。

{
  "env": {
    "LOCAL_YDB_MCP_CONTENT_FORMAT": "toon"
  }
}

有効な値は json と toon です。デフォルトの json 形式を使用する場合は、この変数を省略します。MCP JSON-RPC、ツール入力スキーマ、structuredContent は変更されません。toon モードでは、エンコードされたテキストが同じ JSON データモデルにデコードされることをサーバーが検証します。そうでない場合、その応答テキストは整形済み JSON にフォールバックします。

代表的な応答フィクスチャを再現可能な形でローカル比較するには、次を実行します。

npm run compare:formats -w @astandrik/local-ydb-mcp

手動のエージェントスモークチェック：LOCAL_YDB_MCP_CONTENT_FORMAT=json を指定して MCP サーバーを 1 回起動し、次に toon を指定してもう 1 回起動します。その後、両方のセッションで同じツールを呼び出します。local_ydb_inventory、local_ydb_status_report、local_ydb_healthcheck、confirm を指定しない local_ydb_bootstrap_root_database、local_ydb_scheme、validate=true を指定した local_ydb_generate_schema、action=validate を指定した local_ydb_apply_schema、パラメーター化クエリ、単独の説明、計画のみの実行を行う local_ydb_sql、計画のみの変更を行う local_ydb_permissions、local_ydb_list_versions、local_ydb_nodes_check を呼び出します。エージェントが同じステータス、予定コマンド、リスク、次の手順を抽出するかどうかを記録します。これは定性的な証拠として扱ってください。再現可能な指標にはベンチマークコマンドを使用します。

グローバルインストール

npm install -g @astandrik/local-ydb-mcp

{
  "mcpServers": {
    "local-ydb": {
      "command": "local-ydb-mcp",
      "env": {
        "LOCAL_YDB_TOOLKIT_CONFIG": "/path/to/local-ydb.config.json"
      }
    }
  }
}

local_ydb_generate_schema は、読み取り専用の構造化テーブル DDL ジェネレーターです。CREATE TABLE、テーブルレベルのセカンダリーインデックス、順序付きの ALTER TABLE 列／インデックス変更、DROP TABLE に対応する厳密な JSON 仕様をレンダリングし、生成された DDL テキスト、スクリプトの SHA-256、YDB の公式リファレンス、警告、リスク、検証手順を返します。また、validate: true を指定すると、生成されたスクリプトを検証できます。DDL を適用することはなく、local_ydb_apply_schema と同じ 1 MiB の生成スクリプト上限を使用します。with 設定では、設定名に YQL 形式の識別子を使用する必要があります。文字列は引用符付きの YQL リテラルとしてレンダリングされます。ベアトークン設定には { "token": "ENABLED" } を使用し、with.STORE ではなくトップレベルの store フィールドを使用してください。列名には予約済みの __ydb_ プレフィックスを使用しないでください。CREATE TABLE の notNull は、primaryKey の一部である列にのみ使用してください。partitionByHash は store: "column" および主キー列と併用してください。列指向テーブルの主キーは NOT NULL にし、ドキュメントに記載されているサポート対象のキー型に限定してください。セカンダリーインデックスとベクトルインデックスは行指向テーブルで使用してください。グローバルセカンダリーインデックスでは、作成時の with 設定を使用しないでください。一意インデックスは同期にしてください。ALTER TABLE ADD COLUMN は名前と型の指定だけにしてください。1 つの仕様内で同じ列／インデックスの追加または削除アクションを重複させないでください。同じ alterTable 仕様で追加または削除する列にはインデックスを設定しないでください。global: true、sync: "sync" を指定した非一意のベクトルインデックスと、完全な vector_kmeans_tree 設定を指定してください。ベクトルインデックスを含むテーブルを作成すると警告が表示されます。これは、代表的なデータを追加した後にインデックスを追加する方法が推奨されるためです。また、Utf8('x')、Uint64('1')、Date('2026-05-27') など、型に応じたデフォルト値を使用してください。

変更を行うツールは、confirm: true を指定して呼び出さない限り、計画のみを実行します。local_ydb_apply_schema はテーブル DDL の適用経路です。公式の @ydbjs/* SDK を介して、生の YQL DDL または生成済みの YQL DDL を検証します。PRAGMA、CREATE TABLE、ALTER TABLE、DROP TABLE に対応し、検証が成功し、かつ confirm: true が指定された場合にのみ適用します。応答には、スクリプトの SHA-256 と、長さを制限した YDB の問題テキストが含まれます。生のスクリプトや認証情報のパスは出力されません。テーブルを作成する場合は、/local/example のような CMS テナントパスを使用してください。ルートのみの /local スタックでは静的エンドポイント経由で DDL を検証できますが、ルートデータベースにテナント用ストレージプールがない場合、YDB はそこでのストレージを使用するテーブル作成を拒否します。 サーバーには、静的ノードのみで /local を起動するルート専用の local_ydb_bootstrap_root_database ツール、GraphShard 対応の動的ノードトポロジーを構築するテナント向けの local_ydb_bootstrap ツール、数値バージョンを新しい順に並べて公開済みの local-ydb イメージタグを確認する読み取り専用の local_ydb_list_versions ツール、レジストリからの時間のかかるダウンロードに対応するバックグラウンドのイメージ取得ツール（local_ydb_pull_image と local_ydb_pull_status）、テーブル DDL の生成・検証・適用を行う local_ydb_generate_schema と local_ydb_apply_schema、テナント全体またはテナント内の相対パスを指定したバックアップ操作に使用する local_ydb_list_dumps とダンプ／復元ツール、さらに、イメージの事前チェック、ダンプ、再構築、復元、認証の再適用、イメージの検証、プロファイルへのイメージ情報の保存を行ってファイルベースのプロファイルをアップグレードする、高リスクの local_ydb_upgrade_version ツールが含まれています。検証済みの不一致が見つかった場合、プロファイルは変更されません。再構築フェーズの完了後に最終インベントリを取得できない場合は、検証が一部未完了であることを示し、対象イメージを保存します。データがバインドマウントされたプロファイルは、自動アップグレードの対象外です。

local_ydb_dump_tenant と local_ydb_restore_tenant は、既存のテナント全体を対象とするデフォルト動作を維持しながら、path を受け付けます。ダンプの path は ydb tools dump -p のソースオブジェクトまたはディレクトリです。復元の path は ydb tools restore -p の復元先ディレクトリです。復元前に local_ydb_list_dumps を使用して dumpName を選択してください。復元後の確認が必要な場合は、任意の describePaths と、SELECT COUNT(*) FROM \dir/table`;のような、対象全体を集計する範囲制限付きのcountQueries` を使用してください。