Smart Code Search MCP Server

# SCS-MCP API Reference Complete documentation of all Model Context Protocol (MCP) tools available in SCS-MCP. ## Table of Contents - [Core Search Tools](#core-search-tools) - [Code Analysis Tools](#code-analysis-tools) - [Git History Tools](#git-history-tools) - [Code Quality Tools](#code-quality-tools) - [Model Information Tools](#model-information-tools) - [Orchestration Tools](#orchestration-tools) --- ## Core Search Tools ### 1. search **Purpose**: Semantic code search using embeddings and keyword matching **Parameters**: - `query` (string, required): Search query text - `limit` (integer, optional): Maximum results to return (default: 10) - `threshold` (float, optional): Minimum similarity score (0-1, default: 0.3) - `file_pattern` (string, optional): Filter by file pattern (e.g., "*.py") **Example**: ```json { "query": "authentication middleware", "limit": 5, "file_pattern": "*.py" } ``` **Response**: Array of search results with code snippets, file paths, and similarity scores --- ### 2. find_similar **Purpose**: Find code similar to a given snippet **Parameters**: - `code` (string, required): Code snippet to find similar code for - `limit` (integer, optional): Maximum results (default: 5) - `threshold` (float, optional): Similarity threshold (default: 0.5) **Example**: ```json { "code": "def authenticate(username, password):\n # Check credentials", "limit": 3 } ``` --- ### 3. analyze_symbol **Purpose**: Deep analysis of a specific symbol (function, class, variable) **Parameters**: - `symbol_name` (string, required): Name of the symbol to analyze - `include_usages` (boolean, optional): Include usage locations (default: false) - `include_tests` (boolean, optional): Include related tests (default: false) **Example**: ```json { "symbol_name": "UserAuthentication", "include_usages": true, "include_tests": true } ``` --- ## Code Analysis Tools ### 4. get_file_summary **Purpose**: Generate a comprehensive summary of a file **Parameters**: - `file_path` (string, required): Path to the file - `include_metrics` (boolean, optional): Include code metrics (default: true) **Response**: File overview with structure, dependencies, and metrics --- ### 5. get_project_structure **Purpose**: Analyze and return project directory structure **Parameters**: - `max_depth` (integer, optional): Maximum directory depth (default: 3) - `include_hidden` (boolean, optional): Include hidden files/dirs (default: false) --- ### 6. find_dependencies **Purpose**: Find all dependencies of a file or symbol **Parameters**: - `file_path` (string, optional): File to analyze - `symbol_name` (string, optional): Symbol to track dependencies for - `recursive` (boolean, optional): Follow dependency chain (default: true) --- ### 7. find_dependents **Purpose**: Find all files/symbols that depend on given file/symbol **Parameters**: - `file_path` (string, optional): File to find dependents of - `symbol_name` (string, optional): Symbol to find dependents of --- ### 8. analyze_imports **Purpose**: Analyze import statements and dependencies **Parameters**: - `file_path` (string, optional): Specific file to analyze - `check_circular` (boolean, optional): Check for circular imports (default: true) --- ## Git History Tools ### 9. git_search_history **Purpose**: Search through git commit history **Parameters**: - `query` (string, required): Search query - `limit` (integer, optional): Max commits to search (default: 100) - `path` (string, optional): Filter by file path - `author` (string, optional): Filter by author **Example**: ```json { "query": "bug fix authentication", "limit": 20, "author": "john.doe" } ``` --- ### 10. git_analyze_changes **Purpose**: Analyze code changes in recent commits **Parameters**: - `file_path` (string, optional): Specific file to analyze - `days` (integer, optional): Number of days to look back (default: 30) - `include_stats` (boolean, optional): Include change statistics (default: true) --- ### 11. git_find_related_commits **Purpose**: Find commits related to specific code or issue **Parameters**: - `reference` (string, required): Code snippet, issue number, or keyword - `limit` (integer, optional): Maximum commits (default: 10) --- ## Code Quality Tools ### 12. instant_review **Purpose**: Quick code review with best practices check **Parameters**: - `code` (string, required): Code to review - `language` (string, optional): Programming language - `context` (string, optional): Additional context **Response**: Review with issues, suggestions, and severity ratings --- ### 13. test_gap_analyzer **Purpose**: Identify missing test coverage **Parameters**: - `file_path` (string, optional): File to analyze - `include_suggestions` (boolean, optional): Generate test suggestions (default: true) --- ### 14. complexity_analyzer **Purpose**: Analyze code complexity metrics **Parameters**: - `file_path` (string, optional): Specific file - `threshold` (integer, optional): Complexity threshold for warnings (default: 10) **Response**: Cyclomatic complexity, cognitive complexity, and maintainability index --- ### 15. find_code_patterns **Purpose**: Detect common patterns and anti-patterns **Parameters**: - `pattern_type` (string, optional): Type of pattern to find ("design", "anti", "all") - `file_path` (string, optional): Specific file to analyze --- ### 16. security_analyzer **Purpose**: Basic security vulnerability scanning **Parameters**: - `file_path` (string, optional): File to scan - `scan_type` (string, optional): Type of scan ("basic", "deep") --- ## Model Information Tools ### 17. get_available_models **Purpose**: List all available AI models and their capabilities **Parameters**: None **Response**: Dictionary of models by provider with specifications --- ### 18. compare_models **Purpose**: Compare capabilities of different models **Parameters**: - `models` (array, optional): List of model IDs to compare - `use_case` (string, optional): Specific use case for comparison --- ### 19. suggest_model_for_task **Purpose**: Recommend best model for a specific task **Parameters**: - `task_type` (string, required): Type of task ("code_review", "generation", "analysis", etc.) - `requirements` (object, optional): Specific requirements (speed, accuracy, cost) --- ### 20. get_current_model_status **Purpose**: Get current model information and capabilities **Parameters**: None **Response**: Current model details, context window, supported features --- ### 21. estimate_operation_cost **Purpose**: Estimate token usage and cost for an operation **Parameters**: - `operation` (string, required): Operation type - `input_size` (integer, required): Estimated input tokens - `output_size` (integer, optional): Estimated output tokens --- ## Graph Visualization Tools ### 13. generate_dependency_graph **Purpose**: Generate dependency graphs in text-based formats for visualization **Parameters**: - `output_format` (string, optional): Output format - "dot" (Graphviz), "mermaid" (GitHub/GitLab), or "json" (default: "mermaid") - `graph_type` (string, optional): Type of graph - "imports", "calls", or "inheritance" (default: "imports") - `file_pattern` (string, optional): File pattern to analyze (default: "*.py") - `detect_cycles` (boolean, optional): Detect and report circular dependencies (default: false) **Example**: ```json { "output_format": "mermaid", "graph_type": "imports", "file_pattern": "src/**/*.py", "detect_cycles": true } ``` **Response**: Graph in the requested format with optional circular dependency detection **Output Formats**: - **DOT**: Can be rendered with Graphviz tools or online viewers - **Mermaid**: Renders directly in GitHub/GitLab markdown - **JSON**: Structured data for custom visualization tools --- ## Orchestration Tools ### 22. debt_orchestrator **Purpose**: Comprehensive technical debt analysis **Parameters**: - `scope` (string, optional): Analysis scope ("file", "directory", "project") - `threshold` (string, optional): Severity threshold ("low", "medium", "high") **Response**: Categorized technical debt with remediation priorities --- ### 23. refactor_orchestrator **Purpose**: Coordinate complex refactoring operations **Parameters**: - `target` (string, required): Target for refactoring - `refactor_type` (string, required): Type of refactoring - `preview` (boolean, optional): Preview changes without applying (default: true) --- ### 24. migration_orchestrator **Purpose**: Plan and execute code migrations **Parameters**: - `from_pattern` (string, required): Pattern to migrate from - `to_pattern` (string, required): Pattern to migrate to - `scope` (string, optional): Migration scope --- ### 25. documentation_orchestrator **Purpose**: Generate and update documentation **Parameters**: - `target` (string, optional): Target for documentation - `doc_type` (string, optional): Type of documentation ("api", "readme", "inline") - `format` (string, optional): Output format ("markdown", "html", "rst") --- ### 26. testing_orchestrator **Purpose**: Coordinate test generation and execution **Parameters**: - `target` (string, required): Target for testing - `test_type` (string, optional): Type of tests ("unit", "integration", "all") - `framework` (string, optional): Test framework to use --- ### 27. performance_orchestrator **Purpose**: Analyze and optimize performance **Parameters**: - `target` (string, optional): Target for optimization - `metrics` (array, optional): Specific metrics to analyze - `suggest_fixes` (boolean, optional): Generate optimization suggestions (default: true) --- ### 28. dependency_orchestrator **Purpose**: Manage and analyze dependencies **Parameters**: - `action` (string, required): Action to perform ("analyze", "update", "clean") - `scope` (string, optional): Scope of operation --- ### 29. quality_orchestrator **Purpose**: Comprehensive code quality assessment **Parameters**: - `standards` (array, optional): Quality standards to check against - `auto_fix` (boolean, optional): Attempt automatic fixes (default: false) --- ### 30. import_optimizer **Purpose**: Optimize and organize import statements **Parameters**: - `file_path` (string, optional): File to optimize - `style` (string, optional): Import style ("grouped", "alphabetical", "length") --- ## Error Handling All tools return errors in a consistent format: ```json { "error": { "code": "ERROR_CODE", "message": "Human-readable error message", "details": {} } } ``` Common error codes: - `FILE_NOT_FOUND`: Specified file doesn't exist - `INVALID_PARAMS`: Invalid or missing parameters - `INDEX_ERROR`: Search index not available - `GIT_ERROR`: Git operation failed - `PARSE_ERROR`: Code parsing failed ## Rate Limiting The MCP server implements rate limiting for resource-intensive operations: - Search operations: 100 requests/minute - Analysis operations: 50 requests/minute - Orchestration operations: 10 requests/minute ## Best Practices 1. **Use specific queries**: More specific search queries yield better results 2. **Set appropriate limits**: Don't request more results than needed 3. **Cache results**: The server caches recent searches for 5 minutes 4. **Batch operations**: Use orchestrator tools for multiple related operations 5. **Check capabilities first**: Use model info tools before requesting complex operations ## Examples ### Complete Code Review Workflow ```python # 1. Get file summary summary = await mcp.call_tool("get_file_summary", { "file_path": "src/auth/login.py" }) # 2. Run instant review review = await mcp.call_tool("instant_review", { "code": file_content, "language": "python" }) # 3. Check test coverage tests = await mcp.call_tool("test_gap_analyzer", { "file_path": "src/auth/login.py" }) # 4. Analyze complexity complexity = await mcp.call_tool("complexity_analyzer", { "file_path": "src/auth/login.py" }) ``` ### Find and Fix Technical Debt ```python # 1. Identify debt debt = await mcp.call_tool("debt_orchestrator", { "scope": "project", "threshold": "medium" }) # 2. Get refactoring suggestions refactor = await mcp.call_tool("refactor_orchestrator", { "target": debt["high_priority_items"][0], "refactor_type": "extract_method", "preview": true }) ``` ## Support For issues or questions about the API: - GitHub Issues: [https://github.com/yourusername/scs-mcp/issues](https://github.com/yourusername/scs-mcp/issues) - Documentation: [https://scs-mcp.readthedocs.io](https://scs-mcp.readthedocs.io)