niuzaishu/QueryNest

# 安装uv工具（如果尚未安装）
pip install uv

# 从项目目录启动（推荐）
cd /path/to/QueryNest
uvx --from . --no-cache querynest-mcp

# 或从任何位置启动
uvx --from /path/to/QueryNest --no-cache querynest-mcp

git clone https://github.com/niuzaishu/QueryNest.git
cd QueryNest

cd QueryNest
pip install -r requirements.txt

# 复制配置模板
cp config.example.yaml config.yaml

# 编辑配置文件（根据实际环境修改MongoDB连接字符串）
vim config.yaml  # 或使用您喜欢的编辑器

# 开发模式（直接运行）
python mcp_server.py --log-level DEBUG

# 生产模式（使用uvx，推荐）
uvx --from . --no-cache querynest-mcp

# 设置配置文件路径（如果需要）
export QUERYNEST_CONFIG_PATH=/path/to/config.yaml

# 构建并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

setup(
    name="querynest",
    version="1.0.0",
    description="QueryNest MCP MongoDB查询服务",
    py_modules=["mcp_server", "config"],
    packages=["database", "scanner", "mcp_tools", "utils"],
    entry_points={
        "console_scripts": [
            "querynest-mcp=mcp_server:cli_main",
        ]
    },
)

def cli_main():
    """命令行入口点"""
    # 自动查找配置文件并设置环境
    # 支持从不同目录启动
    asyncio.run(main())

if __name__ == "__main__":
    cli_main()

# 使用pip安装（推荐）
pip install uv

# 或使用官方安装脚本（Linux/macOS）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证安装
uvx --version

# 推荐方式：从项目目录运行
cd /path/to/QueryNest
uvx --from . --no-cache querynest-mcp

# 或设置环境变量指定配置文件
export QUERYNEST_CONFIG_PATH=/path/to/QueryNest/config.yaml
uvx --from /path/to/QueryNest --no-cache querynest-mcp

{"event": "Starting QueryNest MCP server initialization", "config_path": "/path/to/config.yaml"}
{"event": "Configuration loaded successfully", "instances_count": 2}
{"event": "MCP tools initialized successfully", "tools_count": 13}
{"event": "Starting stdio MCP server"}

{
  "mcpServers": {
    "QueryNest": {
      "command": "uvx",
      "args": ["--from", "/path/to/QueryNest", "--no-cache", "querynest-mcp"],
      "cwd": "/path/to/QueryNest",
      "env": {
        "QUERYNEST_CONFIG_PATH": "/path/to/QueryNest/config.yaml",
        "QUERYNEST_LOG_LEVEL": "INFO"
      }
    }
  }
}

{
  "mcpServers": {
    "QueryNest": {
      "command": "uvx",
      "args": ["--from", "C:\\path\\to\\QueryNest", "--no-cache", "querynest-mcp"],
      "cwd": "C:\\path\\to\\QueryNest",
      "env": {
        "QUERYNEST_CONFIG_PATH": "C:\\path\\to\\QueryNest\\config.yaml"
      }
    }
  }
}

# 解决方案：安装uv工具
pip install uv

# 或使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# 验证安装
uvx --version

# 检查配置文件是否存在
ls -la config.yaml

# 从示例创建配置文件
cp config.example.yaml config.yaml

# 设置环境变量
export QUERYNEST_CONFIG_PATH=/path/to/QueryNest/config.yaml

# 检查MongoDB服务状态
python scripts/check_db.py

# 手动测试MongoDB连接
python -c "
from pymongo import MongoClient
client = MongoClient('mongodb://localhost:27017/')
print('MongoDB连接成功')
"

# 检查MongoDB服务是否运行
# Linux/macOS
sudo systemctl status mongod
# Windows
net start | findstr -i mongo

# 测试本地运行
cd /path/to/QueryNest
uvx --from . --no-cache querynest-mcp --help

# 检查项目结构
ls -la setup.py mcp_server.py config.yaml

# 验证入口点
python -c "
from mcp_server import cli_main
print('Entry point OK')
"

# 测试完整启动流程
uvx --from . --no-cache querynest-mcp --log-level INFO

mongodb:
  instances:
    prod-main:
      name: "生产主库"
      environment: "prod"
      connection_string: "mongodb://admin:password@localhost:27017/admin"
      database: "prod_database"
      description: "生产环境主数据库"
      status: "active"
      tags: ["production", "primary"]
    
    crm-prod:
      name: "CRM生产库"
      environment: "crm-prod"
      connection_string: "mongodb://crm_user:${CRM_DB_PASSWORD}@crm-db.company.com:27017/admin"
      database: "crm_database"
      description: "CRM系统生产数据库"
      status: "active"
      tags: ["crm", "production"]
    
    beijing-cluster:
      name: "北京集群"
      environment: "beijing"
      connection_string: "mongodb://readonly:${BEIJING_DB_PASSWORD}@beijing-mongo.company.com:27017/admin"
      database: "beijing_database"
      description: "北京地域MongoDB集群"
      status: "active"
      tags: ["beijing", "cluster"]

security:
  permissions:
    allowed_operations:
      - "find"
      - "count"
      - "aggregate"
      - "distinct"
    forbidden_operations:
      - "insert"
      - "update"
      - "delete"
  limits:
    max_documents: 1000
    query_timeout: 30
  data_masking:
    enabled: true
    sensitive_field_patterns:
      - "password"
      - "email"
      - "phone"

# .env 文件示例
# 传统环境密码
PROD_DB_PASSWORD=your_prod_password
TEST_DB_PASSWORD=your_test_password
DEV_DB_PASSWORD=your_dev_password

# 业务系统密码
CRM_DB_PASSWORD=your_crm_password
ORDER_DB_PASSWORD=your_order_password
USER_CENTER_DB_PASSWORD=your_user_center_password

# 地域集群密码
BEIJING_DB_PASSWORD=your_beijing_password
SHANGHAI_DB_PASSWORD=your_shanghai_password
GUANGZHOU_DB_PASSWORD=your_guangzhou_password

# 自定义实例密码
CUSTOM_INSTANCE_PASSWORD=your_custom_password

metadata:
  instance_id: "dev-local"  # 可以是任意环境标识
  database_name: "querynest_metadata"
  collections:
    instances: "instances"
    databases: "databases"
    collections: "collections"
    fields: "fields"
    query_history: "query_history"

{
  "name": "discover_instances",
  "arguments": {
    "include_health": true,
    "include_stats": true
  }
}

{
  "name": "discover_databases",
  "arguments": {
    "instance_id": "prod-main",
    "include_collections": true,
    "exclude_system": true
  }
}

{
  "name": "analyze_collection",
  "arguments": {
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "users",
    "include_semantics": true,
    "include_examples": true,
    "rescan": false
  }
}

{
  "name": "manage_semantics",
  "arguments": {
    "action": "batch_analyze",
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "users"
  }
}

{
  "name": "generate_query",
  "arguments": {
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "orders",
    "query_description": "查找今天创建的订单，按金额降序排列",
    "query_type": "auto",
    "limit": 50
  }
}

{
  "name": "confirm_query",
  "arguments": {
    "instance_id": "prod-main",
    "database_name": "ecommerce",
    "collection_name": "orders",
    "query_type": "find",
    "mongodb_query": {
      "filter": {"created_at": {"$gte": "2024-01-01T00:00:00Z"}},
      "sort": {"amount": -1},
      "limit": 50
    },
    "explain": true
  }
}

class NewTool:
    def get_tool_definition(self) -> Tool:
        # 定义工具接口
        pass
    
    async def execute(self, arguments: Dict[str, Any]) -> List[TextContent]:
        # 实现工具逻辑
        pass

# 在 mcp_server.py 中注册
new_tool = NewTool(...)
self.tools["new_tool"] = new_tool

# 在 semantic_analyzer.py 中添加
self.semantic_patterns.update({
    "custom_field": {
        "patterns": [r"custom_.*"],
        "meaning": "自定义字段",
        "confidence": 0.8
    }
})

def analyze_custom_semantics(self, field_info):
    # 实现自定义语义分析逻辑
    pass

python -m pytest tests/ -v

# 测试连接管理器
python -m pytest tests/unit/test_connection_manager.py -v

# 测试查询引擎
python -m pytest tests/unit/test_query_engine.py -v

# 测试元数据管理器
python -m pytest tests/unit/test_metadata_manager.py -v

# 测试数据库扫描器
python -m pytest tests/unit/test_database_scanner.py -v

# 测试MCP工具
python -m pytest tests/unit/test_mcp_tools.py -v

pip install pytest-cov
python -m pytest tests/ --cov=src --cov-report=html

# 验证启动环境
python -c "
from utils.startup_validator import validate_startup_environment
print(validate_startup_environment())
"

# 检查MongoDB服务状态
sudo systemctl status mongod

# 测试网络连接
telnet <mongodb_host> <mongodb_port>

# 验证认证信息
mongo --host <host> --port <port> -u <username> -p

# 验证配置文件
python -c "
from utils.config_validator import ConfigValidator
validator = ConfigValidator()
print(validator.validate_config_file('config.yaml'))
"

# 设置配置文件路径
export QUERYNEST_CONFIG_PATH=/path/to/QueryNest/config.yaml

# 设置日志级别
export QUERYNEST_LOG_LEVEL=DEBUG

# MCP传输模式（目前仅支持stdio）
export QUERYNEST_MCP_TRANSPORT=stdio

# CMD
set QUERYNEST_CONFIG_PATH=C:\path\to\QueryNest\config.yaml
set QUERYNEST_LOG_LEVEL=DEBUG

# PowerShell
$env:QUERYNEST_CONFIG_PATH="C:\path\to\QueryNest\config.yaml"
$env:QUERYNEST_LOG_LEVEL="DEBUG"

cd /path/to/QueryNest

# 重新安装依赖
pip install -r requirements.txt --force-reinstall

# 检查Python版本
python --version

# 检查关键包安装状态
pip list | grep -E "(mcp|pymongo|motor)"

# 检查文件是否存在
ls -la config.yaml mcp_server.py

# 检查目录权限
ls -ld . logs/

# 修复权限（如果需要）
chmod 755 .
chmod 644 config.yaml
chmod +x mcp_server.py

# 创建日志目录（如果不存在）
mkdir -p logs/

# 查看应用日志
tail -f logs/querynest.log

# 查看错误日志
tail -f logs/error.log

# 查看系统日志
journalctl -u querynest -f

# 查看系统资源使用
top
htop

# 查看MongoDB性能
mongotop
mongostat

# 查看网络连接
netstat -an | grep :27017

# 克隆项目
git clone <repository_url>
cd QueryNest

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# 安装开发依赖
pip install -r requirements.txt
pip install pytest pytest-cov black flake8

# 运行代码格式化
black src/ tests/

# 运行代码检查
flake8 src/ tests/