CodeCompass MCP

# CodeCompass MCP Usage Examples This document provides practical examples of how to use the CodeCompass MCP server's 18 tools. ## 🔍 Core Data Tools ### 1. Repository Analysis ```javascript // Basic repository analysis { "tool": "fetch_repository_data", "arguments": { "url": "https://github.com/facebook/react", "options": { "include_structure": true, "include_dependencies": true, "include_key_files": true, "max_files": 50 } } } // For large repositories, control response size { "tool": "fetch_repository_data", "arguments": { "url": "https://github.com/facebook/react", "options": { "include_structure": true, "include_dependencies": true, "include_key_files": true, "max_files": 30, "max_response_tokens": 15000, "max_file_content_length": 500 } } } // For large repositories, use chunking (recommended) { "tool": "fetch_repository_data", "arguments": { "url": "https://github.com/facebook/react", "options": { "chunk_mode": true, "chunk_index": 0, "chunk_size": "medium" } } } // Get next chunk { "tool": "fetch_repository_data", "arguments": { "url": "https://github.com/facebook/react", "options": { "chunk_mode": true, "chunk_index": 1, "chunk_size": "medium" } } } // Expected response (regular mode): { "success": true, "data": { "info": { "name": "react", "description": "The library for web and native user interfaces", "language": "JavaScript", "stars": 220000, "forks": 45000 }, "structure": { "fileCount": 850, "lineCount": 125000, "keyFiles": { "package.json": "...", "README.md": "..." } }, "dependencies": { "production": 5, "development": 45 } } } // Expected response (chunked mode): { "success": true, "data": { "info": { /* repository info */ }, "structure": { "fileCount": 850, "lineCount": 125000, "keyFiles": { "package.json": "...", "README.md": "...", "src/index.js": "..." // Only 20 files in this chunk } }, "dependencies": { /* dependency analysis */ }, "architecture": { /* architecture analysis */ }, "chunkInfo": { "chunkIndex": 0, "chunkSize": "medium", "totalFiles": 85, "totalChunks": 5, "filesInChunk": 20, "hasMore": true, "nextChunkIndex": 1 } } } ``` ### 2. Advanced Repository Search ```javascript // Search for React hooks { "tool": "search_repository", "arguments": { "url": "https://github.com/facebook/react", "query": "useState", "search_type": "function", "options": { "file_extensions": [".js", ".jsx", ".ts", ".tsx"], "include_context": true, "max_results": 20 } } } // Search with regex pattern { "tool": "search_repository", "arguments": { "url": "https://github.com/facebook/react", "query": "use[A-Z]\\w+", "search_type": "regex", "options": { "case_sensitive": false, "include_context": true } } } ``` ### 3. File Content Retrieval ```javascript // Basic file retrieval { "tool": "get_file_content", "arguments": { "url": "https://github.com/facebook/react", "file_paths": [ "package.json", "README.md", "packages/react/src/React.js" ], "options": { "max_size": 50000, "include_metadata": true } } } // Advanced batch processing with filtering { "tool": "get_file_content", "arguments": { "url": "https://github.com/facebook/react", "file_paths": [ "src/index.js", "src/components/Button.js", "src/utils/helpers.js", "test/Button.test.js" ], "options": { "max_concurrent": 10, "continue_on_error": true, "include_metadata": true, "file_extensions": [".js", ".jsx", ".ts", ".tsx"], "exclude_patterns": ["node_modules", "\\.test\\.", "\\.spec\\."] } } } // Expected response with rich metadata: { "success": true, "data": { "files": { "src/index.js": { "content": "import React from 'react'...", "metadata": { "name": "index.js", "extension": ".js", "size": 1024, "type": "text", "mimeType": "text/javascript", "language": "javascript", "lineCount": 42, "encoding": "utf8" }, "size": 1024, "truncated": false } }, "summary": { "total": 4, "successful": 3, "failed": 1, "fetchErrors": 0, "statistics": { "totalSize": 3072, "totalLines": 126, "languageDistribution": { "javascript": 3 }, "typeDistribution": { "text": 3 } } } } } ``` ### 4. Code Structure Analysis ```javascript // Analyze code structure { "tool": "analyze_code_structure", "arguments": { "url": "https://github.com/facebook/react", "options": { "include_functions": true, "include_classes": true, "include_complexity": true, "languages": ["javascript", "typescript"] } } } ``` ## 🤖 AI-Enhanced Tools ### 1. AI Code Review ```javascript // Comprehensive AI code review { "tool": "ai_code_review", "arguments": { "url": "https://github.com/your-username/your-repo", "review_focus": ["security", "performance", "maintainability"], "options": { "ai_model": "auto", "severity_threshold": "medium", "include_examples": true } } } // Review specific files { "tool": "ai_code_review", "arguments": { "url": "https://github.com/your-username/your-repo", "file_paths": ["src/auth.js", "src/api.js"], "review_focus": ["security"], "options": { "ai_model": "anthropic/claude-3.5-sonnet", "severity_threshold": "high" } } } ``` ### 2. AI Code Explanation ```javascript // Get overview explanation { "tool": "ai_explain_code", "arguments": { "url": "https://github.com/sindresorhus/is-online", "explanation_type": "overview", "options": { "ai_model": "auto", "target_audience": "intermediate", "include_examples": true, "include_diagrams": true } } } // Detailed architectural explanation { "tool": "ai_explain_code", "arguments": { "url": "https://github.com/facebook/react", "explanation_type": "architecture", "options": { "ai_model": "anthropic/claude-3-opus", "target_audience": "advanced", "focus_on_patterns": true } } } // Tutorial-style explanation { "tool": "ai_explain_code", "arguments": { "url": "https://github.com/simple-example/todo-app", "explanation_type": "tutorial", "options": { "target_audience": "beginner", "include_examples": true } } } ``` ### 3. AI Refactoring Suggestions ```javascript // Modernization suggestions { "tool": "ai_refactor_suggestions", "arguments": { "url": "https://github.com/legacy-app/old-codebase", "refactoring_goals": ["modernize", "performance", "maintainability"], "options": { "ai_model": "auto", "include_code_examples": true, "estimate_effort": true } } } // Framework migration suggestions { "tool": "ai_refactor_suggestions", "arguments": { "url": "https://github.com/jquery-app/legacy-frontend", "refactoring_goals": ["modernize"], "target_framework": "react", "options": { "ai_model": "anthropic/claude-3.5-sonnet", "priority_level": "high" } } } ``` ## 🔧 Code Transformation Tools ### 1. Code Transformation ```javascript // Modernize JavaScript code { "tool": "transform_code", "arguments": { "code": "var userName = 'John'; function greet() { return 'Hello ' + userName; }", "transformations": [ { "type": "modernize", "options": { "target_es_version": "ES2020" } } ], "language": "javascript", "options": { "preserve_comments": true, "validate_syntax": true } } } // Convert to TypeScript { "tool": "transform_code", "arguments": { "code": "function calculateTotal(items) { return items.reduce((sum, item) => sum + item.price, 0); }", "transformations": [ { "type": "modernize" } ], "language": "javascript", "target_language": "typescript" } } ``` ### 2. Component Extraction ```javascript // Extract React components { "tool": "extract_components", "arguments": { "url": "https://github.com/react-app/components", "extraction_types": ["components", "hooks", "utilities"], "options": { "min_reusability_score": 75, "framework": "react", "include_examples": true } } } // Extract utility functions { "tool": "extract_components", "arguments": { "url": "https://github.com/utils-library/helpers", "extraction_types": ["functions", "utilities"], "options": { "min_reusability_score": 60, "include_dependencies": true } } } ``` ### 3. Code Structure Adaptation ```javascript // Migrate to React from Vue { "tool": "adapt_code_structure", "arguments": { "url": "https://github.com/vue-app/frontend", "target_structure": { "framework": "react", "pattern": "mvc" }, "options": { "preserve_logic": true, "update_imports": true, "generate_config": true } } } // Restructure for microservices { "tool": "adapt_code_structure", "arguments": { "url": "https://github.com/monolith-app/backend", "target_structure": { "pattern": "microservices", "folder_structure": { "services/": "Individual service modules", "shared/": "Shared utilities and types", "gateway/": "API gateway configuration" } } } } ``` ## 📊 Analysis Tools ### 1. Architecture Analysis ```javascript // Analyze architectural patterns { "tool": "analyze_architecture", "arguments": { "url": "https://github.com/enterprise-app/backend", "options": { "pattern_types": ["mvc", "clean", "hexagonal"], "include_frameworks": true, "confidence_threshold": 0.8 } } } ``` ### 2. Implementation Comparison ```javascript // Compare different implementations { "tool": "compare_implementations", "arguments": { "implementations": [ { "name": "React Implementation", "url": "https://github.com/team-a/react-solution", "focus_areas": ["performance", "maintainability"] }, { "name": "Vue Implementation", "url": "https://github.com/team-b/vue-solution", "focus_areas": ["performance", "maintainability"] } ], "comparison_criteria": ["performance", "maintainability", "security", "complexity"], "options": { "include_metrics": true, "include_recommendations": true } } } ``` ### 3. Code Quality Validation ```javascript // Comprehensive quality check { "tool": "validate_code_quality", "arguments": { "url": "https://github.com/production-app/codebase", "validation_types": ["security", "performance", "best-practices"], "options": { "severity_level": "medium", "include_fixes": true, "framework_specific": true } } } ``` ## 🔄 Utility Tools ### 1. Batch Processing ```javascript // Process multiple operations { "tool": "batch_process", "arguments": { "operations": [ { "id": "health", "tool": "health_check", "params": { "checks": ["api-limits", "system-health"] }, "priority": 1 }, { "id": "analyze", "tool": "analyze_code_structure", "params": { "url": "https://github.com/example/repo" }, "priority": 2 }, { "id": "metrics", "tool": "calculate_metrics", "params": { "url": "https://github.com/example/repo" }, "priority": 3 } ], "options": { "max_concurrent": 2, "fail_fast": false } } } ``` ### 2. Health Check ```javascript // Basic health check { "tool": "health_check", "arguments": { "checks": ["api-limits", "system-health"], "options": { "include_metrics": true } } } // Comprehensive health check { "tool": "health_check", "arguments": { "checks": ["api-limits", "cache-status", "system-health", "dependencies"], "options": { "include_metrics": true, "include_diagnostics": true } } } ``` ## 📈 Quality Metrics ### 1. Calculate Metrics ```javascript // Basic quality metrics { "tool": "calculate_metrics", "arguments": { "url": "https://github.com/example/repo", "options": { "metrics": ["complexity", "maintainability", "security"], "include_file_level": true } } } // Comprehensive metrics with trends { "tool": "calculate_metrics", "arguments": { "url": "https://github.com/example/repo", "options": { "metrics": ["complexity", "maintainability", "duplication", "security"], "include_file_level": true, "include_trend_analysis": true } } } ``` ### 2. Dependency Analysis ```javascript // Security-focused dependency analysis { "tool": "analyze_dependencies", "arguments": { "url": "https://github.com/production-app/backend", "options": { "include_security_scan": true, "include_version_analysis": true, "check_outdated": true } } } ``` ## 🔄 Workflow Examples ### 1. Complete Repository Analysis ```javascript // Step 1: Get repository overview { "tool": "fetch_repository_data", "arguments": { "url": "https://github.com/new-project/analysis-target" } } // Step 2: Analyze code structure { "tool": "analyze_code_structure", "arguments": { "url": "https://github.com/new-project/analysis-target", "options": { "include_complexity": true } } } // Step 3: Check dependencies { "tool": "analyze_dependencies", "arguments": { "url": "https://github.com/new-project/analysis-target", "options": { "include_security_scan": true } } } // Step 4: Get AI insights { "tool": "ai_explain_code", "arguments": { "url": "https://github.com/new-project/analysis-target", "explanation_type": "overview", "options": { "ai_model": "auto" } } } ``` ### 2. Code Review Workflow ```javascript // Step 1: Quality validation { "tool": "validate_code_quality", "arguments": { "url": "https://github.com/team/pull-request-branch", "validation_types": ["security", "performance", "best-practices"] } } // Step 2: AI code review { "tool": "ai_code_review", "arguments": { "url": "https://github.com/team/pull-request-branch", "review_focus": ["security", "performance", "maintainability"], "options": { "ai_model": "anthropic/claude-3.5-sonnet", "severity_threshold": "medium" } } } // Step 3: Calculate metrics { "tool": "calculate_metrics", "arguments": { "url": "https://github.com/team/pull-request-branch", "options": { "metrics": ["complexity", "maintainability"] } } } ``` ### 3. Refactoring Planning ```javascript // Step 1: Analyze current architecture { "tool": "analyze_architecture", "arguments": { "url": "https://github.com/legacy-app/monolith" } } // Step 2: Get AI refactoring suggestions { "tool": "ai_refactor_suggestions", "arguments": { "url": "https://github.com/legacy-app/monolith", "refactoring_goals": ["modernize", "performance", "maintainability"], "options": { "ai_model": "auto", "estimate_effort": true } } } // Step 3: Plan structure adaptation { "tool": "adapt_code_structure", "arguments": { "url": "https://github.com/legacy-app/monolith", "target_structure": { "framework": "react", "pattern": "clean" } } } ``` ## 🎯 Best Practices ### 1. Model Selection ```javascript // Use auto for most cases { "options": { "ai_model": "auto" } } // Use specific models for specialized tasks { "options": { "ai_model": "anthropic/claude-3-opus" // For complex analysis } } // Cost-effective for batch operations { "options": { "ai_model": "openai/gpt-4o-mini" // For large-scale processing } } ``` ### 2. Rate Limit Management ```javascript // Check limits before large operations { "tool": "health_check", "arguments": { "checks": ["api-limits"] } } // Use batch processing for multiple operations { "tool": "batch_process", "arguments": { "operations": [/* multiple operations */], "options": { "max_concurrent": 2 // Respect rate limits } } } ``` ### 3. Chunking Best Practices ```javascript // Function to process all chunks async function processRepositoryInChunks(url, chunkSize = 'medium') { let chunkIndex = 0; let hasMore = true; const allFiles = {}; while (hasMore) { const response = await callTool('fetch_repository_data', { url, options: { chunk_mode: true, chunk_index: chunkIndex, chunk_size: chunkSize } }); if (response.success) { // Merge files from this chunk Object.assign(allFiles, response.data.structure.keyFiles); // Check if there are more chunks hasMore = response.data.chunkInfo.hasMore; chunkIndex = response.data.chunkInfo.nextChunkIndex; } else { break; } } return allFiles; } // Usage const allFiles = await processRepositoryInChunks('https://github.com/facebook/react'); ``` ### 4. Error Handling ```javascript // Always check response success const response = await callTool('fetch_repository_data', params); if (!response.success) { console.error('Tool failed:', response.error); // Handle error appropriately } ``` This comprehensive guide covers the main usage patterns for all 18 tools in the CodeCompass MCP server. Each example includes realistic parameters and expected response formats to help you get started quickly.