nautilus-mcp-server 0.1.0__tar.gz

nautilus_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: nautilus-mcp-server
+Version: 0.1.0
+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: 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), 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; limites globais de tamanho de query, timeout e número de linhas/registros podem ser ajustados por variáveis de ambiente (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
+
+Cada conexão tem um **identificador** (`connection_id`): letras, números e underscores (ex.: `pg_prod`, `mongo_app`).
+
+Todas as variáveis seguem o padrão:
+
+`DATABASES__<connection_id>__<atributo>`
+
+### Obrigatório por conexão
+
+- **`type`**: um entre `postgresql`, `mysql`, `mariadb` (tratado como MySQL), `sqlite`, `sqlserver`, `oracle`, `mongodb`, `redis`.
+- **Conexão**, em um dos dois formatos:
+  - **`url`**: URL completa de conexão (ex.: `postgresql://user:senha@host:5432/banco`, `mongodb://host:27017/`, `redis://host:6379/0`, arquivo/path para SQLite conforme documentação do driver).
+  - **Ou campos separados** (útil se a senha tem `@`, `:`, `/`, etc.), sempre no formato `DATABASES__<connection_id>__…`: **`host`**, **`port`**, **`user`**, **`password`**, **`database`** ou **`db`**. Exemplo com id `pg`: `DATABASES__pg__host`, **`DATABASES__pg__port`** (ex.: `5432`), `DATABASES__pg__user`, `DATABASES__pg__password`, `DATABASES__pg__database`. Em vez de `port` separado, a porta pode ir junto em `host` (ex.: `db.exemplo.com:3306`). Se **`port`** for omitida e não estiver no `host`, usam-se portas padrão por tipo (PostgreSQL 5432, MySQL 3306, SQL Server 1433, Oracle 1521, MongoDB 27017, Redis 6379).
+
+### Opcional por conexão
+
+- **`read_only`**: padrão é somente leitura.
+
+### Limites e opções globais (opcional)
+
+| Variável | Efeito (padrão se omitida) |
+|----------|----------------------------|
+| `NAUTILUS_QUERY_MAX_LENGTH` | Tamanho máximo da query SQL em caracteres (2000). |
+| `NAUTILUS_MAX_ROW_LIMIT` ou `NAUTILUS_MAX_ROWS` | Teto de linhas/registros e validação de `LIMIT` (200). |
+| `NAUTILUS_DEFAULT_ROW_LIMIT` | Limite padrão quando a tool não fixa outro (50, até o máximo). |
+| `NAUTILUS_QUERY_TIMEOUT_MS` | Timeout das operações em milissegundos (5000 se não usar a de segundos). |
+| `NAUTILUS_QUERY_TIMEOUT_SECONDS` | Alternativa ao timeout em ms (só usada se `NAUTILUS_QUERY_TIMEOUT_MS` não estiver definida). |
+| `NAUTILUS_READ_ONLY_MODE` | Modo somente leitura (`true` por padrão). |
+
+### Exemplos (`.env` ou `env` do MCP)
+
+PostgreSQL por URL:
+
+```env
+DATABASES__pg__type=postgresql
+DATABASES__pg__url=postgresql://user:password@localhost:5432/mydb
+```
+
+PostgreSQL com host e senha com caracteres especiais:
+
+```env
+DATABASES__pg__type=postgresql
+DATABASES__pg__host=localhost
+DATABASES__pg__port=5432
+DATABASES__pg__user=myuser
+DATABASES__pg__password=pa@ss:word/with
+DATABASES__pg__database=mydb
+```
+
+MySQL com host e porta no mesmo campo:
+
+```env
+DATABASES__app__type=mysql
+DATABASES__app__host=db.exemplo.com:3306
+DATABASES__app__user=app
+DATABASES__app__password=secret
+DATABASES__app__database=appdb
+```
+
+## 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**: todas as `DATABASES__…` e, se quiser, as `NAUTILUS__…`.
+
+Exemplo de trecho JSON (Cursor, VS Code com MCP, etc.):
+
+```json
+{
+  "mcpServers": {
+    "nautilus": {
+      "command": "npx",
+      "args": ["-y", "nautilus-mcp-server@latest"],
+      "env": {
+        "DATABASES__pg__type": "postgresql",
+        "DATABASES__pg__host": "localhost",
+        "DATABASES__pg__port": "5432",
+        "DATABASES__pg__user": "app",
+        "DATABASES__pg__password": "secret",
+        "DATABASES__pg__database": "appdb"
+      }
+    }
+  }
+}
+```
+
+### 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`.

nautilus_mcp_server-0.1.0/README.md

@@ -0,0 +1,139 @@
+# 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), 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; limites globais de tamanho de query, timeout e número de linhas/registros podem ser ajustados por variáveis de ambiente (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
+
+Cada conexão tem um **identificador** (`connection_id`): letras, números e underscores (ex.: `pg_prod`, `mongo_app`).
+
+Todas as variáveis seguem o padrão:
+
+`DATABASES__<connection_id>__<atributo>`
+
+### Obrigatório por conexão
+
+- **`type`**: um entre `postgresql`, `mysql`, `mariadb` (tratado como MySQL), `sqlite`, `sqlserver`, `oracle`, `mongodb`, `redis`.
+- **Conexão**, em um dos dois formatos:
+  - **`url`**: URL completa de conexão (ex.: `postgresql://user:senha@host:5432/banco`, `mongodb://host:27017/`, `redis://host:6379/0`, arquivo/path para SQLite conforme documentação do driver).
+  - **Ou campos separados** (útil se a senha tem `@`, `:`, `/`, etc.), sempre no formato `DATABASES__<connection_id>__…`: **`host`**, **`port`**, **`user`**, **`password`**, **`database`** ou **`db`**. Exemplo com id `pg`: `DATABASES__pg__host`, **`DATABASES__pg__port`** (ex.: `5432`), `DATABASES__pg__user`, `DATABASES__pg__password`, `DATABASES__pg__database`. Em vez de `port` separado, a porta pode ir junto em `host` (ex.: `db.exemplo.com:3306`). Se **`port`** for omitida e não estiver no `host`, usam-se portas padrão por tipo (PostgreSQL 5432, MySQL 3306, SQL Server 1433, Oracle 1521, MongoDB 27017, Redis 6379).
+
+### Opcional por conexão
+
+- **`read_only`**: padrão é somente leitura.
+
+### Limites e opções globais (opcional)
+
+| Variável | Efeito (padrão se omitida) |
+|----------|----------------------------|
+| `NAUTILUS_QUERY_MAX_LENGTH` | Tamanho máximo da query SQL em caracteres (2000). |
+| `NAUTILUS_MAX_ROW_LIMIT` ou `NAUTILUS_MAX_ROWS` | Teto de linhas/registros e validação de `LIMIT` (200). |
+| `NAUTILUS_DEFAULT_ROW_LIMIT` | Limite padrão quando a tool não fixa outro (50, até o máximo). |
+| `NAUTILUS_QUERY_TIMEOUT_MS` | Timeout das operações em milissegundos (5000 se não usar a de segundos). |
+| `NAUTILUS_QUERY_TIMEOUT_SECONDS` | Alternativa ao timeout em ms (só usada se `NAUTILUS_QUERY_TIMEOUT_MS` não estiver definida). |
+| `NAUTILUS_READ_ONLY_MODE` | Modo somente leitura (`true` por padrão). |
+
+### Exemplos (`.env` ou `env` do MCP)
+
+PostgreSQL por URL:
+
+```env
+DATABASES__pg__type=postgresql
+DATABASES__pg__url=postgresql://user:password@localhost:5432/mydb
+```
+
+PostgreSQL com host e senha com caracteres especiais:
+
+```env
+DATABASES__pg__type=postgresql
+DATABASES__pg__host=localhost
+DATABASES__pg__port=5432
+DATABASES__pg__user=myuser
+DATABASES__pg__password=pa@ss:word/with
+DATABASES__pg__database=mydb
+```
+
+MySQL com host e porta no mesmo campo:
+
+```env
+DATABASES__app__type=mysql
+DATABASES__app__host=db.exemplo.com:3306
+DATABASES__app__user=app
+DATABASES__app__password=secret
+DATABASES__app__database=appdb
+```
+
+## 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**: todas as `DATABASES__…` e, se quiser, as `NAUTILUS__…`.
+
+Exemplo de trecho JSON (Cursor, VS Code com MCP, etc.):
+
+```json
+{
+  "mcpServers": {
+    "nautilus": {
+      "command": "npx",
+      "args": ["-y", "nautilus-mcp-server@latest"],
+      "env": {
+        "DATABASES__pg__type": "postgresql",
+        "DATABASES__pg__host": "localhost",
+        "DATABASES__pg__port": "5432",
+        "DATABASES__pg__user": "app",
+        "DATABASES__pg__password": "secret",
+        "DATABASES__pg__database": "appdb"
+      }
+    }
+  }
+}
+```
+
+### 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`.