Agent-ready local YDB operations

local-ydb-toolkit

Docker-based local-ydb operations for AI agents, with plan-first MCP tools, a reusable Codex skill, and a GitHub Action for disposable YDB in CI.

Use MCP serverAgent guide
npx @astandrik/local-ydb-mcp@latest
MCP server@astandrik/local-ydb-mcp
Execution modelplan first, confirm later
CI pathsetup-local-ydb@v1
$local_ydb_status_report
inventoryread-only
healthcheckselfCheckResult
mutationplan returned
confirm: true required for execution
YDBDocker local-ydb target stays on your machine

Ask AI about local-ydb-toolkit

Open an AI assistant with product, install, MCP, and project context.
ChatGPTPerplexityClaudeGoogle AI ModeGrok

Safety model

Hosted discovery, local execution

Remote promo MCP

The remote promo MCP is read-only. It explains the product, install paths, workflows, routing guidance, and public links.

Local stdio MCP

Actual local-ydb operations stay in the local stdio MCP server. Mutating tools return a plan first and execute only when confirm: true is supplied by an approved user workflow.

Credentials stay local

Private local-ydb config files, SSH settings, password files, and database credentials stay on the user's machine or CI runner.

Agent access

Install paths for different jobs

MCP server via npx

Run the local stdio MCP server where Docker, SSH profiles, and local-ydb credentials are available.

npx @astandrik/local-ydb-mcp@latest

Codex skill

Install the local-ydb skill so Codex has task-specific runbooks, topology guidance, and safety constraints.

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

GitHub Action

Bootstrap disposable local-ydb in GitHub Actions and export endpoint/database variables for later steps.

uses: astandrik/setup-local-ydb@v1

Examples

Projects using local-ydb

Coverage

Workflow summaries agents can route to tools

Diagnostics

Inventory containers, inspect tenant status, run YDB healthcheck, read logs, and route follow-up checks by issue type.

  • local_ydb_status_report
  • local_ydb_healthcheck
  • local_ydb_container_logs

Bootstrap

Start a root /local database or a tenant-oriented topology when GraphShard, storage workflows, or dynamic nodes are required.

  • local_ydb_check_prerequisites
  • local_ydb_bootstrap_root_database
  • local_ydb_bootstrap

Schema

Generate strict YDB table DDL, validate it through the official SDK, and apply only after explicit confirmation.

  • local_ydb_generate_schema
  • local_ydb_apply_schema

Auth hardening

Prepare native auth config, write dynamic-node auth artifacts, apply hardening, and verify anonymous access is closed.

  • local_ydb_prepare_auth_config
  • local_ydb_write_dynamic_auth_config
  • local_ydb_apply_auth_hardening

Storage

Inspect storage pool placement, add groups, reduce groups by dump/rebuild/restore, and clean leftovers only after review.

  • local_ydb_storage_placement
  • local_ydb_add_storage_groups
  • local_ydb_reduce_storage_groups

Version upgrades

Discover image tags, pull images in the background, and upgrade by dump, rebuild, restore, auth reapply, and verification.

  • local_ydb_list_versions
  • local_ydb_pull_image
  • local_ydb_upgrade_version

Routing

Complementary to ydb/ydb-mcp

Use local-ydb-toolkit when the user needs to operate Docker-based local-ydb environments: prerequisite checks, bootstrap, diagnostics, schema DDL generation/validation/application, auth hardening, storage workflows, dump/restore, or version upgrades.

Use ydb/ydb-mcp when the user already has a reachable YDB endpoint and needs general database-level work such as ad hoc SQL queries, query explanations, directory listing, or path inspection.

Official ydb/ydb-mcpMCP boundary