YDB

🚀 YDB MCP

The Model Context Protocol server for YDB. It enables the use of YDB databases from any MCP - supported LLM, allowing AI to perform database operations and interact with your YDB instances in natural language.

🚀 Quick Start

Run via uvx

uvx is an alias for uv run tool, which allows you to run various Python applications without explicit installation. Here is an example of usage:

Example Configuration File (uv.json)

{
  "interpreter": {
    "name": "python",
    "version": "3"
  },
  "env": {},
  "configurations": [
    {
      "name": "Start MCP Server",
      "type": "process",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "args": []
    }
  ]
}

Run Tests with make Command

Enter the following command in the terminal to run all tests:

make test

💻 Usage Examples

Basic Usage

The above steps demonstrate the basic usage of YDB MCP, including running via uvx and using make to run tests.

📚 Documentation

Provided Tools

YDB MCP provides the following tools for interacting with YDB databases:

• ydb_query: Execute SQL queries on the YDB database

  • Parameters:
    • sql: The SQL query string to be executed

• ydb_query_with_params: Execute parameterized SQL queries using JSON parameters

  • Parameters:
    • sql: The SQL query string with placeholders
    • params: A JSON string containing parameter values

• ydb_list_directory: List the contents of a YDB directory

  • Parameters:
    • path: The path of the YDB directory whose contents are to be listed

• ydb_describe_path: Get detailed information about a YDB path (table, directory, etc.)

  • Parameters:
    • path: The YDB path to be described

• ydb_status: Get the current status of the YDB connection

🔧 Technical Details

Development

The project uses Make as the main development tool, providing a consistent interface to simplify common development tasks.

Available Make Commands

.PHONY: all clean test unit-tests integration-tests run-server lint format install dev

all: clean test

clean:
    # Remove all build artifacts and temporary files
    -rm -rf build/
    -rm -rf *.egg-info/

test:
    LOG_LEVEL?=WARNING
    pytest tests/ --log-level=$(LOG_LEVEL)

unit-tests:
    LOG_LEVEL?=WARNING
    pytest tests/unit/ --log-level=$(LOG_LEVEL) -v

integration-tests:
    YDB_ENDPOINT?=grpc://localhost:2136
    YDB_DATABASE?=local
    MCP_HOST?=127.0.0.1
    MCP_PORT?=8989
    pytest tests/integration/ --log-level=$(LOG_LEVEL) -v

run-server:
    YDB_ENDPOINT?=grpc://localhost:2136
    YDB_DATABASE?=local
    python -m ydb_mcp_server $(ARGS)

lint:
    flake8 .
    mypy .

format:
    black .
    isort .

install:
    pip install -e .

dev:
    pip install -e .[dev]

.DEFAULT_GOAL := all

Test Output Control

By default, the test output verbosity is set to the WARNING level. You can control the detail level of test output by setting the LOG_LEVEL environment variable:

# Run all tests in debug mode
make test LOG_LEVEL=DEBUG

# Run integration tests in info mode
make integration-tests LOG_LEVEL=INFO

# Run unit tests in the default warning mode (default)
make unit-tests LOG_LEVEL=WARNING

Supported output levels:

• DEBUG: Display all debug messages, suitable for detailed testing processes
• INFO: Display informational messages and higher levels
• WARNING: The default setting, only display warnings and errors
• ERROR: Only display error messages

📄 License

This project is licensed under the Apache 2.0 License.