# local-ydb-toolkit full agent context

local-ydb-toolkit helps agents inspect, bootstrap, diagnose, harden, migrate, and upgrade local-ydb deployments without turning operational changes into blind shell scripts.

## Install options

- MCP server via npx: npx @astandrik/local-ydb-mcp@latest
- Codex skill: $skill-installer install https://github.com/astandrik/local-ydb-toolkit/tree/main/skills/local-ydb
- GitHub Action: uses: astandrik/setup-local-ydb@v1

## Agent routing

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.

Use the remote promo MCP only for product discovery, install snippets, workflow summaries, and routing guidance. It does not execute local-ydb operations.

For actual local operations, connect the local stdio MCP server with @astandrik/local-ydb-mcp@latest and keep private config paths and credentials local.

## Workflows

- Diagnostics: Inventory containers, inspect tenant status, run YDB healthcheck, read logs, and route follow-up checks by issue type. Tools: 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. Tools: 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. Tools: 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. Tools: local_ydb_prepare_auth_config, local_ydb_write_dynamic_auth_config, local_ydb_apply_auth_hardening, local_ydb_auth_check.
- Storage: Inspect storage pool placement, add groups, reduce groups by dump/rebuild/restore, and clean leftovers only after review. Tools: local_ydb_storage_placement, local_ydb_add_storage_groups, local_ydb_reduce_storage_groups, local_ydb_cleanup_storage.
- Version upgrades: Discover image tags, pull images in the background, and upgrade by dump, rebuild, restore, auth reapply, and verification. Tools: local_ydb_list_versions, local_ydb_pull_image, local_ydb_upgrade_version.

## Boundaries

- The remote promo MCP is read-only. It explains the product, install paths, workflows, routing guidance, and public links.
- 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.
- Private local-ydb config files, SSH settings, password files, and database credentials stay on the user's machine or CI runner.

The operational model is plan-first: mutating tools describe planned commands, risk, rollback, and verification before execution.

The remote promo MCP is read-only. It is an agent-friendly discovery and documentation surface, not the operational local-ydb server.

## Public API

- GET /api/product
- GET /api/install-options
- GET /api/workflows
- GET /openapi.json
- POST /mcp
- GET /.well-known/mcp
- GET /server.json