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: ✅ Gortex v0.64.2 at C:\Users\270015376\Documents\gortex.exe

Daemon Running: ✅

/c/Users/270015376/Documents/gortex.exe status
# Shows: daemon running, flask-shopdb tracked with 2467 files

Indexed Repository: ✅ 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):

{
  "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:

cat .claude/mcp.json

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

{
  "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:

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:

/c/Users/270015376/Documents/gortex.exe daemon start

Check status:

/c/Users/270015376/Documents/gortex.exe status

Stop daemon:

/c/Users/270015376/Documents/gortex.exe daemon stop

Re-index after major changes:

# 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.