# Token Saver MCP — AI as a Full-Stack Developer
[](https://opensource.org/licenses/MIT)
[](https://github.com/jerry426/token-saver-mcp)
> **Transform AI from a code suggester into a true full-stack developer — with instant access to code intelligence and real browser control.**
📚 [**Full Usage Guide & Examples →**](README_USAGE_GUIDE.md) |
📖 [Detailed Technical README →](README_FULL.md) |
🔄 [Releases](https://github.com/jerry426/token-saver-mcp/releases)
---
## 🚀 What is Token Saver MCP?
Modern AI coding assistants waste enormous context (and your money) by stuffing full grep/search results into the model window. That leads to:
- ❌ Slow lookups (seconds instead of milliseconds)
- ❌ Thousands of wasted tokens per query
- ❌ AI “losing its train of thought” in cluttered context
**Token Saver MCP fixes this.**
It gives AI assistants **direct access to VSCode’s Language Server Protocol (LSP)** and the **Chrome DevTools Protocol (CDP)**, so they can work like *real developers*:
- Instantly navigate & refactor code
- Run code in a real browser (Edge/Chrome)
- Test, debug, and verify changes themselves
**Result:** 90–99% fewer tokens, 100–1000× faster responses, and $200+ in monthly savings — while enabling AI to truly act as a full-stack engineer.
---
## ✨ Why Token Saver?
Think of your AI’s context window like a **workbench**. If it’s cluttered with logs, search dumps, and irrelevant snippets, the AI can’t focus.
**Token Saver MCP keeps the workbench clean.**
### 🔍 Without Token Saver
```text
grep -r "renderProfileImage" .
# 5000+ tokens, 10–30 seconds, bloated context
```
### ⚡ With Token Saver
```text
get_definition('src/components/UserCard.js', 25)
# 50 tokens, <100ms, exact location + type info
```
**Cleaner context = a sharper, more persistent AI assistant.**
---
## 🏗️ Revolutionary Dual Architecture
Token Saver MCP uses a **split architecture** designed for speed and stability:
```
AI Assistant ←→ MCP Server ←→ VSCode Gateway ←→ VSCode Internals
(hot reload) (stable interface)
```
- 🏗️ **VSCode Gateway Extension**
- Installed once, rarely updated
- Exposes VSCode’s LSP via HTTP (port 9600)
- 🚀 **Standalone MCP Server**
- Hot reloadable — no VSCode restarts
- Language-agnostic (JS/TS, Python, Go, Rust…)
- Bridges MCP protocol ↔ VSCode Gateway + CDP (port 9700 by default)
**Why it matters:** You can iterate on MCP tools instantly without rebuilding/restarting VSCode. Development is 60× faster and much more reliable.
---
## 🧰 What You Get
Token Saver MCP currently provides **40 production-ready tools** across five categories:
- **LSP Tools (14)** → `get_definition`, `get_references`, `rename_symbol`, `get_hover`, `find_implementations`, …
- **Memory Tools (9)** → `smart_resume` (86-99% token savings vs /resume), `write_memory`, `read_memory`, `search_memories` (full-text search), `export_memories`, `import_memories`, …
- **Browser Tools (8)** → `navigate_browser`, `execute_in_browser`, `take_screenshot`, `get_browser_console`, …
- **Testing Helpers (5)** → `test_react_component`, `test_api_endpoint`, `check_page_performance`, …
- **System Tools (4)** → `get_instructions`, `retrieve_buffer`, `get_supported_languages`, …
📚 See the full [Usage Guide with JSON examples →](README_USAGE_GUIDE.md)
---
## 📊 Proven Results
| Operation | Traditional Method | With Token Saver MCP | Improvement |
|-----------|-------------------|----------------------|-------------|
| Find function definition | 5–10s, 5k tokens | **10ms, 50 tokens** | 100× faster |
| Find all usages | 10–30s | **50ms** | 200× faster |
| Rename symbol project-wide | Minutes | **100ms** | 1000× faster |
| Resume context (/resume) | 5000+ tokens | **200-500 tokens** | 86-99% savings |
**Token & Cost Savings (GPT-4 pricing):**
- Tokens per search: 5,000 → **50**
- Cost per search: $0.15 → **$0.0015**
- Typical dev workflow: **$200+ saved per month**
---
## 🌐 Browser Control (Edge-Optimized)
Beyond backend code, Token Saver MCP empowers AI to **control a real browser** through CDP:
- Launch Edge/Chrome automatically
- Click, type, navigate, capture screenshots
- Run frontend tests & debug JS errors in real-time
- Analyze performance metrics
Example workflow:
1. AI writes backend API (LSP tools)
2. AI launches browser & tests API (CDP tools)
3. AI sees error logs instantly
4. AI fixes backend code (LSP tools)
5. AI verifies fix in browser
➡️ No more “please test this manually” — AI tests itself.
---
## 🧠 Smart Memory System (NEW!)
Replace wasteful `/resume` commands with intelligent context restoration:
### The Problem with /resume
- Dumps entire conversation history (5000+ tokens)
- Includes irrelevant tangents and discussions
- Costs $0.15+ per resume
- AI gets lost in the noise
### The Solution: Smart Resume
```javascript
smart_resume() // 200-500 tokens, focused context only
```
**Features:**
- **86-99% token savings** compared to /resume
- **Progressive disclosure**: Start minimal, expand as needed
- **Full-text search**: Find memories by content, not just keys
- **Importance levels** (1-5): Critical info persists, trivia can be dropped
- **Verbosity levels** (1-4): Control detail granularity
- **Time-based filtering**: Resume work from specific periods
- **Export/Import**: Backup and share memory contexts between sessions
**Example:**
```javascript
// Standard resume - just the essentials
smart_resume()
// Include everything from last 3 days
smart_resume({ daysAgo: 3, verbosity: 3 })
// Critical items only for quick check-in
smart_resume({ minImportance: 4, verbosity: 1 })
```
Memory is stored locally in SQLite (`~/.token-saver-mcp/memory.db`) with automatic initialization.
---
## 🖥️ Real-Time Dashboard
Visit `http://127.0.0.1:9700/dashboard` to monitor:
- Server status & connection health
- Request metrics & response times
- Token & cost savings accumulating live
- Tool usage statistics
Perfect for seeing your AI’s efficiency gains in action.
---
## ⚡ Quickstart (30 Seconds)
```bash
# Clone repo
git clone https://github.com/jerry426/token-saver-mcp
cd token-saver-mcp
# One-step setup
./mcp setup /path/to/your/project
```
That’s it! The installer:
- Finds open ports
- Creates config files
- Tests connection
- Provides the Claude/Gemini command
➡️ Full installation & build steps: [Detailed README →](README_FULL.md)
---
## 🔌 Supported AI Assistants
- **Claude Code** → works out of the box with MCP endpoint
- **Gemini CLI** → use `/mcp-gemini` endpoint
- **Other AI tools** → MCP JSON-RPC, streaming, or simple REST endpoints available
Endpoints include:
- `http://127.0.0.1:9700/mcp` (standard MCP)
- `http://127.0.0.1:9700/mcp-gemini` (Gemini)
- `http://127.0.0.1:9700/mcp/simple` (REST testing)
- `http://127.0.0.1:9700/dashboard` (metrics UI)
---
## 🔬 Verify It Yourself
Think the claims are too good to be true? Run the built-in test suite:
```bash
python3 test/test_mcp_tools.py
```
Expected output shows: hover, completions, definitions, references, diagnostics, semantic tokens, buffer management, etc. — all passing ✅
---
## 🛠️ Development
```bash
pnpm install
pnpm run dev # hot reload
pnpm run build
pnpm run test
```
MCP server lives in `/mcp-server/`, with modular tools organized by category (`lsp/`, `cdp/`, `helper/`, `system/`).
See [Full Technical README →](README_FULL.md) for architecture diagrams, tool JSON schemas, buffer system details, and contributing guide.
---
## 📍 Roadmap / Vision
Token Saver MCP already unlocks **full-stack AI workflows**. Next up:
- 🔧 More browser automation tools (multi-tab, network control)
- 📦 Plugin ecosystem for custom toolpacks
- 🌐 Multi-assistant coordination (Claude + Gemini + others)
- 🧠 Expanded context management strategies
---
## 📄 License
MIT — free for personal and commercial use.
---
👉 **Start today**:
- Run `./mcp setup`
- Tell your AI: *“Use the get_instructions tool to understand Token Saver MCP.”*
- Watch your AI become a focused, cost-efficient, full-stack developer.
📚 For in-depth details:
- [Usage Guide & Examples](README_USAGE_GUIDE.md)
- [Full Technical README](README_FULL.md)
