shopdb-flask/.claude/setup/GORTEX-MCP-SETUP.md

# Gortex MCP Integration Guide

Gortex is successfully installed and has indexed your ShopDB repository (115K+ symbols, 412K edges). 

Now we need to connect it as an MCP server so Claude Code can use its 48 tools directly.

## Current Status

**Installed:** [X] Gortex v0.64.2 at `C:\Users\270015376\Documents\gortex.exe`

**Daemon Running:** [X] 
```bash
/c/Users/270015376/Documents/gortex.exe status
# Shows: daemon running, flask-shopdb tracked with 2467 files
```

**Indexed Repository:** [X] flask-shopdb at `C:\Users\270015376\Documents\github\flask-shopdb`

## How to Connect as MCP Server

### Option 1: Claude Desktop App

If using Claude Desktop app, add to your MCP config file (likely `~/Library/Application Support/Claude/claude_desktop_config.json` on Mac or equivalent on Windows):

```json
{
  "mcpServers": {
    "gortex": {
      "command": "C:\\Users\\270015376\\Documents\\gortex.exe",
      "args": ["mcp"],
      "cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
    }
  }
}
```

### Option 2: Claude Code CLI

Check if there's an `.claude/mcp.json` in your project:

```bash
cat .claude/mcp.json
```

If it exists, add Gortex server. If not, create it:

```json
{
  "mcpServers": {
    "gortex": {
      "command": "C:\\Users\\270015376\\Documents\\gortex.exe",
      "args": ["mcp"],
      "cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
    }
  }
}
```

### Option 3: Manual Start (Testing)

Test the MCP server manually:
```bash
cd C:\Users\270015376\Documents\github\flask-shopdb
/c/Users/270015376/Documents/gortex.exe mcp
```

This starts the MCP server in stdio mode. Press Ctrl+C to stop.

## Available Tools (48 total)

Once connected, Claude Code will have access to these tools:

### Navigation & Discovery
- `explore` - Start here for any task (gets relevant symbols)
- `find_files` - Find files by name
- `batch_symbols` - Get multiple symbols + callers/callees
- `find_implementations` - What implements this interface
- `find_declaration` - Where is this symbol defined
- `find_co_changing_symbols` - Files that change together

### Code Editing
- `edit_symbol` - Edit code by symbol ID (no need to read whole file)
- `edit_file` - Edit any file by exact replacement
- `batch_edit` - Apply multiple edits atomically

### Analysis & Review
- `detect_changes` - Map uncommitted changes to blast radius
- `diff_context` - Graph context for git diffs (perfect for merges!)
- `explain_change_impact` - What will break if I change this
- `audit_health` - Code health grades (A-F)
- `find_clones` - Duplicate code detection
- `api_impact` - Impact report before modifying routes

### Memory & Session
- `distill_session` - Summarize work session
- Context buffering tools (`ctx_peek`, `ctx_slice`, `ctx_grep`)

## Expected Token Savings

Based on our typical workflow:

**Exploring fleet alerts:**
- Current: 10-15K tokens (multiple grep + read cycles)
- With Gortex: 2-3K tokens (explore tool)
- **Savings: ~70-80%**

**Editing routes.py:**
- Current: 5K tokens (read 3000-line file)
- With Gortex: 1-2K tokens (edit_symbol)
- **Savings: ~60-70%**

**Merging wilm -> wj:**
- Current: 8-12K tokens (read conflicts, understand context)
- With Gortex: 3-5K tokens (diff_context tool)
- **Savings: ~50-60%**

**Overall session savings: 30-50K tokens per session** (out of 200K budget)

## Testing Connection

After adding to MCP config, restart Claude Code and check:

```
# In Claude Code conversation, look for system message about MCP servers
# Or try using a tool:
ToolSearch("gortex explore")
```

If working, you'll see Gortex tools available via ToolSearch.

## Troubleshooting

**Daemon not running:**
```bash
/c/Users/270015376/Documents/gortex.exe daemon start
```

**Check status:**
```bash
/c/Users/270015376/Documents/gortex.exe status
```

**Stop daemon:**
```bash
/c/Users/270015376/Documents/gortex.exe daemon stop
```

**Re-index after major changes:**
```bash
# Daemon auto-updates, but to force:
/c/Users/270015376/Documents/gortex.exe untrack .
/c/Users/270015376/Documents/gortex.exe track .
```

## Why This Matters

Instead of me reading entire files to understand code, I can:
1. Ask Gortex "explore fleet alerts" -> get relevant symbols
2. Query "what calls get_fleet_alerts" -> see usage
3. Edit symbols directly by ID -> no file reading
4. Analyze blast radius before changes -> prevent bugs
5. Get merge context -> easier conflict resolution

This turns Gortex from a "nice to have" into a "fundamental workflow tool" that saves significant tokens and improves code understanding.