YDB MCP

YDB 的 Model Context Protocol 服务器。它允许从任何支持 MCP 的 LLM 使用 YDB 数据库。这种集成使 AI 能够执行数据库操作并与您的 YDB 实例进行自然语言交互。

使用方法

通过 uvx

uvx 是 uv run tool 的别名，允许您无需显式安装即可运行各种 Python 应用程序。以下是使用示例：

示例配置文件 (uv.json)

{
  "interpreter": {
    "name": "python",
    "version": "3"
  },
  "env": {},
  "configurations": [
    {
      "name": "启动 MCP 服务器",
      "type": "process",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "args": []
    }
  ]
}

使用 make 命令运行测试

在终端中输入以下命令以运行所有测试：

make test

提供的工具

YDB MCP 提供以下工具以便与 YDB 数据库交互：

• ydb_query: 对 YDB 数据库执行 SQL 查询

  • 参数：
    • sql: 要执行的 SQL 查询字符串

• ydb_query_with_params: 使用 JSON 参数执行带参数的 SQL 查询

  • 参数：
    • sql: 带占位符的 SQL 查询字符串
    • params: 包含参数值的 JSON 字符串

• ydb_list_directory: 列出 YDB 目录的内容

  • 参数：
    • path: 要列出内容的 YDB 目录路径

• ydb_describe_path: 获取 YDB 路径（表、目录等）的详细信息

  • 参数：
    • path: 要描述的 YDB 路径

• ydb_status: 获取 YDB 连接的当前状态

开发

项目使用 Make 作为主要开发工具，提供一致的接口以简化常见开发任务。

可用 Make 命令

示例 Makefile

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

all: clean test

clean:
    # 除所有构建 artifacts 和临时文件
    -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

测试输出控制

默认情况下，测试运行时输出verbosity为 WARNING 级别。您可以通过设置 LOG_LEVEL 环境变量来控制测试输出的详细程度：

# 以调试模式运行所有测试
make test LOG_LEVEL=DEBUG

# 以信息模式运行集成测试
make integration-tests LOG_LEVEL=INFO

# 以默认警告模式运行单元测试（默认）
make unit-tests LOG_LEVEL=WARNING

支持的输出级别：

• DEBUG: 显示所有调试消息，适用于详细测试流程
• INFO: 显示 informational 消息及更高级别
• WARNING: 默认设置，仅显示警告和错误
• ERROR: 仅显示错误消息