tzero-mcp

Motor de redução de contexto de codebase AST empresarial com economia de até 95% de tokens e proteções de segurança com zero vazamento.

GitHub

Documentação

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

🇬🇧 Documentação em Inglês • 🇹🇷 Documentação em Turco

Construtor de Contexto de Codebase de Nível Empresarial, Analisador de Assinaturas AST e Redutor de Tokens.
Construído para Cursor, VS Code Copilot, Cline, Antigravity IDE, Claude Code e ChatGPT. Reduz a sobrecarga de ingestão de contexto LLM em até 95% enquanto preserva o esboço estrutural do seu código (assinaturas, hierarquia, dependências).
Inclui um servidor nativo Model Context Protocol (MCP) para agentes autônomos de codificação com IA.

Desenvolvedor: Toprak Ahmet Aydoğmuş
LinkedIn: Toprak Ahmet Aydoğmuş
Bio & Hub: https://hopp.bio/siberegitim
Repositório GitHub: https://github.com/toprakahmetaydogmus/TZeroAlgorithm

T-Zero AST Token Reduction Benchmark

⚡ Prova Visual: Ingestão Bruta vs. Poda AST T-Zero (Reproduzível)

Modo de Análise	Volume Bruto de Contexto	Payload Podado T-Zero	Taxa de Redução de Tokens	Delta de Custo / Consulta
Varredura Completa do Repositório	`166,996 tokens`	`8,465 tokens`	-94,9%	-$0,3963 / consulta

Execute você mesmo offline (custo $0): python tzero.py --savings

🚀 Início Rápido em 1 Linha

pip install tzero-mcp

Ou configure diretamente no seu Cliente MCP (Cursor, Claude Desktop, Windsurf ou Antigravity IDE):

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

Ou execute inspeção CLI offline imediatamente (custo $0, 100% Zero-Vazamento):

python tzero.py --savings

🇬🇧 Inglês

Sumário

Arquitetura de Segurança (Garantia 100% Zero-Vazamento)
Servidor Model Context Protocol (MCP)
Arquitetura do Sistema
Destaques Principais e Capacidades
Instalação e Configuração
Guia de Uso (GUI e CLI)
Atalhos de Teclado
Estrutura do Projeto
Suíte de Testes Automatizados e CI/CD
Licença e Créditos

🔒 Arquitetura de Segurança (Garantia 100% Zero-Vazamento)

[!IMPORTANT] O Algoritmo T-Zero contém estritamente ZERO chaves de API, credenciais pessoais ou públicas codificadas em qualquer lugar do repositório.
Princípios de defesa em profundidade e confiança zero são aplicados por padrão.

Criptografia de Credenciais em Nível de SO (Mecanismo Keyring):
- Chaves de API nunca são gravadas em arquivos de configuração de texto simples ou logs.
- Armazenadas através da biblioteca multiplataforma keyring, que usa o armazenamento nativo do SO:
- Windows: Windows Credential Manager
- macOS: Apple Keychain
- Linux: Secret Service API (GNOME Keyring / KWallet via DBus)
Zero Telemetria e Privacidade Absoluta:
- Seu código-fonte, tokens, estrutura de arquivos e credenciais de API nunca são enviados a qualquer servidor de telemetria, análise ou desenvolvedor de terceiros.
- O tráfego de rede de saída é iniciado exclusivamente diretamente do seu cliente para o endpoint do provedor de IA escolhido por você (NVIDIA, OpenAI, Google, Anthropic, OpenRouter ou localhost Ollama).
- O painel web local opcional (--web) vincula-se apenas a 127.0.0.1; sua página carrega uma fonte web do Google Fonts no seu navegador.
Backup de Keyring com Senha Ofuscada:
- Chaves de API podem ser copiadas para um arquivo binário .dat protegido por senha. Isso usa um simples XOR de chave repetitiva (sem salt, não é criptografia forte), então mantenha o arquivo privado e trate-o como um segredo. Ele é ignorado pelo git por padrão.
Detecção de Variáveis de Ambiente 12-Factor:
- Detecta e herda automaticamente variáveis de ambiente padrão do sistema quando presentes:
  - NVIDIA_API_KEY
  - OPENAI_API_KEY
  - GEMINI_API_KEY
  - OPENROUTER_API_KEY
  - ANTHROPIC_API_KEY
Modo Dry-Run 100% Offline (Custo $0):
- Gere árvores de contexto completas, mapas de assinatura AST e blueprints markdown sem qualquer conexão com a internet, chaves de API ou assinaturas de provedores de IA.

🤖 Servidor Model Context Protocol (MCP)

O T-Zero V3 incorpora nativamente um servidor padrão Model Context Protocol (MCP) (tzero_mcp.py) operando sobre stdio. Isso capacita agentes de IA no Cursor, Claude Desktop, Antigravity IDE e Cline a inspecionar, podar e consultar autonomamente a base de código do seu projeto antes de escrever uma única linha de código.

🛠 Ferramentas MCP Disponíveis (16 Ferramentas Autônomas)

Nome da Ferramenta	Parâmetros	Propósito
`get_project_context_tree`	`project_root`, `reduction_mode`, `max_tokens`, `include_file_contents`	Escaneia o workspace e constrói uma árvore de contexto hierárquica T-Zero de múltiplas camadas (T-1 a T-4). Reduz tokens em até 95%.
`query_module_dependencies`	`project_root`, `file_path`	Analisa dependências de importação de entrada e saída em Python, TypeScript, Go, Rust, Java, C# e C++.
`query_architecture_boundaries`	`project_root`, `extra_guidance`	Consulta limites arquiteturais T-4 ativos, restrições operacionais e regras Zero-Vazamento para agentes de codificação.
`generate_architecture_blueprint`	`project_root`	Gera uma especificação completa de arquitetura do sistema (`ARCHITECTURE.md`) com diagramas de topologia Mermaid ao vivo.
`generate_repo_map`	`project_root`, `max_tokens`	Produz um mapa de símbolos AST ultra-comprimido (classes, métodos, assinaturas) otimizado para injeção de prompt.
`audit_codebase_quality`	`project_root`, `file_path`	Executa verificação estática de cheiro de código AST e varredura de vazamento de segredos (detecta funções >30 linhas, variáveis globais, docstrings ausentes).
`find_code_duplicity`	`project_root`, `min_lines`	Escaneia o workspace para identificar blocos de código repetidos/duplicados entre arquivos para refatoração.
`estimate_token_cost`	`text`, `project_root`, `reduction_mode`	Calcula contagem exata de tokens e comparação de custo em USD entre OpenAI, Claude, Groq, NVIDIA NIM e Ollama ($0).
`analyze_change_impact`	`target_symbol`, `project_root`	Rastreia definições de símbolos AST, cascatas de chamadores, dependentes de entrada e calcula uma pontuação de risco de 0-100.
`enforce_architecture_boundaries`	`project_root`, `rules_file`	Valida limites de importação modulares contra `tzero.rules.json` para prevenir erosão arquitetural.
`search_codebase_semantic`	`query`, `project_root`, `top_k`	Busca semântica de código e mecanismo RAG híbrido BM25 + TF-IDF 100% privado, local em memória (custo $0, 0 vazamentos).
`export_agent_rules`	`project_root`	Gera regras com 1 clique para Cursor, Windsurf, Claude Code, Cline e Copilot.
`get_token_savings_metrics`	`project_root`, `team_size`	Calcula taxa quantitativa de redução de tokens, economia de custo mensal/anual e métricas de ROI para desenvolvedores em equipe.
`get_incremental_diff_context`	`base_ref`, `project_root`	Extrai um contexto de diff ultra-compacto com símbolos modificados e raio de explosão downstream para revisões de PR (redução de tokens de 98%+).
`prune_code_snippet`	`code`, `file_path_or_ext`, `reduction_mode`	Poda trechos de código arbitrários em memória em assinaturas AST compactas em tempo real (redução de 80-95%).
`verify_zero_leak_security`	`project_root`, `target_file`, `code_snippet`	Scanner de segurança 100% Zero-Vazamento para chaves de API codificadas (OpenAI, Anthropic, Gemini, NVIDIA, GitHub) e segredos (custo $0, 0 vazamentos).

📦 Recursos MCP Ao Vivo

tzero://architecture: Blueprint de arquitetura Mermaid em tempo real e diagrama de topologia de módulos.
tzero://boundaries: Limites de camadas arquiteturais T-4 ativos, regras de segurança e restrições.
tzero://token-roi: Taxa quantitativa de redução de tokens e economia de ROI econômica para equipes de engenharia.

🧭 Prompts MCP

tzero_grounding: Injeta regras estritas de limites arquiteturais, diretrizes de integridade modular e mandatos de segurança Zero-Vazamento na sessão do sistema do agente.

📊 Benchmark de Tokens (Exemplo de Arquivo Único)

Medido em tzero_v3.py no commit 4846dcf com o estimador count_tokens_precise do projeto (aproximadamente characters / 4):

Entrada	Estimativa de fonte completa	Assinaturas AST ultra	Redução estimada
`tzero_v3.py` (224.150 caracteres)	56.037 tokens	3.088 tokens	94,5%

Reproduza com: 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 é uma comparação de arquivo único, apenas assinaturas, não um benchmark de repositório inteiro ou qualidade de resposta; tokenizadores de provedores e sobrecarga de resposta MCP variam. Use balanced ou busque a fonte quando detalhes de implementação importarem.

🔌 Adicionar T-Zero aos Clientes MCP

O T-Zero roda como um servidor stdio local com suporte completo para Cursor, Claude Desktop, Antigravity IDE, VS Code, Windsurf, Cline e Roo Code.

🚀 Opção 1: Início Rápido de 1 Minuto com pip (PyPI Oficial — Multiplataforma)

A maneira mais rápida e padrão de instalar e executar o T-Zero no Windows, macOS ou Linux:

pip install tzero-mcp

Uma vez instalado, use qualquer uma das interfaces disponíveis:

Auto-Configurar Todos os IDEs Detectados (Cursor, Claude, Antigravity, VS Code, Cline):
```
tzero-add-mcp
```
Assistente de Terminal Interativo (CLI):
```
tzero --cli
```
Painel GUI Cyberpunk para Desktop:
```
tzero-gui
# or:
tzero --gui
```
Configuração Manual do Cliente MCP: Basta adicionar este bloco stdio à configuração do seu cliente (mcp_config.json, claude_desktop_config.json ou configurações do Cursor):
```
{
  "mcpServers": {
    "tzero": {
      "command": "tzero-mcp"
    }
  }
}
```

🌐 Opção 1B: Instalador Web Instantâneo com 1 Clique (Zero Configuração)

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 Smithery:

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

⚡ Opção 2: Instalador Windows de 1 Clique com Zero Dependências (Binário Autônomo)

Baixe AddMCP.exe diretamente da Última Versão (v3.0.7):

Modo GUI: Clique duas vezes em AddMCP.exe. Ele detecta automaticamente todos os IDEs instalados no seu computador e os configura com um único clique.
Modo CLI / Headless: Execute AddMCP.exe --all (instala automaticamente em todos os IDEs detectados sem GUI).
Zero Requisitos: Não requer Python, pip, pipx ou Git. Inclui o runtime autônomo TZeroMCP.exe internamente.

📦 Opção 3: Lançamento Remoto via pipx (Multiplataforma: Windows, macOS, Linux)

O primeiro lançamento baixa o pacote fixado v3.0.7 do GitHub sem clonar o repositório. Instale Python 3.9+ e pipx:

Instalar pipx no Windows

Abra o PowerShell e execute:

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

Reinicie o cliente após a instalação. As configurações do Windows abaixo chamam py -m pipx diretamente, então não dependem de pipx.exe estar no PATH. Para macOS/Linux, instale pipx usando as instruções oficiais da plataforma e execute pipx ensurepath.

Instalação com 1 Clique no Cursor

Escolha o link para o seu sistema operacional, aprove a configuração no Cursor e habilite tzero em Configurações → MCP ou Personalizar → MCP.

Se o Cursor não abrir o instalador, use Configurações → MCP → Adicionar MCP Personalizado e cole o JSON apropriado para a plataforma abaixo.

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 Configurações → Desenvolvedor → Editar Configuração.
Mescle o bloco JSON correspondente do Windows ou macOS/Linux acima no objeto mcpServers existente; mantenha outras entradas de servidor.
Salve o arquivo e saia/reabra completamente o Claude Desktop.
Volte para Configurações → Desenvolvedor e confirme que tzero está em execução.

Locais de configuração: Windows %APPDATA%\Claude\claude_desktop_config.json; macOS ~/Library/Application Support/Claude/claude_desktop_config.json.

Google Antigravity IDE

Abra Configurações → Personalizações → Servidores MCP Instalados.
Adicionar MCP abre a Antigravity MCP Store. Se o T-Zero aparecer lá, selecione Adicionar; caso contrário, configure-o como um servidor stdio personalizado abaixo.
Adicione a entrada tzero para Windows ou macOS/Linux dos blocos JSON acima ao mcp_config.json do Antigravity, preservando outras entradas mcpServers. No Windows, a configuração do usuário é %USERPROFILE%\.gemini\config\mcp_config.json (ou ~/.gemini/antigravity/mcp_config.json).
Salve/recarregue os servidores MCP e aprove as ferramentas quando solicitado.

⚡ Comando Slash e Skill do Antigravity (`/tzero`)

O T-Zero inclui uma skill nativa do Antigravity (.agents/skills/tzero/SKILL.md e ~/.gemini/config/skills/tzero/SKILL.md). Basta digitar /tzero no prompt de chat do Antigravity para ver as ações disponíveis ou executar:

/tzero ou /tzero tree — Constrói árvore de contexto em múltiplas camadas com redução de 95% de tokens
/tzero audit — Executa verificação de code smells via AST e auditoria de segurança 100% Zero-Leak
/tzero arch — Gera ARCHITECTURE.md com diagramas Mermaid ao vivo
/tzero deps [file] — Rastreia a topologia de dependências entre módulos
/tzero impact <symbol> — Calcula a pontuação de raio de impacto antes de refatorar
/tzero rules — Gera .cursorrules, .clinerules, instruções do Copilot
/tzero search <query> — Executa busca semântica de código 100% privada e local via BM25
/tzero savings — Calcula métricas de ROI de tokens da equipe de desenvolvimento
/tzero diff [ref] — Contexto incremental de git diff para revisões de PR com raio de impacto downstream (redução de 98%+ de tokens)

Consulte o guia oficial de MCP do Antigravity para o fluxo atual de Configurações e o esquema de configuração.

VS Code Copilot

Execute MCP: Adicionar Servidor na Paleta de Comandos (Ctrl+Shift+P).
Escolha Comando (stdio), depois insira o comando da plataforma (py no Windows; pipx no macOS/Linux) e os mesmos argumentos mostrados acima.
Salve no .mcp.json do workspace ou .vscode/mcp.json, depois confie/inicie o tzero na visualização de Servidores MCP.

Para .vscode/mcp.json, o VS Code usa um objeto servers de nível superior e requer 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 e Outros Clientes MCP

Abra as configurações de servidor MCP de cada cliente, escolha Adicionar/Editar Servidor e mescle a entrada mcpServers correspondente para Windows ou macOS/Linux acima. O Claude Code pode usar a mesma entrada em um .mcp.json na raiz do projeto; Cline, Roo Code e Windsurf fornecem seus próprios painéis de configuração de servidor MCP. Reinicie/recarregue o cliente e aprove o servidor.

Apenas o Cursor fornece atualmente uma URL de instalação pública verificada com um clique para servidores stdio locais arbitrários. Os outros clientes usam seus arquivos de configuração/configurações documentados; o JSON acima está pronto para colar.

Inicialização via CLI

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

🏗 Arquitetura do 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"]

🌟 Destaques Principais e Capacidades

1. Motor Multi-LLM de Provedores

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: Gateway universal para claude-3.7-sonnet, gpt-4o, deepseek-r1
Ollama Local: llama3:latest, mistral:latest, phi3:latest, qwen2.5:latest (100% local, offline, privado e gratuito)

2. Redutor de Tokens via AST (Economia de Até 95% de Tokens)

Modo Ultra: Remove internals de implementação preservando hierarquias de classes, decoradores, docstrings, dicas de tipo e cabeçalhos completos de funções/classes/imports em múltiplas linhas.
Modo Balanceado: Mantém assinaturas junto com fluxo de controle crítico e declarações de tratamento de exceções.
Modo Nenhum: Preserva 100% do código-fonte bruto.
Linguagens suportadas: Python, JavaScript, TypeScript, JSX/TSX, C/C++, Go, Rust, HTML, CSS, Bash, Batch, JSON, YAML.

3. Ferramentas Avançadas de Análise de Código

Estruturador de Classes e Métodos via AST: Gera uma hierarquia estruturada de cada classe, método, lista de argumentos e decorador.
Auditor Estático de Código: Sinaliza instantaneamente docstrings ausentes, funções com mais de 30 linhas, rotinas com 6+ parâmetros e uso da palavra-chave global (suporta tanto def síncrono quanto async def assíncrono).
Analisador de Dependências: Escaneia declarações de import no AST para compilar um mapa de dependências de módulos externos e internos.
Localizador de Duplicidade no Workspace: Identifica blocos duplicados idênticos de 6+ linhas em todo o código.
Motor de Refatoração via AST: Realiza renomeações globais seguras de funções e identificadores em arquivos do workspace usando transformação de nós AST.

4. Integração Git VCS e Telemetria Visual

Classificador de Histórico de Commits: Classifica commits recentes automaticamente (Adicionado, Corrigido, Refatorado, Atualizado).
Visualizador de Diff Git com Cores: Exibe alterações não commitadas em tempo real (git diff HEAD) com realce de sintaxe.
Gerenciador Git Integrado: Stage, commit e troca de branches diretamente da GUI.
Grafo Interativo de Nós de Dependência: Visualização de nós arrastável baseada em física das relações entre arquivos.
Telemetria ao Vivo de CPU e RAM: Telemetria de hardware em tempo real monitora a sobrecarga de recursos do sistema.
Gráfico de Rosca de Tokens: Divisão visual dinâmica de tipos de arquivo, volume de código e consumo de tokens.

5. UI Futurista, Efeitos de Partículas Dinâmicas e SFX de Áudio Háptico

8 Temas Curados:
- 🌌 Glass Dark (Acentos ciano fosco)
- ⚡ Neon Cyberpunk (Rosa vibrante e azul elétrico)
- 🖤 Midnight OLED (Preto puro 100% #000000 para zero cansaço visual)
- 🟢 Matrix Terminal (Verde fósforo clássico #00ff41)
- 🌆 Synthwave 80s (Magenta laser, laranja neon e ciano retrô)
- ❄️ Nordic Frost (Ardósia ártica e azul glacial)
- ☕ Solarized Amber (Expresso profundo quente e âmbar dourado)
- 🕹 Siber Retro (Estética hacker clássica)
Motor de Partículas Dinâmicas com 4 Modos:
- 🌌 Estrelas: Campo de estrelas 3D de alta velocidade com distorção de profundidade.
- 🟢 Chuva Matrix: Glifos de código verde em cascata digital.
- 🌐 Grade Cibernética: Onda wireframe de horizonte em perspectiva retrô.
- ⬛ Minimalista Sólido: Tela escura sem distrações com 0% de consumo de CPU.
Motor de SFX Háptico: Feedback auditivo não bloqueante para ações (varreduras, cópias, exportações, erros) com alternância instantânea no cabeçalho (🔊 SFX ON / 🔇 SFX OFF).
Toasts Ciberpunk Flutuantes: Banners de status não intrusivos que informam sobre salvamentos e exportações sem interromper o fluxo de trabalho.

6. Hub de Exportação de Contexto Multi-Formato

README.md: Documentação arquitetural abrangente.
AGENTS.md / CLAUDE.md: Blueprint de contexto estruturado especialmente para assistentes de codificação com IA (Cursor, Antigravity IDE, Claude Code, Cline, Copilot) contendo regras de arquitetura, resumos AST e convenções do workspace.
ARCHITECTURE.md: Blueprint de arquitetura do sistema com diagramas de topologia Mermaid gerados automaticamente.
REPO_MAP.txt: Mapa de tokens de símbolos AST altamente comprimido, adaptado para colar diretamente em prompts de chat LLM.
README.html: Documentação HTML estilizada em modo escuro ciberpunk que abre no navegador padrão com um clique.
Orçamento de Tokens ao Vivo e Estimador de Custo em USD: Contador de tokens em tempo real e custo estimado de API por modelo (OpenAI, Claude, Groq, NVIDIA NIM, Ollama).

📦 Instalação e Configuração

Método 1: Instalador com Um Clique (Recomendado para Windows)

install_requirements.bat

Provisiona automaticamente Python 3.12 (se não detectado), configura um ambiente virtual e instala todas as dependências sem exigir configuração manual.

Método 2: Executável Portátil Autônomo (.exe)

Baixe TZeroAlgorithm.exe para o aplicativo de desktop. Para adicionar MCP aos IDEs detectados, execute AddMCP.exe; ele inclui TZeroMCP.exe, não precisa de Python ou pipx, preserva entradas de servidor existentes e faz backup dos arquivos de configuração antes de alterá-los. TZeroMCP.exe também está disponível separadamente para configuração manual.

Método 3: Pacote Python / Instalação via 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

O nome do projeto no PyPI é tzero-algorithm; tzero-mcp é o comando instalado. Até o primeiro upload no PyPI, use a configuração pipx run --spec do GitHub acima.

Verificação automática de dependências: na inicialização, o T-Zero verifica seus pacotes necessários e instala qualquer um que esteja ausente ou desatualizado (o progresso vai para stderr, então o stdio do MCP permanece limpo). Opte por sair com TZERO_NO_AUTO_INSTALL=1. Execute python main.py --doctor para uma verificação completa de saúde. A GUI de desktop precisa de tkinter; o CLI e o servidor MCP funcionam sem ele, então servidores headless, Docker e CI estão ok.

🎮 Guia de Uso (GUI & CLI)

1. Interface Gráfica do Usuário (GUI)

# Launch via Python
python main.py

# Or launch via Windows batch script
run.bat

# Or launch via legacy wrapper
python tzero.py

2. Interface de Linha de Comando (CLI)

O T-Zero V3 oferece um conjunto completo de flags CLI para entusiastas de terminal e 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

⌨️ Atalhos de Teclado

Atalho	Ação
`Ctrl+S`	Escanear Diretório do Workspace Ativo
`Ctrl+G`	Gerar / Compilar Árvore de Contexto
`Ctrl+C`	Copiar Contexto Gerado para a Área de Transferência
`Ctrl+R`	Atualizar Log Git e Branches

📂 Estrutura do Projeto

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

🧪 Suíte de Testes Automatizados e CI/CD

Execute todos os testes unitários e de integração localmente:

python -m unittest discover -s tests -v

Saída esperada:

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

O GitHub Actions executa automaticamente esta suíte de testes em cada push e pull request em runners Ubuntu e Windows sob Python 3.10, 3.11 e 3.12.

🛡️ GitHub Action (GitHub Marketplace)

O T-Zero está disponível como uma GitHub Action oficial (action.yml) para auditar codebases, impor limites de arquitetura e prevenir vazamentos de segredos diretamente em seus 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'

📄 Licença e Créditos

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para os termos completos.

Toprak Ahmet Aydoğmuş — Siber Akademi

💼 LinkedIn: toprak-ahmet-aydoğmuş
🔗 Links e 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.

Criptografia de Identidade em Nível de Sistema Operacional (Motor de Keyring do SO):
- Chaves de API nunca são armazenadas em arquivos de texto simples (.env, .json, .txt) ou em logs.
- São armazenadas no repositório nativo do sistema operacional por meio da biblioteca keyring multiplataforma:
- Windows: Windows Credential Manager
- macOS: Apple Keychain
- Linux: Secret Service API (GNOME Keyring / KWallet - via DBus)
Zero Telemetria e Privacidade Total de Dados:
- Seus códigos-fonte, dados de token, hierarquia de arquivos ou chaves de API nunca são transmitidos a terceiros, telemetria, análises ou servidores de desenvolvedores.
- Todo o tráfego de rede de saída é realizado exclusivamente por HTTPS diretamente para o endpoint oficial do provedor de IA que você escolher (NVIDIA, OpenAI, Google, Anthropic, OpenRouter ou Ollama local).
- O painel web local opcional (--web) roda apenas em 127.0.0.1; sua página carrega uma fonte do Google Fonts no seu navegador.
Backup Local Protegido por Senha (Keyring Backup):
- Quando você quiser transferir ou fazer backup das suas chaves de API, um arquivo binário .dat é criado aplicando um método XOR de chave repetitiva simples com uma senha definida pelo usuário. Este método não é salgado e não é criptografia forte; mantenha o arquivo em segredo e trate-o como um segredo. Por padrão, não é adicionado ao git.
Suporte a Variáveis de Ambiente de Sistema 12-Factor:
- Detecta e disponibiliza automaticamente as variáveis de ambiente definidas no seu sistema:
  - NVIDIA_API_KEY
  - OPENAI_API_KEY
  - GEMINI_API_KEY
  - OPENROUTER_API_KEY
  - ANTHROPIC_API_KEY
Modo 100% Offline (Dry-Run) (Custo de R$ 0):
- Você pode gerar árvores de contexto completas, mapas de assinatura AST e rascunhos de documentação inteiramente na sua máquina local, sem precisar de chaves de API, conexão com a internet ou assinatura de IA.

🤖 Servidor Model Context Protocol (MCP)

O T-Zero V3 oferece um servidor local (tzero_mcp.py) que se comunica via stdio usando o SDK padrão Model Context Protocol (MCP) da Anthropic. Isso permite que agentes de IA como Cursor, Claude Desktop, Antigravity IDE e Cline consultem a arquitetura hierárquica, o grafo de dependências e os limites do projeto antes de gerar ou modificar qualquer código no projeto.

🛠 Ferramentas MCP Oferecidas (13 Ferramentas Autônomas)

Nome da Ferramenta	Parâmetros	Função e Propósito
`get_project_context_tree`	`project_root`, `reduction_mode`, `max_tokens`, `include_file_contents`	Escaneia o diretório do projeto; retorna a Arquitetura Mestra T-1, Referências de Módulo T-2 e regras de limite T-4 como contexto hierárquico. Reduz o uso de tokens em até 95%.
`query_module_dependencies`	`project_root`, `file_path`	Busca o mapa de assinaturas de importação/exportação, links internos e pacotes externos de um arquivo específico ou de todo o repositório.
`query_architecture_boundaries`	`project_root`, `extra_guidance`	Consulta os limites de arquitetura ativos (T-4), regras e restrições Zero-Leak para agentes de IA.
`generate_architecture_blueprint`	`project_root`	Gera um documento de arquitetura do sistema (`ARCHITECTURE.md`) com diagrama de topologia Mermaid automático.
`generate_repo_map`	`project_root`, `max_tokens`	Gera um mapa de símbolos AST ultracomprimido (classes, métodos, assinaturas) para conversas de LLM.
`audit_codebase_quality`	`project_root`, `file_path`	Realiza análise estática de code smells AST e varredura de vazamento de chaves/senhas secretas (funções com 30+ linhas, chaves globais).
`find_code_duplicity`	`project_root`, `min_lines`	Detecta blocos de código copiados/duplicados com 6+ linhas no espaço de trabalho.
`estimate_token_cost`	`text`, `project_root`, `reduction_mode`	Gera uma tabela completa de custos em tokens e USD para o texto ou diretório fornecido, usando modelos OpenAI, Claude, Groq, NVIDIA NIM e Ollama ($0).
`analyze_change_impact`	`target_symbol`, `project_root`	Calcula definições de símbolos AST, cadeias de chamadores e o raio de impacto (blast radius) com pontuação de risco de 0 a 100 antes do refactoring.
`enforce_architecture_boundaries`	`project_root`, `rules_file`	Audita imports proibidos entre camadas de acordo com as regras `tzero.rules.json` e impede a degradação da arquitetura.
`search_codebase_semantic`	`query`, `project_root`, `top_k`	Motor de busca semântica de código e RAG híbrido BM25 + TF-IDF, 100% local e privado, em memória (custo de $0, zero vazamento de dados).
`export_agent_rules`	`project_root`	Gera regras do Cursor (`.cursorrules`, `.cursor/rules/*.mdc`), Cline (`.clinerules`) e Copilot com um clique.
`get_token_savings_metrics`	`project_root`, `team_size`	Calcula a taxa quantitativa de economia de tokens, o lucro mensal/anual de custos e os valores de ROI baseados em equipe.

🧭 Prompts Embutidos do MCP

tzero_grounding: Injeta regras de arquitetura, limites modulares e diretrizes de segurança 100% Zero-Leak em sessões do Cursor / Claude / Antigravity.

📊 Benchmark de Tokens (Exemplo de Arquivo Único)

O tzero_v3.py no commit 4846dcf foi medido com o estimador count_tokens_precise do projeto (aproximadamente karakter / 4):

Entrada	Estimativa de código-fonte completo	Assinaturas AST Ultra	Redução estimada
`tzero_v3.py` (224.150 caracteres)	56.037 tokens	3.088 tokens	94,5%

Para reproduzir: 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 é apenas uma comparação baseada em assinaturas de um único arquivo; não é uma medição de todo o repositório ou da qualidade da resposta. Os tokenizadores do provedor e a sobrecarga de resposta do MCP variam. Use o modo balanced ou o código-fonte quando detalhes de implementação forem necessários.

🔌 Adicionando o T-Zero a Clientes MCP

O T-Zero oferece um servidor MCP stdio local totalmente suportado para Cursor, Claude Desktop, Antigravity IDE, VS Code, Windsurf, Cline e Roo Code.

🚀 Opção 1: Instalação mais simples em 1 minuto com pip (Pacote PyPI Oficial — Multiplataforma)

A maneira mais fácil e oficial de instalar e executar o T-Zero no Windows, macOS ou Linux:

pip install tzero-mcp

Após a instalação, você pode usá-lo como quiser:

Conecte-se a todos os seus IDEs (Cursor, Claude, Antigravity, VS Code, Cline) com um clique:
```
tzero-add-mcp
```
Execute o Assistente de Terminal (CLI):
```
tzero --cli
```
Abra o Painel Visual da Área de Trabalho (GUI):
```
tzero-gui
# veya:
tzero --gui
```
Se você quiser fazer a Configuração Manual do MCP: No arquivo de configuração do seu IDE (mcp_config.json, claude_desktop_config.json ou configurações do Cursor):
```
{
  "mcpServers": {
    "tzero": {
      "command": "tzero-mcp"
    }
  }
}
```

🌐 Opção 1B: Instalação Web Instantânea em Uma Linha (Zero Instalação)

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 Smithery:

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

⚡ Opção 2: Instalação do Windows com um clique e zero requisitos (Binário Independente)

Baixe diretamente o arquivo AddMCP.exe da página Última Versão (v3.0.7):

Interface Gráfica (GUI): Clique duas vezes no arquivo AddMCP.exe. Ele detecta automaticamente todos os IDEs instalados no seu computador e conclui a integração com um clique.
Terminal / Linha de Comando: AddMCP.exe --all (instala silenciosamente em todos os IDEs detectados sem abrir nenhuma interface).
Zero Requisitos: Não requer Python, pip, pipx ou Git. Ele carrega o motor de execução independente TZeroMCP.exe embutido.

📦 Opção 3: Execução Remota com pipx (Multiplataforma: Windows, macOS, Linux)

Na primeira inicialização, o pacote fixado v3.0.7 é baixado automaticamente do GitHub; não é necessário clonar o repositório. Python 3.9+ e pipx são necessários:

Instalação do pipx no Windows

Abra o PowerShell e execute:

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

Após a instalação, reinicie o cliente. As configurações do Windows abaixo executam o comando py -m pipx diretamente; não dependem do arquivo pipx.exe estar no PATH. No macOS/Linux, instale o pipx com as diretrizes oficiais da plataforma e execute pipx ensurepath.

Instalação com um clique no Cursor

Abra o link apropriado para o seu sistema operacional, confirme a configuração do Cursor e ative o servidor tzero em Settings → MCP ou Customize → MCP.

Se o link não abrir, vá para Settings → MCP → Add Custom MCP e cole o JSON apropriado para a plataforma abaixo.

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.
Adicione o bloco JSON do Windows ou macOS/Linux acima ao objeto mcpServers existente; não exclua outros registros de servidor.
Salve o arquivo, feche e reabra o Claude Desktop completamente.
Verifique se o servidor tzero está em execução em Settings → Developer.

Caminhos de configuração: 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.
O botão Add MCP abre o Antigravity MCP Store. Se o T-Zero aparecer na lista, clique em Add; se não aparecer, use a configuração stdio personalizada abaixo.
Adicione o registro tzero do bloco JSON do Windows ou macOS/Linux ao arquivo mcp_config.json do Antigravity; preserve os registros mcpServers existentes. No Windows, o caminho de configuração do usuário é %USERPROFILE%\.gemini\config\mcp_config.json (ou ~/.gemini/antigravity/mcp_config.json).
Salve/atualize os servidores MCP e permita as ferramentas quando solicitado.

⚡ Comando Slash e Recurso do Antigravity (`/tzero`)

O T-Zero oferece suporte integrado ao Antigravity Skill (.agents/skills/tzero/SKILL.md e ~/.gemini/config/skills/tzero/SKILL.md). Digite /tzero diretamente no campo de chat do Antigravity para listar ou executar comandos:

/tzero ou /tzero tree — Gera a árvore de contexto multicamadas com economia de 95% de tokens
/tzero audit — Executa a auditoria de segurança 100% Zero-Leak e code smells AST
/tzero arch — Gera ARCHITECTURE.md com diagramas Mermaid ao vivo
/tzero deps [dosya] — Analisa a topologia de dependências do módulo
/tzero impact <sembol> — Calcula a pontuação do raio de impacto do símbolo antes do refactoring
/tzero rules — Gera regras .cursorrules, .clinerules e Copilot
/tzero search <sorgu> — Executa a busca semântica de código BM25 100% local e privada
/tzero savings — Calcula a análise de economia de tokens ROI baseada em equipe

Consulte o guia oficial do Antigravity MCP para configurações e esquema de configuração atuais.

VS Code Copilot

Abra a Paleta de Comandos (Ctrl+Shift+P) e execute MCP: Add Server.
Selecione Command (stdio); insira o comando py no Windows, pipx no macOS/Linux e os argumentos acima.
Salve em .mcp.json ou .vscode/mcp.json; inicie e confie no servidor tzero na visualização MCP Servers.

Para .vscode/mcp.json, o VS Code usa o objeto servers de nível superior e 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 e Outros

Abra as configurações do servidor MCP do cliente, selecione Add/Edit Server e adicione o registro mcpServers do Windows ou macOS/Linux acima. O Claude Code pode usar o arquivo .mcp.json na raiz do projeto; Cline, Roo Code e Windsurf oferecem seus próprios painéis de configuração MCP. Reinicie o cliente e confirme o servidor.

Atualmente, o único URL público de um clique verificado que instala qualquer servidor MCP stdio local está disponível apenas no Cursor. Outros clientes usam seu próprio arquivo/painel de configuração; os JSONs acima estão prontos para uso direto.

Inicialização pela Linha de Comando

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

🏗 Arquitetura do 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"]

🌟 Recursos e Funcionalidades em Destaque

### 1. Integração com Múltiplos Provedores 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: Gateway universal para claude-3.7-sonnet, gpt-4o, deepseek-r1
Ollama Local: llama3:latest, mistral:latest, phi3:latest, qwen2.5:latest (100% local, offline, privado e gratuito)

2. Redutor Inteligente de Tokens AST (Economia de até 95%)

Modo Ultra: Limpa corpos de funções; preserva hierarquia de classes, decoradores, docstrings, dicas de tipo e cabeçalhos completos de funções/classes/imports multilinha em Python.
Modo Balanceado: Mantém blocos de controle essenciais (if/try/for) e tratamento de exceções junto com as assinaturas.
Modo Nenhum: Preserva 100% do código-fonte original.
Idiomas suportados: Python, JavaScript, TypeScript, JSX/TSX, C/C++, Go, Rust, HTML, CSS, Bash, Batch, JSON, YAML.

3. Ferramentas Avançadas de Análise de Base de Código

Árvore de Classes e Métodos AST: Lista hierarquicamente todas as classes, métodos, listas de argumentos e decoradores.
Auditor de Código Estático: Detecta instantaneamente docstrings ausentes, rotinas excessivamente complexas com mais de 30 linhas, funções com 6 ou mais parâmetros e uso da palavra-chave global (suporta tanto síncrono def quanto assíncrono async def).
Analisador de Dependências: Examina nós de importação AST para mapear módulos internos e externos do projeto.
Localizador de Duplicidade: Detecta blocos de código duplicados com 6+ linhas em todo o espaço de trabalho.
Motor de Refatoração AST: Refatora automaticamente nomes de funções e variáveis em todo o projeto usando transformação segura de AST.

4. Controle de Versão Git e Telemetria Visual ao Vivo

Classificador de Histórico de Commits: Etiqueta automaticamente commits recentes (Adicionado, Corrigido, Refatorado, Atualizado).
Diff Git Colorido ao Vivo: Exibe alterações não salvas (git diff HEAD) com coloração de sintaxe.
Gerenciador Git Integrado: Operações de stage, commit e troca de branch via GUI.
Grafo de Dependências Interativo: Desenha relações entre arquivos como um grafo físico de nós com suporte a arrastar e soltar.
Telemetria de CPU e RAM ao Vivo: Acompanha o uso de recursos do sistema em tempo real.
Gráfico de Rosca de Tokens: Desenha distribuição de tipos de arquivo, volume e consumo de tokens em canvas dinâmico.

5. GUI Futurista, Animações Dinâmicas de Partículas e Sons Hápticos

8 Temas Personalizados:
- 🌌 Glass Dark (Vidro fosco e destaques ciano)
- ⚡ Neon Cyberpunk (Fúcsia vibrante e azul elétrico)
- 🖤 Midnight OLED (Preto puro #000000 para zero cansaço visual)
- 🟢 Matrix Terminal (Verde hacker fosforescente clássico #00ff41)
- 🌆 Synthwave 80s (Magenta laser, laranja neon e azul retrô)
- ❄️ Nordic Frost (Cinza polar e azul glacial)
- ☕ Solarized Amber (Espresso profundo e âmbar quente)
- 🕹 Siber Retro (Tema clássico da Cyber Akademi)
Motor de FX de Partículas Dinâmicas com 4 Modos:
- 🌌 Estrelas: Túnel de estrelas com profundidade 3D e velocidade variável.
- 🟢 Chuva Matrix: Chuva digital de código e caracteres verdes caindo.
- 🌐 Grade Cyber: Onda de wireframe em perspectiva até a linha do horizonte.
- ⬛ Minimal Sólido: Fundo escuro minimalista puro com zero consumo de CPU.
Motor de Som Háptico (SFX): Fornece feedback sonoro em cliques, conclusão de varredura e geração de contexto (winsound.Beep roda em segundo plano, nunca congela a interface; pode ser ativado/desativado com um clique na barra de título 🔊 SFX ON / 🔇 SFX OFF).
Notificações Toast Cyberpunk Flutuantes: Exibe notificações suaves sem incomodar o usuário em operações de copiar e salvar na área de transferência.

6. Pacote de Exportação Multi-Formato (Context Architect Hub)

README.md: Documentação detalhada do repositório e arquitetura.
AGENTS.md / CLAUDE.md: Guia de sistema e regras estruturado especificamente para agentes de codificação de IA como Cursor, Antigravity IDE, Claude Code, Cline e Copilot.
ARCHITECTURE.md: Especificação de arquitetura com diagrama Mermaid gerado automaticamente e hierarquia de dependências de módulos.
REPO_MAP.txt: Mapa de símbolos AST ultracomprimido para colar diretamente em janelas de chat de LLM.
README.html: Pré-visualização HTML visual com tema escuro cyberpunk, aberta com um clique no navegador.
Calculadora de Orçamento de Tokens e Custo em USD ao Vivo: Contagem de tokens em tempo real e custo estimado de gastos com API com base no modelo selecionado.

📦 Instalação e Primeiros Passos

Método 1: Instalação com Um Clique (.bat) — Recomendado para Windows

install_requirements.bat

Baixa automaticamente o Python 3.12 mesmo que não esteja no sistema, configura o ambiente virtual e instala todos os pacotes completamente.

Método 2: Executável Independente (.exe)

Baixe o arquivo TZeroAlgorithm.exe para o aplicativo de desktop. Execute o arquivo AddMCP.exe para adicionar o MCP aos IDEs detectados; vem com TZeroMCP.exe, não requer Python/pipx, preserva registros de servidores existentes e faz backup dos arquivos de configuração antes de alterá-los. TZeroMCP.exe também é fornecido para instalação manual.

Método 3: Pacote Python / Instalação via 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

O nome do projeto no PyPI é tzero-algorithm, e o comando MCP instalado é tzero-mcp. Até o primeiro lançamento no PyPI, use a configuração pipx run --spec do GitHub acima.

Verificação automática de dependências: O T-Zero valida os pacotes necessários na inicialização e instala os ausentes ou desatualizados (a saída vai para stderr, sem corromper o stdio do MCP). Use TZERO_NO_AUTO_INSTALL=1 para desativar. Execute python main.py --doctor para uma verificação completa de saúde. A interface desktop requer tkinter; o CLI e o servidor MCP funcionam sem ele, portanto, servidores, Docker e ambientes CI funcionam sem problemas.

🎮 Guia de Uso (GUI & CLI)

1. Interface Gráfica do Usuário (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. Interface de Linha de Comando (CLI)

Flags avançadas de linha de comando para desenvolvedores de terminal e automações 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

⌨️ Atalhos de Teclado

Atalho	Ação
`Ctrl+S`	Escanear Espaço de Trabalho Selecionado
`Ctrl+G`	Compilar / Gerar Árvore de Contexto
`Ctrl+C`	Copiar Conteúdo Gerado para a Área de Transferência
`Ctrl+R`	Atualizar Histórico e Branches do Git

📂 Árvore de Diretórios do Projeto

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

🧪 Processo de Teste Automatizado e CI/CD

Para executar todos os testes unitários e de integração localmente:

python -m unittest discover -s tests -v

Saída esperada:

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

O GitHub Actions executa automaticamente esses testes com Python 3.10, 3.11 e 3.12 em ambientes Ubuntu e Windows em cada push e pull request no repositório.

🛡️ GitHub Action (Integração com GitHub Marketplace)

O T-Zero também funciona no GitHub Actions para auditar qualidade de código, manter limites de arquitetura e prevenir vazamentos de chaves secretas em seus processos 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'

📄 Licença e Informações do Desenvolvedor

Este projeto é licenciado sob a Licença MIT. Para detalhes, consulte o arquivo LICENSE.

Toprak Ahmet Aydoğmuş — Cyber Akademi

💼 LinkedIn: toprak-ahmet-aydoğmuş
🔗 Links e Biografia: hopp.bio/siberegitim
🐙 GitHub: @toprakahmetaydogmus

tzero-mcp

Documentação

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

⚡ Prova Visual: Ingestão Bruta vs. Poda AST T-Zero (Reproduzível)

🚀 Início Rápido em 1 Linha

🇬🇧 Inglês

Sumário

🔒 Arquitetura de Segurança (Garantia 100% Zero-Vazamento)

🤖 Servidor Model Context Protocol (MCP)

🛠 Ferramentas MCP Disponíveis (16 Ferramentas Autônomas)

📦 Recursos MCP Ao Vivo

🧭 Prompts MCP

📊 Benchmark de Tokens (Exemplo de Arquivo Único)

🔌 Adicionar T-Zero aos Clientes MCP

🚀 Opção 1: Início Rápido de 1 Minuto com pip (PyPI Oficial — Multiplataforma)

🌐 Opção 1B: Instalador Web Instantâneo com 1 Clique (Zero Configuração)

⚡ Opção 2: Instalador Windows de 1 Clique com Zero Dependências (Binário Autônomo)

📦 Opção 3: Lançamento Remoto via pipx (Multiplataforma: Windows, macOS, Linux)

Instalar pipx no Windows

Instalação com 1 Clique no Cursor

Claude Desktop

Google Antigravity IDE

⚡ Comando Slash e Skill do Antigravity (/tzero)

VS Code Copilot

Claude Code, Cline, Roo Code, Windsurf e Outros Clientes MCP

Inicialização via CLI

🏗 Arquitetura do Sistema

🌟 Destaques Principais e Capacidades

1. Motor Multi-LLM de Provedores

2. Redutor de Tokens via AST (Economia de Até 95% de Tokens)

3. Ferramentas Avançadas de Análise de Código

4. Integração Git VCS e Telemetria Visual

5. UI Futurista, Efeitos de Partículas Dinâmicas e SFX de Áudio Háptico

6. Hub de Exportação de Contexto Multi-Formato

📦 Instalação e Configuração

Método 1: Instalador com Um Clique (Recomendado para Windows)

Método 2: Executável Portátil Autônomo (.exe)

Método 3: Pacote Python / Instalação via pip

🎮 Guia de Uso (GUI & CLI)

1. Interface Gráfica do Usuário (GUI)

2. Interface de Linha de Comando (CLI)

⌨️ Atalhos de Teclado

📂 Estrutura do Projeto

🧪 Suíte de Testes Automatizados e CI/CD

🛡️ GitHub Action (GitHub Marketplace)

📄 Licença e Créditos

🇹🇷 Türkçe

İçindekiler

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

🤖 Servidor Model Context Protocol (MCP)

🛠 Ferramentas MCP Oferecidas (13 Ferramentas Autônomas)

🧭 Prompts Embutidos do MCP

📊 Benchmark de Tokens (Exemplo de Arquivo Único)

🔌 Adicionando o T-Zero a Clientes MCP

🚀 Opção 1: Instalação mais simples em 1 minuto com pip (Pacote PyPI Oficial — Multiplataforma)

🌐 Opção 1B: Instalação Web Instantânea em Uma Linha (Zero Instalação)

⚡ Opção 2: Instalação do Windows com um clique e zero requisitos (Binário Independente)

📦 Opção 3: Execução Remota com pipx (Multiplataforma: Windows, macOS, Linux)

Instalação do pipx no Windows

Instalação com um clique no Cursor

Claude Desktop

Google Antigravity IDE

⚡ Comando Slash e Recurso do Antigravity (/tzero)

VS Code Copilot

Claude Code, Cline, Roo Code, Windsurf e Outros

Inicialização pela Linha de Comando

🏗 Arquitetura do Sistema

🌟 Recursos e Funcionalidades em Destaque

2. Redutor Inteligente de Tokens AST (Economia de até 95%)

3. Ferramentas Avançadas de Análise de Base de Código

4. Controle de Versão Git e Telemetria Visual ao Vivo

5. GUI Futurista, Animações Dinâmicas de Partículas e Sons Hápticos

6. Pacote de Exportação Multi-Formato (Context Architect Hub)

📦 Instalação e Primeiros Passos

Método 1: Instalação com Um Clique (.bat) — Recomendado para Windows

Método 2: Executável Independente (.exe)

Método 3: Pacote Python / Instalação via pip

🎮 Guia de Uso (GUI & CLI)

1. Interface Gráfica do Usuário (GUI)

2. Interface de Linha de Comando (CLI)

⚡ Comando Slash e Skill do Antigravity (`/tzero`)

⚡ Comando Slash e Recurso do Antigravity (`/tzero`)