Provides intelligent querying capabilities across multiple MongoDB instances, including database structure discovery, semantic analysis, natural language query generation, and execution of read-only MongoDB operations like find, count, aggregate, and distinct.
Offers integration with Prometheus for real-time monitoring of system performance, query metrics, and health status, with support for metrics export and visualization.
Optional integration with Redis for query caching to improve performance when repeatedly accessing similar data from MongoDB instances.
QueryNest - MongoDB多实例查询服务
QueryNest是一个基于MCP (Model Context Protocol) 的MongoDB多实例查询服务,提供智能化的数据库结构发现、语义分析和自然语言查询生成功能。
📍 项目信息
版本: v1.0.0
状态: ✅ 生产就绪
许可证: MIT License
语言: Python 3.12+
架构: 异步/基于MCP协议
🚀 主要特性
🔍 智能查询
自然语言查询:支持中文自然语言描述查询需求
MongoDB原生查询:支持标准MongoDB查询语法
聚合管道:支持复杂的数据聚合操作
查询优化:自动优化查询性能
查询缓存:智能缓存提升查询速度
🏢 多实例管理
实例发现:自动发现和连接多个MongoDB实例
负载均衡:智能分配查询请求
健康检查:实时监控实例状态
故障转移:自动处理实例故障
连接池管理:优化数据库连接使用
🛡️ 安全控制
只读权限:确保数据安全,仅支持读取操作
查询限制:限制查询复杂度和返回数据量
数据脱敏:自动识别和脱敏敏感信息
访问控制:基于角色的访问权限管理
安全审计:记录所有查询操作
🧠 智能分析
结构发现:自动分析数据库结构和字段类型
语义理解:理解字段的业务含义
查询建议:提供查询优化建议
性能分析:分析查询性能和瓶颈
索引建议:智能推荐索引优化方案
📊 监控与指标
实时监控:系统性能和查询指标实时监控
性能分析:详细的查询性能统计
错误追踪:完整的错误记录和分析
健康检查:系统健康状态评估
指标导出:支持多种格式的指标导出
🔧 用户体验
错误处理:友好的错误提示和建议
用户反馈:完整的反馈收集系统
帮助系统:内置帮助文档和FAQ
配置验证:自动验证配置文件和环境
🔌 MCP集成
标准协议:完全兼容MCP(Model Context Protocol)
工具丰富:提供完整的查询和分析工具集
交互式:支持对话式查询和探索
可扩展:易于集成到各种AI应用中
反馈工具:内置用户反馈和帮助工具
📦 安装部署
环境要求
Python 3.8+
MongoDB 4.0+
可选:Redis(用于缓存)
🚀 快速开始
快速启动(推荐)
使用uvx快速启动服务:
uvx启动的优势:
自动处理依赖关系
无需预安装包到环境
使用隔离的执行环境
自动缓存加速后续启动
手动安装
克隆项目
安装依赖
配置服务
启动服务
Docker 部署
⚙️ 配置说明
🔌 MCP 客户端配置
服务启动后,可以在支持MCP协议的AI客户端中配置QueryNest服务以实现智能数据库查询功能。
1. 项目结构
📖 详细结构说明请参考
docs/PROJECT_STRUCTURE.md
QueryNest 已经配置为可通过 uvx 运行的包,项目包含以下关键文件:
setup.py - 包配置文件:
入口点配置 - 在 mcp_server.py
中定义了 CLI 入口:
2. 本地运行步骤
步骤 1:安装 uv 工具
如果尚未安装uv,可通过以下方式安装:
步骤 2:启动服务
在项目根目录下运行:
步骤 3:验证服务启动
服务启动成功后,您应该看到类似以下的日志输出:
3. MCP客户端集成
uvx 工作原理:
uvx 是一个现代的 Python 包执行工具,它可以:
自动从当前目录(
.
)安装包管理临时虚拟环境
执行包的入口点命令
MCP 客户端配置要点:
对于支持MCP协议的AI客户端,QueryNest 的配置示例:
Windows 配置示例:
关键配置说明:
--from /path/to/QueryNest
: 指定项目绝对路径--no-cache
: 确保使用最新代码cwd
: 设置工作目录为项目根目录querynest-mcp
: 在 setup.py 中定义的入口点命令
优势:
项目路径明确: 使用绝对路径确保找到正确的项目
自动依赖管理: uvx 自动处理所有依赖包
隔离环境: 每次运行都在独立的临时环境中
配置文件自动发现: 服务器会自动查找配置文件
4. 故障排除
常见问题及解决方案:
问题 1:uvx 命令不存在
问题 2:配置文件未找到
问题 3:MCP 服务连接失败
检查 MCP 客户端配置文件格式
确认项目路径是否正确(使用绝对路径)
验证 MongoDB 服务是否运行
检查配置文件
config.yaml
是否存在
问题 4:MongoDB连接失败
验证配置成功:
MongoDB实例配置
QueryNest支持灵活的环境配置,您可以根据实际需求配置不同类型的实例:
传统环境配置(dev、test、uat、sit、staging、prod)
业务系统配置(crm-prod、order-system、user-center)
地域集群配置(beijing、shanghai、guangzhou)
自定义环境配置(任意命名)
安全配置
环境变量配置
支持多实例独立的环境变量管理:
端口配置
MCP服务: 默认使用stdio通信,无需端口;HTTP模式可配置端口(默认8000)
MongoDB: 27017 (Docker容器内部)
Prometheus: 9090 (监控面板)
应用监控: 8000 (可选,用于健康检查)
端口说明:
stdio模式:通过标准输入输出通信,无需网络端口
HTTP模式:通过环境变量
QUERYNEST_MCP_PORT
配置端口
元数据配置
🛠️ MCP工具使用
1. 实例发现 (discover_instances)
发现和列出所有可用的MongoDB实例。
2. 数据库发现 (discover_databases)
列出指定实例中的所有数据库。
3. 集合分析 (analyze_collection)
分析指定集合的结构和字段信息。
4. 语义管理 (manage_semantics)
管理字段的业务语义信息。
5. 查询生成 (generate_query)
根据自然语言描述生成MongoDB查询。
6. 查询确认 (confirm_query)
执行生成的查询并返回结果。
📊 使用示例
场景1:电商数据分析
发现实例和数据库
分析用户集合
自然语言查询
场景2:日志数据查询
语义分析
复杂聚合查询
🔧 开发指南
项目结构
添加新工具
创建工具类
注册工具
扩展语义分析
添加语义规则
自定义分析逻辑
🚨 注意事项
安全考虑
权限控制
确保只允许读取操作
配置适当的查询限制
启用数据脱敏功能
网络安全
使用SSL/TLS连接
配置防火墙规则
定期更新密码
数据保护
避免记录敏感信息
定期清理查询历史
监控异常访问
性能优化
连接管理
合理配置连接池大小
启用连接复用
监控连接健康状态
查询优化
使用适当的索引
限制查询结果数量
避免复杂的聚合操作
缓存策略
启用元数据缓存
缓存常用查询结果
定期清理过期缓存
📝 更新日志
v1.0.0 (2024-01-01)
初始版本发布
支持多实例MongoDB连接
实现基础的结构扫描和语义分析
提供完整的MCP工具集
支持自然语言查询生成
🧪 测试
运行所有测试
运行单元测试
测试覆盖率
环境验证
📚 文档
核心文档
部署文档
开发文档
用户指南
📚 更多资源
🔧 故障排除
常见问题
3. 连接MongoDB失败
4. 配置文件错误
环境变量配置
QueryNest 支持以下环境变量:
环境变量 | 描述 | 默认值 | 示例 |
| 配置文件路径 |
|
|
| 日志级别 |
|
,
,
,
|
| MCP传输方式 |
|
,
|
| HTTP模式主机地址 |
|
|
| HTTP模式端口 |
|
|
| 生产环境MongoDB密码 | - |
|
| 测试环境MongoDB密码 | - |
|
| 开发环境MongoDB密码 | - |
|
Linux/macOS 示例:
Windows 示例:
5. 依赖包问题
6. 权限和路径问题
日志分析
查看详细日志:
性能调优
🤝 贡献指南
我们欢迎各种形式的贡献!请查看 CONTRIBUTING.md 了解如何参与项目开发。
快速贡献指南
Fork 项目
创建功能分支 (
git checkout -b feature/AmazingFeature
)添加测试用例
运行测试确保通过 (
python -m pytest tests/ -v
)提交更改 (
git commit -m 'Add some AmazingFeature'
)推送到分支 (
git push origin feature/AmazingFeature
)开启 Pull Request
开发环境
📄 许可证
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
🙏 致谢
感谢所有贡献者和以下开源项目:
📞 支持
如果您遇到问题或有建议,请:
🙏 致谢
感谢以下项目和贡献者:
QueryNest - 让MongoDB查询变得简单智能 🚀
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A MongoDB multi-instance query service built on MCP that provides intelligent database structure discovery, semantic analysis, and natural language query generation for MongoDB databases.
Related MCP Servers
- -securityAlicense-qualityFull featured MCP Server for MongoDB database analysis.Last updated -69187MIT License
- AsecurityAlicenseAqualityAn MCP server that enables users to create and manage MongoDB Atlas clusters, users, and network access through natural language commands.Last updated -62011MIT License
- -securityAlicense-qualityAn MCP server that enables large language models to interact directly with MongoDB databases, allowing them to query collections, inspect schemas, and manage data through natural language.Last updated -109MIT License
- -securityFlicense-qualityAllows interaction with MongoDB collections and documents through standardized MCP requests, supporting operations like listing collections, reading documents with filtering, and executing structured queries.Last updated -