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.

VerifyMCP reports automated checks of the published npm package, including provenance and MCP schema checks. Its score is not a security certification or a verification of operations against a configured Docker/YDB deployment.

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/local-ydb-mcp@0.18.2 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 to an absolute path in the MCP client environment. An explicit path must name a readable regular JSON file no larger than 1 MiB; missing or invalid explicit files fail closed instead of selecting the default profile. 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

Tool	Mode	Description
local_ydb_inventory	read-only	Read-only Docker inventory for a local-ydb target profile. Success returns ok=true, Docker CLI/daemon state, containers, volumes, and inspect data for configured containers that actually exist; Docker CLI, daemon, or inventory failures return ok=false with a reason and omit inventory arrays so failure cannot be mistaken for an empty host. SSH target or probe failures use docker-inventory-failed with conservative Docker availability flags.
local_ydb_database_status	read-only	Read-only YDB admin database status for the configured tenant path. Returns the command, stdout, stderr, and ok flag; use this for tenant state before bootstrap/restart troubleshooting, and use local_ydb_tenant_check for scheme reachability.
local_ydb_healthcheck	read-only	Read-only YDB monitoring healthcheck for the configured tenant or root database. Uses the official YDB CLI SelfCheck path, returns selfCheckResult, issue counts, issue types, capped raw output, and whether the database is healthy; a requested noCache/noMerge option rejected with the exact recognized two-line legacy parser signature is reported through optionResolution and warnings, while compatibilityFallback says whether a retry actually started. Use after local_ydb_status_report for database-level diagnostics.
local_ydb_container_logs	read-only	Read recent Docker logs from the configured static or primary dynamic local-ydb container. Use when bootstrap, restart, or readiness checks fail; target selects the container role and lines controls the tail length.
local_ydb_status_report	read-only	Read-only aggregate report for quick diagnosis. Runs local_ydb_inventory, local_ydb_auth_check, local_ydb_tenant_check, local_ydb_nodes_check, and local_ydb_healthcheck, returning each result; every component is isolated so an unexpected failure produces a safe component-shaped fallback and does not stop the remaining checks.
local_ydb_tenant_check	read-only	Read-only check that uses the YDB CLI to verify the configured tenant path is reachable. Use after bootstrap or restore to confirm tenant metadata before node or GraphShard checks.
local_ydb_scheme	read-only	Read-only YDB scheme list or describe with capped stdout/stderr. It uses the root database for rootDatabase paths and the tenant database otherwise; list supports recursive/long/onePerLine flags, describe supports stats, and incompatible flag combinations are rejected.
local_ydb_nodes_check	read-only	Read-only check of dynamic node registration through viewer/json nodelist. Use after starting, adding, or removing dynamic nodes; use local_ydb_tenant_check first when tenant reachability is unknown.
local_ydb_graphshard_check	read-only	Read-only GraphShard check through viewer/json capabilities and tabletinfo for the configured tenant. Returns graphShardExists, tablet ids, and viewer status details; use after tenant bootstrap when GraphShard support or tablet visibility is the specific question.
local_ydb_auth_check	read-only	Read-only auth audit that checks anonymous viewer whoami status and configured YDB CLI tenant access, using root credentials when rootPasswordFile is configured. Use after auth hardening or password rotation to verify the expected posture.
local_ydb_storage_placement	read-only	Read-only storage inspection that returns ReadStoragePool output and BSC physical placement. Use before adding or reducing storage groups to confirm the exact pool shape.
local_ydb_storage_leftovers	read-only	Read-only search for candidate leftover local-ydb Docker volumes, dumps, and PDisk/data paths. It scans Docker volume names plus profile.storageSearchPaths and deletes nothing; use before local_ydb_cleanup_storage to decide exact paths or volumes to remove.
local_ydb_list_versions	read-only	List published GHCR or Docker Hub tags for a local-ydb container image, with numeric version tags sorted newest first. Use before local_ydb_upgrade_version; registry pagination and authentication are restricted to trusted origins, and pageSize and maxPages bound pagination.
local_ydb_pull_status	read-only	Check the status of a background Docker image pull started by local_ydb_pull_image. For known jobs it returns a monotonic progressPercent based on completed known Docker layers rather than bytes: 0-99 while running, 100 after successful completion, and the last observed value after failure.

Schema

Tool	Mode	Description
local_ydb_generate_schema	read-only	Read-only structured YDB table DDL generator. It renders strict JSON specs for CREATE TABLE, ALTER TABLE, DROP TABLE, and secondary indexes, returns the generated script with official references and warnings, and can optionally validate through the YDB JS SDK without applying changes.
local_ydb_apply_schema	plan-first mutation	Validate or apply YDB table DDL through the official YDB JS SDK. It accepts raw YQL DDL for PRAGMA plus CREATE TABLE, ALTER TABLE, and DROP TABLE; action=apply validates first and executes only with confirm=true.

Sql

Tool	Mode	Description
local_ydb_sql	plan-first mutation	Run managed YQL v1 against the configured local-ydb target through Query Service. query uses SnapshotRO, explain returns plan/AST, and execute always runs EXPLAIN first and sends one NoTx execution only with confirm=true.

Auth

Tool	Mode	Description
local_ydb_permissions	plan-first mutation	Inspect or change YDB scheme permissions for a path. The default list action is read-only; grant, revoke, set, clear, chown, and inheritance changes return a plan unless confirm=true.
local_ydb_prepare_auth_config	plan-first mutation	Generate a hardened YDB config from the current static-node config. Use before local_ydb_write_dynamic_auth_config and local_ydb_apply_auth_hardening; without confirm=true this returns the planned write only.
local_ydb_write_dynamic_auth_config	plan-first mutation	Write the text-proto dynamic-node auth token file needed for mandatory-auth startup. Use after choosing the SID for auth hardening; without confirm=true this returns the planned file write only.
local_ydb_apply_auth_hardening	plan-first mutation	Apply a reviewed hardened YDB config file only after a full check-only static profile and configured-binding compatibility preflight succeeds before any config or container mutation; immutable mismatches require destroy followed by bootstrap. It then restarts the static node and recreates and verifies every configured dynamic node in index order even when no dynamic-node token file is configured. Exact-container running stability and IC registration must both pass before metadata verification, and rollback uses restart or bootstrap reconciliation after restoring the static config. Use only after preparing and reviewing the config; without confirm=true this returns the preflight/apply/recreate plan only.
local_ydb_set_root_password	plan-first mutation	Rotate the runtime root password with ALTER USER and sync the host auth config and root password file to match. YDB may reject passwords that violate auth_config.password_complexity; this tool requires a non-empty password value.

Storage

Tool	Mode	Description
local_ydb_add_storage_groups	plan-first mutation	Increase NumGroups for one tenant storage pool using the current ReadStoragePool definition. Without confirm=true this returns the DefineStoragePool plan, rollback, target pool, and target count; when the update succeeds it verifies NumGroups and tenant metadata.
local_ydb_reduce_storage_groups	plan-first mutation	Reduce NumGroups for a tenant storage pool by dumping the tenant, rebuilding the profile stack with a smaller storagePoolCount, restoring the dump, and reapplying auth when needed. Before dump or destroy, it inspects every one-off dynamic node and preserves its exact gRPC, monitoring, and IC ports; an incomplete definition aborts the rebuild.
local_ydb_cleanup_storage	plan-first mutation	Delete only the explicitly supplied local-ydb host paths or Docker volumes. Use after inspecting local_ydb_storage_leftovers; without confirm=true this returns the cleanup plan and removes nothing.

Lifecycle