YDB

🚀 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 作为主要开发工具，提供一致的接口以简化常见开发任务。

示例 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：仅显示错误消息

📄 许可证

本项目采用 Apache 2.0 许可证。