Grandpa MCP Server

Why Grandpa?

Your AI coding agent is powerful. But it wastes too much.

Every time you give a prompt to Claude Code, Cursor, Windsurf, Devin, or GitHub Copilot, you are paying in tokens and latency for four invisible forms of waste:

1. Reading too much: Dumps entire repositories into prompt context when a single file mattered.

2. Speaking too much: Spits out 5-paragraph architectural essays for a 2-line CSS fix.

3. Building too much: Pulls in bloated third-party npm packages (axios, lodash, uuid) when modern native runtime primitives exist.

4. Retrying too much: "Lazy" one-line code-golf rules strip timeouts, drop res.ok, and skip null safety—causing runtime 500 crashes and expensive multi-turn debugging cycles.

Grandpa is not code golf. Correctness is a hard requirement.

Grandpa minimizes TCS (Tokens to Correct Solution) across the whole development loop by giving your coding agent four simple instincts:

SPEAK LESS  → Precise, zero-chatter code generation
READ LESS   → Relevance-bounded context retrieval (<3 files)
BUILD LESS  → Native standard library primitives first (Zero npm bloat)
RETRY LESS  → Hardened production safeguards (res.ok, timeouts, null checks)

NORMAL AGENT
  reads 18 files
  loads 21K context tokens
  adds external npm dependency
  writes bloated patch
  runs entire test suite
  fails on stalled network
  feeds huge 4,000-line error log back
  repairs over multiple turns
  TOTAL: 6,840 tokens | 2 attempts | 9.8 sec

GRANDPA (Quick / Standard / Deep)
  identifies relevant target file (<3 files)
  reuses native runtime stdlib
  generates defensive patch (status checks, timeouts preserved)
  runs targeted isolated verification
  PASSES on first turn & STOPS immediately
  TOTAL: 270 tokens | 1 attempt | 74 ms

Key Pillars & What Ponytail Doesn't Have

Live CLI Demonstration

Run Grandpa directly in any project directory:

npx github:bytewhisker/grandpa scan

┌                                                                         ┐
  Welcome to Grandpa
   ▄███▄  ████▄   ▄███▄  ██   ██ ████▄  ████▄   ▄███▄       ▄▄██████▄▄   
  ██   ▀  ██  ██ ██   ██ ███  ██ ██  ██ ██  ██ ██   ██    ▄██▀██████▀██▄ 
  ██ ▄▄▄  ████▀  ███████ ██ █ ██ ██  ██ ████▀  ███████   ██ ██▀█▄▄█▀██ ██
  ██   ██ ██  ██ ██   ██ ██  ███ ██  ██ ██     ██   ██   ██ ██▄█▀▀█▄██ ██
   ▀███▀  ██  ██ ██   ██ ██   ██ ████▀  ██     ██   ██    ▀██▄██████▄██▀ 
                                                               ▀████████▀   
└                                                     CLI Version 1.0.0 ┘
 Version 1.0.0 · Engineered by Mahadi (@bytewhisker)

Target Directory: /workspace/my-app

--- DEPENDENCY AUDIT ---
  Found 3 package(s) that can be replaced with native built-ins:

  • uuid (v9.0.1)
    Grandpa's Native Fix: crypto.randomUUID()
    Native standard library in Node.js and all modern browsers. (Supported in Node 14.17+)

  • lodash.clonedeep (v4.5.0)
    Grandpa's Native Fix: structuredClone(obj)
    Native deep cloning built into modern JavaScript runtimes. (Supported in Node 17.0+)

  • rimraf (v5.0.5)
    Grandpa's Native Fix: fs.rmSync(path, { recursive: true, force: true })
    Native recursive directory deletion in Node.js fs. (Supported in Node 14.14+)

  ┌── AUDIT SUMMARY ──────────────────────────────────────┐
  │  Codebase Score:   55/100
  │  Health Rating:    C (Noticeable dependency bloat)
  │  Dependency Bloat: 3 package(s)
  └───────────────────────────────────────────────────────┘

Head-to-Head Comparison

The 8 Specialized Skills

Grandpa includes 8 specialized skills for every stage of development:

1. grandpa: Core architectural engine and decision ladder.

2. grandpa-audit: Scans whole codebase for bloat, fragile patterns, and framework debt.

3. grandpa-review: Line-by-line PR & diff review for unnecessary complexity.

4. grandpa-debt: Tracks and schedules payoff of architectural exception receipts.

5. grandpa-guard: Real-time safety guard against dangerous AI generation patterns.

6. grandpa-migrate: Step-by-step migration plans from bloated dependencies to native stdlib.

7. grandpa-gain: Quantifies dependencies, bundle size, and maintenance hours saved.

8. grandpa-help: Instant cheat sheet and replacement reference table.

Grandpa Model Context Protocol (MCP) Server

Connect Grandpa directly to Claude Desktop, Cursor, Windsurf, or any MCP client:

{
  "mcpServers": {
    "grandpa": {
      "command": "npx",
      "args": ["-y", "@bytewhisker/grandpa", "mcp"]
    }
  }
}

Exposes tools:

• grandpa_scan: Scans repo for bloat & fragile patterns.

• grandpa_audit: Returns scored codebase report (A+ to F).

• grandpa_guard: Pre-execution validation of code and bash commands.

• grandpa_migrate: Provides stdlib drop-in code for bloated packages.

• grandpa_rules: Injects intensity-specific system instructions.

16 Battle-Tested Examples

Browse our collection of 16 real-world before/after demonstrations in examples/:

• Axios to Native Fetch with Timeouts & Retries

• Moment.js to Native Intl & Date

• Lodash to Native ES6+ & structuredClone

• Classnames to Template Literals

• UUID to Web Crypto

• Chalk to Native ANSI

• Dotenv to Node 20 Flags

• Rimraf & Mkdirp to node:fs

• Zero-Dependency Debounce & Throttle

• Deep Clone via structuredClone

• Zero-Dependency CSV Parser

• In-Memory Token Bucket Rate Limiter

• Query-String to URLSearchParams

• Minimal FastAPI Pattern

• React Countdown Timer

• Glob to Node 20 fs.readdir Recursive

Empirical Benchmark Results

We benchmarked Grandpa against Ponytail, Caveman, and Bare AI across two rigorous environments: Live Real-LLM inference with exact provider token accounting and a 500-run multi-turn repair suite across 25 production tasks.

1. Live Real-LLM Benchmark (Google Gemini Live API)

Evaluated live with real provider token accounting (prompt_tokens, completion_tokens), real model network latency, isolated subprocess execution, and automated multi-turn repair loops.

$$\text{Failure-Aware Efficiency} = \frac{\text{Total Tokens Consumed Across Entire Workflow}}{\text{Tasks Successfully Solved}}$$

Why Grandpa Wins the Workflow:
Minimalist "code-golf" approaches look cheap on turn 1, but frequently strip status checks, timeouts, or clean exports—causing 37% first-pass failure rates on real LLMs. Multi-turn repair loops rapidly burn tokens.
Grandpa achieves 100% first-pass pass rate with standard defensive guards, saving ~32% total workflow tokens over Ponytail/Caveman and 73% over unsteered Bare AI.

2. Comprehensive 500-Run Suite (25 Tasks × 5 Repetitions)

Data source: 500 isolated runs across 8 software engineering domains recorded in benchmarks/results/latest-summary.json.

"Output tokens are cheap. Debugging turns aren't. Grandpa optimizes the whole coding loop."

See complete methodology, per-task breakdowns, and failure analysis in benchmarks/REPORT.md.

Run the benchmarks:

# Run 500-run comprehensive suite
npm run benchmark

# Run live real-LLM benchmark (requires API key in .env)
node --env-file=.env benchmarks/live-harness.js

Quick Start

1. Install Globally (Run grandpa anywhere in any terminal)

# Install globally from GitHub (always latest)
npm install -g github:bytewhisker/grandpa

# Or run instantly without installing
npx github:bytewhisker/grandpa scan

Once installed globally, you can type grandpa in any terminal:

grandpa --help     # Display full interactive help guide and options
grandpa scan       # Audit project for dependency bloat & fragile code
grandpa init       # Install zero-bloat rules for Cursor, Windsurf, Claude Code
grandpa hook       # Install git pre-commit guard against AI dependency bloat
grandpa mcp        # Launch Model Context Protocol server for AI assistants
grandpa gain       # View cumulative token & architecture savings

2. Install Rules Into Your Workspace (25+ Agents)

Installs configurations for Cursor (.cursor/rules), Windsurf (.windsurfrules), Claude Code, Antigravity (AGENTS.md), and 20+ other agents in one command:

grandpa init
# Or targeted: grandpa init cursor | grandpa init windsurf | grandpa init agents

3. Enable Git Pre-Commit Guard

Blocks AI coding assistants from silently adding unvetted dependencies to package.json:

grandpa hook

Continuous Integration (CI/CD)

Enforce zero-bloat architecture automatically in your GitHub Actions pipeline:

name: Grandpa Architecture Audit

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx github:bytewhisker/grandpa scan --strict

License

Distributed under the MIT License. See LICENSE for details.

Author & Credits

╭──────────────────────────╮
│  GRANDPA 🧓              │
│  AI Coding Optimizer     │
│                          │
│  Engineered by Mahadi    │
│  @bytewhisker            │
╰──────────────────────────╯

Designed & engineered by Mahadi (@bytewhisker)
© 2026 Grandpa / ByteWhisker. All rights reserved.