tzero-mcp

Motor de reducción de contexto de codebase AST empresarial con hasta un 95% de ahorro de tokens y salvaguardas de seguridad de cero fugas.

GitHub

Documentación

⚡ SİBER AKADEMİ — T-ZERO CONTEXT ARCHITECT V3

🇬🇧 English Documentation • 🇹🇷 Türkçe Dokümantasyon

Constructor de Contexto de Código de Grado Empresarial, Analizador de Firmas AST y Reductor de Tokens.
Diseñado para Cursor, VS Code Copilot, Cline, Antigravity IDE, Claude Code y ChatGPT. Reduce la sobrecarga de ingesta de contexto LLM en hasta un 95% mientras preserva el esquema estructural de tu código (firmas, jerarquía, dependencias).
Incluye un servidor nativo Model Context Protocol (MCP) para agentes autónomos de codificación con IA.

Desarrollador: Toprak Ahmet Aydoğmuş
LinkedIn: Toprak Ahmet Aydoğmuş
Bio y Hub: https://hopp.bio/siberegitim
Repositorio GitHub: https://github.com/toprakahmetaydogmus/TZeroAlgorithm

T-Zero AST Token Reduction Benchmark

⚡ Prueba Visual: Ingesta Cruda vs. Poda AST de T-Zero (Reproducible)

Modo de Análisis	Volumen de Contexto Crudo	Carga Útil Podada por T-Zero	Ratio de Reducción de Tokens	Delta de Costo / Consulta
Escaneo Completo del Repositorio	`166,996 tokens`	`8,465 tokens`	-94.9%	-$0.3963 / consulta

Ejecútalo tú mismo sin conexión (costo $0): python tzero.py --savings

🚀 Inicio Rápido en 1 Línea

pip install tzero-mcp

O configúralo directamente en tu Cliente MCP (Cursor, Claude Desktop, Windsurf o Antigravity IDE):

{
  "mcpServers": {
    "tzero": {
      "command": "tzero-mcp"
    }
  }
}

O ejecuta una inspección CLI sin conexión inmediatamente (costo $0, 100% Zero-Leak):

python tzero.py --savings

🇬🇧 English

Tabla de Contenidos

Arquitectura de Seguridad (Garantía 100% Zero-Leak)
Servidor Model Context Protocol (MCP)
Arquitectura del Sistema
Aspectos Destacados y Capacidades Principales
Instalación y Configuración
Guía de Uso (GUI y CLI)
Atajos de Teclado
Estructura del Proyecto
Suite de Pruebas Automatizadas y CI/CD
Licencia y Créditos

🔒 Arquitectura de Seguridad (Garantía 100% Zero-Leak)

[!IMPORTANT] El Algoritmo T-Zero contiene estrictamente CERO claves API hardcodeadas, personales o públicas, ni credenciales en cualquier parte del repositorio.
Los principios de defensa en profundidad y cero confianza se aplican por defecto.

Cifrado de Credenciales a Nivel de SO (Motor Keyring):
- Las claves API nunca se escriben en archivos de configuración de texto plano ni en registros.
- Se almacenan a través de la biblioteca multiplataforma keyring, que utiliza el almacén nativo del SO:
- Windows: Administrador de Credenciales de Windows
- macOS: Llavero de Apple
- Linux: API Secret Service (GNOME Keyring / KWallet vía DBus)
Cero Telemetría y Privacidad Absoluta:
- Tu código fuente, tokens, estructura de archivos y credenciales API nunca se envían a servidores de telemetría, análisis o desarrolladores de terceros.
- El tráfico de red saliente se inicia exclusivamente directamente desde tu cliente al endpoint del proveedor de IA que elijas (NVIDIA, OpenAI, Google, Anthropic, OpenRouter o localhost Ollama).
- El panel web local opcional (--web) se vincula solo a 127.0.0.1; su página carga una fuente web de Google Fonts en tu navegador.
Copia de Seguridad del Keyring con Contraseña Ofuscada:
- Las claves API se pueden respaldar en un archivo binario .dat protegido con contraseña. Esto utiliza un XOR de clave repetitiva simple (sin sal, no es criptografía fuerte), así que mantén el archivo privado y trátalo como un secreto. Está en git-ignore por defecto.
Detección de Variables de Entorno de 12 Factores:
- Detecta y hereda automáticamente las variables de entorno estándar del sistema cuando están presentes:
  - NVIDIA_API_KEY
  - OPENAI_API_KEY
  - GEMINI_API_KEY
  - OPENROUTER_API_KEY
  - ANTHROPIC_API_KEY
Modo de Ejecución en Seco 100% Sin Conexión (Costo $0):
- Genera árboles de contexto completos, mapas de firmas AST y planos markdown sin conexión a internet, claves API o suscripciones a proveedores de IA.

🤖 Servidor Model Context Protocol (MCP)

T-Zero V3 integra nativamente un servidor estándar Model Context Protocol (MCP) (tzero_mcp.py) que opera sobre stdio. Esto permite a los agentes de IA en Cursor, Claude Desktop, Antigravity IDE y Cline inspeccionar, podar y consultar de forma autónoma el código de tu proyecto antes de escribir una sola línea de código.

🛠 Herramientas MCP Disponibles (16 Herramientas Autónomas)

Nombre de la Herramienta	Parámetros	Propósito
`get_project_context_tree`	`project_root`, `reduction_mode`, `max_tokens`, `include_file_contents`	Escanea el espacio de trabajo y construye un árbol de contexto jerárquico T-Zero de múltiples niveles (T-1 a T-4). Reduce los tokens hasta en un 95%.
`query_module_dependencies`	`project_root`, `file_path`	Analiza las dependencias de importación entrantes y salientes en Python, TypeScript, Go, Rust, Java, C# y C++.
`query_architecture_boundaries`	`project_root`, `extra_guidance`	Consulta los límites arquitectónicos T-4 activos, las restricciones operativas y las reglas Zero-Leak para agentes de codificación.
`generate_architecture_blueprint`	`project_root`	Genera una especificación completa de arquitectura del sistema (`ARCHITECTURE.md`) con diagramas de topología Mermaid en vivo.
`generate_repo_map`	`project_root`, `max_tokens`	Produce un mapa de símbolos AST ultracomprimido (clases, métodos, firmas) optimizado para inyección de prompts.
`audit_codebase_quality`	`project_root`, `file_path`	Ejecuta una verificación estática de olores de código AST y un escaneo de fugas de secretos (detecta funciones >30 líneas, variables globales, docstrings faltantes).
`find_code_duplicity`	`project_root`, `min_lines`	Escanea el espacio de trabajo para identificar bloques de código repetidos/duplicados entre archivos para refactorización.
`estimate_token_cost`	`text`, `project_root`, `reduction_mode`	Calcula el recuento exacto de tokens y la comparación de costos en USD entre OpenAI, Claude, Groq, NVIDIA NIM y Ollama ($0).
`analyze_change_impact`	`target_symbol`, `project_root`	Rastrea definiciones de símbolos AST, cascadas de llamadores, dependientes entrantes y calcula una puntuación de riesgo de 0-100.
`enforce_architecture_boundaries`	`project_root`, `rules_file`	Valida los límites de importación modulares contra `tzero.rules.json` para prevenir la erosión arquitectónica.
`search_codebase_semantic`	`query`, `project_root`, `top_k`	Búsqueda semántica de código y motor RAG híbrido BM25 + TF-IDF 100% privado, local en memoria (costo $0, 0 fugas).
`export_agent_rules`	`project_root`	Genera reglas con 1 clic para Cursor, Windsurf, Claude Code, Cline y Copilot.
`get_token_savings_metrics`	`project_root`, `team_size`	Calcula el ratio cuantitativo de reducción de tokens, ahorros de costos mensuales/anuales y métricas de ROI para desarrolladores de equipo.
`get_incremental_diff_context`	`base_ref`, `project_root`	Extrae un contexto de diff ultracompacto con símbolos modificados y radio de explosión descendente para revisiones de PR (reducción de tokens del 98%+).
`prune_code_snippet`	`code`, `file_path_or_ext`, `reduction_mode`	Podas fragmentos de código arbitrarios en memoria en firmas AST compactas sobre la marcha (reducción del 80-95%).
`verify_zero_leak_security`	`project_root`, `target_file`, `code_snippet`	Escáner de seguridad 100% Zero-Leak para claves API hardcodeadas (OpenAI, Anthropic, Gemini, NVIDIA, GitHub) y secretos (costo $0, 0 fugas).

📦 Recursos MCP en Vivo

tzero://architecture: Plano de arquitectura Mermaid en tiempo real y diagrama de topología de módulos.
tzero://boundaries: Límites de capas arquitectónicas T-4 activas, reglas de seguridad y restricciones.
tzero://token-roi: Ratio cuantitativo de reducción de tokens y ahorros económicos de ROI para equipos de ingeniería.

🧭 Prompts MCP

tzero_grounding: Inyecta reglas estrictas de límites arquitectónicos, pautas de integridad modular y mandatos de seguridad Zero-Leak en la sesión del sistema del agente.

📊 Benchmark de Tokens (Ejemplo de Archivo Único)

Medido en tzero_v3.py en el commit 4846dcf con el estimador count_tokens_precise del proyecto (aproximadamente characters / 4):

Entrada	Estimación de fuente completa	Firmas AST ultra	Reducción estimada
`tzero_v3.py` (224,150 caracteres)	56,037 tokens	3,088 tokens	94.5%

Reprodúcelo con: python -c "from pathlib import Path; from tzero_v3 import TokenReducer,count_tokens_precise; s=Path('tzero_v3.py').read_text(encoding='utf-8'); r=TokenReducer.reduce(s,'tzero_v3.py',mode='ultra'); print(count_tokens_precise(s),count_tokens_precise(r))". Esta es una comparación de archivo único, solo firmas, no un benchmark de repositorio completo o calidad de respuesta; los tokenizadores de proveedores y la sobrecarga de respuesta MCP varían. Usa balanced o busca la fuente cuando los detalles de implementación importen.

🔌 Añade T-Zero a Clientes MCP

T-Zero se ejecuta como un servidor stdio local con soporte completo para Cursor, Claude Desktop, Antigravity IDE, VS Code, Windsurf, Cline y Roo Code.

🚀 Opción 1: Inicio Rápido de 1 Minuto con pip (PyPI Oficial — Multiplataforma)

La forma más rápida y estándar de instalar y ejecutar T-Zero en Windows, macOS o Linux:

pip install tzero-mcp

Una vez instalado, usa cualquiera de las interfaces disponibles:

Auto-Configurar Todos los IDEs Detectados (Cursor, Claude, Antigravity, VS Code, Cline):
```
tzero-add-mcp
```
Asistente de Terminal Interactivo (CLI):
```
tzero --cli
```
Panel GUI Cyberpunk de Escritorio:
```
tzero-gui
# or:
tzero --gui
```
Configuración Manual del Cliente MCP: Simplemente añade este bloque stdio a la configuración de tu cliente (mcp_config.json, claude_desktop_config.json o configuración de Cursor):
```
{
  "mcpServers": {
    "tzero": {
      "command": "tzero-mcp"
    }
  }
}
```

🌐 Opción 1B: Instalador Web Instantáneo de 1 Clic (Configuración Cero)

Windows (PowerShell):

irm https://raw.githubusercontent.com/toprakahmetaydogmus/TZeroAlgorithm/main/install.ps1 | iex

Linux / macOS (Bash / Zsh):

curl -fsSL https://raw.githubusercontent.com/toprakahmetaydogmus/TZeroAlgorithm/main/install.sh | bash

Registro MCP de Smithery:

npx -y @smithery/cli install tzero --client cursor

⚡ Opción 2: Instalador de Windows de 1 Clic con Cero Dependencias (Binario Independiente)

Descarga AddMCP.exe directamente desde Última Versión (v3.0.7):

Modo GUI: Haz doble clic en AddMCP.exe. Detecta automáticamente todos los IDEs instalados en tu computadora y los configura con un solo clic.
Modo CLI / Sin Interfaz: Ejecuta AddMCP.exe --all (se instala automáticamente en todos los IDEs detectados sin GUI).
Cero Requisitos: No requiere Python, pip, pipx ni Git. Incluye el runtime independiente TZeroMCP.exe internamente.

📦 Opción 3: Lanzamiento Remoto vía pipx (Multiplataforma: Windows, macOS, Linux)

El primer lanzamiento descarga el paquete fijado v3.0.7 desde GitHub sin clonar el repositorio. Instala Python 3.9+ y pipx:

Instalar pipx en Windows

Abre PowerShell y ejecuta:

py -m pip install --user pipx
py -m pipx ensurepath

Reinicia el cliente después de la instalación. Las configuraciones de Windows a continuación llaman a py -m pipx directamente, por lo que no dependen de que pipx.exe esté en PATH. Para macOS/Linux, instala pipx usando las instrucciones oficiales de la plataforma y ejecuta pipx ensurepath.

Instalación de 1 Clic en Cursor

Elige el enlace para tu sistema operativo, aprueba la configuración en Cursor y luego habilita tzero en Configuración → MCP o Personalizar → MCP.

Si Cursor no abre el instalador, usa Configuración → MCP → Añadir MCP Personalizado y pega el JSON apropiado para tu plataforma a continuación.

Windows:

{
  "mcpServers": {
    "tzero": {
      "command": "py",
      "args": ["-m", "pipx", "run", "--spec", "https://github.com/toprakahmetaydogmus/TZeroAlgorithm/archive/refs/tags/v3.0.7.zip", "tzero-mcp"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "tzero": {
      "command": "pipx",
      "args": ["run", "--spec", "https://github.com/toprakahmetaydogmus/TZeroAlgorithm/archive/refs/tags/v3.0.7.zip", "tzero-mcp"]
    }
  }
}

Claude Desktop

Abre Configuración → Desarrollador → Editar Configuración.
Fusiona el bloque JSON de Windows o macOS/Linux correspondiente de arriba en el objeto mcpServers existente; mantén otras entradas de servidores.
Guarda el archivo y cierra/reabre completamente Claude Desktop.
Vuelve a Configuración → Desarrollador y confirma que tzero está en ejecución.

Ubicaciones de configuración: Windows %APPDATA%\Claude\claude_desktop_config.json; macOS ~/Library/Application Support/Claude/claude_desktop_config.json.

Google Antigravity IDE

Abre Configuración → Personalizaciones → Servidores MCP instalados.
Agregar MCP abre la tienda de MCP de Antigravity. Si T-Zero aparece allí, selecciona Agregar; de lo contrario, configúralo como un servidor stdio personalizado a continuación.
Agrega la entrada de Windows o macOS/Linux tzero de los bloques JSON anteriores a mcp_config.json de Antigravity, conservando otras entradas de mcpServers. En Windows, la configuración del usuario es %USERPROFILE%\.gemini\config\mcp_config.json (o ~/.gemini/antigravity/mcp_config.json).
Guarda/recarga los servidores MCP y aprueba las herramientas cuando se te solicite.

⚡ Comando Slash y Skill de Antigravity (`/tzero`)

T-Zero incluye un skill nativo de Antigravity (.agents/skills/tzero/SKILL.md y ~/.gemini/config/skills/tzero/SKILL.md). Simplemente escribe /tzero en el prompt de chat de Antigravity para ver las acciones disponibles o ejecuta:

/tzero o /tzero tree — Construye un árbol de contexto de múltiples niveles con reducción de tokens del 95%
/tzero audit — Ejecuta verificación de code smells AST y auditoría de seguridad 100% Zero-Leak
/tzero arch — Genera ARCHITECTURE.md con diagramas Mermaid en vivo
/tzero deps [file] — Traza la topología de dependencias de módulos
/tzero impact <symbol> — Calcula la puntuación de radio de impacto antes de refactorizar
/tzero rules — Genera .cursorrules, .clinerules, instrucciones de Copilot
/tzero search <query> — Ejecuta búsqueda semántica de código BM25 local 100% privada
/tzero savings — Calcula métricas de ROI de tokens del equipo de desarrollo
/tzero diff [ref] — Contexto incremental de git diff para revisiones de PR con radio de impacto aguas abajo (reducción de tokens del 98%+)

Consulta la guía oficial de MCP de Antigravity para conocer el flujo de Configuración actual y el esquema de configuración.

VS Code Copilot

Ejecuta MCP: Agregar servidor desde la Paleta de comandos (Ctrl+Shift+P).
Elige Comando (stdio), luego ingresa el comando de la plataforma (py en Windows; pipx en macOS/Linux) y los mismos argumentos mostrados arriba.
Guarda en el .mcp.json del espacio de trabajo o .vscode/mcp.json, luego confía/inicia tzero desde la vista de Servidores MCP.

Para .vscode/mcp.json, VS Code usa un objeto servers de nivel superior y requiere type: "stdio":

{
  "servers": {
    "tzero": {
      "type": "stdio",
      "command": "py",
      "args": ["-m", "pipx", "run", "--spec", "https://github.com/toprakahmetaydogmus/TZeroAlgorithm/archive/refs/tags/v3.0.7.zip", "tzero-mcp"]
    }
  }
}

Claude Code, Cline, Roo Code, Windsurf y Otros Clientes MCP

Abre la configuración del servidor MCP de cada cliente, elige Agregar/Editar servidor y fusiona la entrada de Windows o macOS/Linux mcpServers correspondiente de arriba. Claude Code puede usar la misma entrada en un .mcp.json en la raíz del proyecto; Cline, Roo Code y Windsurf proporcionan sus propios paneles de configuración de servidores MCP. Reinicia/recarga el cliente y aprueba el servidor.

Solo Cursor proporciona actualmente una URL de instalación pública verificada con un clic para servidores stdio locales arbitrarios. Los otros clientes usan sus archivos de configuración/ajustes documentados; el JSON anterior está listo para pegar.

Inicio CLI

python tzero_mcp.py
# Or: python main.py --mcp

🏗 Arquitectura del Sistema

flowchart TD
    A["Source Code Repository"] --> B["CodebaseScanner"]
    B --> C{"Token Reducer"}
    C -->|"Ultra Mode"| D["Function & Class Signatures Only"]
    C -->|"Balanced Mode"| E["Signatures + Control Flow Lines"]
    C -->|"None Mode"| F["Full Original Source Code"]
    
    B --> G["AST Static Code Auditor"]
    G --> H["Code Smells & Complexity Report"]
    
    B --> I["Dependency Analyzer"]
    I --> J["Import Graph & Module Tree"]
    
    B --> K["Workspace Duplicity Finder"]
    K --> L["Clone & Duplicate Code Blocks"]

    D --> M{"Context Generator"}
    J --> M
    L --> M
    M -->|"Offline Dry-Run"| N["Local T-Zero Context Tree"]
    M -->|"AI Provider Mode"| O["LLM Prompt Synthesizer"]
    O --> P["NVIDIA NIM / OpenAI / Gemini / Anthropic / Ollama"]
    P --> Q["High-Fidelity README.md, AGENTS.md, & ARCHITECTURE.md"]

    M --> R["Model Context Protocol (MCP)"]
    R --> S["Cursor / Claude Desktop / Antigravity / Cline"]

🌟 Aspectos Destacados y Capacidades Principales

1. Motor Multi-LLM de Proveedores

NVIDIA NIM: deepseek-v4.1-flash, deepseek-coder-6.7b, nemotron-70b, mistral-large-2, llama-3.2-90b-vision
OpenAI: gpt-4o, gpt-4o-mini, o3-mini, o1
Google Gemini: gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
Anthropic: claude-3-7-sonnet-20250219, claude-3-5-sonnet, claude-3-5-haiku
OpenRouter: Puerta de enlace universal para claude-3.7-sonnet, gpt-4o, deepseek-r1
Ollama Local: llama3:latest, mistral:latest, phi3:latest, qwen2.5:latest (100% local, sin conexión, privado y gratuito)

2. Reductor de Tokens AST (Ahorro de Tokens de hasta el 95%)

Modo Ultra: Elimina los detalles internos de implementación mientras conserva jerarquías de clases, decoradores, docstrings, sugerencias de tipo y encabezados completos de funciones/clases/importaciones de Python de múltiples líneas.
Modo Equilibrado: Conserva las firmas junto con las declaraciones críticas de flujo de control y manejo de excepciones.
Modo Ninguno: Preserva el 100% del código fuente original.
Idiomas compatibles: Python, JavaScript, TypeScript, JSX/TSX, C/C++, Go, Rust, HTML, CSS, Bash, Batch, JSON, YAML.

3. Herramientas Avanzadas de Análisis de Código Base

Esquematizador de Clases y Métodos AST: Genera una jerarquía estructurada de cada clase, método, lista de argumentos y decorador.
Auditor de Código Estático: Señala al instante docstrings faltantes, funciones que superan las 30 líneas, rutinas con 6+ parámetros y el uso de la palabra clave global (admite tanto def síncrono como async def asíncrono).
Analizador de Dependencias: Escanea declaraciones de importación AST para compilar un mapa de dependencias de módulos externos e internos.
Buscador de Duplicados en el Espacio de Trabajo: Identifica bloques duplicados idénticos de 6+ líneas en todo el código base.
Motor de Refactorización AST: Realiza renombrados globales seguros de funciones e identificadores en archivos del espacio de trabajo mediante transformación de nodos AST.

4. Integración Git VCS y Telemetría Visual

Clasificador de Historial de Commits: Clasifica automáticamente los commits recientes (Agregado, Corregido, Refactorizado, Actualizado).
Visor de Diff Git con Código de Colores: Muestra cambios no confirmados en tiempo real (git diff HEAD) con resaltado de sintaxis.
Administrador Git Integrado: Prepara, confirma y cambia de rama directamente desde la GUI.
Grafo de Nodos de Dependencias Interactivo: Visualización de nodos basada en física y arrastrable de las relaciones entre archivos.
Telemetría de CPU y RAM en Vivo: Telemetría de hardware en tiempo real que monitorea la sobrecarga de recursos del sistema.
Gráfico de Donut de Tokens: Desglose visual dinámico de tipos de archivo, volumen de código y consumo de tokens.

5. UI Futurista, FX de Partículas Dinámicas y SFX de Audio Háptico

8 Temas Curados:
- 🌌 Glass Dark (Acentos cian esmerilado)
- ⚡ Neon Cyberpunk (Rosa neón vibrante y azul eléctrico)
- 🖤 Midnight OLED (Negro puro 100% #000000 para cero fatiga visual)
- 🟢 Matrix Terminal (Verde fósforo clásico #00ff41)
- 🌆 Synthwave 80s (Magenta láser, naranja neón y cian retro)
- ❄️ Nordic Frost (Pizarra ártica y azul glaciar)
- ☕ Solarized Amber (Espresso profundo cálido y ámbar dorado)
- 🕹 Siber Retro (Estética hacker clásica)
Motor de Partículas Dinámicas de 4 Modos:
- 🌌 Estrellas: Campo estelar 3D de alta velocidad con deformación de profundidad.
- 🟢 Lluvia Matrix: Glifos de código verde en cascada digital.
- 🌐 Cyber Grid: Onda de estructura alámbrica de horizonte en perspectiva retro.
- ⬛ Minimalista Sólido: Lienzo oscuro sin distracciones con 0% de consumo de CPU.
Motor SFX Háptico: Retroalimentación auditiva no bloqueante para acciones (escaneos, copias, exportaciones, errores) con un interruptor de encabezado instantáneo (🔊 SFX ON / 🔇 SFX OFF).
Notificaciones Flotantes Cyberpunk: Banners de estado no intrusivos que te informan sobre guardados y exportaciones sin interrumpir tu flujo de trabajo.

6. Centro de Exportación de Contexto Multi-Formato

README.md: Documentación arquitectónica integral.
AGENTS.md / CLAUDE.md: Plano de contexto estructurado especialmente para asistentes de codificación de IA (Cursor, Antigravity IDE, Claude Code, Cline, Copilot) que contiene reglas de arquitectura, resúmenes AST y convenciones del espacio de trabajo.
ARCHITECTURE.md: Plano de arquitectura del sistema con diagramas de topología Mermaid generados automáticamente.
REPO_MAP.txt: Mapa de tokens de símbolos AST altamente comprimido diseñado para pegar directamente en prompts de chat de LLM.
README.html: Documentación HTML con estilo cyberpunk de modo oscuro que se abre en tu navegador web predeterminado con un clic.
Presupuesto de Tokens en Vivo y Estimador de Costos USD: Contador de tokens en tiempo real y costo estimado de API por modelo (OpenAI, Claude, Groq, NVIDIA NIM, Ollama).

📦 Instalación y Configuración

Método 1: Instalador de Un Clic (Recomendado para Windows)

install_requirements.bat

Aprovisiona automáticamente Python 3.12 (si no se detecta), configura un entorno virtual e instala todas las dependencias sin requerir configuración manual.

Método 2: Ejecutable Portátil Independiente (.exe)

Descarga TZeroAlgorithm.exe para la aplicación de escritorio. Para agregar MCP a los IDEs detectados, ejecuta AddMCP.exe; incluye TZeroMCP.exe, no necesita Python ni pipx, conserva las entradas de servidor existentes y respalda los archivos de configuración antes de modificarlos. TZeroMCP.exe también está disponible por separado para configuración manual.

Método 3: Paquete Python / Instalación con pip

# Install from a cloned checkout
git clone https://github.com/toprakahmetaydogmus/TZeroAlgorithm.git
cd TZeroAlgorithm
pip install .
# The package provides the `tzero` and `tzero-mcp` commands.

# After the package is published to PyPI:
pipx install tzero-algorithm

El nombre del proyecto en PyPI es tzero-algorithm; tzero-mcp es el comando instalado. Hasta la primera carga en PyPI, usa la configuración de GitHub pipx run --spec anterior.

Verificación automática de dependencias: al iniciar, T-Zero verifica sus paquetes requeridos e instala los que faltan o están desactualizados (el progreso va a stderr, por lo que el stdio de MCP permanece limpio). Opta por no participar con TZERO_NO_AUTO_INSTALL=1. Ejecuta python main.py --doctor para una verificación de salud completa. La GUI de escritorio necesita tkinter; la CLI y el servidor MCP funcionan sin él, por lo que los servidores sin cabeza, Docker y CI están bien.

🎮 Guía de Uso (GUI y CLI)

1. Interfaz Gráfica de Usuario (GUI)

# Launch via Python
python main.py

# Or launch via Windows batch script
run.bat

# Or launch via legacy wrapper
python tzero.py

2. Interfaz de Línea de Comandos (CLI)

T-Zero V3 ofrece un conjunto completo de banderas CLI para entusiastas de la terminal y pipelines automatizados de CI/CD:

# 1. Start Model Context Protocol (MCP) stdio server
python main.py --mcp

# 2. Scan directory and print metric table
python main.py --scan .

# 3. Audit codebase quality and detect code smells
python main.py --audit .

# 4. Generate offline context tree locally ($0 API cost)
python main.py --dry-run --dir . --output README.md

# 5. Generate AI Agent Rules & Blueprint (AGENTS.md / CLAUDE.md)
python main.py --export-agents AGENTS.md --dir .

# 6. Generate System Architecture Specification (ARCHITECTURE.md)
python main.py --export-arch ARCHITECTURE.md --dir .

# 7. Generate Compressed Token Symbol Map (REPO_MAP.txt)
python main.py --export-repomap REPO_MAP.txt --dir .

# 8. Generate Cyberpunk Styled HTML Preview (README.html)
python main.py --export-html README.html --dir .

# 9. Launch Interactive Terminal Wizard
python main.py --cli

# 10. Print current engine version
python main.py --version

# 11. Analyze blast radius of changing a symbol
python main.py --impact MyClass

# 12. Private local semantic code search (BM25 + TF-IDF)
python main.py --search "retry logic"

# 13. Enforce architecture boundaries in CI (exits 1 on violation)
python main.py --enforce-boundaries

# 14. Token reduction metrics and team ROI
python main.py --savings

# 15. Export native agent rules (.cursorrules, .clinerules, Copilot)
python main.py --export-agent-rules

# 16. Launch local web dashboard (default port 7300)
python main.py --web

# 17. Launch the desktop GUI
python main.py --gui

# 18. Check Python, dependencies, tkinter, git and keyring (installs what is missing)
python main.py --doctor

⌨️ Atajos de Teclado

Atajo	Acción
`Ctrl+S`	Escanear Directorio del Espacio de Trabajo Activo
`Ctrl+G`	Generar / Compilar Árbol de Contexto
`Ctrl+C`	Copiar Contexto Generado al Portapapeles
`Ctrl+R`	Actualizar Registro Git y Ramas

📂 Estructura del Proyecto

TZeroAlgorithm/
├── .mcp.json                    # Claude Code MCP integration
├── .cursor/
│   └── mcp.json                 # Pre-configured Cursor MCP integration
├── .github/
│   └── workflows/
│       ├── ci.yml               # Automated GitHub Actions test workflow
│       └── release.yml          # Builds TZeroAlgorithm.exe, TZeroMCP.exe, AddMCP.exe, and publishes releases
├── tests/
│   ├── __init__.py
│   ├── test_addmcp.py            # Installer config merge/backup and detection tests
│   ├── test_analyzer.py         # AST analysis and code smell unit tests
│   ├── test_cli.py              # CLI integration tests
│   ├── test_config.py           # Configuration & Keyring security tests
│   ├── test_exports.py          # Multi-format exports & token cost tests
│   ├── test_deps.py             # Dependency bootstrap & doctor tests
│   ├── test_features.py         # Feature module tests (impact, rules, search, ROI)
│   ├── test_headless.py         # No-tkinter, MCP output & secret-scan regression tests
│   ├── test_generator.py        # Template engine & context generator tests
│   ├── test_gui.py              # Tkinter GUI headless smoke tests
│   ├── test_mcp.py              # Model Context Protocol (MCP) server tests
│   ├── test_providers.py        # Multi-provider LLM adapter tests
│   └── test_scanner.py          # TokenReducer & CodebaseScanner tests
├── build_exe.bat                # One-click Windows PyInstaller build script
├── compile.py                   # PyInstaller asset packaging pipeline
├── addmcp.py                    # Windows installer for supported IDE MCP configs
├── install_requirements.bat     # Windows automated setup script
├── LICENSE                      # MIT Open Source License
├── main.py                      # Primary execution entrypoint (CLI & GUI)
├── pyproject.toml               # Modern PEP 517/621 packaging metadata
├── README.md                    # Bilingual comprehensive documentation
├── requirements.txt             # Production Python dependencies
├── run.bat                      # Windows quick-launch runner
├── siber_akademi.ico            # High-resolution application icon
├── tzero.py                     # Backward-compatibility API wrapper
├── tzero.rules.json             # T-4 architecture boundary rules
├── tzero_deps.py                # Dependency bootstrap and --doctor
├── tzero_features.py            # Impact analysis, boundary rules, semantic search, ROI, web dashboard
├── tzero_mcp.py                 # Standard Model Context Protocol (MCP) Server
├── tzero_v3.py                  # Monolithic portable T-Zero V3 core engine
└── WALKTHROUGH.md               # Technical architecture walkthrough

🧪 Suite de Pruebas Automatizadas y CI/CD

Ejecuta todas las pruebas unitarias y de integración localmente:

python -m unittest discover -s tests -v

Salida esperada:

Ran 79 tests in ~4s
OK (the GUI smoke test is skipped when no display is available)

GitHub Actions ejecuta automáticamente esta suite de pruebas en cada push y pull request en ejecutores de Ubuntu y Windows bajo Python 3.10, 3.11 y 3.12.

🛡️ Acción de GitHub (GitHub Marketplace)

T-Zero está disponible como una Acción de GitHub oficial (action.yml) para auditar código base, hacer cumplir límites de arquitectura y prevenir fugas de secretos directamente en tus pipelines de CI/CD:

name: T-Zero Quality Guard

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: T-Zero Architecture & Quality Guard
        uses: toprakahmetaydogmus/TZeroAlgorithm@v4.0.0-beta.1
        with:
          workspace: '.'
          audit: 'true'
          enforce-boundaries: 'false'

📄 Licencia y Créditos

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para conocer los términos completos.

Toprak Ahmet Aydoğmuş — Siber Akademi

💼 LinkedIn: toprak-ahmet-aydoğmuş
🔗 Enlaces y Bio: hopp.bio/siberegitim
🐙 GitHub: @toprakahmetaydogmus

🇹🇷 Türkçe

İçindekiler

Şifreli Güvenlik Mimarisi (%100 Zero-Leak Garantisi)
Model Context Protocol (MCP) Sunucusu
Sistem Mimarisi
Öne Çıkan Yetenekler & Özellikler
Kurulum ve Başlangıç
Kullanım Kılavuzu (GUI & CLI)
Klavye Kısayolları
Proje Dizin Ağacı
Otomatik Test Süreci ve CI/CD
Lisans ve Geliştirici Bilgileri

🔒 Şifreli Güvenlik Mimarisi (%100 Zero-Leak Garantisi)

[!IMPORTANT] T-Zero Algorithm, kod tabanında kesinlikle sabit kodlanmış (hardcoded), şahsi veya umumi hiçbir API anahtarı veya kimlik bilgisi barındırmaz.
Uygulama varsayılan olarak sıfır güven (zero-trust) ilkelerini uygular.

Cifrado de Identidad a Nivel de Sistema Operativo (Motor de Llavero del SO):
- Las claves API nunca se almacenan en archivos de texto plano (.env, .json, .txt) ni en registros.
- Se almacenan en el repositorio nativo del sistema operativo a través de la biblioteca multiplataforma keyring:
- Windows: Administrador de Credenciales de Windows
- macOS: Llavero de Apple
- Linux: API de Secret Service (GNOME Keyring / KWallet - a través de DBus)
Cero Telemetría y Privacidad Total de Datos:
- Sus códigos fuente, datos de tokens, jerarquía de archivos o claves API nunca se transmiten a servidores de telemetría, análisis o desarrolladores de terceros.
- Todo el tráfico de red saliente se realiza únicamente mediante HTTPS directo al endpoint oficial del proveedor de IA que usted designe (NVIDIA, OpenAI, Google, Anthropic, OpenRouter u Ollama local).
- El panel web local opcional (--web) solo se ejecuta en 127.0.0.1; su página carga una fuente desde Google Fonts en su navegador.
Copia de Seguridad Local Protegida con Contraseña (Respaldo del Llavero):
- Cuando desee transferir o respaldar sus claves API, se genera un archivo binario .dat aplicando un método XOR de clave repetitiva simple con una contraseña definida por el usuario. Este método no tiene sal y no es un cifrado fuerte; mantenga el archivo oculto y trátelo como un secreto. Por defecto, no se agrega a git.
Soporte de Variables de Entorno del Sistema de 12 Factores:
- Detecta automáticamente y pone a disposición las variables de entorno definidas en su sistema:
  - NVIDIA_API_KEY
  - OPENAI_API_KEY
  - GEMINI_API_KEY
  - OPENROUTER_API_KEY
  - ANTHROPIC_API_KEY
Modo 100% Sin Conexión (Prueba en Seco) (Costo 0 TL):
- Puede generar árboles de contexto completos, mapas de firmas AST y borradores de documentación completamente en su máquina local, sin necesidad de claves API, conexión a internet o suscripción de IA.

🤖 Servidor del Protocolo de Contexto de Modelo (MCP)

T-Zero V3 ofrece un servidor local (tzero_mcp.py) que se comunica a través de stdio utilizando el SDK estándar del Protocolo de Contexto de Modelo (MCP) de Anthropic. Esto permite que agentes de IA como Cursor, Claude Desktop, Antigravity IDE y Cline consulten la arquitectura jerárquica, el grafo de dependencias y los límites del proyecto antes de generar o modificar cualquier código.

🛠 Herramientas MCP Ofrecidas (13 Herramientas Autónomas)

Nombre de la Herramienta	Parámetros	Función y Propósito
`get_project_context_tree`	`project_root`, `reduction_mode`, `max_tokens`, `include_file_contents`	Escanea el directorio del proyecto; devuelve la Arquitectura Maestra T-1, las Referencias de Módulos T-2 y las reglas de límites T-4 como contexto jerárquico. Reduce el uso de tokens hasta en un 95%.
`query_module_dependencies`	`project_root`, `file_path`	Obtiene el mapa de firmas de importación/exportación, enlaces internos y paquetes externos de un archivo específico o de todo el repositorio.
`query_architecture_boundaries`	`project_root`, `extra_guidance`	Consulta los límites de arquitectura activos (T-4), reglas y restricciones de Zero-Leak para agentes de IA.
`generate_architecture_blueprint`	`project_root`	Genera un documento de arquitectura del sistema (`ARCHITECTURE.md`) con un diagrama de topología Mermaid automático.
`generate_repo_map`	`project_root`, `max_tokens`	Genera un mapa de símbolos AST ultracomprimido (clases, métodos, firmas) para conversaciones de LLM.
`audit_codebase_quality`	`project_root`, `file_path`	Realiza análisis estático de olores de código AST y escaneo de fugas de claves/contraseñas secretas (funciones de más de 30 líneas, claves globales).
`find_code_duplicity`	`project_root`, `min_lines`	Detecta bloques de código duplicados/repetidos de más de 6 líneas en el espacio de trabajo.
`estimate_token_cost`	`text`, `project_root`, `reduction_mode`	Genera una tabla completa de costos de tokens y USD para el texto o directorio dado a través de modelos OpenAI, Claude, Groq, NVIDIA NIM y Ollama ($0).
`analyze_change_impact`	`target_symbol`, `project_root`	Calcula definiciones de símbolos AST, cadenas de llamadas y el radio de impacto (blast radius) con una puntuación de riesgo de 0-100 antes de la refactorización.
`enforce_architecture_boundaries`	`project_root`, `rules_file`	Audita importaciones prohibidas entre capas según las reglas de `tzero.rules.json` y previene la degradación de la arquitectura.
`search_codebase_semantic`	`query`, `project_root`, `top_k`	Motor de búsqueda semántica de código y RAG híbrido BM25 + TF-IDF en memoria, 100% local y privado (costo $0, cero fugas de datos).
`export_agent_rules`	`project_root`	Genera reglas de Cursor (`.cursorrules`, `.cursor/rules/*.mdc`), Cline (`.clinerules`) y Copilot con un solo clic.
`get_token_savings_metrics`	`project_root`, `team_size`	Calcula la tasa cuantitativa de ahorro de tokens, la ganancia de costos mensual/anual y los valores de ROI basados en equipo.

🧭 Prompts Integrados de MCP

tzero_grounding: Inyecta reglas de arquitectura, límites modulares y directivas de seguridad 100% Zero-Leak en sesiones de Cursor / Claude / Antigravity.

📊 Benchmark de Tokens (Ejemplo de Archivo Único)

tzero_v3.py en el commit 4846dcf se midió con el estimador count_tokens_precise del proyecto (aproximadamente karakter / 4):

Entrada	Estimación de código fuente completo	Firmas AST Ultra	Reducción estimada
`tzero_v3.py` (224.150 caracteres)	56.037 tokens	3.088 tokens	94,5%

Para reproducir: python -c "from pathlib import Path; from tzero_v3 import TokenReducer,count_tokens_precise; s=Path('tzero_v3.py').read_text(encoding='utf-8'); r=TokenReducer.reduce(s,'tzero_v3.py',mode='ultra'); print(count_tokens_precise(s),count_tokens_precise(r))". Esta es solo una comparación basada en firmas de un solo archivo; no es una medición de todo el repositorio ni de la calidad de la respuesta. Los tokenizadores de los proveedores y la sobrecarga de respuesta de MCP varían. Cuando se necesiten detalles de implementación, use el modo balanced o el código fuente.

🔌 Agregar T-Zero a Clientes MCP

T-Zero ofrece un servidor MCP stdio local totalmente compatible para Cursor, Claude Desktop, Antigravity IDE, VS Code, Windsurf, Cline y Roo Code.

🚀 Opción 1: Instalación más simple en 1 minuto con pip (Paquete Oficial de PyPI — Multiplataforma)

La forma más fácil y oficial de instalar y ejecutar T-Zero en Windows, macOS o Linux:

pip install tzero-mcp

Después de completar la instalación, puede usarlo como desee:

Conéctese con un clic a todos sus IDE (Cursor, Claude, Antigravity, VS Code, Cline):
```
tzero-add-mcp
```
Ejecute el Asistente de Terminal (CLI):
```
tzero --cli
```
Abra el Panel Visual de Escritorio (GUI):
```
tzero-gui
# veya:
tzero --gui
```
Si desea realizar una Configuración Manual de MCP: En su archivo de configuración del IDE (mcp_config.json, claude_desktop_config.json o configuración de Cursor):
```
{
  "mcpServers": {
    "tzero": {
      "command": "tzero-mcp"
    }
  }
}
```

🌐 Opción 1B: Instalación Web Instantánea en una Sola Línea (Cero Instalación)

Windows (PowerShell):

irm https://raw.githubusercontent.com/toprakahmetaydogmus/TZeroAlgorithm/main/install.ps1 | iex

Linux / macOS (Bash / Zsh):

curl -fsSL https://raw.githubusercontent.com/toprakahmetaydogmus/TZeroAlgorithm/main/install.sh | bash

Registro MCP de Smithery:

npx -y @smithery/cli install tzero --client cursor

⚡ Opción 2: Instalación de Windows con un Clic y Cero Requisitos (Binario Independiente)

Descargue directamente el archivo AddMCP.exe desde la página de Última Versión (v3.0.7):

Interfaz Gráfica (GUI): Haga doble clic en el archivo AddMCP.exe. Detecta automáticamente todos los IDE instalados en su computadora y completa la integración con un solo clic.
Terminal / Línea de Comandos: AddMCP.exe --all (instala silenciosamente en todos los IDE detectados sin abrir ninguna interfaz).
Cero Requisitos: No requiere Python, pip, pipx ni Git. Incluye el motor de ejecución independiente TZeroMCP.exe integrado.

📦 Opción 3: Ejecución Remota con pipx (Multiplataforma: Windows, macOS, Linux)

En el primer inicio, el paquete fijado v3.0.7 se descarga automáticamente desde GitHub; no es necesario clonar el repositorio. Se requieren Python 3.9+ y pipx:

Instalación de pipx en Windows

Abra PowerShell y ejecute:

py -m pip install --user pipx
py -m pipx ensurepath

Después de la instalación, reinicie el cliente. La siguiente configuración de Windows ejecuta el comando py -m pipx directamente; no depende de que el archivo pipx.exe esté en el PATH. En macOS/Linux, instale pipx con las directrices oficiales de la plataforma y ejecute pipx ensurepath.

Instalación con un Clic en Cursor

Abra el enlace correspondiente a su sistema operativo, confirme la configuración de Cursor y active el servidor tzero en Settings → MCP o Customize → MCP.

Si el enlace no se abre, vaya a Settings → MCP → Add Custom MCP y pegue el JSON correspondiente a su plataforma.

Windows:

{
  "mcpServers": {
    "tzero": {
      "command": "py",
      "args": ["-m", "pipx", "run", "--spec", "https://github.com/toprakahmetaydogmus/TZeroAlgorithm/archive/refs/tags/v3.0.7.zip", "tzero-mcp"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "tzero": {
      "command": "pipx",
      "args": ["run", "--spec", "https://github.com/toprakahmetaydogmus/TZeroAlgorithm/archive/refs/tags/v3.0.7.zip", "tzero-mcp"]
    }
  }
}

Claude Desktop

Abra Settings → Developer → Edit Config.
Agregue el bloque JSON de Windows o macOS/Linux anterior al objeto mcpServers existente; no elimine otros registros de servidores.
Guarde el archivo, cierre y vuelva a abrir Claude Desktop por completo.
Verifique que el servidor tzero esté ejecutándose en Settings → Developer.

Rutas de configuración: Windows %APPDATA%\Claude\claude_desktop_config.json; macOS ~/Library/Application Support/Claude/claude_desktop_config.json.

Google Antigravity IDE

Abra Settings → Customizations → Installed MCP Servers.
El botón Add MCP abre la tienda MCP de Antigravity. Si T-Zero aparece en la lista, haga clic en Add; si no aparece, use la siguiente configuración stdio personalizada.
Agregue el registro tzero del bloque JSON de Windows o macOS/Linux al archivo mcp_config.json de Antigravity; conserve los registros mcpServers existentes. En Windows, la ruta de configuración de usuario es %USERPROFILE%\.gemini\config\mcp_config.json (o ~/.gemini/antigravity/mcp_config.json).
Guarde/actualice los servidores MCP y permita las herramientas cuando se le solicite.

⚡ Comando Slash y Capacidad de Antigravity (`/tzero`)

T-Zero ofrece soporte integrado de Skill de Antigravity (.agents/skills/tzero/SKILL.md y ~/.gemini/config/skills/tzero/SKILL.md). Escriba directamente /tzero en el campo de chat de Antigravity para listar o ejecutar comandos:

/tzero o /tzero tree — Genera el árbol de contexto multicapa con ahorro de tokens del 95%
/tzero audit — Ejecuta la auditoría de olores de código AST y seguridad 100% Zero-Leak
/tzero arch — Genera ARCHITECTURE.md con diagramas Mermaid en vivo
/tzero deps [dosya] — Analiza la topología de dependencias de módulos
/tzero impact <sembol> — Calcula la puntuación del radio de impacto de símbolos antes de la refactorización
/tzero rules — Genera reglas de .cursorrules, .clinerules y Copilot
/tzero search <sorgu> — Ejecuta la búsqueda semántica de código BM25 100% local y privada
/tzero savings — Calcula el análisis de ahorro de tokens ROI basado en equipo

Consulte la guía oficial de MCP de Antigravity para conocer la configuración y el esquema de configuración actuales.

VS Code Copilot

Abra la Paleta de Comandos (Ctrl+Shift+P) y ejecute MCP: Add Server.
Seleccione Command (stdio); ingrese el comando py en Windows, pipx en macOS/Linux y los argumentos anteriores.
Guarde en el archivo .mcp.json o .vscode/mcp.json; inicie y confíe en el servidor tzero desde la vista de Servidores MCP.

Para .vscode/mcp.json, VS Code usa el objeto servers de nivel superior y type: "stdio":

{
  "servers": {
    "tzero": {
      "type": "stdio",
      "command": "py",
      "args": ["-m", "pipx", "run", "--spec", "https://github.com/toprakahmetaydogmus/TZeroAlgorithm/archive/refs/tags/v3.0.7.zip", "tzero-mcp"]
    }
  }
}

Claude Code, Cline, Roo Code, Windsurf y Otros

Abra la configuración del servidor MCP del cliente, seleccione Add/Edit Server y agregue el registro mcpServers de Windows o macOS/Linux anterior. Claude Code puede usar el archivo .mcp.json en la raíz del proyecto; Cline, Roo Code y Windsurf ofrecen sus propios paneles de configuración de MCP. Reinicie el cliente y confirme el servidor.

Actualmente, la única URL pública de un clic verificada que instala un servidor MCP stdio local está disponible en Cursor. Otros clientes usan su propio archivo/panel de configuración; los JSON anteriores están listos para usar directamente.

Inicio desde la Línea de Comandos

python tzero_mcp.py
# Veya: python main.py --mcp

🏗 Arquitectura del Sistema

flowchart TD
    A["Kaynak Kod Deposu"] --> B["CodebaseScanner"]
    B --> C{"Token Reducer"}
    C -->|"Ultra Mod"| D["Yalnızca Fonksiyon & Sınıf İmzaları"]
    C -->|"Balanced Mod"| E["İmzalar + Temel Kontrol Akışı"]
    C -->|"None Mod"| F["Tam Orijinal Kaynak Kod"]
    
    B --> G["AST Statik Kod Denetçisi"]
    G --> H["Kod Kokuları & Karmaşıklık Raporu"]
    
    B --> I["Bağımlılık Analizörü"]
    I --> J["Import Grafı & Modül Haritası"]
    
    B --> K["Workspace Duplicity Finder"]
    K --> L["Tekrar Eden Kod Blokları"]

    D --> M{"Context Generator"}
    J --> M
    L --> M
    M -->|"Çevrimdışı Dry-Run"| N["Yerel T-Zero Context Ağacı"]
    M -->|"AI API Modu"| O["LLM Prompt Sentezleyici"]
    O --> P["NVIDIA NIM / OpenAI / Gemini / Anthropic / Ollama"]
    P --> Q["Yüksek Sadakatli README.md, AGENTS.md & ARCHITECTURE.md"]

    M --> R["Model Context Protocol (MCP)"]
    R --> S["Cursor / Claude Desktop / Antigravity / Cline"]

🌟 Capacidades y Características Destacadas

1. Integración Multi-Proveedor de LLM

NVIDIA NIM: deepseek-v4.1-flash, deepseek-coder-6.7b, nemotron-70b, mistral-large-2, llama-3.2-90b-vision
OpenAI: gpt-4o, gpt-4o-mini, o3-mini, o1
Google Gemini: gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
Anthropic: claude-3-7-sonnet-20250219, claude-3-5-sonnet, claude-3-5-haiku
OpenRouter: Puerta de enlace universal para claude-3.7-sonnet, gpt-4o, deepseek-r1
Ollama Local: llama3:latest, mistral:latest, phi3:latest, qwen2.5:latest (100% local, sin conexión, privado y gratuito)

2. Reductor Inteligente de Tokens AST (Ahorro de hasta el 95%)

Modo Ultra: Limpia los cuerpos de las funciones; conserva la jerarquía de clases, decoradores, docstrings, sugerencias de tipo y los encabezados completos de funciones/clases/importaciones de Python de varias líneas.
Modo Equilibrado: Conserva los bloques de control básicos (if/try/for) junto con las firmas y el manejo de excepciones.
Modo Ninguno: Mantiene el 100% del código fuente original.
Idiomas compatibles: Python, JavaScript, TypeScript, JSX/TSX, C/C++, Go, Rust, HTML, CSS, Bash, Batch, JSON, YAML.

3. Herramientas Avanzadas de Análisis de Código Base

Árbol de Clases y Métodos AST: Enumera jerárquicamente todas las clases, métodos, listas de argumentos y decoradores.
Auditor de Código Estático: Detecta al instante docstrings faltantes, rutinas excesivamente complejas de más de 30 líneas, funciones con 6 o más parámetros y el uso de la palabra clave global (se admiten tanto def síncrono como async def asíncrono).
Analizador de Dependencias: Examina los nodos de importación del AST para extraer el mapa de módulos internos y externos del proyecto.
Buscador de Duplicados: Detecta bloques de código duplicados de 6+ líneas en todo el espacio de trabajo.
Motor de Refactorización AST: Refactoriza automáticamente nombres de funciones y variables en todo el proyecto mediante transformación segura del AST.

4. Control de Versiones Git y Telemetría Visual en Vivo

Clasificador de Historial de Commits: Etiqueta automáticamente los commits recientes (Añadido, Corregido, Refactorizado, Actualizado).
Diff Git en Vivo con Colores: Muestra los cambios sin guardar (git diff HEAD) con resaltado de sintaxis.
Gestor Git Integrado: Operaciones de stage, commit y cambio de rama desde la GUI.
Grafo de Dependencias Interactivo: Dibuja la relación entre archivos como un grafo de nodos físico con soporte de arrastrar y soltar.
Telemetría de CPU y RAM en Vivo: Monitorea el uso de recursos del sistema en tiempo real.
Gráfico de Donut de Tokens: Dibuja la distribución por tipo de archivo, volumen y consumo de tokens en un lienzo dinámico.

5. GUI Futurista, Animaciones de Partículas Dinámicas y Sonidos Hápticos

8 Temas Personalizados:
- 🌌 Glass Dark (Vidrio esmerilado y acentos cian)
- ⚡ Neon Cyberpunk (Fucsia vibrante y azul eléctrico)
- 🖤 Midnight OLED (Negro puro #000000 para cero fatiga visual)
- 🟢 Matrix Terminal (Verde hacker fosforescente clásico #00ff41)
- 🌆 Synthwave 80s (Magenta láser, naranja neón y azul retro)
- ❄️ Nordic Frost (Gris polar y azul glaciar)
- ☕ Solarized Amber (Espresso profundo y ámbar cálido)
- 🕹 Siber Retro (Tema clásico de Cyber Academia)
Motor FX de Partículas Dinámicas de 4 Modos:
- 🌌 Estrellas: Túnel de estrellas con profundidad 3D y velocidad variable.
- 🟢 Lluvia Matrix: Lluvia digital de código y caracteres verdes descendentes.
- 🌐 Cyber Grid: Onda de malla alámbrica en perspectiva hacia el horizonte.
- ⬛ Minimal Sólido: Fondo oscuro minimalista puro con consumo de CPU cero.
Motor de Sonido Háptico (SFX): Proporciona retroalimentación de audio en clics, finalización de escaneo y generación de contexto (winsound.Beep se ejecuta en segundo plano, nunca congela la interfaz; se puede 🔊 SFX ON / 🔇 SFX OFF con un solo clic desde la barra de título).
Notificaciones Toast Cyberpunk Flotantes: Muestra notificaciones suaves sin molestar al usuario al copiar y guardar en el portapapeles.

6. Paquete de Exportación Multi-Formato (Context Architect Hub)

README.md: Documentación detallada del repositorio y la arquitectura.
AGENTS.md / CLAUDE.md: Guía de sistema y reglas especialmente estructurada para agentes de codificación de IA como Cursor, Antigravity IDE, Claude Code, Cline y Copilot.
ARCHITECTURE.md: Especificación de arquitectura con diagrama Mermaid generado automáticamente y jerarquía de dependencias de módulos.
REPO_MAP.txt: Mapa de símbolos AST ultracomprimido para pegar directamente en ventanas de chat de LLM.
README.html: Vista previa HTML visual con tema oscuro cyberpunk, abrible con un clic en el navegador.
Calculadora de Presupuesto de Tokens y Costo en USD en Vivo: Conteo de tokens en tiempo real y costo estimado de gasto de API según el modelo seleccionado.

📦 Instalación y Primeros Pasos

Método 1: Instalación con un Solo Clic (.bat) — Recomendado para Windows

install_requirements.bat

Incluso si no tiene Python en su sistema, descarga automáticamente Python 3.12, configura el entorno virtual e instala todos los paquetes por completo.

Método 2: Ejecutable Independiente (.exe)

Descargue el archivo TZeroAlgorithm.exe para la aplicación de escritorio. Ejecute el archivo AddMCP.exe para agregar el MCP a los IDE detectados; viene incluido en TZeroMCP.exe, no requiere Python/pipx, conserva los registros de servidores existentes y respalda los archivos de configuración antes de modificarlos. TZeroMCP.exe también se ofrece por separado para instalación manual.

Método 3: Instalación como Paquete Python / pip

# Klonlanmış depodan kurun
git clone https://github.com/toprakahmetaydogmus/TZeroAlgorithm.git
cd TZeroAlgorithm
pip install .
# `tzero` ve `tzero-mcp` komutları kurulur.

# PyPI yayını yapıldıktan sonra:
pipx install tzero-algorithm

El nombre del proyecto en PyPI es tzero-algorithm y el comando MCP instalado es tzero-mcp. Hasta la primera publicación en PyPI, use la configuración de GitHub pipx run --spec anterior.

Verificación automática de dependencias: T-Zero valida los paquetes necesarios al iniciar e instala los que falten o estén desactualizados (la salida va a stderr, el stdio del MCP no se corrompe). Use TZERO_NO_AUTO_INSTALL=1 para desactivarlo. Ejecute python main.py --doctor para una verificación de salud completa. La interfaz de escritorio requiere tkinter; el CLI y el servidor MCP funcionan sin él, por lo que los entornos de servidor, Docker y CI funcionan sin problemas.

🎮 Guía de Uso (GUI y CLI)

1. Interfaz Gráfica de Usuario (GUI)

# Python ile çalıştırma
python main.py

# Veya Windows başlatıcı betiği ile
run.bat

# Veya uyumluluk sarmalayıcısı ile
python tzero.py

2. Interfaz de Línea de Comandos (CLI)

Indicadores avanzados de línea de comandos para desarrolladores de terminal y automatizaciones de CI/CD:

# 1. Model Context Protocol (MCP) stdio sunucusunu başlat
python main.py --mcp

# 2. Projeyi tara ve metrik tablosunu ekrana bas
python main.py --scan .

# 3. Kod kalitesini denetle ve code smell raporu al
python main.py --audit .

# 4. Sıfır API maliyetiyle yerel çevrimdışı context ağacı üret
python main.py --dry-run --dir . --output README.md

# 5. Yapay Zeka Ajan Kılavuzu (AGENTS.md / CLAUDE.md) üret
python main.py --export-agents AGENTS.md --dir .

# 6. Mermaid Mimari Şeması (ARCHITECTURE.md) üret
python main.py --export-arch ARCHITECTURE.md --dir .

# 7. Sıkıştırılmış Token Repo Haritası (REPO_MAP.txt) üret
python main.py --export-repomap REPO_MAP.txt --dir .

# 8. Koyu Modlu Görsel HTML Önizlemesi (README.html) üret
python main.py --export-html README.html --dir .

# 9. İnteraktif Terminal Sihirbazını başlat
python main.py --cli

# 10. Sürüm bilgisini görüntüle
python main.py --version

# 11. Bir sembolü değiştirmenin etki alanını analiz et
python main.py --impact MyClass

# 12. Yerel ve gizli anlamsal kod arama (BM25 + TF-IDF)
python main.py --search "retry logic"

# 13. CI'da mimari sınırları denetle (ihlalde 1 ile çıkar)
python main.py --enforce-boundaries

# 14. Token tasarruf metrikleri ve ekip ROI hesabı
python main.py --savings

# 15. Yerel ajan kurallarını üret (.cursorrules, .clinerules, Copilot)
python main.py --export-agent-rules

# 16. Yerel web panelini başlat (varsayılan port 7300)
python main.py --web

# 17. Masaüstü arayüzünü (GUI) başlat
python main.py --gui

# 18. Python, bağımlılıklar, tkinter, git ve keyring kontrolü (eksikleri kurar)
python main.py --doctor

⌨️ Atajos de Teclado

Atajo	Acción
`Ctrl+S`	Escanear el Espacio de Trabajo Seleccionado
`Ctrl+G`	Compilar / Generar el Árbol de Contexto
`Ctrl+C`	Copiar el Contenido Generado al Portapapeles
`Ctrl+R`	Actualizar el Historial de Git y las Ramas

📂 Árbol de Directorios del Proyecto

TZeroAlgorithm/
├── .mcp.json                    # Claude Code MCP integration
├── .cursor/
│   └── mcp.json                 # Hazır Cursor MCP sunucu yapılandırması
├── .github/
│   └── workflows/
│       ├── ci.yml               # GitHub Actions CI/CD otomatik test boru hattı
│       └── release.yml          # TZeroAlgorithm.exe, TZeroMCP.exe ve AddMCP.exe derler; sürümlerde yayınlar
├── tests/
│   ├── __init__.py
│   ├── test_addmcp.py            # Config merge, backups and client detection tests
│   ├── test_analyzer.py         # AST analiz ve denetim testleri
│   ├── test_cli.py              # CLI komut satırı entegrasyon testleri
│   ├── test_config.py           # Config ve Keyring güvenlik testleri
│   ├── test_exports.py          # Çoklu format dışa aktarım & maliyet testleri
│   ├── test_deps.py             # Bağımlılık kontrolü & doctor testleri
│   ├── test_features.py         # Özellik modülü testleri (etki, kurallar, arama, ROI)
│   ├── test_headless.py         # tkinter'sız çalışma, MCP çıktısı & gizli anahtar taraması testleri
│   ├── test_generator.py        # Şablon motoru ve bağlam derleme testleri
│   ├── test_gui.py              # Tkinter GUI başlatma testleri
│   ├── test_mcp.py              # Model Context Protocol (MCP) sunucu testleri
│   ├── test_providers.py        # 6 AI sağlayıcı adaptör testleri
│   └── test_scanner.py          # TokenReducer ve CodebaseScanner testleri
├── build_exe.bat                # Windows PyInstaller tek tık derleme betiği
├── compile.py                   # PyInstaller asset paketleme boru hattı
├── addmcp.py                    # IDE MCP ayarlarını kuran Windows installer
├── install_requirements.bat     # Windows otomatik ortam kurulum betiği
├── LICENSE                      # MIT Açık Kaynak Lisansı
├── main.py                      # Ana çalıştırma giriş noktası (CLI & GUI)
├── pyproject.toml               # Modern PEP 517/621 paket yapılandırması
├── README.md                    # İki dilli kapsamlı dokümantasyon
├── requirements.txt             # Üretim bağımlılık listesi
├── run.bat                      # Windows hızlı başlatıcısı
├── siber_akademi.ico            # Yüksek çözünürlüklü uygulama ikonu
├── tzero.py                     # Geriye dönük uyumluluk API sarmalayıcısı
├── tzero.rules.json             # T-4 mimari sınır kuralları
├── tzero_deps.py                # Bağımlılık kontrolü ve --doctor
├── tzero_features.py            # Etki analizi, sınır kuralları, anlamsal arama, ROI, web paneli
├── tzero_mcp.py                 # Standart Model Context Protocol (MCP) Sunucusu
├── tzero_v3.py                  # Bağımsız taşınabilir T-Zero V3 motoru
└── WALKTHROUGH.md               # Detaylı teknik mimari kılavuzu

🧪 Proceso de Pruebas Automatizadas y CI/CD

Para ejecutar todas las pruebas unitarias y de integración localmente:

python -m unittest discover -s tests -v

Salida esperada:

Ran 79 tests in ~4s
OK (the GUI smoke test is skipped when no display is available)

GitHub Actions ejecuta automáticamente estas pruebas con Python 3.10, 3.11 y 3.12 en entornos Ubuntu y Windows en cada push y pull request al repositorio.

🛡️ GitHub Action (Integración con GitHub Marketplace)

T-Zero también funciona en GitHub Actions para auditar la calidad del código, mantener los límites de arquitectura y prevenir fugas de claves secretas en sus procesos de CI/CD:

name: T-Zero Quality Guard

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: T-Zero Architecture & Quality Guard
        uses: toprakahmetaydogmus/TZeroAlgorithm@v4.0.0-beta.1
        with:
          workspace: '.'
          audit: 'true'
          enforce-boundaries: 'false'

📄 Licencia e Información del Desarrollador

Este proyecto está licenciado bajo la Licencia MIT. Para más detalles, consulte el archivo LICENSE.

Toprak Ahmet Aydoğmuş — Cyber Academia

💼 LinkedIn: toprak-ahmet-aydoğmuş
🔗 Enlaces y Biografía: hopp.bio/siberegitim
🐙 GitHub: @toprakahmetaydogmus

tzero-mcp

Documentación

⚡ SİBER AKADEMİ — T-ZERO CONTEXT ARCHITECT V3

⚡ Prueba Visual: Ingesta Cruda vs. Poda AST de T-Zero (Reproducible)

🚀 Inicio Rápido en 1 Línea

🇬🇧 English

Tabla de Contenidos

🔒 Arquitectura de Seguridad (Garantía 100% Zero-Leak)

🤖 Servidor Model Context Protocol (MCP)

🛠 Herramientas MCP Disponibles (16 Herramientas Autónomas)

📦 Recursos MCP en Vivo

🧭 Prompts MCP

📊 Benchmark de Tokens (Ejemplo de Archivo Único)

🔌 Añade T-Zero a Clientes MCP

🚀 Opción 1: Inicio Rápido de 1 Minuto con pip (PyPI Oficial — Multiplataforma)

🌐 Opción 1B: Instalador Web Instantáneo de 1 Clic (Configuración Cero)

⚡ Opción 2: Instalador de Windows de 1 Clic con Cero Dependencias (Binario Independiente)

📦 Opción 3: Lanzamiento Remoto vía pipx (Multiplataforma: Windows, macOS, Linux)

Instalar pipx en Windows

Instalación de 1 Clic en Cursor

Claude Desktop

Google Antigravity IDE

⚡ Comando Slash y Skill de Antigravity (/tzero)

VS Code Copilot

Claude Code, Cline, Roo Code, Windsurf y Otros Clientes MCP

Inicio CLI

🏗 Arquitectura del Sistema

🌟 Aspectos Destacados y Capacidades Principales

1. Motor Multi-LLM de Proveedores

2. Reductor de Tokens AST (Ahorro de Tokens de hasta el 95%)

3. Herramientas Avanzadas de Análisis de Código Base

4. Integración Git VCS y Telemetría Visual

5. UI Futurista, FX de Partículas Dinámicas y SFX de Audio Háptico

6. Centro de Exportación de Contexto Multi-Formato

📦 Instalación y Configuración

Método 1: Instalador de Un Clic (Recomendado para Windows)

Método 2: Ejecutable Portátil Independiente (.exe)

Método 3: Paquete Python / Instalación con pip

🎮 Guía de Uso (GUI y CLI)

1. Interfaz Gráfica de Usuario (GUI)

2. Interfaz de Línea de Comandos (CLI)

⌨️ Atajos de Teclado

📂 Estructura del Proyecto

🧪 Suite de Pruebas Automatizadas y CI/CD

🛡️ Acción de GitHub (GitHub Marketplace)

📄 Licencia y Créditos

🇹🇷 Türkçe

İçindekiler

🔒 Şifreli Güvenlik Mimarisi (%100 Zero-Leak Garantisi)

🤖 Servidor del Protocolo de Contexto de Modelo (MCP)

🛠 Herramientas MCP Ofrecidas (13 Herramientas Autónomas)

🧭 Prompts Integrados de MCP

📊 Benchmark de Tokens (Ejemplo de Archivo Único)

🔌 Agregar T-Zero a Clientes MCP

🚀 Opción 1: Instalación más simple en 1 minuto con pip (Paquete Oficial de PyPI — Multiplataforma)

🌐 Opción 1B: Instalación Web Instantánea en una Sola Línea (Cero Instalación)

⚡ Opción 2: Instalación de Windows con un Clic y Cero Requisitos (Binario Independiente)

📦 Opción 3: Ejecución Remota con pipx (Multiplataforma: Windows, macOS, Linux)

Instalación de pipx en Windows

Instalación con un Clic en Cursor

Claude Desktop

Google Antigravity IDE

⚡ Comando Slash y Capacidad de Antigravity (/tzero)

VS Code Copilot

Claude Code, Cline, Roo Code, Windsurf y Otros

Inicio desde la Línea de Comandos

🏗 Arquitectura del Sistema

🌟 Capacidades y Características Destacadas

1. Integración Multi-Proveedor de LLM

2. Reductor Inteligente de Tokens AST (Ahorro de hasta el 95%)

3. Herramientas Avanzadas de Análisis de Código Base

4. Control de Versiones Git y Telemetría Visual en Vivo

5. GUI Futurista, Animaciones de Partículas Dinámicas y Sonidos Hápticos

6. Paquete de Exportación Multi-Formato (Context Architect Hub)

📦 Instalación y Primeros Pasos

Método 1: Instalación con un Solo Clic (.bat) — Recomendado para Windows

Método 2: Ejecutable Independiente (.exe)

Método 3: Instalación como Paquete Python / pip

🎮 Guía de Uso (GUI y CLI)

1. Interfaz Gráfica de Usuario (GUI)

⚡ Comando Slash y Skill de Antigravity (`/tzero`)

⚡ Comando Slash y Capacidad de Antigravity (`/tzero`)