local-ydb-toolkit

Reusable Codex skill for operating local-ydb deployments.

Directory listing: Local YDB MCP on Skiln.

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"

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.

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"
      }
    }
  }
}

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"
      }
    }
  }
}

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"
      }
    }
  }
}

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, tenant topology bootstrap, version upgrades, auth hardening, a

... View full README on GitHub