@mailoko/hydra-tools-mcp

Official native Model Context Protocol (MCP) server for HYDRA TOKENS ANTIGRAVITY — cutting AI API costs by up to 90% using local token optimization tools.

⚡ What is @mailoko/hydra-tools-mcp?

@mailoko/hydra-tools-mcp is a zero-dependency, local stdio MCP server for Google Antigravity IDE and any MCP-compatible client. It processes heavy operations — log filtering, snippet extraction, token estimation, context snapshots, and response caching — locally on your machine before sending data to the AI model, saving thousands of input and generation tokens per request.

🛠️ Available Tools (9)

1. hydra_filter_log

Filters large log files locally in milliseconds, returning ONLY matching error/warning lines.

• Inputs: file_path, max_lines (optional, default: 50).
• Impact: Up to 99.8% token reduction on log inspection.

2. hydra_token_estimate

Calculates file size, character count, and estimated tokens before loading a file into context.

• Inputs: file_path.
• Impact: Prevents accidental context bloat from opening massive files.

3. hydra_clean_scratch

Scans and cleans up temporary .tmp, .log, and .bak files from the scratch directory.

• Inputs: dry_run (boolean, optional, default: true).
• Impact: Keeps workspace clean and light.

4. hydra_snippet

Extracts only a specific function, class, or code block from a file by name.

• Inputs: file_path, symbol, context_lines (optional, default: 2).
• Impact: Up to 90% token reduction on file reads.

5. hydra_cache

Saves, retrieves, or lists cached responses to avoid regenerating repeated answers.

• Inputs: action (save/get/list/delete), key, value.
• Impact: 100% reduction on repeated questions (0 generation tokens).

6. hydra_context_snapshot

Scans a directory and reports estimated token costs per file, sorted by heaviest.

• Inputs: directory, max_depth (optional), extensions (optional).
• Impact: Identifies heavy files before loading.

7. hydra_dependency_trace

Traces call references for a function/symbol across project files to prevent breaking changes during edits.

• Inputs: file_path, symbol, search_dir (optional).
• Impact: Prevents broken code & saves multi-file debugging cycles.

8. hydra_edit_verify

Runs post-edit syntax & structure verification on a file to ensure no syntax errors were introduced.

• Inputs: file_path, language (optional).
• Impact: Catch syntax/structural errors before testing.

9. hydra_file_hash

Checks if a file's MD5 hash changed since last read to avoid re-reading identical files.

• Inputs: file_path, action (check/clear).
• Impact: 100% token savings on un-modified file reads.

🤖 Automatic Triggers (HYDRA Integration)

When used alongside HYDRA TOKENS ANTIGRAVITY rules & skills, these tools trigger automatically during chat interactions:

| Trigger Event | Automated Action | Tool Used | |---------------|------------------|-----------| | Every 15 turns | Workspace token scan (top 5 heaviest files) | hydra_context_snapshot | | Every 20 turns | Prompt to clean scratch workspace | hydra_clean_scratch | | Opening a file | Prompts to extract single function instead of full read | hydra_snippet | | Opening a log | Prompts to filter error lines locally | hydra_filter_log | | Opening heavy file | Prompts for token cost estimate before load | hydra_token_estimate | | Repeated query | Checks local cache for instant 0-token answer | hydra_cache |

🚀 Installation & Setup

Add this configuration to your MCP settings file (e.g., Google Antigravity ~/.gemini/config/mcp_config.json or Claude Desktop claude_desktop_config.json):

Option A: NPX (Recommended)

{
  "mcpServers": {
    "hydra-tools-mcp": {
      "command": "npx",
      "args": ["-y", "@mailoko/hydra-tools-mcp@latest"]
    }
  }
}

Option B: Local Python Script

{
  "mcpServers": {
    "hydra-tools-mcp": {
      "command": "python",
      "args": ["C:\\Users\\YourUsername\\.gemini\\config\\hydra_mcp_server.py"]
    }
  }
}

🔗 Project Links

• GitHub Repository: Mailor-Jorge/hydra-tokens-antigravity
• Walkthrough Guide: WALKTHROUGH.md
• NPM Package: @mailoko/hydra-tools-mcp
• License: MIT