From a4b32f23b897225d41884f8ee30abd771be63e0e Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 28 Sep 2025 16:40:01 +0800 Subject: [PATCH] feat: Add experimental MCP tools integration for enhanced codebase analysis MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## New Features - **MCP Tools Integration**: Added support for Model Context Protocol tools - Exa MCP Server: External API patterns and best practices - Code Index MCP: Advanced internal codebase search and indexing - **Enhanced Workflow Planning**: Updated pre_analysis to include MCP tool steps - **Documentation Updates**: Added MCP tool setup guides and usage examples ## Changes ### Core Components - Updated `plan.md` with MCP integration principles and implementation approach guidelines - Added MCP tool steps in pre_analysis workflow: `mcp_codebase_exploration`, `mcp_external_context` - Enhanced context accumulation with external best practices lookup ### Documentation - Added comprehensive MCP tools section in both English and Chinese README - Updated installation requirements and integration guidelines - Added GitHub repository links for required MCP servers ### Agent Enhancements - Updated multiple agents to support MCP tool integration - Enhanced context gathering capabilities with external pattern analysis ## Technical Details - MCP tools provide faster analysis through direct codebase indexing - Automatic fallback to traditional bash/CLI tools when MCP unavailable - Enhanced pattern recognition and similarity detection capabilities 🧪 **Experimental**: MCP integration is currently experimental and optional 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/agents/action-planning-agent.md | 1 + .claude/agents/code-developer.md | 6 + .claude/agents/code-review-test-agent.md | 5 + .claude/agents/conceptual-planning-agent.md | 22 +-- .claude/agents/general-purpose.md | 1 + .claude/agents/memory-gemini-bridge.md | 8 +- .claude/commands/update-memory-full.md | 8 +- .claude/commands/update-memory-related.md | 8 +- .../commands/workflow/brainstorm/artifacts.md | 1 + .claude/commands/workflow/brainstorm/auto.md | 1 + .claude/commands/workflow/concept-eval.md | 1 + .claude/commands/workflow/plan.md | 92 ++++++++-- .claude/workflows/mcp-tool-strategy.md | 168 ++++++++++++++++++ CLAUDE.md | 1 + README_CN.md | 29 +++ 15 files changed, 322 insertions(+), 30 deletions(-) create mode 100644 .claude/workflows/mcp-tool-strategy.md diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index 1a249b51..e1a8cbe5 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.claude/agents/action-planning-agent.md @@ -71,6 +71,7 @@ You are a pure execution agent specialized in creating actionable implementation 4. Use consolidated analysis to inform implementation stages and task breakdown #### Analysis Dimensions Coverage +- **Exa Research**: Use `mcp__exa__get_code_context_exa` for technology stack selection and API patterns - Architecture patterns and component relationships - Implementation conventions and coding standards - Module dependencies and integration points diff --git a/.claude/agents/code-developer.md b/.claude/agents/code-developer.md index fd77fbe9..70fbeaac 100644 --- a/.claude/agents/code-developer.md +++ b/.claude/agents/code-developer.md @@ -85,6 +85,12 @@ ELIF context insufficient OR task has flow control marker: **Rule**: Before referencing modules/components, use `rg` or search to verify existence first. +**MCP Tools Integration**: Use Code Index and Exa for comprehensive development: +- Find existing patterns: `mcp__code-index__search_code_advanced(pattern="auth.*function")` +- Locate files: `mcp__code-index__find_files(pattern="src/**/*.ts")` +- Get API examples: `mcp__exa__get_code_context_exa(query="React authentication hooks", tokensNum="dynamic")` +- Update after changes: `mcp__code-index__refresh_index()` + **Test-Driven Development**: - Write tests first (red → green → refactor) - Focus on core functionality and edge cases diff --git a/.claude/agents/code-review-test-agent.md b/.claude/agents/code-review-test-agent.md index 66437fc7..1e51b7bc 100644 --- a/.claude/agents/code-review-test-agent.md +++ b/.claude/agents/code-review-test-agent.md @@ -159,6 +159,11 @@ if [FAST_MODE]: apply targeted review process - Missing or unused imports identification - Circular dependency detection +**MCP Tools Integration**: Use Code Index for comprehensive analysis: +- Pattern discovery: `mcp__code-index__search_code_advanced(pattern="import.*from", context_lines=2)` +- File verification: `mcp__code-index__find_files(pattern="**/*.test.js")` +- Post-review refresh: `mcp__code-index__refresh_index()` + ### Performance - Algorithm complexity (time and space) - Database query optimization diff --git a/.claude/agents/conceptual-planning-agent.md b/.claude/agents/conceptual-planning-agent.md index 0cdb2568..95123ca4 100644 --- a/.claude/agents/conceptual-planning-agent.md +++ b/.claude/agents/conceptual-planning-agent.md @@ -86,17 +86,17 @@ def handle_brainstorm_assignment(prompt): ### Role-Specific Analysis Dimensions -| Role | Primary Dimensions | Focus Areas | -|------|-------------------|--------------| -| system-architect | architecture_patterns, scalability_analysis, integration_points | Technical design and system structure | -| ui-designer | user_flow_patterns, component_reuse, design_system_compliance | UI/UX patterns and consistency | -| business-analyst | process_optimization, cost_analysis, efficiency_metrics, workflow_patterns | Business process and ROI | -| data-architect | data_models, flow_patterns, storage_optimization | Data structure and flow | -| security-expert | vulnerability_assessment, threat_modeling, compliance_check | Security risks and compliance | -| user-researcher | usage_patterns, pain_points, behavior_analysis | User behavior and needs | -| product-manager | feature_alignment, market_fit, competitive_analysis | Product strategy and positioning | -| innovation-lead | emerging_patterns, technology_trends, disruption_potential | Innovation opportunities | -| feature-planner | implementation_complexity, dependency_mapping, risk_assessment | Development planning | +| Role | Primary Dimensions | Focus Areas | Exa Usage | +|------|-------------------|--------------|-----------| +| system-architect | architecture_patterns, scalability_analysis, integration_points | Technical design and system structure | `mcp__exa__get_code_context_exa("microservices patterns")` | +| ui-designer | user_flow_patterns, component_reuse, design_system_compliance | UI/UX patterns and consistency | `mcp__exa__get_code_context_exa("React design system patterns")` | +| business-analyst | process_optimization, cost_analysis, efficiency_metrics, workflow_patterns | Business process and ROI | `mcp__exa__get_code_context_exa("business workflow automation")` | +| data-architect | data_models, flow_patterns, storage_optimization | Data structure and flow | `mcp__exa__get_code_context_exa("database schema patterns")` | +| security-expert | vulnerability_assessment, threat_modeling, compliance_check | Security risks and compliance | `mcp__exa__get_code_context_exa("security authentication patterns")` | +| user-researcher | usage_patterns, pain_points, behavior_analysis | User behavior and needs | `mcp__exa__get_code_context_exa("user research methodologies")` | +| product-manager | feature_alignment, market_fit, competitive_analysis | Product strategy and positioning | `mcp__exa__get_code_context_exa("product management frameworks")` | +| innovation-lead | emerging_patterns, technology_trends, disruption_potential | Innovation opportunities | `mcp__exa__get_code_context_exa("emerging technology trends")` | +| feature-planner | implementation_complexity, dependency_mapping, risk_assessment | Development planning | `mcp__exa__get_code_context_exa("agile development patterns")` | ### Output Integration diff --git a/.claude/agents/general-purpose.md b/.claude/agents/general-purpose.md index 1d4031cf..8b769aee 100644 --- a/.claude/agents/general-purpose.md +++ b/.claude/agents/general-purpose.md @@ -31,6 +31,7 @@ You are a versatile execution specialist focused on completing high-quality task ### 1. Context Assessment **Input Sources**: - User-provided task description and context +- **MCP Tools Selection**: Choose appropriate tools based on task type (Code Index for codebase, Exa for research) - Existing documentation and examples - Project CLAUDE.md standards - Domain-specific requirements diff --git a/.claude/agents/memory-gemini-bridge.md b/.claude/agents/memory-gemini-bridge.md index ffee4d28..83e17dc1 100644 --- a/.claude/agents/memory-gemini-bridge.md +++ b/.claude/agents/memory-gemini-bridge.md @@ -15,11 +15,15 @@ Coordinate parallel execution of `~/.claude/scripts/update_module_claude.sh` scr ### 1. Analyze Project Structure ```bash -# Step 1: Get module list with depth information +# Step 1: Code Index architecture analysis +mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}") +mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}") + +# Step 2: Get module list with depth information modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list)) count=$(echo "$modules" | wc -l) -# Step 2: Display project structure +# Step 3: Display project structure Bash(~/.claude/scripts/get_modules_by_depth.sh grouped) ``` diff --git a/.claude/commands/update-memory-full.md b/.claude/commands/update-memory-full.md index 9922152e..21a56503 100644 --- a/.claude/commands/update-memory-full.md +++ b/.claude/commands/update-memory-full.md @@ -16,10 +16,14 @@ Complete project-wide documentation update using depth-parallel execution. #!/bin/bash # Complete project-wide CLAUDE.md documentation update -# Step 1: Cache git changes +# Step 1: Code Index architecture analysis +mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}") +mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}") + +# Step 2: Cache git changes Bash(git add -A 2>/dev/null || true) -# Step 2: Get and display project structure +# Step 3: Get and display project structure modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list)) count=$(echo "$modules" | wc -l) diff --git a/.claude/commands/update-memory-related.md b/.claude/commands/update-memory-related.md index 88c40d76..2b672d63 100644 --- a/.claude/commands/update-memory-related.md +++ b/.claude/commands/update-memory-related.md @@ -17,10 +17,14 @@ Context-aware documentation update for modules affected by recent changes. #!/bin/bash # Context-aware CLAUDE.md documentation update -# Step 1: Detect changed modules (before staging) +# Step 1: Code Index refresh and architecture analysis +mcp__code-index__refresh_index() +mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}") + +# Step 2: Detect changed modules (before staging) changed=$(Bash(~/.claude/scripts/detect_changed_modules.sh list)) -# Step 2: Cache git changes (protect current state) +# Step 3: Cache git changes (protect current state) Bash(git add -A 2>/dev/null || true) # Step 3: Use detected changes or fallback diff --git a/.claude/commands/workflow/brainstorm/artifacts.md b/.claude/commands/workflow/brainstorm/artifacts.md index f6f60121..ca9ab2c0 100644 --- a/.claude/commands/workflow/brainstorm/artifacts.md +++ b/.claude/commands/workflow/brainstorm/artifacts.md @@ -25,6 +25,7 @@ Dedicated command for topic discussion, decomposition, and analysis artifacts ge ### Discussion & Artifacts Generation Process **0. Session Management** ⚠️ FIRST STEP +- **MCP Tools Integration**: Use Code Index for technical context, Exa for industry insights - **Active session detection**: Check `.workflow/.active-*` markers - **Session selection**: Prompt user if multiple active sessions found - **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists diff --git a/.claude/commands/workflow/brainstorm/auto.md b/.claude/commands/workflow/brainstorm/auto.md index b2ac2bb0..5d7fe6cc 100644 --- a/.claude/commands/workflow/brainstorm/auto.md +++ b/.claude/commands/workflow/brainstorm/auto.md @@ -41,6 +41,7 @@ ls ~/.claude/workflows/cli-templates/planning-roles/ # Show all available roles The command performs dedicated role analysis through: **0. Session Management** ⚠️ FIRST STEP +- **MCP Tools Integration**: Use Code Index for codebase context, Exa for external insights - **Active session detection**: Check `.workflow/.active-*` markers - **Session selection**: Prompt user if multiple active sessions found - **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists diff --git a/.claude/commands/workflow/concept-eval.md b/.claude/commands/workflow/concept-eval.md index cdeec99a..43e4f850 100644 --- a/.claude/commands/workflow/concept-eval.md +++ b/.claude/commands/workflow/concept-eval.md @@ -46,6 +46,7 @@ Pre-planning evaluation command that assesses concept feasibility, identifies po The command performs comprehensive concept evaluation through: **0. Context Preparation** ⚠️ FIRST STEP +- **MCP Tools Integration**: Use Code Index for codebase exploration, Exa for external context - **Documentation loading**: Automatic context gathering based on concept scope - **Always check**: `CLAUDE.md`, `README.md` - Project context and conventions - **For architecture concepts**: `.workflow/docs/architecture/`, existing system patterns diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 1eb56873..c67cef49 100644 --- a/.claude/commands/workflow/plan.md +++ b/.claude/commands/workflow/plan.md @@ -11,6 +11,24 @@ examples: # Workflow Plan Command +## 🚀 MCP Tools Integration (NEW!) + +**Enhanced with MCP (Model Context Protocol) tools for advanced codebase analysis:** + +### Required MCP Servers +1. **Exa MCP Server** - External API patterns and examples + - Repository: https://github.com/exa-labs/exa-mcp-server + - Function: `mcp__exa__get_code_context_exa()` - Get external best practices + +2. **Code Index MCP** - Internal codebase exploration + - Repository: https://github.com/johnhuang316/code-index-mcp + - Functions: + - `mcp__code-index__find_files()` - File pattern matching + - `mcp__code-index__search_code_advanced()` - Advanced code search + +### Installation & Setup +Please install these MCP servers to enable enhanced codebase analysis. The workflow will automatically use them when available. + ## Usage ```bash /workflow:plan @@ -91,6 +109,18 @@ The following pre_analysis steps are generated for agent execution: "command": "bash(cat .workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md 2>/dev/null || echo 'planning analysis not found')", "output_to": "planning_context" }, + { + "step": "mcp_codebase_exploration", + "action": "Explore codebase structure and patterns using MCP tools", + "command": "mcp__code-index__find_files(pattern=\"[task_focus_patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[relevant_patterns]\", file_pattern=\"[target_extensions]\")", + "output_to": "codebase_structure" + }, + { + "step": "mcp_external_context", + "action": "Get external API examples and best practices", + "command": "mcp__exa__get_code_context_exa(query=\"[task_technology] [task_patterns]\", tokensNum=\"dynamic\")", + "output_to": "external_context" + }, { "step": "load_dependencies", "action": "Retrieve dependency task summaries", @@ -104,18 +134,11 @@ The following pre_analysis steps are generated for agent execution: "output_to": "doc_context" }, { - "step": "analyze_patterns", - "action": "Analyze codebase patterns and architecture using CLI tools with directory context", - "command": "bash(cd \"[target_directory]\" && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze existing patterns TASK: Identify implementation patterns for [task_type] CONTEXT: [planning_context] [dependency_context] EXPECTED: Pattern analysis and recommendations RULES: Focus on architectural consistency\")", - "output_to": "pattern_analysis", - "on_error": "skip_optional" - }, - { - "step": "analyze_implementation", - "action": "Development-focused analysis using Codex when needed", - "command": "bash(codex -C [target_directory] --full-auto exec \"PURPOSE: Analyze implementation patterns TASK: Review development patterns for [task_type] CONTEXT: [planning_context] [dependency_context] EXPECTED: Development strategy and code patterns RULES: Focus on implementation consistency\" -s danger-full-access)", - "output_to": "implementation_analysis", - "on_error": "skip_optional" + "step": "gather_task_context", + "action": "Analyze task context and dependencies without implementation", + "command": "bash(cd \"[task_focus_paths]\" && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze task context and patterns TASK: Review existing patterns and dependencies for '[task_title]' CONTEXT: Task ID [task_id], Focus paths: [task_focus_paths], MCP findings: [codebase_structure] [external_context] EXPECTED: Pattern analysis, dependency mapping, and architectural insights RULES: Focus on understanding existing code patterns, no implementation\")", + "output_to": "task_context", + "on_error": "fail" } ] } @@ -126,7 +149,49 @@ Flow_control design should follow these principles: 1. **Structure Analysis**: Project hierarchy and patterns 2. **Dependency Mapping**: Previous task summaries → inheritance context 3. **Task Context Generation**: Combined analysis → task.context fields -4. **CLI Tool Analysis**: Use Gemini/Codex appropriately for pattern analysis when needed +4. **CLI Tool Analysis**: Use Gemini/Codex appropriately for pattern analysis when needed + +**MCP Integration Principles**: +- **Code Index First**: Use `mcp__code-index__` for internal codebase exploration before external tools +- **Exa for Context**: Use `mcp__exa__get_code_context_exa` to supplement with external API patterns and examples +- **Automatic Fallback**: If MCP tools unavailable, workflow uses traditional bash/CLI tools +- **Enhanced Analysis**: MCP tools provide deeper codebase understanding and external best practices + +**Benefits of MCP Integration**: +- **Faster Analysis**: Direct codebase indexing vs. manual file searching +- **External Context**: Real-world API patterns and implementation examples +- **Pattern Recognition**: Advanced code pattern matching and similarity detection +- **Comprehensive Coverage**: Both internal code exploration and external best practice lookup + +**Implementation Approach Planning**: +Each task's `flow_control.implementation_approach` defines execution strategy (planning phase): + +1. **task_description**: Implementation strategy definition: + - Clear implementation goal to be executed later + - Planned reference to patterns from pre_analysis results + - Integration strategy with existing codebase + +2. **modification_points**: Planned code modification targets: + - Specific code changes to be made during execution + - Planned use of parent task patterns via `[parent]` context + - Integration points with existing components via `[context]` from dependencies + +3. **logic_flow**: Business logic execution plan: + - Step-by-step workflow to be implemented + - Planned data flow between components + - Integration points using `[inherited]` and `[shared]` context + +4. **target_files**: Target file specifications for execution: + - `src/auth/login.ts:handleLogin:75-120` (planned function and line range) + - `src/middleware/auth.ts:validateToken` (planned function target) + - Must align with task's `context.focus_paths` + +**Variable Reference System**: +- `[design]` - Results from pre_analysis steps +- `[parent]` - Context inherited from parent tasks +- `[context]` - Dependencies from related tasks +- `[inherited]` - Shared context from session +- `[shared]` - Global rules and patterns **Content Sources**: - Task summaries: `.workflow/WFS-[session]/.summaries/` @@ -157,6 +222,7 @@ Flow_control design should follow these principles: - ✅ **Correct (Function-based)**: `IMPL-001: User authentication system` (models + routes + components + middleware + tests) - ❌ **Wrong (File/step-based)**: `IMPL-001: Create database model`, `IMPL-002: Create API endpoint` + ## Document Generation **Workflow**: Identifier Creation → Folder Structure → IMPL_PLAN.md → .task/IMPL-NNN.json → TODO_LIST.md diff --git a/.claude/workflows/mcp-tool-strategy.md b/.claude/workflows/mcp-tool-strategy.md new file mode 100644 index 00000000..3b41b681 --- /dev/null +++ b/.claude/workflows/mcp-tool-strategy.md @@ -0,0 +1,168 @@ +# MCP Tool Strategy: Triggers & Workflows + +## ⚡ Triggering Mechanisms + +**Auto-Trigger Scenarios**: +- 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**: +- 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操作后) + +## 📊 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" && ~/.claude/scripts/gemini-wrapper -p " +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 + +### 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" && ~/.claude/scripts/gemini-wrapper -p "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" && ~/.claude/scripts/gemini-wrapper -p "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 diff --git a/CLAUDE.md b/CLAUDE.md index f2059258..fd2f607a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,7 @@ This document defines project-specific coding standards and development principl For all CLI tool usage, command syntax, and integration guidelines: - **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md - **Context Search Commands**: @~/.claude/workflows/context-search-strategy.md +- **MCP Tool Strategy**: @~/.claude/workflows/mcp-tool-strategy.md **Context Requirements**: - Identify 3+ existing similar patterns before implementation diff --git a/README_CN.md b/README_CN.md index be8beea6..53f8a7f1 100644 --- a/README_CN.md +++ b/README_CN.md @@ -25,6 +25,32 @@ - **✅ 计划验证系统**: 使用 Gemini/Codex 双重分析的执行前验证 (`/workflow:plan-verify`) - **🎯 JSON优先架构**: 具有原子会话管理的单一数据源 - **💡 头脑风暴产物**: 多视角规划与综合和结构化文档生成 +- **🚀 MCP 工具集成**: 通过模型上下文协议实现增强的代码库分析和外部上下文获取 + +### 🔧 MCP 工具增强 (NEW!) + +**通过 MCP (Model Context Protocol) 工具实现的高级代码库分析:** + +#### 必需的 MCP 服务器 +1. **Exa MCP Server** - 外部 API 模式和示例 + - 仓库: https://github.com/exa-labs/exa-mcp-server + - 功能: `mcp__exa__get_code_context_exa()` - 获取外部最佳实践 + +2. **Code Index MCP** - 内部代码库探索 + - 仓库: https://github.com/johnhuang316/code-index-mcp + - 功能: + - `mcp__code-index__find_files()` - 文件模式匹配 + - `mcp__code-index__search_code_advanced()` - 高级代码搜索 + +#### MCP 集成优势 +- **📊 更快分析**: 直接代码库索引 vs 手动文件搜索 +- **🌐 外部上下文**: 真实世界的 API 模式和实现示例 +- **🔍 模式识别**: 高级代码模式匹配和相似性检测 +- **📈 全面覆盖**: 内部代码探索和外部最佳实践查找 +- **⚡ 自动回退**: 如果 MCP 工具不可用，工作流使用传统 bash/CLI 工具 + +#### 安装和设置 +请安装这些 MCP 服务器以启用增强的代码库分析。工作流将在可用时自动使用它们。 --- @@ -509,6 +535,9 @@ cd src/api && /update-memory-related - **🔮 Qwen CLI**: 架构分析和代码生成必需 - **📂 Git仓库**: 变更跟踪和版本控制必需 - **🎯 Claude Code IDE**: 推荐用于最佳体验 +- **🔧 MCP 服务器**: 推荐用于增强代码库分析 + - **Exa MCP Server**: 外部 API 模式和最佳实践获取 + - **Code Index MCP**: 高级内部代码库搜索和索引 ## 配置