From da908d8db4d48674ec484b74fbec945e979b80a4 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Fri, 24 Oct 2025 15:45:26 +0800 Subject: [PATCH] refactor: remove MCP code-index dependency, replace with ripgrep/find MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace all mcp__code-index__ calls with native ripgrep and find commands across workflow and command files for better performance and portability. Changes: - Remove 41 mcp__code-index__ function calls from 12 files - Replace with ripgrep (rg) for content search - Replace with find for file discovery - Remove index refresh dependencies (no longer needed) Modified files: - workflow/tools: context-gather, test-context-gather, task-generate-agent, task-generate, test-task-generate (core workflow tools) - workflow: review (security scanning) - memory: load, update-related, docs (memory management) - cli/mode: plan, bug-index, code-analysis (CLI modes) Documentation updates: - Simplify mcp-tool-strategy.md to only Exa usage (5 lines) - Streamline context-search-strategy.md to 69 lines - Standardize codebase-retrieval syntax per intelligent-tools-strategy.md Benefits: - Faster search with ripgrep (no index overhead) - Better cross-platform compatibility - Simpler configuration (fewer MCP dependencies) - -232 lines of code removed 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/commands/cli/mode/bug-index.md | 2 +- .claude/commands/cli/mode/code-analysis.md | 2 +- .claude/commands/cli/mode/plan.md | 2 +- .claude/commands/memory/docs.md | 2 +- .claude/commands/memory/load.md | 14 +- .claude/commands/memory/update-related.md | 5 +- .claude/commands/workflow/review.md | 6 +- .../commands/workflow/tools/context-gather.md | 82 ++++----- .../workflow/tools/task-generate-agent.md | 24 +-- .../commands/workflow/tools/task-generate.md | 6 +- .../workflow/tools/test-context-gather.md | 62 +++---- .../workflow/tools/test-task-generate.md | 10 +- .claude/workflows/context-search-strategy.md | 90 ++++----- .claude/workflows/mcp-tool-strategy.md | 173 +----------------- 14 files changed, 124 insertions(+), 356 deletions(-) diff --git a/.claude/commands/cli/mode/bug-index.md b/.claude/commands/cli/mode/bug-index.md index 91524c95..83e94f69 100644 --- a/.claude/commands/cli/mode/bug-index.md +++ b/.claude/commands/cli/mode/bug-index.md @@ -138,7 +138,7 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fail ```bash # 1. Find bug-related files rg "error_keyword" --files-with-matches -mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts") +rg "error|exception" -g "*.ts" # 2. Execute bug analysis with focused context (analysis only, no code changes) /cli:mode:bug-index --cd "src/module" "specific error description" diff --git a/.claude/commands/cli/mode/code-analysis.md b/.claude/commands/cli/mode/code-analysis.md index 7c8cac5a..639910e8 100644 --- a/.claude/commands/cli/mode/code-analysis.md +++ b/.claude/commands/cli/mode/code-analysis.md @@ -141,7 +141,7 @@ RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security ```bash # 1. Find entry points and related files rg "function.*authenticate|class.*AuthService" --files-with-matches -mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern="*.ts") +rg "authenticate|login" -g "*.ts" # 2. Build call graph understanding # entry → middleware → service → repository diff --git a/.claude/commands/cli/mode/plan.md b/.claude/commands/cli/mode/plan.md index 9696a8dc..16792e9d 100644 --- a/.claude/commands/cli/mode/plan.md +++ b/.claude/commands/cli/mode/plan.md @@ -139,7 +139,7 @@ RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibili ```bash # 1. Discover project structure ~/.claude/scripts/get_modules_by_depth.sh -mcp__code-index__find_files(pattern="*.ts") +find . -name "*.ts" -type f # 2. Gather existing architecture info rg "architecture|design" --files-with-matches diff --git a/.claude/commands/memory/docs.md b/.claude/commands/memory/docs.md index 56f60bce..17653b3f 100644 --- a/.claude/commands/memory/docs.md +++ b/.claude/commands/memory/docs.md @@ -658,7 +658,7 @@ bash( "pre_analysis": [ { "step": "discover_api_endpoints", - "command": "mcp__code-index__search_code_advanced(pattern='router\\.|@(Get|Post)', file_pattern='*.{ts,js}')", + "command": "bash(rg 'router\\.| @(Get|Post)' -g '*.{ts,js}')", "output_to": "endpoint_discovery" }, { diff --git a/.claude/commands/memory/load.md b/.claude/commands/memory/load.md index 725d3df3..633e0324 100644 --- a/.claude/commands/memory/load.md +++ b/.claude/commands/memory/load.md @@ -121,14 +121,14 @@ Task( ### Step 2: Keyword Extraction & File Discovery 1. Extract core keywords from task description -2. Discover relevant files using MCP code-index or rg: - \`\`\`javascript - // Prefer MCP tools - mcp__code-index__find_files(pattern="*{keyword}*") - mcp__code-index__search_code_advanced(pattern="{keyword}", context_lines=2) +2. Discover relevant files using ripgrep and find: + \`\`\`bash + # Find files by name + find . -name "*{keyword}*" -type f - // Fallback: use rg - bash(rg -l "{keyword}" --type ts --type md) + # Search content with ripgrep + rg "{keyword}" --type ts --type md -C 2 + rg -l "{keyword}" --type ts --type md # List files only \`\`\` ### Step 3: Deep Analysis via CLI diff --git a/.claude/commands/memory/update-related.md b/.claude/commands/memory/update-related.md index 2443b661..f54feafd 100644 --- a/.claude/commands/memory/update-related.md +++ b/.claude/commands/memory/update-related.md @@ -40,10 +40,7 @@ Orchestrates context-aware CLAUDE.md updates for changed modules using batched a ## Phase 1: Change Detection & Analysis ```bash -# Refresh code index -bash(mcp__code-index__refresh_index) - -# Detect changed modules +# Detect changed modules (no index refresh needed) bash(~/.claude/scripts/detect_changed_modules.sh list) # Cache git changes diff --git a/.claude/commands/workflow/review.md b/.claude/commands/workflow/review.md index ac4ac405..82031872 100644 --- a/.claude/commands/workflow/review.md +++ b/.claude/commands/workflow/review.md @@ -92,10 +92,10 @@ After bash validation, the model takes control to: 2. **Perform Specialized Review**: Based on `review_type` **Security Review** (`--type=security`): - - Use MCP code search for security patterns: + - Use ripgrep for security patterns: ```bash - mcp__code-index__search_code_advanced(pattern="password|token|secret|auth", file_pattern="*.{ts,js,py}") - mcp__code-index__search_code_advanced(pattern="eval|exec|innerHTML|dangerouslySetInnerHTML", file_pattern="*.{ts,js,tsx}") + rg "password|token|secret|auth" -g "*.{ts,js,py}" + rg "eval|exec|innerHTML|dangerouslySetInnerHTML" -g "*.{ts,js,tsx}" ``` - Use Gemini for security analysis: ```bash diff --git a/.claude/commands/workflow/tools/context-gather.md b/.claude/commands/workflow/tools/context-gather.md index 1f72989e..6cf7aab5 100644 --- a/.claude/commands/workflow/tools/context-gather.md +++ b/.claude/commands/workflow/tools/context-gather.md @@ -17,7 +17,7 @@ Agent-driven intelligent context collector that gathers relevant information fro - **Agent-Driven**: Delegate execution to universal-executor agent for autonomous operation - **Two-Phase Flow**: Discovery (context loading) → Execution (context gathering and packaging) - **Memory-First**: Reuse loaded documents from conversation memory -- **MCP-Enhanced**: Use MCP tools for advanced code analysis and file discovery +- **Ripgrep-Enhanced**: Use ripgrep and native tools for code analysis and file discovery - **Intelligent Collection**: Auto-identify relevant resources based on keyword analysis - **Comprehensive Coverage**: Collect code, documentation, configurations, and dependencies - **Standardized Output**: Generate unified format context-package.json @@ -36,9 +36,10 @@ Agent-driven intelligent context collector that gathers relevant information fro // If in memory: use cached content // Else: Load from .workflow/{session-id}/workflow-session.json }, - "mcp_capabilities": { - // Agent will use these tools to discover project context - "code_index": true, + "search_tools": { + // Agent will use these native tools to discover project context + "ripgrep": true, + "find": true, "exa_code": true, "exa_web": true } @@ -76,8 +77,9 @@ Task( ### Session Metadata {session_metadata_content} -### MCP Capabilities -- code-index: Available for file discovery and code search +### Search Tools +- ripgrep: Available for content search and pattern matching +- find: Available for file discovery - exa-code: Available for external research - exa-web: Available for web search @@ -87,7 +89,7 @@ Task( 1. **Project Structure Analysis**: Execute get_modules_by_depth.sh for architecture overview 2. **Documentation Loading**: Load CLAUDE.md, README.md and relevant documentation 3. **Keyword Extraction**: Extract core keywords from task description -4. **Smart File Discovery**: Use MCP code-index tools to locate relevant files +4. **Smart File Discovery**: Use ripgrep and find to locate relevant files 5. **Code Structure Analysis**: Analyze project structure to identify relevant modules 6. **Dependency Discovery**: Identify tech stack and dependency relationships 7. **Context Packaging**: Generate standardized JSON context package @@ -120,22 +122,18 @@ Task( - Identify potentially involved modules and components - Set file type filters -#### Step 2: MCP-Enhanced File Discovery +#### Step 2: File Discovery with Native Tools 1. **Code File Location** - Use MCP code-index tools: - \`\`\`javascript - // Find files by pattern - mcp__code-index__find_files(pattern="*{keyword}*") + Use ripgrep and find commands: + \`\`\`bash + # Find files by pattern + find . -name "*{keyword}*" -type f - // Search code content - mcp__code-index__search_code_advanced( - pattern="{keyword_patterns}", - file_pattern="*.{ts,js,py,go,md}", - context_lines=3 - ) + # Search code content with ripgrep + rg "{keyword_patterns}" --type-add 'custom:*.{ts,js,py,go,md}' -t custom -C 3 - // Get file summaries - mcp__code-index__get_file_summary(file_path="relevant/file.ts") + # Get file summaries (find function/class definitions) + rg "^(class|function|export|def|interface)" relevant/file.ts \`\`\` 2. **Configuration Files Discovery** @@ -321,34 +319,27 @@ Before completion, verify: - File count limit: Maximum 50 files per type - Size filtering: Skip oversized files (>10MB) - Depth limit: Maximum search depth of 3 levels -- Use MCP tools for efficient discovery +- Use ripgrep for efficient discovery -**MCP Tools Integration**: -Agent should use MCP code-index tools when available: -\`\`\`javascript -// Set project path -mcp__code-index__set_project_path(path="{current_project_path}") +**Native Tools Integration**: +Agent should use ripgrep and find commands: +\`\`\`bash +# Find files by pattern +find . -name "*{keyword}*" -type f -// Refresh index -mcp__code-index__refresh_index() +# Search code content with ripgrep +rg "{keyword_patterns}" --type ts --type js --type py --type go --type md -C 3 -// Find files by pattern -mcp__code-index__find_files(pattern="*{keyword}*") +# Alternative: use glob patterns +rg "{keyword_patterns}" -g "*.{ts,js,py,go,md}" -C 3 -// Search code content -mcp__code-index__search_code_advanced( - pattern="{keyword_patterns}", - file_pattern="*.{ts,js,py,go,md}", - context_lines=3 -) +# Count matches +rg "{keyword_patterns}" -c + +# List files with matches +rg "{keyword_patterns}" --files-with-matches \`\`\` -**Fallback Strategy**: -When MCP tools unavailable, agent should use traditional commands: -- \`find\` for file discovery -- \`rg\` or \`grep\` for content search -- Bash commands from project structure analysis - ## Output Generate context-package.json and report completion: @@ -391,9 +382,10 @@ const agentContext = { ? memory.get("workflow-session.json") : Read(.workflow/WFS-[id]/workflow-session.json), - // MCP capabilities - agent will use these tools - mcp_capabilities: { - code_index: true, + // Search tools - agent will use these native tools + search_tools: { + ripgrep: true, + find: true, exa_code: true, exa_web: true } diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md index 6170cd2a..11187d95 100644 --- a/.claude/commands/workflow/tools/task-generate-agent.md +++ b/.claude/commands/workflow/tools/task-generate-agent.md @@ -93,14 +93,11 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit } ``` -5. **MCP Code Analysis** (optional - enhance understanding) - ```javascript - // Find relevant files for task context - mcp__code-index__find_files(pattern="*auth*") - mcp__code-index__search_code_advanced( - pattern="authentication|oauth", - file_pattern="*.ts" - ) +5. **Code Analysis with Native Tools** (optional - enhance understanding) + ```bash + # Find relevant files for task context + find . -name "*auth*" -type f + rg "authentication|oauth" -g "*.ts" ``` 6. **MCP External Research** (optional - gather best practices) @@ -274,18 +271,13 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt) **Code Index Usage**: \`\`\`javascript // Discover authentication-related files -mcp__code-index__find_files(pattern="*auth*") +bash(find . -name "*auth*" -type f) // Search for OAuth patterns -mcp__code-index__search_code_advanced( - pattern="oauth|jwt|authentication", - file_pattern="*.{ts,js}" -) +bash(rg "oauth|jwt|authentication" -g "*.{ts,js}") // Get file summary for key components -mcp__code-index__get_file_summary( - file_path="src/auth/index.ts" -) +bash(rg "^(class|function|export|interface)" src/auth/index.ts) \`\`\` **Exa Research Usage**: diff --git a/.claude/commands/workflow/tools/task-generate.md b/.claude/commands/workflow/tools/task-generate.md index 4ddc2803..5d755f56 100644 --- a/.claude/commands/workflow/tools/task-generate.md +++ b/.claude/commands/workflow/tools/task-generate.md @@ -249,9 +249,9 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut } }, { - "step": "mcp_codebase_exploration", - "action": "Explore codebase using MCP tools", - "command": "mcp__code-index__find_files(pattern=\"[patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[patterns]\")", + "step": "codebase_exploration", + "action": "Explore codebase using native tools", + "command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")", "output_to": "codebase_structure" }, { diff --git a/.claude/commands/workflow/tools/test-context-gather.md b/.claude/commands/workflow/tools/test-context-gather.md index 3b32bc01..3fbd7170 100644 --- a/.claude/commands/workflow/tools/test-context-gather.md +++ b/.claude/commands/workflow/tools/test-context-gather.md @@ -17,11 +17,11 @@ Specialized context collector for test generation workflows that analyzes test c - **Gap Identification**: Locate implementation files without corresponding tests - **Source Context Loading**: Import implementation summaries from source session - **Framework Detection**: Auto-detect test framework and patterns -- **MCP-Powered**: Leverage code-index tools for precise analysis +- **Ripgrep-Powered**: Leverage ripgrep and native tools for precise analysis ## Core Responsibilities - Load source session implementation context -- Analyze current test coverage using MCP tools +- Analyze current test coverage using ripgrep - Identify files requiring test generation - Detect test framework and conventions - Package test context for analysis phase @@ -41,21 +41,17 @@ Specialized context collector for test generation workflows that analyzes test c - Extract changed files and implementation scope - Identify implementation patterns and tech stack -### Phase 2: Test Coverage Analysis (MCP Tools) +### Phase 2: Test Coverage Analysis (Ripgrep) 1. **Existing Test Discovery** ```bash # Find all test files - mcp__code-index__find_files(pattern="*.test.*") - mcp__code-index__find_files(pattern="*.spec.*") - mcp__code-index__find_files(pattern="*test_*.py") + find . -name "*.test.*" -type f + find . -name "*.spec.*" -type f + find . -name "*test_*.py" -type f # Search for test patterns - mcp__code-index__search_code_advanced( - pattern="describe|it|test|@Test", - file_pattern="*.test.*", - context_lines=0 - ) + rg "describe|it|test|@Test" -g "*.test.*" ``` 2. **Coverage Gap Analysis** @@ -80,18 +76,10 @@ Specialized context collector for test generation workflows that analyzes test c 1. **Framework Identification** ```bash # Check package.json or requirements.txt - mcp__code-index__search_code_advanced( - pattern="jest|mocha|jasmine|pytest|unittest|rspec", - file_pattern="package.json|requirements.txt|Gemfile", - context_lines=2 - ) + rg "jest|mocha|jasmine|pytest|unittest|rspec" -g "package.json" -g "requirements.txt" -g "Gemfile" -C 2 # Analyze existing test patterns - mcp__code-index__search_code_advanced( - pattern="describe\\(|it\\(|test\\(|def test_", - file_pattern="*.test.*", - context_lines=3 - ) + rg "describe\(|it\(|test\(|def test_" -g "*.test.*" -C 3 ``` 2. **Convention Analysis** @@ -207,33 +195,26 @@ Generate `test-context-package.json`: .workflow/{test_session_id}/.process/test-context-package.json ``` -## MCP Tools Usage +## Native Tools Usage ### File Discovery ```bash # Test files -mcp__code-index__find_files(pattern="*.test.*") -mcp__code-index__find_files(pattern="*.spec.*") +find . -name "*.test.*" -type f +find . -name "*.spec.*" -type f # Implementation files -mcp__code-index__find_files(pattern="*.ts") -mcp__code-index__find_files(pattern="*.js") +find . -name "*.ts" -type f +find . -name "*.js" -type f ``` ### Content Search ```bash # Test framework detection -mcp__code-index__search_code_advanced( - pattern="jest|mocha|pytest", - file_pattern="package.json|requirements.txt" -) +rg "jest|mocha|pytest" -g "package.json" -g "requirements.txt" # Test pattern analysis -mcp__code-index__search_code_advanced( - pattern="describe|it|test", - file_pattern="*.test.*", - context_lines=2 -) +rg "describe|it|test" -g "*.test.*" -C 2 ``` ### Coverage Analysis @@ -249,7 +230,7 @@ test_file_patterns=( # Search for test file for pattern in "${test_file_patterns[@]}"; do - if mcp__code-index__find_files(pattern="$pattern") | grep -q .; then + if [ -f "$pattern" ]; then echo "✅ Test exists: $pattern" break fi @@ -262,10 +243,9 @@ done |-------|-------|------------| | Source session not found | Invalid source_session reference | Verify test session metadata | | No implementation summaries | Source session incomplete | Complete source session first | -| MCP tools unavailable | MCP not configured | Fallback to bash find/grep | | No test framework detected | Missing test dependencies | Request user to specify framework | -## Fallback Strategy (No MCP) +## Native Tools Implementation ```bash # File discovery @@ -287,8 +267,8 @@ done - `/workflow:test-gen` (Phase 3: Context Gathering) ### Calls -- MCP code-index tools for analysis -- Bash file operations for fallback +- Ripgrep and find for file analysis +- Bash file operations for coverage analysis ### Followed By - `/workflow:tools:test-concept-enhanced` - Analyzes context and plans test generation @@ -296,7 +276,7 @@ done ## Success Criteria - ✅ Source session context loaded successfully -- ✅ Test coverage gaps identified with MCP tools +- ✅ Test coverage gaps identified with ripgrep - ✅ Test framework detected and documented - ✅ Valid test-context-package.json generated - ✅ All missing tests catalogued with priority diff --git a/.claude/commands/workflow/tools/test-task-generate.md b/.claude/commands/workflow/tools/test-task-generate.md index e244244f..08b0582a 100644 --- a/.claude/commands/workflow/tools/test-task-generate.md +++ b/.claude/commands/workflow/tools/test-task-generate.md @@ -146,9 +146,9 @@ Generate **TWO task JSON files**: "step": "load_existing_test_patterns", "action": "Study existing tests for pattern reference", "commands": [ - "mcp__code-index__find_files(pattern=\"*.test.*\")", + "bash(find . -name \"*.test.*\" -type f)", "bash(# Read first 2 existing test files as examples)", - "bash(test_files=$(mcp__code-index__find_files(pattern=\"*.test.*\") | head -2))", + "bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))", "bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)" ], "output_to": "existing_test_patterns", @@ -282,11 +282,11 @@ Generate **TWO task JSON files**: "step": "analyze_test_coverage", "action": "Analyze test coverage and identify missing tests", "commands": [ - "mcp__code-index__find_files(pattern=\"*.test.*\")", - "mcp__code-index__search_code_advanced(pattern=\"test|describe|it|def test_\", file_pattern=\"*.test.*\")", + "bash(find . -name \"*.test.*\" -type f)", + "bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")", "bash(# Count implementation files vs test files)", "bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))", - "bash(test_count=$(mcp__code-index__find_files(pattern=\"*.test.*\") | wc -l))", + "bash(test_count=$(find . -name \"*.test.*\" -type f | wc -l))", "bash(echo \"Implementation files: $impl_count, Test files: $test_count\")" ], "output_to": "test_coverage_analysis", diff --git a/.claude/workflows/context-search-strategy.md b/.claude/workflows/context-search-strategy.md index 4c0eb68e..c0d23ad4 100644 --- a/.claude/workflows/context-search-strategy.md +++ b/.claude/workflows/context-search-strategy.md @@ -8,89 +8,61 @@ type: search-guideline ## ⚡ Execution Environment -**CRITICAL**: All commands execute in **Bash environment** (Git Bash on Windows, Bash on Linux/macOS) +**CRITICAL**: All commands execute in **Bash environment** (Git Bash on Windows) -**❌ Forbidden**: Windows-specific commands (`findstr`, `dir`, `where`, `type`, `copy`, `del`) - Use Bash equivalents (`grep`, `find`, `which`, `cat`, `cp`, `rm`) +**❌ Forbidden**: Windows commands (`findstr`, `dir`, `where`) - Use Bash (`grep`, `find`, `cat`) ## ⚡ Core Search Tools **codebase-retrieval**: Semantic file discovery via Gemini CLI with all files analysis **rg (ripgrep)**: Fast content search with regex support **find**: File/directory location by name patterns -**grep**: Built-in pattern matching in files -**get_modules_by_depth.sh**: Program architecture analysis and structural discovery +**grep**: Built-in pattern matching (fallback when rg unavailable) +**get_modules_by_depth.sh**: Program architecture analysis (MANDATORY before planning) -### Decision Principles -- **Use codebase-retrieval for semantic discovery** - Intelligent file discovery based on task context -- **Use rg for content** - Fastest for searching within files -- **Use find for files** - Locate files/directories by name -- **Use grep sparingly** - Only when rg unavailable -- **Use get_modules_by_depth.sh first** - MANDATORY for program architecture analysis before planning -- **Always use Bash commands** - NEVER use Windows cmd/PowerShell commands - -### Tool Selection Matrix +## 📋 Tool Selection Matrix | Need | Tool | Use Case | |------|------|----------| -| **Semantic file discovery** | codebase-retrieval | Find files relevant to task/feature context | +| **Semantic discovery** | codebase-retrieval | Find files relevant to task/feature context | | **Pattern matching** | rg | Search code content with regex | | **File name lookup** | find | Locate files by name patterns | -| **Architecture analysis** | get_modules_by_depth.sh | Understand program structure | +| **Architecture** | get_modules_by_depth.sh | Understand program structure | + +## 🔧 Quick Command Reference -### Quick Command Reference ```bash # Semantic File Discovery (codebase-retrieval) -gemini "CONTEXT: @**/* List all files relevant to: [task/feature description]" -bash(gemini "CONTEXT: @**/* List all files relevant to: [task/feature description]") +cd [directory] && gemini -p " +PURPOSE: Discover files relevant to task/feature +TASK: List all files related to [task/feature description] +MODE: analysis +CONTEXT: @**/* +EXPECTED: Relevant file paths with relevance explanation +RULES: Focus on direct relevance to task requirements +" -# Program Architecture Analysis (MANDATORY FIRST) -~/.claude/scripts/get_modules_by_depth.sh # Discover program architecture -bash(~/.claude/scripts/get_modules_by_depth.sh) # Analyze structural hierarchy +# Program Architecture (MANDATORY FIRST) +~/.claude/scripts/get_modules_by_depth.sh # Content Search (rg preferred) -rg "pattern" --type js # Search in JS files -rg -i "case-insensitive" # Ignore case -rg -n "show-line-numbers" # Show line numbers -rg -A 3 -B 3 "context-lines" # Show 3 lines before/after +rg "pattern" --type js -n # Search JS files with line numbers +rg -i "case-insensitive" # Ignore case +rg -C 3 "context" # Show 3 lines before/after -# File Search (find) -find . -name "*.ts" -type f # Find TypeScript files +# File Search +find . -name "*.ts" -type f # Find TypeScript files find . -path "*/node_modules" -prune -o -name "*.js" -print -# Built-in alternatives -grep -r "pattern" . # Recursive search (slower) -grep -n -i "pattern" file.txt # Line numbers, case-insensitive +# Workflow Examples +rg "IMPL-\d+" .workflow/ --type json # Find task IDs +find .workflow/ -name "*.json" -path "*/.task/*" # Locate task files +rg "status.*pending" .workflow/.task/ # Find pending tasks ``` -### Workflow Integration Examples -```bash -# Semantic Discovery → Content Search → Analysis (Recommended Pattern) -gemini "CONTEXT: @**/* List all files relevant to: [task/feature]" # Get relevant files -rg "[pattern]" --type [filetype] # Then search within discovered files +## ⚡ Performance Tips -# Program Architecture Analysis (MANDATORY BEFORE PLANNING) -~/.claude/scripts/get_modules_by_depth.sh # Discover program architecture -bash(~/.claude/scripts/get_modules_by_depth.sh) # Analyze structural hierarchy - -# Search for task definitions -rg "IMPL-\d+" .workflow/ --type json # Find task IDs -find .workflow/ -name "*.json" -path "*/.task/*" # Locate task files - -# Analyze workflow structure -rg "status.*pending" .workflow/.task/ # Find pending tasks -rg "depends_on" .workflow/.task/ -A 2 # Show dependencies - -# Find workflow sessions -find .workflow/ -name ".active-*" # Active sessions -rg "WFS-" .workflow/ --type json # Session references - -# Content analysis for planning -rg "flow_control" .workflow/ -B 2 -A 5 # Flow control patterns -find . -name "IMPL_PLAN.md" -exec grep -l "requirements" {} \; -``` - -### Performance Tips - **rg > grep** for content search - **Use --type filters** to limit file types -- **Exclude common dirs**: `--glob '!node_modules'` -- **Use -F for literal** strings (no regex) \ No newline at end of file +- **Exclude dirs**: `--glob '!node_modules'` +- **Use -F** for literal strings (no regex) diff --git a/.claude/workflows/mcp-tool-strategy.md b/.claude/workflows/mcp-tool-strategy.md index 8e9ae356..952f3d08 100644 --- a/.claude/workflows/mcp-tool-strategy.md +++ b/.claude/workflows/mcp-tool-strategy.md @@ -1,176 +1,11 @@ -# MCP Tool Strategy: Triggers & Workflows +# MCP Tool Strategy: Exa Usage -## ⚡ Triggering Mechanisms +## ⚡ Exa Triggering Mechanisms -**Auto-Trigger Scenarios**: +**Auto-Trigger**: - User mentions "exa-code" or code-related queries → `mcp__exa__get_code_context_exa` - Need current web information → `mcp__exa__web_search_exa` -- Finding code patterns/files → `mcp__code-index__search_code_advanced` -- Locating specific files → `mcp__code-index__find_files` -**Manual Trigger Rules**: +**Manual Trigger**: - Complex API research → Exa Code Context -- Architecture pattern discovery → Exa Code Context + Gemini analysis - Real-time information needs → Exa Web Search -- Codebase exploration → Code Index tools first, then Gemini analysis - -## 🎯 Available MCP Tools - -### Exa Code Context (mcp__exa__get_code_context_exa) -**Purpose**: Search and get relevant context for programming tasks -**Strengths**: Highest quality context for libraries, SDKs, and APIs -**Best For**: Code examples, API patterns, learning frameworks - -**Usage**: -```bash -mcp__exa__get_code_context_exa( - query="React useState hook examples", - tokensNum="dynamic" # or 1000-50000 -) -``` - -**Examples**: "React useState", "Python pandas filtering", "Express.js middleware" - -### Exa Web Search (mcp__exa__web_search_exa) -**Purpose**: Real-time web searches with content scraping -**Best For**: Current information, research, recent solutions - -**Usage**: -```bash -mcp__exa__web_search_exa( - query="latest React 18 features", - numResults=5 # default: 5 -) -``` - - -### Code Index Tools (mcp__code-index__) -**核心方法**: `search_code_advanced`, `find_files`, `refresh_index` - -**核心搜索**: -```bash -mcp__code-index__search_code_advanced(pattern="function.*auth", file_pattern="*.ts") -mcp__code-index__find_files(pattern="*.test.js") -mcp__code-index__refresh_index() # git操作后刷新 -``` - -**实用场景**: -- **查找代码**: `search_code_advanced(pattern="old.*API")` -- **定位文件**: `find_files(pattern="src/**/*.tsx")` -- **更新索引**: `refresh_index()` (git操作后) - -**文件搜索测试结果**: -- ✅ `find_files(pattern="*.md")` - 搜索所有 Markdown 文件 -- ✅ `find_files(pattern="*complete*")` - 通配符匹配文件名 -- ❌ `find_files(pattern="complete.md")` - 精确匹配可能失败 -- 📝 建议使用通配符模式获得更好的搜索结果 - -## 📊 Tool Selection Matrix - -| Task | MCP Tool | Use Case | Integration | -|------|----------|----------|-------------| -| **Code Context** | Exa Code | API examples, patterns | → Gemini analysis | -| **Research** | Exa Web | Current info, trends | → Planning phase | -| **Code Search** | Code Index | Pattern discovery, file location | → Gemini analysis | -| **Navigation** | Code Index | File exploration, structure | → Architecture phase | - -## 🚀 Integration Patterns - -### Standard Workflow -```bash -# 1. Explore codebase structure -mcp__code-index__find_files(pattern="*async*") -mcp__code-index__search_code_advanced(pattern="async.*function", file_pattern="*.ts") - -# 2. Get external context -mcp__exa__get_code_context_exa(query="TypeScript async patterns", tokensNum="dynamic") - -# 3. Analyze with Gemini -cd "src/async" && gemini " -PURPOSE: Understand async patterns -CONTEXT: Code index results + Exa context + @src/async/**/* -EXPECTED: Pattern analysis -RULES: Focus on TypeScript best practices -" - -# 4. Implement with Codex -codex -C src/async --full-auto exec "Apply modern async patterns" -s danger-full-access -``` - -### Enhanced Planning -1. **Explore codebase** with Code Index tools -2. **Research** with Exa Web Search -3. **Get code context** with Exa Code Context -4. **Analyze** with Gemini -5. **Architect** with Qwen -6. **Implement** with Codex - -## 🔧 Best Practices - -### Code Index -- **Search first** - Use before external tools for codebase exploration -- **Refresh after git ops** - Keep index synchronized -- **Pattern specificity** - Use precise regex patterns for better results -- **File patterns** - Combine with glob patterns for targeted search -- **Glob pattern matching** - Use `*.md`, `*complete*` patterns for file discovery -- **Exact vs wildcard** - Exact names may fail, use wildcards for better results - -### Exa Code Context -- **Use "dynamic" tokens** for efficiency -- **Be specific** - include technology stack -- **MANDATORY** when user mentions exa-code or code queries - -### Exa Web Search -- **Default 5 results** usually sufficient -- **Use for current info** - supplement knowledge cutoff - - - -## 🎯 Common Scenarios - -### Learning New Technology -```bash -# Explore existing patterns + get examples + research + analyze -mcp__code-index__search_code_advanced(pattern="router|routing", file_pattern="*.ts") -mcp__exa__get_code_context_exa(query="Next.js 14 app router", tokensNum="dynamic") -mcp__exa__web_search_exa(query="Next.js 14 best practices 2024", numResults=3) -cd "src/app" && gemini "Learn Next.js patterns" -``` - -### Debugging -```bash -# Find similar patterns + solutions + fix -mcp__code-index__search_code_advanced(pattern="similar.*error", file_pattern="*.ts") -mcp__exa__get_code_context_exa(query="TypeScript generic constraints", tokensNum="dynamic") -codex --full-auto exec "Fix TypeScript issues" -s danger-full-access -``` - -### Codebase Exploration -```bash -# Comprehensive codebase understanding workflow -mcp__code-index__set_project_path(path="/current/project") # 设置项目路径 -mcp__code-index__refresh_index() # 刷新索引 -mcp__code-index__find_files(pattern="*auth*") # Find auth-related files -mcp__code-index__search_code_advanced(pattern="function.*auth", file_pattern="*.ts") # Find auth functions -mcp__code-index__get_file_summary(file_path="src/auth/index.ts") # Understand structure -cd "src/auth" && gemini "Analyze auth architecture" -``` - -### Project Setup Workflow -```bash -# 新项目初始化流程 -mcp__code-index__set_project_path(path="/path/to/new/project") -mcp__code-index__get_settings_info() # 确认设置 -mcp__code-index__refresh_index() # 建立索引 -mcp__code-index__configure_file_watcher(enabled=true) # 启用文件监控 -mcp__code-index__get_file_watcher_status() # 确认监控状态 -``` - -## ⚡ Performance Tips - -- **Code Index first** → explore codebase before external tools -- **Use "dynamic" tokens** for Exa Code Context -- **MCP first** → gather context before analysis -- **Focus queries** - avoid overly broad searches -- **Integrate selectively** - use relevant context only -- **Refresh index** after major git operations \ No newline at end of file