Reorganize repository structure and clean up documentation
Clean up and organize the flask-shopdb repository for better maintainability and discoverability: ## Changes - Update .gitignore for build artifacts (publish/, data/, 122M total) - Reorganize .claude/ into 6 subdirectories with README navigation - Consolidate overlapping MCP setup guides into MCP-QUICK-START.md - Move deployment docs from root to docs/deployment/ - Archive dated status reports to .claude/archived/ - Delete temporary files (logs, backups, empty reports, ~50K) ## New Structure .claude/ organized into: - setup/ - MCP, VM, Hyper-V, GitHub setup guides + scripts (17 files) - plans/ - Feature plans and protocols (5 files) - maintenance/ - Deployment checklists and reports (4 files) - archived/ - Historical documentation (9 files) - skills/ - Claude Code automation (5 files) - workflows/ - Security audit workflow (1 file) docs/deployment/ created with 6 deployment guides: - LOCAL-DEV-SETUP.md, DOCKER-SETUP.md, DOCKER-PREBUILT-APPROACH.md - PRODUCTION-READINESS.md, DEPLOY-TO-VM.md, README.md Root directory cleaned to essential docs only: - CLAUDE.md, README.md, CONTRIBUTING.md, CHANGELOG.md Benefits: - Clear navigation via README.md in each subdirectory - No duplicate/overlapping documentation - Large artifacts properly gitignored (won't bloat repository) - Historical context preserved in archived/ See .claude/CLEANUP-SUMMARY.md for complete details. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Proudlock
164
.claude/setup/GORTEX-MCP-SETUP.md
Normal file
164
.claude/setup/GORTEX-MCP-SETUP.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# 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:** ✅
|
||||
```bash
|
||||
/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):
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user