Metadata-Version: 2.4
Name: nautilus-mcp-server
Version: 0.2.3
Summary: Add your description here
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.27.2
Requires-Dist: oracledb>=4.0.1
Requires-Dist: psycopg[binary]>=3.3.4
Requires-Dist: pymongo>=4.17.0
Requires-Dist: pymssql>=2.3.13
Requires-Dist: pymysql>=1.2.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: redis>=8.0.0

# Nautilus MCP Server

## O que é

É um servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io) que fala com o assistente pela entrada/saída padrão (**stdio**). Está publicado no npm como **`nautilus-mcp-server`** e precisa de **Node.js 18 ou superior**. Recomenda-se executar com **`npx -y nautilus-mcp-server@latest`** para o `npx` resolver sempre o dist-tag **latest** (evita reutilizar cache de instalação antiga). Se precisar travar em uma versão exata, use `nautilus-mcp-server@<versão>` no lugar de `@latest`.

## O que faz

- **Bancos SQL** (PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle): listar tabelas, ver colunas e índices, executar apenas consultas de leitura (`SELECT` / `WITH`) com validação de segurança e limite de linhas, e pequenas amostras de dados.
- **MongoDB**: listar coleções, buscar documentos com filtro em JSON e paginação, ver índices da coleção, amostra rápida.
- **Redis**: listar chaves (com padrão e cursor), ler valores conforme o tipo da chave (string, hash, lista, set, sorted set, **stream** e **RedisJSON**), com decode seguro de binário e teto de bytes por valor; amostra rápida.

Em muitas respostas o cliente recebe também **`structuredContent`** (JSON estruturado) além do texto, para quem consome colunas, linhas, documentos ou chaves sem depender só de texto formatado.

Comportamento padrão: **somente leitura** no SQL; tamanho de query, timeout e número de linhas/registros têm defaults globais no YAML (bloco `defaults`) e podem ser sobrescritos por conexão (veja abaixo).

## Tools

| Tool | Função |
|------|--------|
| **`db_list_connections`** | Lista os `connection_id` configurados, tipo de engine e `read_only`. Use antes das demais tools para escolher o id correto. |
| **`db_list_resources`** | SQL: tabelas. MongoDB: coleções (parâmetro `database` obrigatório). Redis: chaves (`key_pattern` e `cursor` opcionais). |
| **`db_get_metadata`** | SQL: metadados/colunas da tabela. MongoDB: amostra de documentos. Redis: tipo e amostra do valor da chave. |
| **`db_describe_indexes`** | Índices de uma tabela SQL ou de uma coleção MongoDB. |
| **`db_query_sql`** | Executa `SELECT`/`WITH` em conexões SQL. `output_format`: `table`, `json` ou `csv`; `limit` opcional (respeitando o teto global). |
| **`db_fetch_documents`** | MongoDB: `find` com `filter_json`, `limit` e `skip`. |
| **`db_read_cache`** | Redis: leitura conforme o tipo da chave. |
| **`db_peek_sample`** | Até três registros: linhas (SQL), documentos (MongoDB) ou amostra (Redis). |

## Resources (MCP)

| URI | Conteúdo |
|-----|----------|
| **`nautilus://connections`** | JSON com `{ "connections": [...] }` (mesmos campos que `db_list_connections`: `connection_id`, `type`, `read_only`). |

## Como configurar as conexões

As conexões ficam num **único arquivo YAML**. O servidor lê o caminho de `NAUTILUS_CONFIG` (padrão `./nautilus.yaml`) e **valida na subida, falhando cedo** com mensagem clara se algo estiver inconsistente. Veja `nautilus.yaml.example` para um modelo completo.

Cada conexão tem um **identificador** (`connection_id`): letras, números e underscores (ex.: `pg_prod`, `mongo_app`).

> **Segredos sempre por `${VAR}`.** Qualquer valor pode referenciar uma variável de ambiente com `${NOME}`; o servidor a resolve do ambiente e **falha cedo** se ela não existir (a mensagem cita só o nome, nunca o valor). Nunca coloque senha em texto puro no YAML.

### Estrutura

```yaml
defaults:                 # valores herdados por todas as conexões (todos opcionais)
  read_only: true
  query_timeout_ms: 30000
  connect_timeout_ms: 5000
  max_rows: 200
  default_rows: 50
  query_max_length: 2000

connections:
  <connection_id>:
    type: <engine>        # obrigatório
    # ...atributos da conexão...
```

### Por conexão

- **`type`** (obrigatório): um entre `postgresql`, `mysql`, `mariadb` (tratado como MySQL), `sqlite`, `sqlserver`, `oracle`, `mongodb`, `redis`.
- **Conexão**, em um dos dois formatos:
  - **`url`**: URL completa (ex.: `postgresql://user:senha@host:5432/banco`). Para SQLite use `url: ":memory:"` ou `url: "file:..."`, ou o atalho `path:`.
  - **Ou campos separados** (útil se a senha tem `@`, `:`, `/`): `host`, `port`, `user`, `password`, `database` (ou `db`). A porta pode ir junto em `host` (`db.exemplo.com:3306`); omitida, usa-se a padrão por tipo (PostgreSQL 5432, MySQL 3306, SQL Server 1433, Oracle 1521, MongoDB 27017, Redis 6379).
- **Overrides opcionais do `defaults`**: `read_only`, `query_timeout_ms`, `connect_timeout_ms`. Redis aceita ainda `socket_timeout_ms` (teto por operação; padrão = `query_timeout_ms`).

### Exemplos

PostgreSQL por URL, com timeout maior só nesta conexão:

```yaml
connections:
  pg:
    type: postgresql
    url: "${PG_URL}"
    query_timeout_ms: 60000
```

PostgreSQL por componentes (senha vem do ambiente), não somente-leitura:

```yaml
connections:
  pg_app:
    type: postgresql
    host: localhost
    port: 5432
    user: myuser
    password: "${PG_APP_PASSWORD}"
    database: mydb
    read_only: false
```

Redis com teto de operação:

```yaml
connections:
  cache:
    type: redis
    url: "${REDIS_URL}"
    socket_timeout_ms: 10000
```

## Como usar nos clientes

Em qualquer cliente MCP com transporte **stdio**, configure:

- **Comando**: `npx` (no Windows, se necessário, use o caminho completo de `npx.cmd`).
- **Argumentos**: use `["-y", "nautilus-mcp-server@latest"]`. Opcionalmente fixe versão com `["-y", "nautilus-mcp-server@<versão>"]`.
- **Variáveis de ambiente**: `NAUTILUS_CONFIG` (caminho do YAML) e os segredos referenciados por `${VAR}` dentro dele.

Exemplo de trecho JSON (Cursor, VS Code com MCP, etc.):

```json
{
  "mcpServers": {
    "nautilus": {
      "command": "npx",
      "args": ["-y", "nautilus-mcp-server@latest"],
      "env": {
        "NAUTILUS_CONFIG": "C:/caminho/para/nautilus.yaml",
        "PG_APP_PASSWORD": "secret"
      }
    }
  }
}
```

### Cursor

**Configurações → MCP** (ou JSON de MCP do projeto): adicione o servidor com `command`, `args` e `env` como acima.

### Claude Desktop

Use o mesmo esquema de `command`, `args` e `env` no arquivo de configuração MCP do aplicativo. Caminho e formato exato variam por sistema; veja a [documentação da Anthropic sobre MCP](https://docs.anthropic.com/en/docs/agents-and-tools/mcp).

### Claude Code e outras IDEs

Mesma ideia: processo `npx` (ou Node apontando para o pacote instalado), argumentos `-y` e `nautilus-mcp-server@latest`, e o mesmo bloco de variáveis de ambiente.

### Problemas comuns no Windows com `npx`

Se aparecer **`EPERM`**, **`TAR_ENTRY_ERROR`** ou **`MODULE_NOT_FOUND`** (por exemplo em dependências sob o cache do npm), feche o cliente MCP, apague a pasta **`%LocalAppData%\npm-cache\_npx`** e tente de novo. Outra opção estável é instalar o pacote globalmente (`npm install -g nautilus-mcp-server`) e configurar o MCP para executar o **`node`** com o caminho do `cli.js` dessa instalação global, em vez de `npx`.
