Metadata-Version: 2.5
Name: nz-mcp
Version: 0.1.0a1
Summary: MCP server for IBM Netezza Performance Server
Project-URL: Homepage, https://github.com/Oscarsp15/nz-mcp
Project-URL: Repository, https://github.com/Oscarsp15/nz-mcp
Project-URL: Issues, https://github.com/Oscarsp15/nz-mcp/issues
Project-URL: Changelog, https://github.com/Oscarsp15/nz-mcp/blob/main/CHANGELOG.md
Author-email: Oscar Sirlopú <oscar.sirlopu@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Oscar Sirlopú (https://github.com/Oscarsp15)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: anthropic,claude,ibm,llm,mcp,netezza,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: keyring>=25.0
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: nzpy>=1.17.7
Requires-Dist: pydantic>=2.6
Requires-Dist: sqlglot>=25.0
Requires-Dist: structlog>=24.1
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.15
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.5; extra == 'dev'
Requires-Dist: types-toml; extra == 'dev'
Description-Content-Type: text/markdown

# nz-mcp

Servidor MCP (Model Context Protocol) para **IBM Netezza Performance Server**. Permite que asistentes IA (Claude Desktop, Claude Code, Cursor, etc.) consulten Netezza con tools de responsabilidad única y permisos granulares por perfil.

🇬🇧 English version: [README.en.md](README.en.md)

> **Estado**: v0.1 en construcción. Desarrollo 100 % asistido por IA siguiendo [`AGENTS.md`](AGENTS.md).

## ¿Qué hace?

- Expone herramientas seguras para **listar bases de datos, schemas, tablas, vistas y procedimientos**.
- Ejecuta **`SELECT`** controlados con `LIMIT` forzado y `timeout`.
- Habilita **`INSERT`/`UPDATE`/`DELETE`** y DDL **solo si el perfil lo autoriza**.
- Permite **clonar procedimientos almacenados** entre bases.
- Tres barreras defensivas: tools single-purpose → `sql_guard` (sqlglot) → grants Netezza.

## Requisitos

- Python **3.11+**
- Acceso a Netezza NPS 11.x (probado con `Release 11.2.1.11-IF1`)
- Conectividad a Netezza (VPN si aplica — el MCP corre en tu máquina local)
- Cliente MCP: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code MCP, etc.

## Instalación

1. **Recomendada — [pipx](https://pypa.github.io/pipx/)** (aisla dependencias; evita choques de `typer`/`click` con otros CLI globales):

   ```bash
   pipx install nz-mcp
   nz-mcp init
   ```

   > Versión de desarrollo (último `main`, sin pasar por PyPI): `pipx install git+https://github.com/Oscarsp15/nz-mcp.git`.

2. **Desarrollo** — clona el repo y usa un venv:

   ```bash
   python -m venv .venv
   .venv\Scripts\activate
   pip install -e ".[dev]"
   ```

3. **Global con `pip`** — posible pero **desaconsejada**: otros paquetes pueden fijar versiones viejas de `typer`/`click` y romper el arranque del CLI.

Rutas completas al ejecutable para Claude Desktop (pipx vs `.venv`) y ejemplos de `claude_desktop_config.json`: [docs/guides/claude-desktop-setup.md](docs/guides/claude-desktop-setup.md).

Campos opcionales por perfil en `~/.nz-mcp/profiles.toml` (se editan a mano): `security_level` (0-3, default `2` = negocia SSL con fallback a claro; `3` = SSL obligatorio) y `ca_certs` (ruta a un bundle CA en PEM para **verificar** el certificado del servidor; si se omite, la conexión SSL se establece sin verificar el certificado). Detalle en [docs/architecture/security-model.md](docs/architecture/security-model.md).

## Configuración rápida en Claude Desktop

`claude_desktop_config.json` (ajusta `command` al `nz-mcp` de pipx o del venv, ver guía arriba):

```json
{
  "mcpServers": {
    "netezza": {
      "command": "nz-mcp",
      "args": ["serve"]
    }
  }
}
```

Reinicia Claude Desktop y pídele: *"lista las bases de datos de mi Netezza"*.

### Diagnóstico

Para revisar el entorno local (versión de Python, rutas de config, perfiles sin credenciales, keyring) **sin conectar a Netezza**:

```bash
nz-mcp doctor
```

Ejemplo de salida literal (referencia Linux, Python 3.11; rutas y perfiles ficticios ``demo`` / ``dev`` / ``prod`` — coincide con ``format_diagnostic_report`` del paquete):

```text
Diagnóstico local (nz-mcp doctor)

Versión nz-mcp: 0.1.0a0
Versión de Python: 3.11.9
Plataforma: Linux-6.8.0-generic-x86_64-with-glibc2.39
Directorio de configuración: /home/demo/.nz-mcp
  Existe: sí
  Escribible: sí
Ruta de perfiles: /home/demo/.nz-mcp/profiles.toml
  Existe: sí
Carga de perfiles OK: sí
Número de perfiles: 2
Nombres de perfiles: dev, prod
Perfil activo: prod
Backend de keyring: SecretService Keyring
  Disponible: sí
Idioma (locale): es
```

Código de salida: `0` si el entorno es usable; `1` si hay un problema crítico (p. ej. keyring no disponible).

### Diagnóstico de catálogo

Tras configurar un perfil y guardar la contraseña en el keyring, puedes validar que **todas las consultas del catálogo** (incluidas las de `catalog_overrides` en `profiles.toml`) se ejecutan contra tu Netezza con parámetros dummy seguros:

```bash
nz-mcp probe-catalog
nz-mcp probe-catalog --profile mi_perfil
nz-mcp probe-catalog --json
```

Mide duración y filas devueltas por query; si una consulta solo falla porque no existe un objeto de prueba (p. ej. tabla ficticia), se marca como advertencia, no como fallo duro. Código de salida: `0` si no hay errores graves, `1` si alguna query falla de forma definitiva o no se puede conectar.

## Tools disponibles (27)

Ver el contrato completo en [`docs/architecture/tools-contract.md`](docs/architecture/tools-contract.md).

| Categoría | Tools |
|---|---|
| Lectura | `nz_query_select`, `nz_explain`, `nz_list_databases`, `nz_list_schemas`, `nz_list_tables`, `nz_describe_table`, `nz_table_sample`, `nz_table_stats`, `nz_get_table_ddl`, `nz_list_views`, `nz_get_view_ddl`, `nz_list_procedures`, `nz_describe_procedure`, `nz_get_procedure_ddl`, `nz_export_ddl`, `nz_get_procedure_section` |
| Escritura | `nz_insert`, `nz_insert_select`, `nz_update`, `nz_delete` |
| DDL / SP | `nz_create_table`, `nz_create_table_as`, `nz_truncate`, `nz_drop_table`, `nz_clone_procedure` |
| Sesión | `nz_current_profile`, `nz_switch_profile` |

## Seguridad

Resumen del modelo en [`docs/architecture/security-model.md`](docs/architecture/security-model.md). Reportes de vulnerabilidad: [`SECURITY.md`](SECURITY.md).

## Desarrollo

Este repositorio se desarrolla **principalmente con agentes IA**. Si quieres contribuir (humano o IA), lee:

- [`AGENTS.md`](AGENTS.md) — router central, reglas inviolables.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — setup, idioma, flujo.
- [`docs/standards/`](docs/standards/) — coding, testing, git, i18n, pr-audit, issue-workflow, maintainability.

## Licencia

[MIT](LICENSE)
