Querynest

🚀 QueryNest - MongoDB多實例查詢服務

QueryNest是一個基於MCP (Model Context Protocol) 的MongoDB多實例查詢服務，它能提供智能化的數據庫結構發現、語義分析和自然語言查詢生成功能，極大地簡化了MongoDB的查詢操作。

🚀 快速開始

環境要求

• Python 3.8+
• MongoDB 4.0+
• 可選：Redis（用於緩存）

🚀 快速啟動（推薦）

使用uvx快速啟動服務：

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

# 從項目目錄啟動（推薦）
cd /path/to/QueryNest
uvx --from . --no-cache querynest-mcp

# 或從任何位置啟動
uvx --from /path/to/QueryNest --no-cache querynest-mcp

uvx啟動的優勢：

• 自動處理依賴關係
• 無需預安裝包到環境
• 使用隔離的執行環境
• 自動緩存加速後續啟動

手動安裝

1. 克隆項目

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

2. 安裝依賴

cd QueryNest
pip install -r requirements.txt

3. 配置服務

# 複製配置模板
cp config.example.yaml config.yaml

# 編輯配置文件（根據實際環境修改MongoDB連接字符串）
vim config.yaml  # 或使用您喜歡的編輯器

4. 啟動服務

# 開發模式（直接運行）
python mcp_server.py --log-level DEBUG

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

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

Docker 部署

# 構建並啟動
docker-compose up -d

# 查看日誌
docker-compose logs -f

# 停止服務
docker-compose down

✨ 主要特性

🔍 智能查詢

• 自然語言查詢：支持中文自然語言描述查詢需求
• MongoDB原生查詢：支持標準MongoDB查詢語法
• 聚合管道：支持複雜的數據聚合操作
• 查詢優化：自動優化查詢性能
• 查詢緩存：智能緩存提升查詢速度

🏢 多實例管理

• 實例發現：自動發現和連接多個MongoDB實例
• 負載均衡：智能分配查詢請求
• 健康檢查：即時監控實例狀態
• 故障轉移：自動處理實例故障
• 連接池管理：優化數據庫連接使用

🛡️ 安全控制

• 只讀權限：確保數據安全，僅支持讀取操作
• 查詢限制：限制查詢複雜度和返回數據量
• 數據脫敏：自動識別和脫敏敏感信息
• 訪問控制：基於角色的訪問權限管理
• 安全審計：記錄所有查詢操作

🧠 智能分析

• 結構發現：自動分析數據庫結構和字段類型
• 語義理解：理解字段的業務含義
• 查詢建議：提供查詢優化建議
• 性能分析：分析查詢性能和瓶頸
• 索引建議：智能推薦索引優化方案

📊 監控與指標

• 即時監控：系統性能和查詢指標即時監控
• 性能分析：詳細的查詢性能統計
• 錯誤追蹤：完整的錯誤記錄和分析
• 健康檢查：系統健康狀態評估
• 指標導出：支持多種格式的指標導出

🔧 用戶體驗

• 錯誤處理：友好的錯誤提示和建議
• 用戶反饋：完整的反饋收集系統
• 幫助系統：內置幫助文檔和FAQ
• 配置驗證：自動驗證配置文件和環境

🔌 MCP集成

• 標準協議：完全兼容MCP（Model Context Protocol）
• 工具豐富：提供完整的查詢和分析工具集
• 交互式：支持對話式查詢和探索
• 可擴展：易於集成到各種AI應用中
• 反饋工具：內置用戶反饋和幫助工具

📦 安裝指南

環境要求

• Python 3.8+
• MongoDB 4.0+
• 可選：Redis（用於緩存）

快速啟動（推薦）

使用uvx快速啟動服務：

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

# 從項目目錄啟動（推薦）
cd /path/to/QueryNest
uvx --from . --no-cache querynest-mcp

# 或從任何位置啟動
uvx --from /path/to/QueryNest --no-cache querynest-mcp

uvx啟動的優勢：

• 自動處理依賴關係
• 無需預安裝包到環境
• 使用隔離的執行環境
• 自動緩存加速後續啟動

手動安裝

1. 克隆項目

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

2. 安裝依賴

cd QueryNest
pip install -r requirements.txt

3. 配置服務

# 複製配置模板
cp config.example.yaml config.yaml

# 編輯配置文件（根據實際環境修改MongoDB連接字符串）
vim config.yaml  # 或使用您喜歡的編輯器

4. 啟動服務

# 開發模式（直接運行）
python mcp_server.py --log-level DEBUG

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

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

Docker 部署

# 構建並啟動
docker-compose up -d

# 查看日誌
docker-compose logs -f

# 停止服務
docker-compose down

💻 使用示例

基礎用法

場景1：電商數據分析

1. 發現實例和數據庫

用戶："幫我查看有哪些可用的數據庫實例"
助手：使用 discover_instances 工具

2. 分析用戶集合

用戶："分析一下電商數據庫中的用戶表結構"
助手：使用 analyze_collection 工具分析 users 集合

3. 自然語言查詢

用戶："查找最近一週註冊的活躍用戶，按註冊時間排序"
助手：使用 generate_query 生成查詢，然後用 confirm_query 執行

場景2：日誌數據查詢

1. 語義分析

用戶："幫我理解日誌集合中各個字段的含義"
助手：使用 manage_semantics 進行批量語義分析

2. 複雜聚合查詢

用戶："統計每小時的錯誤日誌數量，按時間分組"
助手：生成聚合查詢並執行

高級用法

MCP工具使用示例

1. 實例發現 (discover_instances)

發現和列出所有可用的MongoDB實例。

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

2. 數據庫發現 (discover_databases)

列出指定實例中的所有數據庫。

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

3. 集合分析 (analyze_collection)

分析指定集合的結構和字段信息。

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

4. 語義管理 (manage_semantics)

管理字段的業務語義信息。

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

5. 查詢生成 (generate_query)

根據自然語言描述生成MongoDB查詢。

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

6. 查詢確認 (confirm_query)

執行生成的查詢並返回結果。

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

📚 詳細文檔

配置說明

🔌 MCP 客戶端配置

服務啟動後，可以在支持MCP協議的AI客戶端中配置QueryNest服務以實現智能數據庫查詢功能。

1. 項目結構

QueryNest/
├── 📄 配置文件
│   ├── config.yaml              # 主配置文件
│   ├── config.example.yaml      # 配置模板
│   └── config.py               # 配置管理
├── 🚀 核心服務
│   ├── mcp_server.py           # MCP服務器入口
│   ├── start.py               # 備用啟動腳本
│   └── database/              # 數據庫連接和管理
├── 🔧 MCP工具集
│   └── mcp_tools/             # MCP協議工具實現
├── 🔍 掃描分析
│   └── scanner/               # 數據庫掃描和語義分析
├── 🛠️ 工具類
│   └── utils/                 # 驗證、錯誤處理、工作流管理
├── 🧪 測試代碼
│   └── tests/                 # 單元測試和集成測試
├── 📚 文檔
│   └── docs/                  # 完整項目文檔
├── 📦 部署
│   └── deployment/            # Docker和服務配置
└── 📜 腳本
    └── scripts/               # 數據庫檢查和測試工具

📖 詳細結構說明請參考

QueryNest 已經配置為可通過 uvx 運行的包，項目包含以下關鍵文件：

setup.py - 包配置文件：

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",
        ]
    },
)

入口點配置 - 在 mcp_server.py 中定義了 CLI 入口：

def cli_main():
    """命令行入口點"""
    # 自動查找配置文件並設置環境
    # 支持從不同目錄啟動
    asyncio.run(main())

if __name__ == "__main__":
    cli_main()

2. 本地運行步驟

步驟 1：安裝 uv 工具 如果尚未安裝uv，可通過以下方式安裝：

# 使用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

步驟 2：啟動服務 在項目根目錄下運行：

# 推薦方式：從項目目錄運行
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

步驟 3：驗證服務啟動 服務啟動成功後，您應該看到類似以下的日誌輸出：

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

3. MCP客戶端集成

uvx 工作原理： uvx 是一個現代的 Python 包執行工具，它可以：

• 自動從當前目錄（.）安裝包
• 管理臨時虛擬環境
• 執行包的入口點命令

MCP 客戶端配置要點： 對於支持MCP協議的AI客戶端，QueryNest 的配置示例：

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

Windows 配置示例：

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

關鍵配置說明：

• --from /path/to/QueryNest: 指定項目絕對路徑
• --no-cache: 確保使用最新代碼
• cwd: 設置工作目錄為項目根目錄
• querynest-mcp: 在 setup.py 中定義的入口點命令

優勢：

1. 項目路徑明確: 使用絕對路徑確保找到正確的項目
2. 自動依賴管理: uvx 自動處理所有依賴包
3. 隔離環境: 每次運行都在獨立的臨時環境中
4. 配置文件自動發現: 服務器會自動查找配置文件

4. 故障排除

常見問題及解決方案： 問題 1：uvx 命令不存在

# 解決方案：安裝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

問題 2：配置文件未找到

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

# 從示例創建配置文件
cp config.example.yaml config.yaml

# 設置環境變量
export QUERYNEST_CONFIG_PATH=/path/to/QueryNest/config.yaml

問題 3：MCP 服務連接失敗

• 檢查 MCP 客戶端配置文件格式
• 確認項目路徑是否正確（使用絕對路徑）
• 驗證 MongoDB 服務是否運行
• 檢查配置文件 config.yaml 是否存在

問題 4：MongoDB連接失敗

# 檢查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實例配置

QueryNest支持靈活的環境配置，您可以根據實際需求配置不同類型的實例：

1. 傳統環境配置（dev、test、uat、sit、staging、prod）
2. 業務系統配置（crm-prod、order-system、user-center）
3. 地域集群配置（beijing、shanghai、guangzhou）
4. 自定義環境配置（任意命名）

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

端口配置

• MCP服務: 默認使用stdio通信，無需端口；HTTP模式可配置端口（默認8000）
• MongoDB: 27017 (Docker容器內部)
• Prometheus: 9090 (監控面板)
• 應用監控: 8000 (可選，用於健康檢查)

端口說明：

• stdio模式：通過標準輸入輸出通信，無需網絡端口
• HTTP模式：通過環境變量 QUERYNEST_MCP_PORT 配置端口

元數據配置

metadata:
  instance_id: "dev-local"  # 可以是任意環境標識
  database_name: "querynest_metadata"
  collections:
    instances: "instances"
    databases: "databases"
    collections: "collections"
    fields: "fields"
    query_history: "query_history"

開發指南

項目結構

QueryNest/
├── src/
│   ├── __init__.py
│   ├── config.py              # 配置管理
│   ├── mcp_server.py          # MCP服務器主文件
│   ├── database/              # 數據庫模塊
│   │   ├── __init__.py
│   │   ├── connection_manager.py
│   │   ├── metadata_manager.py
│   │   └── query_engine.py
│   ├── scanner/               # 掃描模塊
│   │   ├── __init__.py
│   │   ├── structure_scanner.py
│   │   └── semantic_analyzer.py
│   └── mcp_tools/             # MCP工具
│       ├── __init__.py
│       ├── instance_discovery.py
│       ├── database_discovery.py
│       ├── collection_analysis.py
│       ├── semantic_management.py
│       ├── query_generation.py
│       └── query_confirmation.py
├── config.yaml                # 配置文件
├── requirements.txt           # 依賴列表
└── README.md                  # 項目文檔

添加新工具

1. 創建工具類

class NewTool:
    def get_tool_definition(self) -> Tool:
        # 定義工具接口
        pass
    
    async def execute(self, arguments: Dict[str, Any]) -> List[TextContent]:
        # 實現工具邏輯
        pass

2. 註冊工具

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

擴展語義分析

1. 添加語義規則

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

2. 自定義分析邏輯

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())
"

文檔資源

核心文檔

• 技術架構 - 詳細的技術架構說明
• 配置指南 - 配置文件說明
• 環境變量 - 環境變量配置說明

部署文檔

• 部署腳本 - 自動部署工具
• Docker部署 - 容器化部署
• 服務配置 - 系統服務配置

開發文檔

• 單元測試 - 完整的單元測試套件
• 錯誤處理 - 錯誤處理機制
• 監控指標 - 性能監控系統
• 配置驗證 - 配置驗證工具

用戶指南

• 快速開始 - 快速部署和使用
• 功能特性 - 詳細功能說明
• 故障排除 - 常見問題解決

更多資源

• Docker部署指南
• 貢獻指南
• 變更日誌
• MCP協議文檔
• MongoDB官方文檔
• Python異步編程指南

🔧 技術細節

項目信息

屬性	詳情
模型類型	基於MCP（Model Context Protocol）的MongoDB多實例查詢服務
訓練數據	未提及

項目依賴

• Python 3.8+
• MongoDB 4.0+
• 可選：Redis（用於緩存）

項目結構

QueryNest/
├── src/
│   ├── __init__.py
│   ├── config.py              # 配置管理
│   ├── mcp_server.py          # MCP服務器主文件
│   ├── database/              # 數據庫模塊
│   │   ├── __init__.py
│   │   ├── connection_manager.py
│   │   ├── metadata_manager.py
│   │   └── query_engine.py
│   ├── scanner/               # 掃描模塊
│   │   ├── __init__.py
│   │   ├── structure_scanner.py
│   │   └── semantic_analyzer.py
│   └── mcp_tools/             # MCP工具
│       ├── __init__.py
│       ├── instance_discovery.py
│       ├── database_discovery.py
│       ├── collection_analysis.py
│       ├── semantic_management.py
│       ├── query_generation.py
│       └── query_confirmation.py
├── config.yaml                # 配置文件
├── requirements.txt           # 依賴列表
└── README.md                  # 項目文檔

工具開發與擴展

添加新工具

1. 創建工具類

class NewTool:
    def get_tool_definition(self) -> Tool:
        # 定義工具接口
        pass
    
    async def execute(self, arguments: Dict[str, Any]) -> List[TextContent]:
        # 實現工具邏輯
        pass

2. 註冊工具

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

擴展語義分析

1. 添加語義規則

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

2. 自定義分析邏輯

def analyze_custom_semantics(self, field_info):
    # 實現自定義語義分析邏輯
    pass

📄 許可證

本項目採用 MIT 許可證 - 查看 LICENSE 文件瞭解詳情。

🚨 注意事項

安全考慮

⚠️ 重要提示

• 確保只允許讀取操作
• 配置適當的查詢限制
• 啟用數據脫敏功能
• 使用SSL/TLS連接
• 配置防火牆規則
• 定期更新密碼
• 避免記錄敏感信息
• 定期清理查詢歷史
• 監控異常訪問

性能優化

💡 使用建議

• 合理配置連接池大小
• 啟用連接複用
• 監控連接健康狀態
• 使用適當的索引
• 限制查詢結果數量
• 避免複雜的聚合操作
• 啟用元數據緩存
• 緩存常用查詢結果
• 定期清理過期緩存

📝 更新日誌

v1.0.0 (2024-01-01)

• 初始版本發佈
• 支持多實例MongoDB連接
• 實現基礎的結構掃描和語義分析
• 提供完整的MCP工具集
• 支持自然語言查詢生成

🔧 故障排除

常見問題

連接MongoDB失敗

# 檢查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'))
"

依賴包問題

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

🤝 貢獻指南

我們歡迎各種形式的貢獻！請查看 CONTRIBUTING.md 瞭解如何參與項目開發。

快速貢獻指南

1. Fork 項目
2. 創建功能分支 (git checkout -b feature/AmazingFeature)
3. 添加測試用例
4. 運行測試確保通過 (python -m pytest tests/ -v)
5. 提交更改 (git commit -m 'Add some AmazingFeature')
6. 推送到分支 (git push origin feature/AmazingFeature)
7. 開啟 Pull Request

開發環境

# 克隆項目
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/

🙏 致謝

感謝所有貢獻者和以下開源項目：

• PyMongo - MongoDB Python驅動
• PyYAML - YAML解析器
• psutil - 系統監控庫
• pytest - 測試框架
• MCP (Model Context Protocol)
• Motor
• Pydantic
• StructLog

---

QueryNest - 讓MongoDB查詢變得簡單智能 🚀