README_OLD.md•35.2 kB
# 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 complete control over both backend code and frontend browsers.**
📚 **[📖 Complete Usage Guide & Examples →](README_USAGE_GUIDE.md)** | 🔄 [View Releases](https://github.com/jerry426/token-saver-mcp/releases)
## The Core Message: Context Conservation
Think of your AI's context window like a workbench. If it's cluttered with old notes, unused tools, and conversational fluff, the AI can't work effectively on the current task. **Token Saver MCP keeps the workbench clean**, ensuring only the most relevant information is present.
This leads to a more focused, capable, and persistent AI assistant that can tackle complex, multi-step projects without losing its train of thought.
**VSCode's Language Server already knows everything about your code.** Token Saver MCP gives AI instant access to that knowledge—no searching, no waiting, no context waste.
## Why "Token Saver"? It's About Focus, Not Just Cost
AI models have a finite context window—their short-term memory. Every time you ask a question or provide information, you fill that window.
Perhaps the fastest way to fill that window is by allowing the AI model to use grep and other text searching tools to find the needle in the haystack. HUGE problem with this is now the needle AND the entire haystack is needlessly stuffed into the context window. Once it's full of irrelevant information, the AI loses focus and its performance degrades, forcing you to start over.
Token Saver solves this by replacing verbose natural language and bloated text search results with exactly what the AI needs: easy access to focused search results along with the other powerful tools provided by Token Saver.
### Without Token Saver (Cluttered Context):
```
"Hey, could you please look at the file named 'src/components/UserCard.js'
and find the definition for the 'renderProfileImage' function for me?
I need to see what arguments it takes."
```
**What happens:**
1. AI runs grep/find commands
2. Waits 10-30 seconds
3. Gets hundreds of lines of context
4. Burns 5,000+ tokens
5. Context window fills with irrelevant code
### With Token Saver (Focused Context):
```
get_definition('src/components/UserCard.js', 25)
```
**What happens:**
1. Direct LSP call to VSCode
2. Instant response (<100ms)
3. Gets exact location and type info
4. Uses ~50 tokens
5. Context stays clean and focused
This approach keeps the context window **95% cleaner**, allowing the AI to maintain its focus and perform many more steps before running out of memory. The result? An AI that can work alongside you on complex tasks from start to finish.
## Revolutionary Dual Architecture
Token Saver MCP uses a **groundbreaking split architecture** that separates concerns for maximum developer productivity:
### 🏗️ **Component 1: VSCode Extension (Gateway)**
- **Purpose**: Simple, stable interface to VSCode's internal APIs
- **Installs once**: Rarely needs updates or reinstallation
- **Exposes**: Language Server Protocol (LSP) features via HTTP
- **Port**: Runs on 9600 (auto-discovered)
- **Maintenance**: Set-it-and-forget-it - stays out of your way
### 🚀 **Component 2: Standalone MCP Server**
- **Purpose**: Translates between MCP protocol and VSCode Gateway, plus Chrome DevTools Protocol (CDP)
- **Hot reloadable**: Instant development without VSCode restarts
- **Language agnostic**: Could be rewritten in Python, Go, Rust, etc.
- **Port**: Runs on 9700 (configurable)
- **Development**: Rapid iteration with `npm run dev`
### 🎯 **Why This Architecture is Revolutionary**
**Traditional Approach (Bad):**
```
AI ←→ VSCode Extension (must restart VSCode for every change)
```
**Token Saver Approach (Good):**
```
AI ←→ MCP Server ←→ VSCode Gateway ←→ VSCode Internals
(hot reload) (stable interface) (never restart)
```
**Benefits:**
- ⚡ **60x faster development** - No VSCode extension rebuilds
- 🔄 **Hot reload support** - Changes reflect instantly
- 🛡️ **Stable VSCode integration** - Gateway rarely needs updates
- 🌍 **Language flexibility** - MCP server can be any language
- 🧪 **Easy testing** - Debug MCP server independently
## What Token Saver MCP Provides
This dual architecture delivers **TWO revolutionary toolsets** that transform AI into a true full-stack developer:
### 🔍 Language Server Protocol (LSP) Tools
Gives AI direct access to VSCode's already-indexed code intelligence - delivering answers in **milliseconds instead of seconds** with **90% fewer tokens**.
### 🌐 Chrome DevTools Protocol (CDP) Tools
Gives AI complete control over Edge/Chrome browsers for testing, debugging, and automation - enabling **instant verification** of code changes in real browsers.
### 🛠️ Complete Tool Arsenal (31 Tools)
**Language Server Protocol (14 tools):**
`get_hover`, `get_completions`, `get_definition`, `get_type_definition`, `get_references`, `find_implementations`, `get_document_symbols`, `get_call_hierarchy`, `rename_symbol`, `get_code_actions`, `get_diagnostics`, `get_semantic_tokens`, `find_text`, `find_symbols`
**Chrome DevTools Protocol (8 tools):**
`execute_in_browser`, `navigate_browser`, `click_element`, `type_in_browser`, `get_browser_console`, `get_dom_snapshot`, `take_screenshot`, `wait_for_element`
**Browser Testing Helpers (5 tools):**
`test_react_component`, `test_api_endpoint`, `test_form_validation`, `check_page_performance`, `debug_javascript_error`
**System Tools (4 tools):**
`retrieve_buffer`, `get_buffer_stats`, `get_instructions`, `get_supported_languages`
## Proven Results (Measured, Not Marketing)
- ⚡ **0.5ms average response time** - Verified with Edge browser
- 🎯 **31 production-ready tools** (14 LSP + 8 CDP + 5 Helper + 4 System)
- 📊 **Real-time dashboard** - Watch your savings accumulate
- 🛡️ **Intelligent buffer protection** - Prevents token overflow
- 🔄 **Auto-recovery** - WebSocket reconnection, no restarts needed
- 🚀 **Full-stack capabilities** - Backend code + frontend browser
- 💰 **$200+ monthly savings** - Based on actual usage metrics
## Real-World Performance
| Operation | Traditional Approach | With Token Saver MCP | Your Time Saved |
|-----------|---------------------|---------------------|-----------------|
| Find where a function is defined | 5-10 seconds | **10ms** | ☕ Make coffee |
| Find all usages of a variable | 10-30 seconds | **50ms** | 💭 Keep your flow |
| Get type information | Manual lookup | **5ms** | ⚡ Instant |
| Rename across entire project | Several minutes | **100ms** | 🚀 Already done |
| Search for text patterns | 2-15 seconds | **30ms** | 📈 100x faster |
## Token & Cost Savings Calculator
| Metric | Without Token Saver | With Token Saver | Your Savings |
|--------|-------------------|------------------|--------------|
| Tokens per search | ~5,000 tokens | ~50 tokens | **99% fewer** |
| Cost per search (GPT-4) | $0.15 | $0.0015 | **$0.1485** |
| Daily searches (avg) | 50 | 50 | - |
| **Daily cost** | **$7.50** | **$0.075** | **$7.43 saved** |
| **Monthly cost** | **$225** | **$2.25** | **$222.75 saved** |
| **Yearly cost** | **$2,700** | **$27** | **$2,673 saved** |
*Based on typical development patterns and AI code assistant pricing. Your savings may vary.
## 🌐 Revolutionary Browser Control (Edge Optimized!)
Token Saver MCP includes **Chrome DevTools Protocol integration** with **Microsoft Edge prioritized** for superior performance (0.5ms response times vs Chrome's sluggish performance).
**Key Features:**
- 🚀 **Automatic browser launch** - No manual setup required
- ⚡ **Edge preferred** - 10x better performance than Chrome
- 🔄 **WebSocket auto-recovery** - No VSCode restarts when connections drop
- 🎯 **Sub-millisecond responses** - Real-time browser control
### Browser Testing & Automation Tools
| Tool | What It Does | Example Use |
|------|--------------|-------------|
| `test_react_component` | Test React components instantly | Verify component renders with correct props |
| `test_api_endpoint` | Test APIs from browser context | Check CORS, auth, response times |
| `test_form_validation` | Test forms completely | Submit, validate, check errors |
| `check_page_performance` | Analyze performance metrics | Get load times, memory usage, recommendations |
| `debug_javascript_error` | Debug JS errors in real-time | Capture stack traces, identify issues |
### Full-Stack Development Workflow
```
1. AI writes backend API endpoint (LSP tools)
2. AI launches browser automatically (CDP tools)
3. AI tests the API from frontend (CDP tools)
4. AI sees any errors immediately (CDP tools)
5. AI fixes the code (LSP tools)
6. AI verifies the fix works (CDP tools)
```
**No more**: "Please test this manually and tell me if it works"
**Now**: AI tests everything itself, instantly!
## Before & After Comparison
### ❌ **Before Token Saver MCP** - What You're Doing Now
```
AI: "Let me search for that function definition..."
> Running: grep -r "functionName" . --include="*.ts"
> [10 seconds pass...]
> Found 47 matches, let me search more specifically...
> Running: find . -name "*.ts" -exec grep -l "function functionName" {} \;
> [15 more seconds...]
> Tokens used: 5,000+
> Time wasted: 25 seconds
> Result: Maybe found it, maybe not
```
### ✅ **After Token Saver MCP** - Instant Intelligence
```
AI: "Getting definition..."
> Using: get_definition at file.ts:42:15
> [10ms]
> Tokens used: 50
> Time: Instant
> Result: Exact location with type info
```
## 🔬 Don't Take Our Word For It - Verify It Yourself!
**Think these performance claims are too good to be true?**
Don't trust us - let your own AI prove it! Install Token Saver MCP in your VSCode, then challenge your AI assistant to compare approaches:
**Ask your AI to:**
1. **Find a function definition** - First with grep, then with `get_definition`
2. **Find all usages of a variable** - First with text search, then with `get_references`
3. **Get type information** - First by reading files, then with `get_hover`
4. **Understand code structure** - First by parsing manually, then with `get_document_symbols`
5. **Trace function calls** - First with grep patterns, then with `get_call_hierarchy`
**Your AI will report:**
- 🎯 Exact token counts for each approach
- ⏱️ Response time differences
- 📊 Accuracy improvements
- 💰 Cost savings per operation
The results speak for themselves - typically **100-1000x faster** with **90-99% fewer tokens**. Your AI assistant will confirm these aren't marketing claims - they're measurable facts.
## Features
This extension exposes VSCode's Language Server Protocol and Chrome DevTools Protocol features through MCP, providing AI assistants with **30 powerful tools**:
### Core Navigation & Intelligence
- **Go to Definition** (`get_definition`) - Navigate to symbol definitions
- **Go to Type Definition** (`get_type_definition`) - Navigate to type definitions
- **Find References** (`get_references`) - Locate all usages of a symbol
- **Find Implementations** (`find_implementations`) - Find all implementations of an interface/class
- **Hover Information** (`get_hover`) - Access documentation and type information
### Code Analysis & Refactoring
- **Code Completions** (`get_completions`) - Get intelligent code suggestions at any position
- **Code Actions** (`get_code_actions`) - Get available quick fixes and refactorings
- **Symbol Rename** (`rename_symbol`) - Refactor symbols across the workspace
- **Document Symbols** (`get_document_symbols`) - Get file structure with all symbols hierarchically
- **Call Hierarchy** (`get_call_hierarchy`) - Trace incoming/outgoing function calls
### Diagnostics & Search
- **Diagnostics** (`get_diagnostics`) - Get errors, warnings, and hints for files
- **Find Text** (`find_text`) - Search for text patterns across all files with intelligent buffering
- **Find Symbols** (`find_symbols`) - Search for symbols across workspace using semantic search
- **Semantic Tokens** (`get_semantic_tokens`) - Get detailed syntax highlighting information
### Browser Control & Testing (CDP Tools)
- **Test React Component** (`test_react_component`) - Complete React component testing
- **Test API Endpoint** (`test_api_endpoint`) - Test APIs with CORS checks from browser
- **Test Form Validation** (`test_form_validation`) - Automated form testing
- **Check Page Performance** (`check_page_performance`) - Performance metrics & analysis
- **Debug JavaScript Error** (`debug_javascript_error`) - Capture and analyze JS errors
- **Execute in Browser** (`execute_in_browser`) - Run any JavaScript in browser context
- **Navigate Browser** (`navigate_browser`) - Control browser navigation
- **Click/Type/Screenshot** - Full browser automation capabilities
### System & Utilities
- **Buffer Retrieval** (`retrieve_buffer`) - Retrieve full data from buffered responses
- **Buffer Statistics** (`get_buffer_stats`) - Monitor buffer system usage
- **Get Instructions** (`get_instructions`) - Self-documenting API returns complete usage guide
- **Supported Languages** (`get_supported_languages`) - Get all registered languages and their status
### Intelligent Buffer System
The extension includes a sophisticated buffer system to prevent token overflow:
- **Automatic buffering** for responses over 2,500 tokens (~10KB)
- **Smart previews** with tool-specific intelligent summaries
- **Depth truncation** to limit deeply nested data structures
- **Session-based isolation** for multiple concurrent users
- **60-second TTL** with automatic cleanup
### Performance Benefits
- **Instant results**: <100ms response time vs 10-30 seconds with grep
- **Semantic accuracy**: Real code intelligence, not text pattern matching
- **Zero additional cost**: Leverages existing VSCode computation
- **Works across your workspace**: Automatic Language Server activation for any file type - no manual setup needed
## 🚀 Get Started in 30 Seconds
```bash
# One command does everything:
./mcp setup /path/to/your/project
```
That's it! The extension automatically:
- ✅ Finds an available port
- ✅ Creates configuration files
- ✅ Tests the connection
- ✅ Provides the Claude command
## Installation: Two Components, One Simple Process
Token Saver MCP requires installing **two components** that work together:
### 🏗️ **Step 1: Install VSCode Extension (Gateway) - Install Once, Forget Forever**
The VSCode extension is a **stable gateway** that rarely needs updates:
**Option A: From Pre-built Release (Recommended)**
1. **Download the latest .vsix file** from the [Releases](https://github.com/jerry426/token-saver-mcp/releases) page
2. **Install in VSCode** using one of these methods:
- Command Palette: `Extensions: Install from VSIX...` then select the file
- Terminal: `code --install-extension token-saver-mcp-*.vsix`
- Or drag and drop the .vsix file onto the VSCode Extensions view
3. **Reload VSCode** to activate the extension
**✅ That's it for the VSCode component!** The gateway will auto-start and rarely needs attention.
**Option B: Build VSCode Extension from Source**
1. **Clone and build the extension:**
```bash
git clone https://github.com/jerry426/token-saver-mcp.git
cd token-saver-mcp
pnpm install
pnpm run build
```
2. **Create the extension package:**
```bash
pnpm exec vsce package --no-dependencies
# This creates token-saver-mcp-*.vsix in the current directory
```
3. **Install the .vsix file in VSCode:**
```bash
code --install-extension token-saver-mcp-*.vsix
```
4. **Reload VSCode** to activate the extension:
- Command Palette: `Developer: Reload Window`
- Or restart VSCode
### 🚀 **Step 2: Run Standalone MCP Server - Hot Reloadable Development**
The MCP server is where all the development happens and supports hot reloading:
**For Development (Recommended):**
```bash
cd token-saver-mcp/mcp-server
npm install
npm run dev # Hot reload - changes reflect instantly!
```
**For Production:**
```bash
cd token-saver-mcp/mcp-server
npm install
npm run build
npm start
```
**✅ MCP Server Benefits:**
- 🔥 **Hot reload support** - Edit code, see changes instantly
- 🚫 **No VSCode restarts** - MCP server runs independently
- 🧪 **Easy testing** - Debug and test tools separately
- 🌍 **Language agnostic** - Could rewrite in Python, Go, etc.
### 🔗 **Step 3: Verify Connection Between Components**
Once both components are running, verify they're communicating:
```bash
# Check if VSCode Gateway is running
curl http://127.0.0.1:9600/health
# Should return: {"status": "ok", "message": "VSCode Gateway is running"}
# Check if MCP Server is running
curl http://127.0.0.1:9700/health
# Should return: {"status": "ok", "message": "MCP Server is running"}
# Test MCP tool communication
curl -X POST http://127.0.0.1:9700/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# Should return: List of all 31 available tools
```
**✅ Success Indicators:**
- VSCode extension shows "Token Saver MCP: Connected" in status bar
- MCP server console shows "VSCode Gateway connected on port 9600"
- Dashboard available at `http://127.0.0.1:9700/dashboard`
- All 31 tools listed in MCP tools/list response
## Usage
### 🎯 IMPORTANT: For Best Results with AI Assistants
**Tell your AI assistant to use the get_instructions tool!**
```
"Please use the get_instructions MCP tool to understand how to use Token Saver MCP tools effectively"
```
The `get_instructions` tool returns the README_USAGE_GUIDE.md documentation instantly through the MCP protocol - much more efficient than having the AI read the file directly.
This ensures your AI assistant:
- Uses Token Saver MCP tools instead of slow text searches
- Understands all 31 available tools and their parameters (14 LSP + 8 CDP + 5 Helper + 4 System)
- Follows best practices for maximum performance
- Saves 90-99% of tokens on code navigation tasks
- Has direct control over Edge/Chrome browsers for frontend testing and verification
Token Saver MCP provides both backend code intelligence (LSP) and frontend browser control (CDP), making your AI a true full-stack developer capable of writing, testing, and verifying code changes in real browsers.
### 📊 Real-Time Developer Dashboard
**Monitor your AI's performance live in your browser:**
Navigate to: `http://127.0.0.1:9700/dashboard`
The dashboard features a **3x3 grid layout** showing:
- **Top Row:** Server Status | Request Metrics | Token Savings
- **Middle Row:** Available Tools (full-width display of all 31 tools)
- **Bottom Row:** Recent Activity | Response Time Graph | Most Used Tools
Watch in real-time as:
- Token savings accumulate with each operation
- Response times stay under 1ms with Edge
- Tool usage patterns emerge
- Cost savings calculate automatically
### Status Dashboard
**See all your MCP-enabled projects:**
```bash
./mcp status
```
Shows which projects are configured, running, and connected to Claude.
### Multiple Projects Setup
Each project needs its own unique port number:
1. **Assign unique ports to each project:**
```bash
# Project A
echo "9700" > /path/to/project-a/.mcp_server_port
# Project B
echo "9701" > /path/to/project-b/.mcp_server_port
# Project C
echo "9702" > /path/to/project-c/.mcp_server_port
```
2. **Set up Claude for each project:**
```bash
# Get the Claude command for each project
./mcp claude /path/to/project-a
./mcp claude /path/to/project-b
```
3. **The extension will automatically use the port from `.mcp_server_port`** when you open each project
### Port Discovery
To see all running MCP servers:
```bash
python3 test/find_mcp_servers.py
```
This shows which ports are actually in use and their workspace paths.
## Available MCP Tools
> **Automatic Language Server Activation:** The extension automatically activates the appropriate Language Server when you use any MCP tool. No manual file opening required - just call the tool and it works instantly! If a Language Server isn't already active, the extension will very briefly open and close a file of that type in the background to trigger activation. This happens automatically and takes just milliseconds.
### Position-Based Tools
These tools require a file URI and position (line/character):
#### `get_hover`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15
}
```
Returns: Type information, documentation, and signatures
#### `get_completions`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15
}
```
Returns: Context-aware code completion suggestions
#### `get_definition`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15
}
```
Returns: Location(s) where the symbol is defined
#### `get_type_definition`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15
}
```
Returns: Location(s) where the type is defined
#### `get_code_actions`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15
}
```
Returns: Available quick fixes and refactorings at the position
#### `get_references`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15
}
```
Returns: All locations where the symbol is used
#### `find_implementations`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15
}
```
Returns: All locations where the interface/class is implemented
#### `get_call_hierarchy`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15,
"direction": "incoming" // or "outgoing"
}
```
Returns: Function call relationships - incoming shows callers, outgoing shows callees
#### `rename_symbol`
```json
{
"uri": "file:///path/to/file.ts",
"line": 10,
"character": 15,
"newName": "newSymbolName"
}
```
Returns: Edit operations to rename across all files
### Document-Level Tools
#### `get_document_symbols`
```json
{
"uri": "file:///path/to/file.ts"
}
```
Returns: Hierarchical structure of all symbols in the file (classes, methods, properties, etc.)
### Search Tools
#### `search_text`
```json
{
"query": "searchTerm",
"useRegExp": false,
"isCaseSensitive": false,
"matchWholeWord": false,
"maxResults": 100,
"includes": ["**/*.ts"],
"excludes": ["node_modules/**"]
}
```
Returns: File locations and positions matching the search
### Diagnostics Tools
#### `get_diagnostics`
```json
{
"uri": "file:///path/to/file.ts" // Optional - if not provided, gets all diagnostics
}
```
Returns: Errors, warnings, and hints for the file(s)
#### `get_semantic_tokens`
```json
{
"uri": "file:///path/to/file.ts"
}
```
Returns: Detailed syntax highlighting information with token types and modifiers
### Buffer Management Tools
#### `retrieve_buffer`
```json
{
"bufferId": "get_document_symbols_1754955026362_z2ksv6t8z"
}
```
Returns: Complete original data from a buffered response
#### `get_buffer_stats`
```json
{} // No parameters required
```
Returns: Active buffer count, total size, oldest buffer age
### Self-Documentation Tool
#### `get_instructions`
```json
{} // No parameters required
```
Returns: Complete AI-MCP-USER.md guide with all usage instructions
#### `get_supported_languages`
```json
{} // No parameters required
```
Returns: All languages registered in VSCode organized by category, active languages in workspace, and total count
## Configuration
**No VSCode settings required!** The dual architecture is designed to be zero-configuration:
- **VSCode Extension (Gateway)**: Uses hardcoded port 9600 - no configuration needed
- **MCP Server**: Auto-discovers port from `.mcp_server_port` file for external connections
- **Communication**: MCP Server connects to VSCode Gateway on port 9600 automatically
The days of complex VSCode settings are over - everything works automatically!
### 🔌 Available Endpoints
The MCP Server provides multiple endpoints for different AI assistants and use cases:
| Endpoint | Purpose | Protocol | Used By |
|----------|---------|----------|---------|
| `http://127.0.0.1:9700/mcp` | Standard MCP protocol | JSON-RPC | Claude Code, most MCP clients |
| `http://127.0.0.1:9700/mcp-gemini` | Gemini-specific endpoint | Streaming JSON-RPC | Gemini CLI |
| `http://127.0.0.1:9700/mcp-streaming` | Alternative streaming endpoint | Streaming JSON-RPC | Future clients |
| `http://127.0.0.1:9700/mcp/simple` | REST API for testing | Simple JSON | Testing, debugging |
| `http://127.0.0.1:9700/dashboard` | Real-time metrics dashboard | Web UI | Browser monitoring |
| `http://127.0.0.1:9700/health` | Health check endpoint | JSON | Monitoring tools |
### 📐 API Conventions
**Line Numbers**: All tools use **1-indexed line numbers** (line 1 is the first line) for consistency with how developers think about code.
**Character Positions**: Character positions are **0-indexed** (character 0 is the first character in a line).
**Symbol Positions**: The `find_symbols` tool returns the exact character position where the symbol name begins, not the start of the declaration.
## Testing
Test all MCP tools:
```bash
python3 test/test_mcp_tools.py
```
Expected output:
```
✓ Hover works - returned documentation
✓ Completions works - returned 193 items
✓ Definition works - found 1 location(s)
✓ References works - found 5 reference(s)
✓ Implementations works - interface/class implementations
✓ Document symbols works - found 10 top-level symbol(s)
✓ Text search works - found 6 match(es)
✓ Call hierarchy works - target: startMcp, 2 call(s)
✓ Rename works - would affect 2 file(s)
✓ Type definition works - found 1 location(s)
✓ Code actions works - found 3 quick fix(es)
✓ Diagnostics works - found issues in 2 file(s)
✓ Semantic tokens works - 500+ tokens decoded
✓ Buffer system works - response buffered (8744 tokens)
✓ retrieve_buffer works - retrieved 21 items
✓ Buffer stats works - 3 active buffer(s)
🎉 SUCCESS! All 17 tools are working!
```
## Architecture: The Split That Changes Everything
```
┌─────────────┐ MCP/HTTP ┌──────────────┐ HTTP/API ┌─────────────────┐
│ AI Assistant│ ◄─────────────► │ MCP Server │ ◄────────────► │ VSCode Extension│
│ (Claude) │ │ (Port 9700) │ │ (Gateway) │
│ │ │ │ │ (Port 9600) │
│ Hot Reload │ │ Hot Reload │ │ Install Once │
│ Compatible │ │ Development │ │ Stable Forever │
└─────────────┘ └──────────────┘ └─────────────────┘
│ │
│ CDP/WebSocket │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Browser (Chrome)│ │ VSCode Internals│
│ • DOM Snapshot │ │ • Language Svrs │
│ • Console Logs │ │ • File System │
│ • Screenshots │ │ • Diagnostics │
│ • Performance │ │ • Navigation │
│ • Interactions │ │ • Completions │
└─────────────────┘ └─────────────────┘
```
### 🔄 **Data Flow Explanation**
**For Code Intelligence (LSP Tools):**
1. **AI Assistant** sends MCP request for code navigation/analysis
2. **MCP Server** translates MCP → HTTP API call to VSCode Gateway
3. **VSCode Gateway** forwards to appropriate Language Server
4. **VSCode Internals** process LSP commands (definitions, references, etc.)
5. **Response flows back** through gateway with intelligent buffering
**For Browser Control (CDP Tools):**
1. **AI Assistant** sends MCP request for browser interaction
2. **MCP Server** connects directly to Chrome via WebSocket (CDP)
3. **Browser** executes commands (click, navigate, screenshot, etc.)
4. **Browser** returns results (DOM, console logs, performance data)
5. **Response flows back** to AI with intelligent buffering
**Key Insight:** MCP Server acts as a **dual-purpose bridge**:
1. **For accessing VSCode internals** via HTTP endpoint built into the VSCode internals gateway
2. **To gain full control over Edge browser** via Chrome DevTools Protocol using WebSocket transport (Edge greatly outperforms Chrome)
### 🏗️ **Key Design Principles**
**VSCode Extension (Gateway):**
- **Minimal & Stable**: Simple HTTP API exposure, rarely changes
- **Auto-activation**: Automatically activates Language Servers as needed
- **Session isolation**: Each MCP client gets isolated session
- **Port auto-discovery**: Finds available port, communicates via `.mcp_server_port`
**MCP Server:**
- **Hot reloadable**: `npm run dev` for instant development feedback
- **Language agnostic**: Core logic separate from VSCode integration
- **Intelligent buffering**: Large responses buffered to save tokens
- **Error resilience**: Graceful handling of missing files or invalid positions
- **Modular architecture**: 31 self-documenting tools in organized categories
### 🚀 **Developer Experience Benefits**
- **No VSCode restarts**: MCP server changes don't affect VSCode
- **Faster iteration**: Test MCP tools without extension rebuilds
- **Independent debugging**: Debug MCP server separately from VSCode
- **Language flexibility**: Rewrite MCP server in any language
- **Stable foundation**: VSCode gateway stays constant while MCP server evolves
## Development
```bash
# Install dependencies
pnpm install
# Development with watch mode
pnpm run dev
# Build for production
pnpm run build
# Run tests
pnpm run test
# Lint code
pnpm run lint
# Type checking
pnpm run typecheck
```
### Project Structure
```
mcp-server/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── tool-registry.ts # Tool registration system
│ ├── buffer-manager.ts # Intelligent buffer system
│ └── tools/ # Modular tool definitions
│ ├── lsp/ # Language Server Protocol tools
│ │ ├── get-hover.ts
│ │ ├── get-completions.ts
│ │ ├── get-definition.ts
│ │ ├── get-references.ts
│ │ ├── find-implementations.ts
│ │ ├── get-document-symbols.ts
│ │ ├── get-call-hierarchy.ts
│ │ ├── rename-symbol.ts
│ │ ├── get-code-actions.ts
│ │ ├── get-diagnostics.ts
│ │ ├── get-semantic-tokens.ts
│ │ ├── get-type-definition.ts
│ │ ├── find-text.ts
│ │ └── find-symbols.ts
│ ├── cdp/ # Chrome DevTools Protocol tools
│ │ ├── execute-in-browser.ts
│ │ ├── navigate-browser.ts
│ │ ├── click-element.ts
│ │ ├── type-in-browser.ts
│ │ ├── get-browser-console.ts
│ │ ├── get-dom-snapshot.ts
│ │ ├── take-screenshot.ts
│ │ └── wait-for-element.ts
│ ├── helper/ # Browser testing helpers
│ │ ├── test-react-component.ts
│ │ ├── test-api-endpoint.ts
│ │ ├── test-form-validation.ts
│ │ ├── check-page-performance.ts
│ │ └── debug-javascript-error.ts
│ └── system/ # System utilities
│ ├── retrieve-buffer.ts
│ ├── get-buffer-stats.ts
│ ├── get-instructions.ts
│ └── get-supported-languages.ts
└── utils/
└── index.ts # Logging utilities
```
## AI Assistant Compatibility
### Claude Code
Token Saver MCP works seamlessly with Claude Code out of the box. Simply configure your `.claude.json` file to point to `http://127.0.0.1:9700/mcp`.
### Gemini CLI
Token Saver MCP now supports Gemini CLI! To use with Gemini:
1. Configure `.gemini/settings.json` in your project root to connect to `http://127.0.0.1:9700/mcp-gemini`
2. When prompting Gemini, explicitly tell it to use the MCP server tools in preference to its default file operations
3. Example prompt: "Use the MCP server tools to find where function X is defined"
### Other AI Assistants
The server provides multiple endpoints for compatibility:
- Standard MCP: `http://127.0.0.1:9700/mcp`
- Streaming: `http://127.0.0.1:9700/mcp-streaming`
- REST API: `http://127.0.0.1:9700/mcp/simple`
## Troubleshooting
**Extension not responding?**
```bash
# Check if MCP server is running
python3 test/find_mcp_servers.py
```
**Need a specific port?**
```bash
echo "9700" > .mcp_server_port
```
**Port already in use?**
- Check `.mcp_server_port` file or let extension auto-increment from default port
**MCP tools not responding?**
- Ensure VSCode has the workspace open
- **Language Servers are automatically activated** when you use any MCP tool
- Verify VSCode extension is installed and active
- Verify the MCP server is running on the expected port
**Claude Code stuck on "connecting..." or showing "failed"?**
- **Reload the VSCode window** with `Cmd+Shift+R` (Mac) or `Ctrl+Shift+R` (Windows/Linux) to restart the extension and MCP server
- This clears any stale connection states and forces a fresh initialization
- After reloading, restart Claude Code in your project terminal
**Large responses causing issues?**
- Responses over 2,500 tokens are automatically buffered
- Use the returned `bufferId` with `retrieve_buffer` tool to get full data
- Check buffer stats with `get_buffer_stats` tool
**Testing the connection:**
```bash
# Run the comprehensive test suite
python3 test/test_mcp_tools.py
```
## Contributing
Contributions welcome! Please check the roadmap above for features to implement.
## License
MIT