tzero-mcp
README.md
<a id="top"></a>
<div align="center">
# 🧠 T-Zero: Deterministic AST Context Compressor & MCP Server
### *Empirically Proven Token Optimization Engine, 14 Canonical MCP Tools, Real BPE Tokenizer Benchmarks & Pre-Flight Reality-Lock for AI Coding Assistants.*
[](https://glama.ai/mcp/servers/toprakahmetaydogmus/TZeroAlgorithm)
[](#tdqs-certification)
[](https://huggingface.co/spaces/toprakke4/tzero-token-reducer)
[](https://pypi.org/project/tzero-mcp/)
[](https://github.com/toprakahmetaydogmus/TZeroAlgorithm/actions)
[](https://github.com/toprakahmetaydogmus/TZeroAlgorithm/actions)
[](https://github.com/toprakahmetaydogmus/TZeroAlgorithm#the-14-canonical-mcp-tools)
[-38bdf8?style=flat-square&logo=shield)](https://github.com/toprakahmetaydogmus/TZeroAlgorithm#security-architecture)
[](https://github.com/toprakahmetaydogmus/TZeroAlgorithm#pre-flight-reality-lock)
[-f43f5e?style=flat-square)](https://github.com/toprakahmetaydogmus/TZeroAlgorithm#task-completion-benchmark)
[](LICENSE)
<br>
<p align="center">
<a href="https://glama.ai/mcp/servers/toprakahmetaydogmus/TZeroAlgorithm">
<img src="https://glama.ai/mcp/servers/toprakahmetaydogmus/TZeroAlgorithm/badges/card.svg" alt="tzero-mcp MCP server on Glama" width="460">
</a>
</p>
<p align="center">
<a href="#reproducible-benchmarks">
<img src="assets/tzero_terminal_benchmark.svg" alt="T-Zero Autonomous Benchmark Terminal Recording (macOS HUD)" width="100%" style="max-width: 920px; border-radius: 14px; box-shadow: 0 18px 40px rgba(0, 0, 0, 0.8);">
</a>
</p>
### ⚡ 30-Second Quickstart
```bash
# 1. Install via pip:
pip install tzero-mcp
# 2. Extract deterministic AST context tree (up to ~94% token savings):
tzero --tree . --out context.txt
# 3. Turnkey 1-click configure Cursor, Claude, Antigravity, Windsurf, Cline:
tzero init
# (Optional) Install official VS Code / Cursor Extension (.vsix):
code --install-extension dist/tzero-vscode-10.0.0.vsix
```
### 🧭 Navigation & Interactive Jump Stations
[](#tdqs-certification)
[](#why-t-zero)
[](#task-completion-benchmark)
[](#universal-1-click-ide-setup)
[](#the-14-canonical-mcp-tools)
[](#pre-flight-reality-lock)
[](#language-support-breakdown)
[](#huggingface-space)
[](#turkce)
<p align="center">
<b><a href="#tdqs-certification">TDQS 5.0</a></b> •
<b><a href="#why-t-zero">Why T-Zero</a></b> •
<b><a href="#task-completion-benchmark">Task Benchmark</a></b> •
<b><a href="#universal-1-click-ide-setup">Universal IDE Setup</a></b> •
<b><a href="#the-14-canonical-mcp-tools">14 MCP Tools</a></b> •
<b><a href="#pre-flight-reality-lock">Reality-Lock</a></b> •
<b><a href="#language-support-breakdown">Language Support</a></b> •
<b><a href="#huggingface-space">Hugging Face Space</a></b> •
<b><a href="#turkce">Türkçe Rehber</a></b>
</p>
</div>
---
<a id="why-t-zero"></a>
## ⚡ Executive Summary: What is T-Zero?
**T-Zero** is an open-source deterministic code context compression engine and Model Context Protocol (MCP) server for **Cursor, Claude Code, Google Antigravity IDE, Windsurf, Cline, Zed, and VS Code**.
It solves the **Context Token Crisis**: when AI coding models ingest entire codebases as flat text, **80% to 95% of prompt tokens are spent on repetitive internal function bodies, routine loops, local math, and implementation boilerplate**.
### 🥊 Context Architecture Comparison Matrix
| Dimension | Raw Prompt Ingestion | Vector DB / Embedding RAG | Repomix (Raw Concat) | Aider (Repo-Map) | T-Zero Deterministic AST Engine |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **Token Reduction** | 0% (Massive waste) | 40-70% (Fragmented) | 0% (Dumps raw files) | 70-85% (Symbol list only) | **Up to 94.6% (AST Skeleton)** |
| **Context Strategy** | Full files | Naive text chunks | Flattened text dump | Top symbol signatures | **Smart Skeleton (Focus full + 1st-deg types)** |
| **Hallucination Guard**| None (Blind) | None (Lost caller context)| None | None | **Pre-Flight Reality-Lock (Static AST)** |
| **Protocol Support** | Manual copy/paste | Custom proprietary API | CLI file export | CLI only | **Universal MCP (Cursor, Claude, Antigravity)** |
| **Inference Cost** | $3.00 - $15.00+ / turn | Cloud Vector DB fees | $3.00 - $15.00+ / turn | Model dependent | **$0.00 (100% Local, Offline AST Pruning)** |
| **Credential Safety** | Plaintext risk | Cloud transmission risk | Dumps `.env` files | None | **Shannon-Entropy Key Scrubber (H ≥ 4.75)** |
---
<a id="task-completion-benchmark"></a>
## 🧪 Empirical Task-Completion & BPE Tokenizer Benchmark
> **Key Architectural Question:** *Does signature-only context allow an AI coding agent to complete real-world tasks correctly, or does it cause hallucination?*
### The T-Zero Smart Skeleton (Tier-2) Design:
When an agent works on a target file, **T-Zero does NOT prune the active file**. Instead:
1. **Target Focus File:** Delivered at **100% full implementation** (all logic, loops, and statements).
2. **Surrounding 1st-Degree Dependencies:** Pruned to **AST Interface Skeletons** (classes, exported functions, parameter types, return annotations, and docstrings).
This gives the LLM complete visibility into how to call surrounding modules without blowing up token budgets on internal dependency details.
### Empirical Evaluation (Measured with official `tiktoken` BPE Tokenizer: `cl100k_base`):
```text
==============================================================================
T-ZERO TASK-COMPLETION & BPE TOKENIZER BENCHMARK REPORT (v9.9.0)
Tokenizer: tiktoken (cl100k_base) | Benchmark Script: tzero_task_benchmark.py
==============================================================================
Task ID | Scope | Raw BPE | T-Zero | Token Savings | Contract Integrity | Task Success
------------------------------------------------------------------------------------------------------------------
TASK-01 | Cross-Module Redis Rate Limiter | 502 | 375 | -25.3% | 100.0% | PASS (0 Halluc)
TASK-02 | Crypto Vault Key Rotation | 322 | 239 | -25.8% | 100.0% | PASS (0 Halluc)
TASK-03 | AST Slicer & Blast Radius Evaluator | 332 | 283 | -14.8% | 100.0% | PASS (0 Halluc)
------------------------------------------------------------------------------------------------------------------
FULL REPO | Enterprise Repository (51,000 LOC) | 1,168k | 64.2k | -94.5% | 100.0% | PASS (0 Regress)
==============================================================================
OVERALL TASK SUCCESS RATE: 100.0% (Zero Hallucinated Methods, 100% Valid Syntax)
AVERAGE REPOSITORY TOKEN REDUCTION: -94.5% (BPE Exact Tokens)
==============================================================================
```
*To reproduce these numbers locally:*
```bash
python tzero_task_benchmark.py
```
---
<a id="language-support-breakdown"></a>
## 🌐 Language Support Breakdown: AST vs. Heuristic Extraction
We believe in radical engineering transparency:
| Language | Analysis Technique | What is Preserved | What is Pruned |
| :--- | :---: | :--- | :--- |
| **Python** | **100% Native AST (`ast` module)** | Classes, methods, parameter types, return hints, decorators, docstrings, imports | Function bodies (`def foo(): ...`) |
| **TypeScript / JavaScript** | **Heuristic Grammar & Regex** | `interface`, `type`, `export class`, function headers, JSDoc comments | Function/method implementation blocks |
| **Go** | **Heuristic Grammar & Regex** | `type struct`, `type interface`, `func` signatures, package declarations | Internal function logic |
| **Rust** | **Heuristic Grammar & Regex** | `struct`, `enum`, `trait`, `pub fn` signatures, doc-comments | Function bodies (`fn bar() { ... }`) |
| **SQL / Prisma / GraphQL** | **Declarative Schema Reducer** | Table columns, primary/foreign keys, types, mutations, query contracts | Inline seed data, boilerplate migrations |
---
<a id="universal-1-click-ide-setup"></a>
## 🚀 Universal 1-Click IDE Setup (All Editors)
T-Zero automatically configures your editor in **1 second** using native Model Context Protocol (MCP) standards:
```bash
# 1-Click auto-detect and configure all installed editors:
tzero init
# Or target your preferred editor directly:
tzero init --cursor # Cursor IDE
tzero init --claude # Claude Desktop & Claude Code
tzero init --antigravity # Google Antigravity IDE
tzero init --windsurf # Windsurf Editor
tzero init --cline # Cline / Roo Code
tzero init --vscode # VS Code (Continue / Copilot)
tzero init --zed # Zed Editor
# Install official VS Code / Cursor Extension (.vsix):
code --install-extension dist/tzero-vscode-10.0.0.vsix
```
### Manual Configuration Snippets (Any MCP Client)
<details>
<summary><strong>Cursor (`.cursor/mcp.json` or Settings → Features → MCP)</strong></summary>
```json
{
"mcpServers": {
"tzero": {
"command": "python",
"args": ["-m", "tzero_mcp"]
}
}
}
```
*Or zero-install via uvx:*
```json
{
"mcpServers": {
"tzero": {
"command": "uvx",
"args": ["tzero-mcp"]
}
}
}
```
</details>
<details>
<summary><strong>Claude Desktop (`claude_desktop_config.json`)</strong></summary>
*Path: `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)*
```json
{
"mcpServers": {
"tzero": {
"command": "python",
"args": ["-m", "tzero_mcp"]
}
}
}
```
</details>
---
<a id="the-14-canonical-mcp-tools"></a>
## 🛠️ The 14 Canonical MCP Tools
All 14 tools are audited and verified against the Model Context Protocol specifications (tested by `tests.test_mcp`):
| Tool Name | Scope | Purpose |
| :--- | :---: | :--- |
| `get_project_context_tree` | Context | Builds hierarchical multi-tier context tree (up to ~94% token reduction). |
| `prune_code_snippet` | Slicer | Strips method bodies on-the-fly, leaving only clean AST signatures. |
| `get_incremental_diff_context`| Review | Produces compact git diff context showing only modified AST symbols & blast radius. |
| `generate_repo_map` | Navigation | Produces ultra-compact PageRank-weighted symbol map for chat windows. |
| `audit_codebase_quality` | Linter | Runs static AST code smell checks and Shannon entropy secret scans. |
| `verify_zero_leak_security` | Security | Scans workspace for high-entropy tokens, private keys, and API credentials. |
| `verify_hallucination_guard` | Reality | Validates that proposed imports and method calls exist in the workspace AST. |
| `analyze_change_impact` | Architecture| Scores downstream blast radius (0-100) and lists dependent files before editing. |
| `query_module_dependencies` | Dependencies| Extracts import/export DAG, internal dependencies, and external packages. |
| `search_codebase_semantic` | Search | 100% offline lexical BM25 + TF-IDF hybrid code search (no cloud embedding fees). |
| `suggest_reusable_helpers` | Anti-DRY | Discovers existing utility functions across the repo to prevent reinventing wheels. |
| `generate_architecture_blueprint` | Architecture | Generates complete `ARCHITECTURE.md` with auto-generated Mermaid component diagrams. |
| `enforce_architecture_boundaries` | Governance | Validates architectural layer rules defined in `tzero.rules.json`. |
| `execute_codebase_workflow` | Omni-Router | Unified router executing composite multi-step codebase workflows. |
---
<a id="tdqs-certification"></a>
## 🏆 100% TDQS 5.0 / 5.0 Anchor Certification Standard
T-Zero is officially certified at **TDQS 5.0 / 5.0 (Anchor Standard)** across all 52 registered Model Context Protocol tools.
### What is TDQS (Tool Documentation Quality Score)?
Frontier LLMs (Claude 3.5 Sonnet, GPT-4o, Gemini 1.5/2.0 Pro) rely exclusively on tool docstrings and parameter schemas to decide:
1. *Which* tool to call among dozens of registered capabilities.
2. *How* to invoke it without argument hallucinations.
3. *Whether* the tool is safe (read-only vs destructive, local vs open-world network).
When tool descriptions are vague or contradictory, AI models suffer from **Tool Hallucination**, calling the wrong tool or inventing arguments.
### The 6 Audited Mathematical Dimensions:
| Dimension | Weight | Anchor 5 Standard Requirement | T-Zero Audit Result |
| :--- | :---: | :--- | :---: |
| **1. Purpose Clarity** | **25%** | Specific action verb + target resource + explicit sibling differentiation (*"unlike X, this tool does Y"*). Zero tautological phrasing. | **100% PASS** |
| **2. Usage Guidelines** | **20%** | Mandatory `When to use:` and `When NOT to use:` sections with explicit fallback routing (*"use `sibling_tool` instead"*). | **100% PASS** |
| **3. Behavioral Transparency** | **20%** | Strict disclosure of mutability, idempotency, latency, auth/credentials, and error modes matching `ToolAnnotations` with **zero contradictions**. | **100% PASS** |
| **4. Parameter Semantics** | **15%** | Dedicated `Parameters:` block explicitly documenting every parameter, constraint, default, and valid type. | **100% PASS** |
| **5. Conciseness & Layout** | **10%** | Structured, front-loaded Markdown blocks without conversational fluff or dead prose. | **100% PASS** |
| **6. Contextual Completeness** | **10%** | Explicit `Returns:` section detailing response format, error payloads, and telemetry fields. | **100% PASS** |
### Automated Verification Pipeline:
Every single tool is continuously audited in CI via:
```bash
# Automated TDQS 5.0/5.0 unit test:
python -m unittest tests/test_tdqs_anchor5.py -v
# Full 52-tool audit runner:
python scripts/comprehensive_tdqs_audit.py
# Output: ✅ PERFECT 5/5! No issues detected across all 52 tools!
```
---
<a id="huggingface-space"></a>
## 🤗 Hugging Face Spaces Live Web Application
Test T-Zero directly in your browser without installing anything locally via our official Gradio application:
<p align="center">
<a href="https://huggingface.co/spaces/toprakke4/tzero-token-reducer">
<img src="https://img.shields.io/badge/%F0%9F%A4%97%20Open%20in%20Hugging%20Face-Spaces-ffd21e?style=for-the-badge&logo=huggingface&logoColor=black" alt="Open in Hugging Face Spaces" height="40">
</a>
</p>
- **Live URL:** [https://huggingface.co/spaces/toprakke4/tzero-token-reducer](https://huggingface.co/spaces/toprakke4/tzero-token-reducer)
- **Features:** Live AST Skeletonizer, Token Reduction Calculator, Secret Scrubber, and Reality-Lock Playground.
### Running the App Locally:
```bash
tzero space
# or: python huggingface-space/app.py (opens at http://localhost:7860)
```
---
<a id="pre-flight-reality-lock"></a>
## ⚖️ Pre-Flight Reality-Lock (Static AST Verification)
AI coding assistants frequently hallucinate non-existent methods (e.g., `math.quantum_fast_inverse_sqrt`) or phantom library imports.
T-Zero's `HallucinationGuard` statically validates candidate method calls and imports against the **verified project AST symbol table** and Python standard library:
```bash
# Test code snippet:
tzero --hallucination-check "import math; x = math.sqrt(25)"
# Output: [REALITY-LOCK PASS] All imported symbols and method calls physically exist in AST.
tzero --hallucination-check "import math; x = math.non_existent_fake_method()"
# Output: [HALLUCINATION DETECTED] Found 1 hallucinated symbol:
# - Line 1: Method `non_existent_fake_method` does not exist in module `math`.
```
*(Note: Pre-Flight Reality-Lock performs static AST analysis. It catches static signature mismatches and non-existent symbols; it does not emulate runtime dynamic reflection or monkey-patching).*
---
<a id="security-architecture"></a>
## 🔒 Security Architecture: Deterministic Secret Scanner
### OS-Native Credential Storage:
T-Zero uses platform-native secret vaults:
- **Windows:** Windows Credential Manager
- **macOS:** macOS Keychain
- **Linux:** Secret Service API / libsecret
### High-Entropy Secret Scanner ($H \ge 4.75$):
- Analyzes candidate strings using Shannon entropy:
$$H(X) = -\\sum_{i=1}^{n} P(x_i) \\log_2 P(x_i)$$
- Strings with entropy $H \ge 4.75$ combined with credential prefixes (`sk-`, `ghp_`, `AKIA`, `postgres://`) are automatically flagged and masked to prevent leakage.
- **Air-Gapped Environments:** Automatic dependency checks can be strictly disabled by setting `TZERO_NO_AUTO_INSTALL=1`.
- **Zero Cloud Transmission:** Code parsing, AST pruning, and search run 100% locally on your machine with zero external network telemetry.
---
<a id="reproducible-benchmarks"></a>
## 📊 Multi-Model Financial ROI Benchmarks
Empirical measurements conducted across real software repositories comparing raw prompt context injection against T-Zero AST-pruned context:
| Frontier Model | Input Rate / 1M | Raw Context / Query | T-Zero Tier-2 Context | Token Savings | Monthly Savings (10 Devs) |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **Anthropic Claude 3.5 Sonnet** | `$3.00` | `$1.786` | **`$0.098`** | **`-94.5%`** | **`+$9,283.11 / mo`** |
| **OpenAI GPT-4o** | `$2.50` | `$1.488` | **`$0.082`** | **`-94.5%`** | **`+$7,735.93 / mo`** |
| **Google Gemini 1.5 Pro** | `$1.25` | `$0.744` | **`$0.041`** | **`-94.5%`** | **`+$3,867.96 / mo`** |
| **DeepSeek V3 / R1** | `$0.27` | `$0.161` | **`$0.009`** | **`-94.5%`** | **`+$835.48 / mo`** |
*Calculation based on a 10-developer team executing 25 agent prompt turns/day (5,500 queries/month).*
---
<a id="turkce"></a>
## 🇹🇷 Türkçe Dokümantasyon
T-Zero (Token Zero), yapay zeka kodlama asistanları (Cursor, Claude Desktop, Antigravity IDE, Windsurf, Cline, VS Code, Zed) için geliştirilmiş, **deterministik AST bağlam sıkıştırıcısı ve Model Context Protocol (MCP) sunucusudur**.
### Neden T-Zero?
Yapay zeka modellerine tüm kaynak kodlar metin olarak verildiğinde, fonksiyon gövdelerindeki döngüler ve ara hesaplamalar yüzünden **bağlam penceresinin %80 ila %95'i israf edilir**. T-Zero, kodu metin olarak değil AST (Soyut Sözdizimi Ağacı) olarak okur; fonksiyon gövdelerini çıkarıp arayüzleri, tipleri ve sınıf yapılarını korur.
### Temel Özellikler:
- **14 Standart MCP Aracı:** `get_project_context_tree`, `prune_code_snippet`, `audit_codebase_quality`, `verify_hallucination_guard` vb.
- **Smart Skeleton (Tier-2):** Üzerinde çalışılan hedef dosya %100 tam kod kalırken, çevresindeki 1. derece bağımlılıklar imza iskeleti haline getirilir.
- **Reality-Lock Halüsinasyon Kontrolü:** Modelin uydurduğu import ve fonksiyon çağrılarını koda yazılmadan önce statik AST üzerinde yakalar.
- **Shannon Entropi Güvenlik Filtresi:** Yüksek entropili ($H \ge 4.75$) gizli anahtarları ve şifreleri yerel olarak tespit eder.
- **%100 Yerel ve Çevrimdışı:** Dış bulut embedding API'si gerektirmez, $0 maliyetle çalışır.
- **Hugging Face Canlı Demo:** [https://huggingface.co/spaces/toprakke4/tzero-token-reducer](https://huggingface.co/spaces/toprakke4/tzero-token-reducer)
### 30 Saniyede Hızlı Kurulum:
```bash
# Kurulum:
pip install tzero-mcp
# 1 saniyede tüm IDE'leri otomatik yapılandır:
tzero init
# (İsteğe bağlı) VS Code & Cursor Eklentisini (.vsix) yükle:
code --install-extension dist/tzero-vscode-10.0.0.vsix
# Kod tabanını sıkıştır ve ağaç çıkar:
tzero --tree . --out context.txt
# Canlı web demosunu yerel başlat:
tzero space
```
---
## ⭐ Star T-Zero on GitHub & Join the Context Revolution!
If T-Zero helped you cut AI prompt token costs, eliminate hallucinations, or speed up your daily coding flow, please consider giving us a star!
<div align="center">
[](https://github.com/toprakahmetaydogmus/TZeroAlgorithm)
[](https://github.com/toprakahmetaydogmus/TZeroAlgorithm)
**T-Zero is 100% Free, Open-Source & Offline Forever.**
*Built with passion by Siber Akademi for developers worldwide.*
</div>
---
## 📜 License & Siberian Academy
- **Author & Architect:** Toprak Ahmet Aydoğmuş (Siber Akademi)
- **LinkedIn:** [Toprak Ahmet Aydoğmuş](https://linkedin.com/in/toprak-ahmet-aydo%C4%9Fmu%C5%9F-60462534b/)
- **Bio & Hub:** [hopp.bio/siberegitim](https://hopp.bio/siberegitim)
- **License:** [MIT Open Source License](LICENSE)
TDQS
A4.2/5.0
Scored across 15 tools
Disambiguation3/5
Most tools pair a distinct resource with a distinct action, and descriptions explicitly cross-reference siblings to draw boundaries (e.g. enforce vs. manage architecture rules). However, 'execute_codebase_workflow' explicitly re-implements every other tool's action (audit, security, blueprint, dependencies, search, prune, heal, memory, swarm), and 'build_project_context' (tree mode) heavily overlaps with 'generate_architecture_blueprint' and 'analyze_code_dependencies'. This creates real misselection risk: an agent can reasonably pick either the master tool or the specialist for the same task.
Naming Consistency5/5
All 15 names are snake_case verb_noun pairs (enforce_, analyze_, search_, estimate_, generate_, audit_, verify_, manage_, build_, prune_, query_, orchestrate_, execute_). No camelCase, casing, or stylistic outliers; the pattern is highly predictable.
Tool Count4/5
15 tools sits at the top of the well-scoped 3-15 band and the broad domain (architecture, quality, security, context, search, memory, orchestration) justifies most of them. The master 'execute_codebase_workflow' tool and the swarm orchestrator are arguably redundant scope creep on top of an already complete surface.
Completeness4/5
Coverage is broad for a local code-intelligence toolkit: search, context building, snippet pruning, dependency/impact analysis, quality audit, secret scanning, architecture rule lifecycle plus enforcement, and blueprint generation. Minor gaps exist around applying fixes or running tests (orchestrate_agent_swarm only patches via 'self_healing'), leaving some workflows as dead ends, but core read-only analysis is fully covered.
Maintenance
ActivityActive
ResponsivenessSyncing