使用说明

FastMCP MongoDB服务器

用于 MongoDB 的 FastMCP 服务器，允许 AI 代理以动态和安全的方式与 MongoDB 银行进行交互。

特征

动态连接无需预先配置环境变量
连接检查所有工具在运行前都会检查是否有活动连接
界面直观人工智能可以根据需要配置连接
完成操作支持 CRUD、指数、聚合和统计
错误处理明确的信息和行动建议
装饰系统自动注册具有依赖注入的工具
强大的验证使用 Pydantic 进行数据验证
结构化日志使用 structlog 的高级日志系统
完整测试测试套件，模拟和58%的覆盖率
开发脚本全自动化开发环境

如何运作

1. 连接设置

人工智能必须首先使用该工具配置与MongoDB的连接 mongodb_configure_connection:

# Exemplo de uso pela IA
result = await mongodb_configure_connection(
    host="localhost",
    port=27017,
    username="usuario",
    password="senha",
    auth_source="admin"
)

2. 自动验证

所有其他工具都会自动检查是否存在活动连接。如果没有，则返回一个明确的消息，表明必须首先设置连接。

3. 可用操作

设置连接后，AI可以使用所有可用的工具：

数据库列出，创建，删除，获取信息
集合列出，创建，删除，重命名，验证
Documentos插入，搜索，更新，删除，列出
索引创建，列出，删除
统计服务器状态，系统统计

可用工具

连接工具

mongodb_configure_connection设置 MongoDB 连接
mongodb_test_connection测试当前连接
mongodb_get_connection_status: 获取连接状态
mongodb_disconnect从 MongoDB 断开连接

数据库工具

mongodb_list_databases列出全部数据库
mongodb_create_database创建新数据库
mongodb_drop_database：删除um数据库
mongodb_get_database_info从数据库获取信息

收藏工具

mongodb_list_collections: 列出数据库的集合
mongodb_create_collection创建新收藏
mongodb_drop_collection: 删除收藏
mongodb_get_collection_info从集合获取信息
mongodb_validate_collection: 有效的集合完整性
mongodb_count_documents在集合中计算文档
mongodb_aggregate: 运行聚合管道

文档工具

mongodb_list_documents列出集合中的文档
mongodb_get_document查找特定文档
mongodb_insert_document插入新文档
mongodb_update_document更新现有文档
mongodb_delete_document删除文档

索引工具

mongodb_list_indexes列出集合的索引
mongodb_create_index创建新索引
mongodb_drop_index删除索引

统计工具

mongodb_get_server_status获取 MongoDB 服务器状态
mongodb_get_system_stats获取系统统计

要求

python：3.8优
MongoDB4.0或更高版本（用于工具）
系统：Linux、macOS或Windows
内存：Mínimo 512MB内存
空间最少 100MB 磁盘

安装

本地安装

克隆仓库

创建虚拟环境：

python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

安装依赖关系：
```
pip install -r requirements.txt
```
运行服务器：
```
python -m src.main
```

光标设置

若要在 Cursor 中使用 MCP 服务器，请将以下设置添加到配置文件：

{
  "mcpServers": {
    "mongodb": {
      "command": "/caminho/para/seu/projeto/mongodb/start-mcp.sh"
    }
  }
}

当前工程示例：

{
  "mcpServers": {
    "mongodb": {
      "command": "/home/fabio/Documentos/work/codes/ai/mcp/mongodb/start-mcp.sh"
    }
  }
}

注：确保脚本 start-mcp.sh 有执行权限：

chmod +x start-mcp.sh

使用开发脚本安装（推荐）

克隆仓库
执行配置脚本：
```
./scripts/dev.sh up
```
脚本将自动创建：
- Ambiente虚拟Python
- 安装所有依赖关系
要运行服务器：
```
./scripts/dev.sh run
```

开发脚本

该项目包括有用的开发脚本：

# Usar o helper de desenvolvimento
./scripts/dev.sh up          # Configurar ambiente de desenvolvimento
./scripts/dev.sh test        # Executar testes
./scripts/dev.sh lint        # Verificar qualidade do código
./scripts/dev.sh format      # Formatar código automaticamente
./scripts/dev.sh run         # Executar servidor
./scripts/dev.sh debug       # Executar servidor em modo debug
./scripts/dev.sh clean       # Limpar ambiente completamente

# Usar comandos Make (alternativa)
make help                    # Mostrar todos os comandos disponíveis
make install-dev             # Instalar dependências de desenvolvimento
make test                    # Executar testes com cobertura
make lint                    # Verificar qualidade do código
make format                  # Formatar código automaticamente
make run                     # Executar servidor
make clean                   # Limpar arquivos temporários

人工智能使用

典型流

配置连接人工智能应该始终从设置连接开始
检查状态测试连接是否正常
执行操作按需要使用工具
Gerenciar回忆: 完成时断开连接

会话示例

# 1. Configurar conexão
connection_result = await mongodb_configure_connection(
    host="mongodb.example.com",
    port=27017,
    username="admin",
    password="secret123"
)

# 2. Verificar status
status = await mongodb_get_connection_status()

# 3. Listar databases
databases = await mongodb_list_databases()

# 4. Trabalhar com collections
collections = await mongodb_list_collections("meu_database")

# 5. Desconectar ao final
await mongodb_disconnect()

安全

我是铁杆: 没有凭据存储在代码中
动态连接每个会话可以使用不同的凭据
日志清洁: 凭据会自动隐藏在日志中
校验所有操作在运行前都经过验证
隔离连接按会话隔离
输入验证使用 Pydantic 进行强大的验证
记录Seguro记录系统：保护敏感信息

错误处理

系统提供明确的信息和行动建议：

无连接: 表示必须先设定连线
认证错误: 建议验证凭据
操作失败解释出了什么错以及如何纠正

开发

项目结构

src/
├── tools/           # Tools MCP com sistema de decorators
│   ├── tools_connection.py    # Gerenciamento de conexões
│   ├── tools_databases.py     # Operações com databases
│   ├── tools_collections.py   # Operações com collections
│   ├── tools_documents.py     # Operações com documentos
│   ├── tools_indexes.py       # Operações com índices
│   ├── tools_stats.py         # Estatísticas do servidor
│   ├── decorators.py          # Sistema de decorators
│   └── dependencies.py        # Container de dependências
├── utils/           # Utilitários (conector, logger, segurança)
├── config/          # Configurações com Pydantic
├── core/            # Exceções e lógica central
├── models/          # Schemas Pydantic para validação
├── services/        # Camada de serviços
└── server.py        # Servidor principal

添加新工具

创建文件于 src/tools/
使用装饰器 @mongodb_tool 自动停止记录
使用适当的错误处理实现函数
使用 DependencyContainer 访问依赖关系
一个工具seráregistrada automatice no servidor

装饰系统

该项目使用先进的装饰系统：

自动注册 de工具
检查连接 汽车
依赖注入 中央集权
错误处理 一致性

代码质量

# Verificar qualidade
make lint

# Formatar código
make format

# Executar testes
make test

# Verificar cobertura
make coverage

测试

该项目包括一个完整的测试套件：

# Executar todos os testes
make test

# Executar testes específicos
make test-unit          # Apenas testes unitários
make test-fast          # Testes sem cobertura

# Executar testes com script
./scripts/dev.sh test

测试覆盖：

103睾丸 成功执行
模拟单元测试
测试数据夹具
代码覆盖率 58%
HTML 和 XML 报告

依赖关系

生产

mcp>=1.10.1：框架MCP基础
fastmcp创建 MCP 服务器的库
pymongo>=4.5.0：驱动程序MongoDB para Python
pydantic>=2.0.0：数据验证
structlog>=23.0.0结构化日志

开发

pytest>=7.0.0：测试框架
pytest-asyncio>=0.21.0支持异步测试
pytest-cov>=4.0.0：测试覆盖
black>=23.0.0：代码格式
flake8>=6.0.0：林婷
mypy>=1.0.0类型检查
isort>=5.12.0：进口排序

贡献

欢迎捐款！为了贡献：

Fork 仓库
创建分支 为您的功能
进行更改 遵循代码指南
执行操作系统测试 和质量检查
Crie-um Pull请求

捐款准则

在巴西语中使用 docstrings
遵循代码模式（ Black， isort， flake8）
添加新功能测试
必要时更新文档

有用的贡献命令

# Configurar ambiente
./scripts/dev.sh up

# Verificar qualidade
make lint

# Executar testes
make test

# Formatar código
make format

许可证

MIT许可证

支持

问题：对位错误和功能
文档此README和源代码
测试：执行 make test 检查操作