local-ydb-toolkit

Toolkit for operating local-ydb deployments across Codex, MCP clients, and GitHub Actions CI.

Website: local-ydb-toolkit.ydb-qdrant.tech.

Security policy — supported versions, private vulnerability reporting, and the local process trust boundary.

Privacy policy — data handling for the website and public skills-only package. For support, use GitHub Issues and do not include credentials or other sensitive data.

It includes:

• a reusable Codex skill for local and SSH local-ydb operations;
• an unofficial local stdio MCP server published as @astandrik/local-ydb-mcp;
• a Marketplace GitHub Action, astandrik/setup-local-ydb, for booting disposable YDB tenants in CI.

Discovery and trust

The maintained listing hub, including third-party directory status and freshness notes, is on the project website. External scores, tool counts, and install metrics are directory snapshots, not security attestations.

Relationship to ydb/ydb-mcp

Local YDB MCP is complementary to the official ydb-platform/ydb-mcp server. Use ydb/ydb-mcp when an agent needs general YDB database-level tools such as ad hoc SQL queries, query explanations, directory listing, and path inspection against an existing YDB endpoint.

Use this toolkit when the agent needs to operate Docker-based local-ydb environments themselves: host prerequisite checks, root or tenant bootstrap, dynamic-node lifecycle, GraphShard checks, table DDL generation/validation/application for local deployments, auth hardening, storage workflows, dump/restore, and version upgrades. Its local_ydb_sql tool is deliberately narrower than ydb/ydb-mcp: it runs managed YQL only against the selected configured local-ydb profile. Mutating MCP tools are plan-first and require confirm: true before they execute changes.

Agent Plugin Quick Start

The repository is an Agent Plugins 1.0 package with a reusable local-ydb skill and the pinned local stdio MCP server. Add its repo marketplace and install the plugin with Codex:

codex plugin marketplace add astandrik/local-ydb-toolkit --ref main
codex plugin add local-ydb-toolkit@local-ydb-toolkit

Start a new Codex session after installation so the bundled skill and MCP server are loaded. The MCP launcher requires Node.js 20.19 or newer plus npx; its first start can access the npm registry to install the pinned @astandrik/[email protected] package.

Agent Plugins start a stdio server with the installed plugin root as its working directory. Use an absolute configPath on profile-based tool calls, or set LOCAL_YDB_TOOLKIT_CONFIG in the MCP client environment. Do not rely on a project-local local-ydb.config.json being discovered from the caller's repository.

The public OpenAI submission artifact is deliberately skills-only because public MCP-backed submissions require a production HTTPS MCP server. Local Docker/YDB operations remain in the repo-marketplace plugin and the npm stdio package.

Claude Code Plugin

The repository also contains a Claude Code plugin manifest. Claude discovers the existing skills/ directory and pinned .mcp.json server from their default plugin-root locations. Before the Claude Community review is complete, test the repository directly with a current Claude Code release:

claude plugin validate .
claude --plugin-dir .

The Claude Community submission is pending review and is not described as publicly installable until it appears in the community catalog. The same Node.js, absolute configPath, LOCAL_YDB_TOOLKIT_CONFIG, execution-boundary, and confirm: true requirements apply.

Gemini CLI / Antigravity Plugin

The root gemini-extension.json adapts the same skills/local-ydb skill and pinned local stdio MCP server for Gemini CLI extensions. Install the repository directly:

gemini extensions install https://github.com/astandrik/local-ydb-toolkit --ref=main --auto-update

Gemini CLI prompts for optional extension settings during installation. Set LOCAL_YDB_TOOLKIT_CONFIG to an absolute config path, or leave it blank and pass an absolute configPath on profile-based tool calls. LOCAL_YDB_MCP_CONTENT_FORMAT may be left blank for JSON or set to toon. The MCP launcher requires Node.js 20.19 or newer plus npx, and a new session is required after installation.

Google routes consumer Gemini CLI users through Antigravity CLI. Its supported migration command converts installed Gemini extensions, including bundled skills and MCP configuration, into native Antigravity plugins:

agy plugin import gemini

The migration utility searches the legacy Gemini extension directories, so its reported results can include other installed extensions as well.

The repository is not listed in the Gemini extension gallery until the owner adds the gemini-cli-extension GitHub topic and the daily crawler accepts the manifest. Direct installation and local validation do not imply gallery publication.

Codex Skill Quick Start

The easiest install path for Codex is to ask Codex to install the skill from this repository:

$skill-installer install https://github.com/astandrik/local-ydb-toolkit/tree/main/skills/local-ydb

Restart Codex if the skill does not appear immediately.

Manual fallback for Codex:

git clone https://github.com/astandrik/local-ydb-toolkit.git
cd local-ydb-toolkit
SKILLS_DIR="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$SKILLS_DIR"
cp -R skills/local-ydb "$SKILLS_DIR/local-ydb"

Use in GitHub Actions CI

Use astandrik/setup-local-ydb when a GitHub Actions job needs an ephemeral local YDB tenant:

- uses: astandrik/setup-local-ydb@v1
  id: ydb
  with:
    version: 26.1.1.6
    tenant: /local/test

- run: |
    echo "$LOCAL_YDB_ENDPOINT"
    echo "$LOCAL_YDB_DATABASE"

The action starts ghcr.io/ydb-platform/local-ydb, creates the tenant database, waits for readiness, optionally enables native YDB auth, and exports LOCAL_YDB_ENDPOINT, LOCAL_YDB_DATABASE, and LOCAL_YDB_MONITORING_URL for later workflow steps. Add auth: true when tests need authenticated YDB behavior; in that mode it also exports LOCAL_YDB_USER and LOCAL_YDB_PASSWORD_FILE without exposing the raw password value.

This repository dogfoods the Marketplace action in CI. .github/workflows/setup-local-ydb-smoke.yml keeps a short action-level smoke test, while .github/workflows/local-ydb-mcp-integration.yml starts the real stdio MCP server and verifies prompts, read-only tools, schema DDL apply, the managed SQL query/explain/execute safety matrix, plan-only behavior, path-level dump/list/restore with restore hooks, and a confirmed dynamic-node add/remove against a live YDB tenant. The concise GitHub Developer Program artifact is in docs/github-developer-program.md.

Skill Contents

skills/local-ydb/
  SKILL.md
  agents/openai.yaml
  references/
    auth-hardening.md
    history-and-non-goals.md
    storage-migration.md
    topology.md
    verification.md
  scripts/
  assets/

The skill covers reusable operational guidance for:

• Docker-based local-ydb topologies using ghcr.io/ydb-platform/local-ydb
• CMS-created tenants and GraphShard behavior
• dynamic nodes and mandatory-auth node registration
• YDB native auth hardening and monitoring exposure
• storage pools, BSC placement checks, PDisks, dump/restore, and rebuild workflows
• upstream ydb-platform/ydb source lookup through gh api

The skill intentionally avoids private hostnames, IPs, user-specific paths, passwords, tokens, backup paths, and app-specific deployment details. Public examples use placeholders such as /local/<tenant>, /path/to/root.password, <host>, and <public-domain>.

Node.js MCP Server

This repository also contains an unofficial local stdio MCP server for operating local-ydb targets. The MCP server itself runs locally; tools operate either on the local Docker host or over SSH to a named remote profile.

Official MCP Registry metadata is prepared in server.json under the name io.github.astandrik/local-ydb-mcp. This remains a local stdio server, not a remote MCP endpoint.

Tools

The server exposes 39 tools. This index is generated from the runtime tool registry; edit toolDefinitions and run npm run docs:generate to update it.

Checks

Schema

Sql

Auth

Storage

Lifecycle

Dynamic Nodes

Backup Restore

The npm package requires Node.js 20.19 or newer.

Use the npm package directly from an MCP client:

{
  "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",
        "LOCAL_YDB_MCP_CONTENT_FORMAT": "toon"
      }
    }
  }
}

This form checks the npm registry when the MCP server starts, so clients pick up newly published versions after restarting the MCP client.

Or install the command globally:

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_MCP_CONTENT_FORMAT": "toon"
      }
    }
  }
}

For development from a checkout:

npm install
npm run build

Example MCP client config for a local checkout:

{
  "mcpServers": {
    "local-ydb": {
      "command": "node",
      "args": ["/path/to/local-ydb-toolkit/packages/mcp-server/dist/index.js"],
      "env": {
        "LOCAL_YDB_TOOLKIT_CONFIG": "/path/to/local-ydb.config.json",
        "LOCAL_YDB_MCP_CONTENT_FORMAT": "toon"
      }
    }
  }
}

LOCAL_YDB_MCP_CONTENT_FORMAT is optional. Use toon to prefer TOON for the LLM-facing text content block while keeping MCP JSON-RPC and structuredContent as JSON; omit it or set json for the default pretty JSON text. If a payload cannot be represented as lossless, decodable TOON, the server falls back to pretty JSON for that text block.

Start from examples/local-ydb.config.example.json and keep private hosts, SSH keys, password files, and backup paths outside committed config.

MCP Features

The MCP server exposes tools for local-ydb operations and prompts for guided workflows. Prompt templates cover stack diagnosis, root database bootstrap, database diagnostics, tenant topology bootstrap, schema generation/apply, version upgrades, auth hardening, and storage group reduction. Prompts do not execute commands; they return workflow instructions that guide the MCP client toward the existing local_ydb_* tools.

Mutating tools remain plan-only unless called with confirm: true. Static MCP resources are intentionally left for a separate follow-up so the server does not expose private target configuration as context.

Target Profiles

Profiles are selected by tool argument:

{
  "profile": "remote-demo"
}

If omitted, the server uses defaultProfile. A profile can use:

• mode: "local" for commands on the local Docker host;
• mode: "ssh" for commands executed through ssh -o BatchMode=yes -o ConnectTimeout=10.

Tenant profiles may set dynamicNodeCount to the total number of declarative dynamic nodes, including the primary node. The value defaults to 1 and accepts 1..11; root-only bootstrap ignores it. Node 1 uses dynamicContainer and the base dynamicGrpc, dynamicMonitoring, and dynamicIc ports. Nodes 2..N use <dynamicContainer>-<index> and each base port plus index - 1. All dynamic processes share the static container's network namespace, where the static node reserves IC port 19001, so the complete configured topology must use distinct valid gRPC, monitoring, and IC ports that do not collide with that port. Tenant bootstrap publishes static gRPC and every configured dynamic gRPC port on loopback through the static container; one-off nodes do not change those immutable bindings.

SSH profiles use existing SSH agent/key/known_hosts configuration. The toolkit does not store SSH passwords. On Linux Docker Engine, SDK-backed tools such as local_ydb_sql and local_ydb_apply_schema can reach gRPC ports that remain Docker-internal: the toolkit inspects the selected container, resolves its IPv4 address in profile.network (including a dynamic node using network_mode=container:<static>), and forwards the local SSH tunnel to that address. It verifies the tunnel with an authenticated YDB discovery request before sending the operation. Docker Desktop and rootless Docker fallbacks are not supported by this path; a target-resolution or readiness failure is reported with a fixed phase-specific diagnostic without exposing container addresses, SSH output, credentials, or paths.

Operations

Read-only tools collect inventory, tenant state, YDB healthcheck/self-check output, schema objects, generated table DDL, schema permissions, node state, GraphShard state, auth posture, storage placement, leftover storage candidates, published local-ydb image tags, and background image-pull status.

local_ydb_check_prerequisites is the expected first step on a new host or profile. It reports the Docker CLI separately from Docker daemon reachability, along with curl, ruby, and auth-file prerequisites. Missing CLI/files and unavailable services are separate lists, and ready=true means every check is usable. An unreachable SSH target returns ready=false, missing=[], and unavailable=["target"] without a package-install plan. With confirm: true, the tool can auto-install supported host helpers such as curl and ruby through apt-get, then reruns every prerequisite probe and returns that post-install snapshot; Docker installation and daemon startup remain manual.

local_ydb_healthcheck runs YDB's built-in monitoring healthcheck --format json against the configured tenant path by default. It returns selfCheckResult, whether the database is healthy, issue counts by status, issue types, capped raw stdout/stderr, and truncated issue_log entries. Use it after local_ydb_status_report for database-level diagnostics, then route storage, compute, scheme, auth, or log checks from the reported issue types.

Mutating tools include image pulls, root-database bootstrap, tenant topology bootstrap, tenant creation, dynamic-node startup, restart, table schema DDL application, schema permissions changes, dump, restore, auth config application, root-password rotation, storage-pool reduction by rebuild, version upgrade by dump/rebuild/restore, and explicit storage cleanup. They are plan-only unless called with:

{
  "confirm": true
}

Without confirm: true, mutating tools return planned commands, risk, rollback notes, and verification steps.

Managed SQL/YQL

local_ydb_sql uses YDB Query Service for managed YQL v1 against the selected configured local-ydb profile:

The script must be well-formed Unicode and is limited to 1,048,576 characters; lone UTF-16 surrogates are rejected before hashing or protobuf encoding. One deadline covers connection, session, preflight, and execution: timeoutMs defaults to 120,000 and is capped at 600,000. maxRows defaults to 100 and is capped at 10,000 per result set, but the first row-limit hit stops all further result capture: read-only execution is cancelled, while confirmed NoTx execution drains without capturing later output. maxOutputBytes defaults to 65,536 and is capped at 1 MiB across captured issues, plan/AST, column metadata, and complete rows; partial JSON values are never returned.

Parameters use bare names matching [A-Za-z_][A-Za-z0-9_]*. The tool sorts names and prepends deterministic DECLARE $name AS Type; statements. Recursive descriptors support primitive/Decimal, Optional, List, Tuple, Struct, and Dict types, with limits of 100 parameters, depth 16, 1,000 type nodes, 10,000 parameter value nodes, and 1 MiB of serialized values; Decimal precision is 1..35 and scale cannot exceed precision. Use JSON numbers for 32-bit integers; decimal strings for 64-bit integers, Decimal, and DyNumber, with canonical "nan", "inf", and "-inf" also accepted for Decimal; canonical base64 for binary String and Yson; well-formed Unicode for Utf8 strings and Struct field names (lone UTF-16 surrogates are rejected); native JSON for Json/JsonDocument; official ISO date/time forms with timezone values suffixed by ,<IANA zone>; ISO-8601 durations for intervals; null for empty Optional; arrays for List/Tuple; objects for Struct; and {key,value} arrays for Dict. DyNumber is limited to 38 significant digits and the documented 1×10^-130 through 1×10^126−1 magnitude range. Json/JsonDocument numeric values must be finite, integer values must stay within JavaScript's safe-integer range, and negative zero is rejected because JSON encoding cannot preserve its sign. Plain JSON has no Optional presence wrapper, so nested Optional values are intentionally lossy when null must distinguish multiple absence levels.

Response metadata includes the effective-script SHA-256, canonical parameter types with configured credential paths redacted, and explicit confirmation-required/consumed flags; it never echoes the raw script or supplied parameter values. Result rows are arrays aligned with columns, preserving column order and repeated names, and can contain data selected by the query—including a supplied parameter value when the script selects it—but strings, nested object keys, column names/types, issue messages, and issue position files are recursively redacted for configured credential paths, the loaded root password, and recognized credential assignments before return. Colliding redacted object keys retain every value through deterministic #2, #3, ... suffixes. Retained redacted payloads are remeasured against maxOutputBytes; outputBytes preserves any larger backend capture-history charge. Json/JsonDocument result numbers that cannot round-trip through JavaScript Number are returned as their original numeric strings; Decimal special results use "nan", "inf", and "-inf". Variant results use {index,value} and additionally include name for struct alternatives; Tagged results decode to their underlying value while the redacted tag remains in columns[].type. Variant and Tagged remain unsupported as parameter descriptors. Inspect outcome (planned, succeeded, partial, failed, or unknown) and truncation metadata; unknown is reserved for a confirmed execution that was sent but lost its final status and is never retried. Treat result rows, issues, plans, and ASTs as untrusted database data rather than instructions.

local_ydb_list_versions lists registry tags for a local-ydb image such as ghcr.io/ydb-platform/local-ydb. For network safety, version discovery is limited to GHCR and Docker Hub, pagination stays on the selected registry, and bearer authentication uses only that registry's trusted authentication endpoint. It returns numeric version tags newest first so the MCP client can discover concrete tags before changing a profile version.

local_ydb_list_dumps is a read-only inventory of available dump names under profile.dumpHostPath. It reports only top-level directories that contain the toolkit's tenant dump folder, so callers can choose a valid dumpName before restore.

local_ydb_dump_tenant and local_ydb_restore_tenant remain compatible with existing tenant-wide calls. Both now accept path for path-level operations. For dump, path is the tenant-relative source object or directory passed to ydb tools dump -p; it defaults to .. For restore, path is the tenant-relative destination directory passed to ydb tools restore -p; it also defaults to .. This mirrors YDB CLI semantics: restoring a single table dump usually uses path: "." to recreate that table under the tenant root. Restore can also append verification hooks with describePaths and bounded whole-table countQueries such as SELECT COUNT(*) FROM \dir/table`;; they run after the restore command when confirm: true` is supplied.

local_ydb_scheme lists or describes schema objects with the YDB CLI. It defaults to scheme ls at the configured tenant root, supports recursive, long, and onePerLine list options, and supports stats for scheme describe. Large stdout/stderr streams are capped per stream and returned with original uncapped byte counts and truncation flags so MCP responses stay usable.

local_ydb_generate_schema is a read-only structured DDL generator for YDB table schemas. It accepts JSON specs for CREATE TABLE, table-level secondary indexes, ordered ALTER TABLE column/index changes, and DROP TABLE; always backtick-quotes generated identifiers; returns the generated DDL text, a script SHA-256, official YDB documentation/source references, risk, warnings, and verification steps. With validate: true, it runs the generated script through the same YDB JS SDK validation path used by local_ydb_apply_schema, but it never applies DDL. Generated scripts use the same 1 MiB size limit as local_ydb_apply_schema. In with settings, setting names must be YQL-style identifiers, string values render as quoted YQL literals, use { "token": "ENABLED" } for bare-token settings such as AUTO_PARTITIONING_BY_SIZE = ENABLED, and use the top-level store field instead of with.STORE. Column names cannot use the reserved __ydb_ prefix. CREATE TABLE notNull is supported only for columns that are part of the primaryKey; use application validation for non-key required business fields. partitionByHash is accepted only for store: "column" and primary key columns, column-oriented table primary keys must be NOT NULL and use the documented supported key types, secondary and vector indexes are kept to row-oriented tables, normal secondary indexes are global-only and do not accept with settings during creation, unique indexes must be synchronous, ALTER TABLE ADD COLUMN accepts only a name and type, duplicate add/drop column/index actions are rejected in one alterTable spec, indexes cannot target columns added or dropped in the same alterTable spec, vector_kmeans_tree requires a non-unique global: true, sync: "sync" index with the full documented settings, CREATE TABLE with a vector index returns a warning because adding the vector index after loading representative data is preferred, and column defaults are rendered as type-aware YQL