diff --git a/ce_mcp/server.py b/ce_mcp/server.py index 77808e6..2c95fa6 100644 --- a/ce_mcp/server.py +++ b/ce_mcp/server.py @@ -41,71 +41,25 @@ async def compile_check_tool( create_binary: bool = False, create_object_only: bool = False, ) -> str: - """Quick compilation validation - checks if code compiles without verbose output. - - This tool provides fast syntax and compilation validation without executing code - or returning detailed output. Perfect for CI checks, syntax validation, and - quick error detection. - - **Use Cases:** - - **Syntax validation**: Check if code compiles before detailed analysis - - **CI pipeline checks**: Fast validation in automated builds - - **Code review**: Quick verification that proposed changes compile - - **Learning**: Test code snippets while learning new language features - - **Bulk validation**: Check multiple code samples efficiently - - **Parameters:** - - source: Source code to compile (minimal comments preferred) - - language: Programming language (c++, c, rust, go, python, etc.) - - compiler: Compiler identifier (e.g., "g132", "clang1600") or friendly name - - options: Compiler flags (e.g., "-O2 -Wall", "-std=c++20") - - extract_args: If True, extracts compiler flags from source comments like "// flags: -Wall" - - libraries: List of libraries with format [{"id": "library_name", "version": "latest"}] - - create_binary: If True, creates a full executable binary (enables binary analysis tools like ldd) - - create_object_only: If True, creates object file without linking (for code without main function) - - **Returns JSON with:** - - success: Boolean indicating if compilation succeeded - - exit_code: Compiler exit code (0 = success) - - error_count: Number of compilation errors found - - warning_count: Number of warnings generated - - first_error: Text of the first error encountered (if any) - - **Example Tool Calls:** - - Quick C++ syntax check: - ``` - compile_check_tool({ - "source": "int main() { return 0; }", - "language": "c++", - "compiler": "g132" - }) - ``` - - Check with specific compiler flags: - ``` - compile_check_tool({ - "source": "#include \\nint main() { std::cout << \\"Hello\\"; }", - "language": "c++", - "compiler": "g132", - "options": "-std=c++20 -Wall" - }) - ``` - - Use flags from source comments: - ``` - compile_check_tool({ - "source": "// flags: -std=c++17 -O2\\nint main() { return 0; }", - "language": "c++", - "compiler": "clang1600", - "extract_args": true - }) - ``` - - **When to use vs other tools:** - - Use compile_check_tool for fast validation without execution - - Use compile_and_run_tool when you need to see program output - - Use compile_with_diagnostics_tool for detailed error analysis + """Check if code compiles without executing it. + + Fast syntax validation for CI checks, code review, and debugging. + + Args: + source: Source code to compile + language: Programming language (c++, c, rust, go, python, etc.) + compiler: Compiler ID (e.g., "g132", "clang1600") or friendly name + options: Compiler flags (e.g., "-O2 -Wall", "-std=c++20") + extract_args: Extract flags from source comments like "// flags: -Wall" + libraries: Libraries list [{"id": "name", "version": "latest"}] + create_binary: Create full executable binary + create_object_only: Create object file without linking + + Returns: {success, exit_code, error_count, warning_count, first_error} + + Example: compile_check_tool(source="int main(){return 0;}", language="c++", compiler="g132") + + Use for fast validation without execution. Use compile_and_run_tool when you need program output. """ result = await compile_check( { @@ -137,87 +91,28 @@ async def compile_and_run_tool( create_binary: bool = False, create_object_only: bool = False, ) -> str: - """Compile and run code, returning execution results and program output. - - This tool compiles source code and executes the resulting program, capturing - stdout, stderr, exit codes, and execution time. Perfect for testing algorithms, - debugging programs, and validating program behavior. - - **Use Cases:** - - **Testing programs**: Verify that code produces expected output - - **Algorithm validation**: Test implementations with sample inputs - - **Debugging**: See actual program behavior and error messages - - **Performance measurement**: Check execution time for simple benchmarks - - **Learning**: Run example code to understand language features - - **Integration testing**: Test programs with different inputs and arguments - - **Parameters:** - - source: Source code to compile and execute (minimal comments preferred) - - language: Programming language (c++, c, rust, go, python, etc.) - - compiler: Compiler identifier (e.g., "g132", "clang1600") or friendly name - - options: Compiler flags (e.g., "-O2 -Wall", "-std=c++20") - - stdin: Standard input to provide to the program during execution - - args: Command line arguments passed to the program (list of strings) - - timeout: Maximum execution time in milliseconds (default: 5000ms) - - libraries: List of libraries with format [{"id": "library_name", "version": "latest"}] - - create_binary: If True, creates a full executable binary (enables binary analysis tools like ldd) - - create_object_only: If True, creates object file without linking (for code without main function) - - **Returns JSON with:** - - compiled: Boolean indicating if compilation succeeded - - executed: Boolean indicating if the program ran - - exit_code: Program exit code (0 typically means success) - - execution_time_ms: How long the program took to run - - stdout: Program's standard output - - stderr: Program's error output - - truncated: Boolean indicating if output was truncated due to length - - **Example Tool Calls:** - - Simple program execution: - ``` - compile_and_run_tool({ - "source": "#include \\nint main() { std::cout << \\"Hello World\\"; return 0; }", - "language": "c++", - "compiler": "g132" - }) - ``` - - Program with command line arguments: - ``` - compile_and_run_tool({ - "source": "#include \\nint main(int argc, char* argv[]) { std::cout << argv[1]; }", - "language": "c++", - "compiler": "g132", - "args": ["test_argument"] - }) - ``` - - Program with stdin input: - ``` - compile_and_run_tool({ - "source": "#include \\nint main() { int x; std::cin >> x; std::cout << x*2; }", - "language": "c++", - "compiler": "g132", - "stdin": "42" - }) - ``` - - With timeout for long-running programs: - ``` - compile_and_run_tool({ - "source": "while True: pass", - "language": "python", - "compiler": "python311", - "timeout": 1000 - }) - ``` - - **When to use vs other tools:** - - Use compile_and_run_tool when you need to see program output - - Use compile_check_tool for fast validation without execution - - Use analyze_optimization_tool to examine generated assembly - - Use compare_compilers_tool to compare execution across different compilers + """Compile and execute code, capturing output and execution results. + + Test algorithms, debug programs, validate behavior with different inputs. + + Args: + source: Source code to compile and run + language: Programming language (c++, c, rust, go, python, etc.) + compiler: Compiler ID (e.g., "g132", "clang1600") or friendly name + options: Compiler flags (e.g., "-O2 -Wall", "-std=c++20") + stdin: Standard input for the program + args: Command line arguments (list of strings) + timeout: Max execution time in ms (default: 5000) + libraries: Libraries list [{"id": "name", "version": "latest"}] + tools: Additional tools to run [{"id": "tool_name", "args": []}] + create_binary: Create full executable binary + create_object_only: Create object file without linking + + Returns: {compiled, executed, exit_code, execution_time_ms, stdout, stderr, truncated} + + Example: compile_and_run_tool(source="#include \nint main(){std::cout<<\"Hi\";}", language="c++", compiler="g132") + + Use when you need program output. Use compile_check_tool for fast validation only. """ if args is None: args = [] @@ -252,92 +147,24 @@ async def compile_with_diagnostics_tool( create_binary: bool = False, create_object_only: bool = False, ) -> str: - """Get comprehensive compilation warnings and errors with detailed analysis. - - This tool provides detailed compilation diagnostics including warnings, errors, - line numbers, and compiler suggestions. Perfect for code analysis, debugging - compilation issues, and learning about compiler warnings. - - **Use Cases:** - - **Code analysis**: Get detailed warnings and suggestions for code improvement - - **Debugging compilation issues**: Understand why code fails to compile - - **Learning**: See what compiler warnings teach about language best practices - - **Code review**: Identify potential issues before code integration - - **Static analysis**: Find potential bugs through compiler diagnostics - - **Standard compliance**: Check code against language standards - - **Parameters:** - - source: Source code to analyze for compilation issues (minimal comments preferred) - - language: Programming language (c++, c, rust, go, etc.) - - compiler: Compiler identifier (e.g., "g132", "clang1600") or friendly name - - options: Additional compiler flags (e.g., "-std=c++20", "-march=native") - - diagnostic_level: Controls verbosity of diagnostics: - - "normal": Standard warnings with -Wall - - "verbose": Comprehensive warnings with -Wall -Wextra -Wpedantic - - libraries: List of libraries with format [{"id": "library_name", "version": "latest"}] - - tools: List of tools to run alongside compilation (e.g., [{"id": "iwyu022", "args": []}]) - - create_binary: If True, creates a full executable binary (enables binary analysis tools like ldd) - - create_object_only: If True, creates object file without linking (for code without main function) - - **Returns JSON with:** - - success: Boolean indicating if compilation succeeded - - diagnostics: Array of diagnostic messages with details: - - type: "error", "warning", "note", etc. - - line: Line number where issue occurs - - column: Column number (if available) - - message: Human-readable diagnostic message - - suggestion: Compiler suggestion for fixing the issue (if available) - - command: The exact compiler command that was executed - - **Example Tool Calls:** - - Basic diagnostic analysis: - ``` - compile_with_diagnostics_tool({ - "source": "int main() { int unused_var; return 0; }", - "language": "c++", - "compiler": "g132", - "diagnostic_level": "normal" - }) - ``` - - Verbose diagnostics for thorough analysis: - ``` - compile_with_diagnostics_tool({ - "source": "void func(int* p) { delete p; }\\nint main() { int x; func(&x); }", - "language": "c++", - "compiler": "clang1600", - "diagnostic_level": "verbose" - }) - ``` - - Check modern C++ standard compliance: - ``` - compile_with_diagnostics_tool({ - "source": "auto lambda = [=](auto x) { return x + 1; };", - "language": "c++", - "compiler": "g132", - "options": "-std=c++14", - "diagnostic_level": "verbose" - }) - ``` - - Analyze with specific warning flags: - ``` - compile_with_diagnostics_tool({ - "source": "#include \\nint main() { printf(\\"Hello\\"); }", - "language": "c++", - "compiler": "g132", - "options": "-Wformat-security -Wno-unused", - "diagnostic_level": "normal" - }) - ``` - - **When to use vs other tools:** - - Use compile_with_diagnostics_tool for detailed error analysis and code quality - - Use compile_check_tool for quick pass/fail validation - - Use compile_and_run_tool when you need to see program execution - - Use analyze_optimization_tool to examine generated assembly + """Get detailed compilation warnings and errors with line numbers. + + Code analysis, debugging compilation issues, static analysis. + + Args: + source: Source code to analyze + language: Programming language (c++, c, rust, go, etc.) + compiler: Compiler ID (e.g., "g132", "clang1600") or friendly name + options: Additional compiler flags (e.g., "-std=c++20") + diagnostic_level: "normal" (-Wall) or "verbose" (-Wall -Wextra -Wpedantic) + libraries: Libraries list [{"id": "name", "version": "latest"}] + tools: Additional tools [{"id": "tool_name", "args": []}] + create_binary: Create full executable binary + create_object_only: Create object file without linking + + Returns: {success, diagnostics: [{type, line, column, message, suggestion}], command} + + Use for detailed error analysis. Use compile_check_tool for quick pass/fail validation. """ result = await compile_with_diagnostics( { @@ -369,108 +196,30 @@ async def analyze_optimization_tool( do_demangle: bool | None = None, libraries: list | None = None, ) -> str: - """Analyze compiler optimizations and generated assembly code. - - This tool examines how compilers optimize code by providing the raw assembly output - for analysis. The LLM can interpret the assembly to detect optimizations like - vectorization, inlining, loop transformations, and other compiler optimizations. - Perfect for performance analysis and understanding how different code patterns - affect optimization across different architectures. - - **Use Cases:** - - **Performance investigation**: Understand why code is fast or slow - - **Optimization validation**: Verify that compilers apply expected optimizations - - **Learning**: See how different coding patterns affect compiler behavior - - **Code review**: Check if performance-critical code optimizes well - - **Benchmarking**: Compare optimization effectiveness across compilers - - **Algorithm analysis**: See how different implementations optimize - - **Parameters:** - - source: Source code to analyze for optimizations (minimal comments preferred) - - language: Programming language (c++, c, rust, go, etc.) - - compiler: Compiler identifier (e.g., "g132", "clang1600") or friendly name - - optimization_level: Optimization flags (e.g., "-O0", "-O2", "-O3", "-Os", "-Ofast") - - analysis_type: Focus of analysis ("all", "vectorization", "inlining", "loops") - - include_optimization_remarks: Include compiler optimization remarks/passes in output - - filter_out_library_code: Hide standard library implementations for cleaner output - - filter_out_debug_calls: Hide debug and profiling function calls - - do_demangle: Convert mangled C++ symbols to readable names - - libraries: List of libraries with format [{"id": "library_name", "version": "latest"}] - - **Returns JSON with:** - - assembly_lines: Number of assembly lines generated - - instruction_count: Number of actual instructions (excluding comments/labels) - - assembly_output: Complete assembly output (filtered based on settings) - - truncated: Boolean indicating if assembly output was truncated - - total_instructions: Total instruction count including truncated lines - - optimization_remarks: List of compiler optimization remarks (if include_optimization_remarks=True) - - **Assembly Analysis Examples:** - - *Vectorization Detection:* - - x86: Look for SIMD instructions like `movdqu`, `paddd`, `vpaddd`, `vmovups` - - ARM: Look for NEON instructions like `ld1`, `add.4s`, `fmla.4s` - - RISC-V: Look for vector instructions like `vle32.v`, `vadd.vv` - - *Function Inlining:* - - Absence of `call`/`bl`/`jal` instructions for expected function calls - - Code expansion where function body appears inline - - *Loop Optimizations:* - - Unrolling: Repeated instruction patterns within loops - - Memcpy conversion: Calls to `memcpy`/`memmove` instead of explicit loops - - Strength reduction: Multiplication replaced by shifts/additions - - **Example Tool Calls:** - - Basic optimization analysis: - ``` - analyze_optimization_tool({ - "source": "void copy_array(int* dst, int* src, int n) { for(int i=0; i int power(int x) { return x * power(x); }", - "language": "c++", - "compiler": "g132", - "optimization_level": "-O2", - "filter_out_library_code": true, - "do_demangle": true - }) - ``` - - **When to use vs other tools:** - - Use analyze_optimization_tool to understand compiler optimizations and assembly - - Use compile_and_run_tool to test program behavior and performance - - Use compare_compilers_tool to compare optimization across different compilers - - Use compile_with_diagnostics_tool for code quality and warning analysis + """Analyze generated assembly code to understand compiler optimizations. + + Performance investigation, optimization validation, learning compiler behavior. + + Args: + source: Source code to analyze + language: Programming language (c++, c, rust, go, etc.) + compiler: Compiler ID (e.g., "g132", "clang1600") or friendly name + optimization_level: Optimization flags ("-O0", "-O2", "-O3", "-Os", "-Ofast") + analysis_type: Focus area ("all", "vectorization", "inlining", "loops") + include_optimization_remarks: Include compiler optimization passes + filter_out_library_code: Hide standard library implementations + filter_out_debug_calls: Hide debug/profiling function calls + do_demangle: Convert mangled C++ symbols to readable names + libraries: Libraries list [{"id": "name", "version": "latest"}] + + Returns: {assembly_lines, instruction_count, assembly_output, truncated, total_instructions, optimization_remarks} + + Assembly Analysis Patterns: + - Vectorization: Look for SIMD instructions (movdqu, vpaddd on x86; ld1, add.4s on ARM) + - Inlining: Absence of call/bl/jal instructions for expected function calls + - Loop optimizations: Unrolling patterns, memcpy conversion, strength reduction + + Use to understand compiler optimizations. Use compile_and_run_tool for performance testing. """ result = await analyze_optimization( { @@ -498,14 +247,18 @@ async def compare_compilers_tool( comparison_type: str, libraries: list | None = None, ) -> str: - """Compare output across different compilers/options. + """Compare compilation/execution results across multiple compilers. Args: source: Source code to compile - language: Programming language (e.g., 'c++', 'rust') - compilers: List of compiler configurations - comparison_type: Type of comparison (execution, assembly, diagnostics) - libraries: List of libraries with format [{"id": "library_name", "version": "latest"}] + language: Programming language (c++, rust, etc.) + compilers: List of compiler configurations [{"compiler": "id", "options": "flags"}] + comparison_type: "execution", "assembly", or "diagnostics" + libraries: Libraries list [{"id": "name", "version": "latest"}] + + Returns: Comparison results based on type (diffs for execution, side-by-side for assembly) + + Use to compare behavior across compilers. Use individual tools for single compiler analysis. """ result = await compare_compilers( { @@ -532,109 +285,24 @@ async def generate_share_url_tool( create_binary: bool = False, create_object_only: bool = False, ) -> str: - """Generate shareable Compiler Explorer URLs for collaboration and demonstration. - - This tool creates URLs that link directly to Compiler Explorer with your code, - compiler settings, and configuration pre-loaded. Perfect for sharing examples, - demonstrating issues, collaborating on code, and creating educational content. - - **Use Cases:** - - **Bug reports**: Share minimal reproducible examples with exact compiler settings - - **Code collaboration**: Send colleagues links to specific compiler configurations - - **Education**: Create examples for teaching compiler behavior or language features - - **Documentation**: Include live, interactive code examples in documentation - - **Performance discussions**: Share assembly output for performance analysis - - **Standard compliance**: Demonstrate how code behaves across different compiler versions - - **Parameters:** - - source: Source code to include in the shareable URL (minimal comments preferred) - - language: Programming language (c++, c, rust, go, python, etc.) - - compiler: Compiler identifier (e.g., "g132", "clang1600") or friendly name - - options: Compiler flags (e.g., "-O2 -Wall", "-std=c++20 -march=native") - - layout: Controls the Compiler Explorer interface layout: - - "simple": Clean, minimal interface - - "comparison": Side-by-side compiler comparison view - - "assembly": Focus on assembly output view - - libraries: List of libraries with format [{"id": "library_name", "version": "latest"}] - - tools: List of tools with format [{"id": "tool_name", "args": []}] - - create_binary: If True, creates a full executable binary (enables binary analysis tools like ldd) - - create_object_only: If True, creates object file without linking (for code without main function) - - **Returns JSON with:** - - url: Shareable Compiler Explorer URL with all settings pre-loaded - - **Example Tool Calls:** - - Simple code sharing: - ``` - generate_share_url_tool({ - "source": "#include \\nint main() { std::cout << \\"Hello World\\"; return 0; }", - "language": "c++", - "compiler": "g132", - "options": "-std=c++20" - }) - ``` - - Bug report with optimization flags: - ``` - generate_share_url_tool({ - "source": "volatile int x = 0;\\nint main() { return x++; }", - "language": "c++", - "compiler": "clang1600", - "options": "-O3 -ffast-math", - "layout": "assembly" - }) - ``` - - Educational example with comparison view: - ``` - generate_share_url_tool({ - "source": "auto lambda = [](auto x) { return x + 1; };", - "language": "c++", - "compiler": "g132", - "options": "-std=c++14", - "layout": "comparison" - }) - ``` - - Example with libraries: - ``` - generate_share_url_tool({ - "source": "#include \\nint main() { fmt::print(\\"Hello\\"); }", - "language": "c++", - "compiler": "g132", - "options": "-std=c++17", - "libraries": [{"id": "fmt", "version": "latest"}] - }) - ``` - - Example with tools: - ``` - generate_share_url_tool({ - "source": "int square(int n) { return n * n; }\\nint main() { return square(2); }", - "language": "c++", - "compiler": "g132", - "options": "-fvisibility=hidden", - "tools": [{"id": "readelf", "args": ["-s"]}] - }) - ``` - - Example with binary creation: - ``` - generate_share_url_tool({ - "source": "int main() { return 42; }", - "language": "c++", - "compiler": "g132", - "options": "-O2", - "create_binary": True - }) - ``` - - **When to use vs other tools:** - - Use generate_share_url_tool to create shareable links for collaboration - - Use compile_and_run_tool to test and validate code behavior first - - Use analyze_optimization_tool to understand assembly before sharing - - Use compare_compilers_tool to compare multiple configurations before sharing + """Generate shareable Compiler Explorer URL with code and settings. + + Create URLs for bug reports, collaboration, education, performance discussions. + + Args: + source: Source code to include + language: Programming language (c++, c, rust, go, python, etc.) + compiler: Compiler ID (e.g., "g132", "clang1600") or friendly name + options: Compiler flags (e.g., "-O2 -Wall", "-std=c++20") + layout: UI layout ("simple", "comparison", "assembly") + libraries: Libraries list [{"id": "name", "version": "latest"}] + tools: Tools list [{"id": "tool_name", "args": []}] + create_binary: Create full executable binary + create_object_only: Create object file without linking + + Returns: {url: shareable Compiler Explorer URL} + + Example: generate_share_url_tool(source="int main(){}", language="c++", compiler="g132", options="-std=c++20") """ result = await generate_share_url( { @@ -669,34 +337,24 @@ async def find_compilers_tool( ) -> str: """Find compilers with optional filtering by experimental features, proposals, or tools. - ⚠️ AVOID generic searches like 'gcc' or 'clang' - they exceed token limits (25k+). + ⚠️ CRITICAL: AVOID generic searches like 'gcc' or 'clang' - they exceed token limits (25k+). Use specific terms: 'gcc 13', 'x86-64 gcc', or exact compiler IDs with exact_search=True. Args: language: Programming language (default: c++) - proposal: Specific proposal number to search for (e.g., 'P3385', '3385') - feature: Experimental feature to search for (e.g., 'reflection', 'concepts', 'modules') - category: Category to filter by (e.g., 'proposals', 'reflection', 'concepts') + proposal: Specific proposal number (e.g., 'P3385', '3385') + feature: Experimental feature (e.g., 'reflection', 'concepts', 'modules') + category: Category filter (e.g., 'proposals', 'reflection', 'concepts') show_all: Show all experimental compilers organized by category - search_text: Filter compilers by text search in compiler names and IDs (should be compiler-related keywords like "gcc 13", "clang17", "msvc", "nightly") - exact_search: If True, search_text is treated as an exact compiler ID match (case-sensitive) - ids_only: Return only compiler IDs (use sparingly, only when search_text isn't sufficient) - include_overrides: Include possibleOverrides field for architecture discovery (increases output significantly) - include_runtime_tools: Include possibleRuntimeTools field for runtime tool discovery (increases output significantly) - include_compile_tools: Include tools field for compile-time tool discovery (increases output significantly; requires specific compiler ID in search_text) - - Examples: - - Find all C++ compilers: language="c++" - - Find GCC 13 compilers: search_text="gcc 13" - - Find MSVC compilers: search_text="msvc" - - Find P3385 proposal compilers: proposal="P3385" - - Find reflection feature compilers: feature="reflection" - - Find nightly/experimental compilers: search_text="nightly" - - Get only compiler IDs for MSVC (if needed): search_text="msvc", ids_only=True - - Get GCC with architecture overrides: search_text="gcc", include_overrides=True - - Get clang 17 with runtime tools: search_text="clang1701", include_runtime_tools=True - - Get GCC 13.2 with compile tools: search_text="g132", include_compile_tools=True - - Find exact compiler by ID: search_text="clang1600", exact_search=True + search_text: Filter by compiler names/IDs (use specific terms like "gcc 13", "clang17", "msvc") + exact_search: Treat search_text as exact compiler ID match (case-sensitive) + ids_only: Return only compiler IDs (use sparingly) + include_overrides: Include architecture discovery info (increases output significantly) + include_runtime_tools: Include runtime tool discovery (increases output significantly) + include_compile_tools: Include compile-time tool discovery (increases output significantly) + + Valid Examples: "gcc 13", "clang 17", "msvc", "nightly", "g132", "clang1600" + Invalid Examples: "gcc", "clang", "g++", "clang++" """ # Validate search_text to prevent overly broad searches that exceed token limits if search_text and not exact_search: @@ -746,11 +404,7 @@ async def get_libraries_tool( language: Programming language (default: c++) search_text: Filter libraries by text search in names and IDs (optional) - Examples: - - Get all C++ libraries: language="c++" - - Search for boost libraries: language="c++", search_text="boost" - - Search for format libraries: language="c++", search_text="fmt" - - Get Rust libraries: language="rust" + Returns simplified library list. Use get_library_details_tool for full library information. """ result = await get_libraries_list( { @@ -773,11 +427,7 @@ async def get_library_details_tool( language: Programming language (default: c++) library_id: The ID of the library to get details for (required) - Examples: - - Get boost details: language="c++", library_id="boost" - - Get fmt details: language="c++", library_id="fmt" - - Get range-v3 details: language="c++", library_id="range-v3" - - Get Rust crate details: language="rust", library_id="serde" + Returns: Complete library information including all available versions and usage details. """ result = await get_library_details_info( { @@ -798,11 +448,7 @@ async def get_languages_tool( Args: search_text: Filter languages by text search in names and IDs (optional) - Examples: - - Get all languages: (no arguments) - - Search for C languages: search_text="c" - - Search for JavaScript/TypeScript: search_text="script" - - Search for Python: search_text="python" + Returns: Simplified language list for discovery. Use specific language names in other tools. """ result = await get_languages_list( { @@ -819,84 +465,22 @@ async def lookup_instruction_tool( opcode: str, format_output: bool = True, ) -> str: - """Get detailed documentation for assembly instructions/opcodes. - - This tool provides comprehensive documentation for assembly instructions across - multiple architectures. Perfect for understanding instruction behavior, syntax, - and usage during assembly analysis or debugging. - - **Use Cases:** - - **Assembly analysis**: Understand what specific instructions do - - **Debugging**: Quick reference for instruction behavior - - **Learning**: Explore instruction sets and their capabilities - - **Code review**: Verify instruction usage and semantics - - **Parameters:** - - instruction_set: Architecture/instruction set name - - x86/x86-64: "amd64", "x86", "x86_64", "x64", "intel" - - ARM: "aarch64", "arm64", "armv8", "arm" - - Others: "mips", "riscv", "powerpc" (if supported) - - opcode: Instruction/opcode to look up (e.g., "pop", "stp", "mov", "add") - - format_output: Format for readability (true) vs raw JSON (false) - - **Returns JSON with:** - - found: Boolean indicating if instruction was found - - instruction_set: Resolved instruction set name - - opcode: The looked up instruction - - documentation: Raw instruction documentation from Compiler Explorer - - formatted_docs: Human-readable formatted documentation (if format_output=true) - - error: Error message if lookup failed - - **Example Tool Calls:** - - Look up x86-64 POP instruction: - ``` - lookup_instruction_tool({ - "instruction_set": "amd64", - "opcode": "pop" - }) - ``` - - Look up ARM64 STP instruction: - ``` - lookup_instruction_tool({ - "instruction_set": "aarch64", - "opcode": "stp" - }) - ``` - - Using instruction set aliases: - ``` - lookup_instruction_tool({ - "instruction_set": "arm64", # resolves to aarch64 - "opcode": "ldr" - }) - ``` - - Get raw JSON for programmatic use: - ``` - lookup_instruction_tool({ - "instruction_set": "amd64", - "opcode": "mov", - "format_output": false - }) - ``` - - **Supported Architectures:** - - **x86/x86-64**: Comprehensive Intel/AMD instruction documentation - - **ARM64**: ARMv8 AArch64 instruction set - - **Additional**: Other architectures as supported by Compiler Explorer - - **Smart Features:** - - **Alias resolution**: Automatically maps common aliases (x64→amd64, arm64→aarch64) - - **Case insensitive**: Works with any case for instruction names - - **Fallback handling**: Tries both resolved and original instruction set names - - **Formatted output**: Clean, readable documentation optimized for AI workflows - - **When to use vs other tools:** - - Use lookup_instruction_tool for assembly instruction documentation - - Use analyze_optimization_tool to see how compilers generate assembly - - Use compile_and_run_tool to test code that uses specific instructions + """Get documentation for assembly instructions/opcodes. + + Understand instruction behavior during assembly analysis or debugging. + + Args: + instruction_set: Architecture ("amd64"/"x86_64", "aarch64"/"arm64", "mips", "riscv") + opcode: Instruction to look up (e.g., "pop", "stp", "mov", "add") + format_output: Format for readability (true) vs raw JSON (false) + + Returns: {found, instruction_set, opcode, documentation, formatted_docs, error} + + Supports alias resolution (x64→amd64, arm64→aarch64) and case-insensitive lookups. + + Example: lookup_instruction_tool(instruction_set="amd64", opcode="pop") + + Use with analyze_optimization_tool to understand generated assembly instructions. """ result = await lookup_instruction( { @@ -918,56 +502,24 @@ async def download_shortlink_tool( include_metadata: bool = True, overwrite_existing: bool = False, ) -> str: - """Download and save source code from a Compiler Explorer shortlink to local files. - - This tool extracts source code from Compiler Explorer shared links and saves it to - local files, preserving original filenames when available. Perfect for extracting - code examples, analyzing shared configurations, and integrating CE examples into - local projects. - - **Use Cases:** - - **Code extraction**: Download shared code examples for local analysis - - **Project integration**: Import CE examples into local development - - **Learning**: Save interesting code snippets for study - - **Backup**: Archive important code configurations - - **Collaboration**: Download team-shared code examples - - **Parameters:** - - shortlink_url: Full CE URL (https://godbolt.org/z/G38YP7eW4) or just ID (G38YP7eW4) - - destination_path: Directory path where files should be saved (LLM-controlled) - - preserve_filenames: Use original CE filenames when available (default: True) - - fallback_prefix: Prefix for generated filenames when no original name (default: "ce") - - include_metadata: Save compilation settings as JSON metadata file (default: True) - - overwrite_existing: Overwrite existing files instead of creating numbered variants (default: False) - - **Response includes:** - - List of saved files with original names, languages, and sizes - - Metadata files created (if requested) - - Summary of download operation - - Error details if download fails - - **File Naming:** - - Original filenames are preserved when available (example.cpp) - - Generated names for anonymous files (ce_001.cpp, ce_002.c) - - Main source files can be marked with suffix (example_main.cpp) - - Conflicts resolved with numbers (example_1.cpp, example_2.cpp) - - **Multi-file Support:** - - Handles complex CE projects with multiple files - - Preserves file relationships and metadata - - Saves compiler configurations for reproduction - - **Examples:** - ``` - # Save to current directory - download_shortlink_tool("https://godbolt.org/z/G38YP7eW4", ".") - - # Save to specific project directory - download_shortlink_tool("G38YP7eW4", "/path/to/project/examples") - - # Save without metadata - download_shortlink_tool("https://godbolt.org/z/abc123", "./temp", include_metadata=False) - ``` + """Download source code from Compiler Explorer shortlink to local files. + + Extract code examples, analyze shared configurations, integrate CE examples into projects. + + Args: + shortlink_url: Full CE URL or just ID (e.g., "G38YP7eW4") + destination_path: Directory where files should be saved + preserve_filenames: Use original CE filenames (default: True) + fallback_prefix: Prefix for generated filenames (default: "ce") + include_metadata: Save compilation settings as JSON (default: True) + overwrite_existing: Overwrite existing files (default: False) + + Returns: {saved_files, metadata_file, summary, error} + + File naming: Preserves original names (example.cpp), generates names for anonymous files (ce_001.cpp), + resolves conflicts with numbers (example_1.cpp, example_2.cpp). + + Example: download_shortlink_tool("https://godbolt.org/z/G38YP7eW4", ".") """ result = await download_shortlink( { diff --git a/docs/TOOLS_INTEGRATION_PLAN.md b/docs/TOOLS_INTEGRATION_PLAN.md new file mode 100644 index 0000000..8dcf9b4 --- /dev/null +++ b/docs/TOOLS_INTEGRATION_PLAN.md @@ -0,0 +1,282 @@ +# Compiler Explorer Tools Integration Plan + +## Overview + +This document outlines the plan to integrate Compiler Explorer's static analysis and code quality tools into the ce-mcp project. This enhancement will transform ce-mcp from a compilation-focused service into a comprehensive code analysis platform. + +## Background + +Compiler Explorer (godbolt.org) supports various static analysis tools including: +- **clang-tidy** - Clang-based C++ linter with hundreds of checks +- **cppcheck** - Static analysis tool for C/C++ detecting bugs compilers miss +- **GCC Static Analyzer** - Built-in static analysis via `-fanalyzer` +- **PVS-Studio** - Commercial static analyzer +- **Other tools** - Language-specific analyzers and formatters + +Currently, these tools are accessible through the web interface but not programmatically via the API. + +## Catalyst: New API Endpoint + +**PR #7950** adds `/api/tools/` endpoint: +- Lists available tools for each language +- Provides tool metadata (id, name, type, languageId, allowStdin) +- Enables programmatic tool discovery + +**Example Response:** +```json +[ + { + "id": "clangtidy", + "name": "Clang-Tidy", + "type": "postprocessor", + "languageId": "c++", + "allowStdin": true + }, + { + "id": "cppcheck", + "name": "Cppcheck", + "type": "postprocessor", + "languageId": "c++", + "allowStdin": false + } +] +``` + +## Implementation Plan + +### Phase 1: Foundation (Immediate) +**Prerequisites:** PR #7950 merged + +1. **Add tools discovery to API client** + - Implement `get_tools(language)` method + - Cache tool availability per language + - Handle tool metadata parsing + +2. **Extend existing MCP tools with tools parameter** + - Add optional `tools: list[str]` to all compilation functions + - Pass tools to Compiler Explorer API payload + - Parse and return tool outputs alongside compilation results + +3. **Enhanced API client methods** + - Update `compile()` to accept tools parameter + - Parse tool outputs from API responses + - Structure tool results for easy consumption + +### Phase 2: New MCP Tools (Core Features) + +1. **`list_available_tools_tool`** - Discovery function + ```python + @mcp.tool() + async def list_available_tools_tool(language: str) -> str: + """List all static analysis tools available for a language.""" + ``` + +2. **`run_static_analysis_tool`** - Dedicated analysis function + ```python + @mcp.tool() + async def run_static_analysis_tool( + source: str, + language: str, + tools: list[str], + compiler: str = "g132" + ) -> str: + """Run static analysis tools without compilation.""" + ``` + +3. **`analyze_code_quality_tool`** - Comprehensive analysis + ```python + @mcp.tool() + async def analyze_code_quality_tool( + source: str, + language: str, + analysis_level: str = "standard" # basic, standard, comprehensive + ) -> str: + """Run multiple static analysis tools and aggregate results.""" + ``` + +### Phase 3: Advanced Features + +1. **Tool-specific analyzers** + - `run_clang_tidy_tool` with check selection + - `run_cppcheck_tool` with severity filtering + - Language-specific tool wrappers + +2. **Intelligent tool selection** + - Auto-select relevant tools based on code patterns + - Severity-based filtering and reporting + - Performance impact analysis + +3. **Comparative analysis** + - Compare tool outputs across compiler versions + - Before/after code quality metrics + - Tool recommendation engine + +## Technical Architecture + +### API Client Extensions + +```python +class CompilerExplorerClient: + async def get_tools(self, language: str) -> List[Dict[str, Any]]: + """Get available tools for language.""" + + async def compile_with_tools( + self, + source: str, + language: str, + compiler: str, + tools: List[str] = None + ) -> Dict[str, Any]: + """Compile with static analysis tools.""" +``` + +### Tool Output Parsing + +```python +class ToolOutputParser: + def parse_clang_tidy(self, output: str) -> List[Dict]: + """Parse clang-tidy warnings into structured format.""" + + def parse_cppcheck(self, output: str) -> List[Dict]: + """Parse cppcheck reports into structured format.""" + + def aggregate_tool_results(self, tool_outputs: Dict) -> Dict: + """Combine multiple tool outputs into unified report.""" +``` + +### Enhanced MCP Tool Structure + +```python +{ + "compilation": { + "success": true, + "warnings": [], + "errors": [] + }, + "static_analysis": { + "tools_used": ["clang-tidy", "cppcheck"], + "total_issues": 15, + "by_severity": { + "error": 2, + "warning": 8, + "info": 5 + }, + "by_tool": { + "clang-tidy": [...], + "cppcheck": [...] + } + }, + "recommendations": [ + "Consider using std::array instead of C arrays", + "Add const qualifiers to improve optimization" + ] +} +``` + +## Use Cases + +### Code Review Enhancement +```python +# Analyze pull request changes +result = await analyze_code_quality_tool( + source=modified_code, + language="c++", + analysis_level="comprehensive" +) +# Returns: structured issues, severity counts, recommendations +``` + +### Educational Code Analysis +```python +# Help students understand code quality +result = await run_static_analysis_tool( + source=student_code, + language="c++", + tools=["clang-tidy"] +) +# Returns: learning-focused explanations of issues +``` + +### CI/CD Integration +```python +# Automated quality gates +issues = await analyze_code_quality_tool(source, "c++", "strict") +if issues["static_analysis"]["by_severity"]["error"] > 0: + # Fail build +``` + +## Implementation Todos + +### Immediate (Phase 1) +- [ ] Monitor PR #7950 merge status +- [ ] Implement `get_tools()` in API client +- [ ] Add `tools` parameter to existing MCP functions +- [ ] Create tool output parsing utilities +- [ ] Add tool integration tests + +### Short-term (Phase 2) +- [ ] Implement `list_available_tools_tool` +- [ ] Implement `run_static_analysis_tool` +- [ ] Implement `analyze_code_quality_tool` +- [ ] Create structured tool output format +- [ ] Add comprehensive tool documentation + +### Medium-term (Phase 3) +- [ ] Add tool-specific MCP functions +- [ ] Implement intelligent tool selection +- [ ] Create comparative analysis features +- [ ] Add tool performance metrics +- [ ] Build recommendation engine + +### Long-term (Future) +- [ ] Custom tool configurations +- [ ] Tool result caching and analytics +- [ ] Integration with IDE plugins +- [ ] Real-time collaborative analysis +- [ ] Machine learning for code quality insights + +## Success Metrics + +1. **Tool Coverage**: Support for 90%+ of Compiler Explorer's available tools +2. **Response Quality**: Structured, actionable analysis results +3. **Performance**: Tool analysis within 5s for typical code samples +4. **Usability**: Clear documentation and examples for each tool +5. **Integration**: Seamless workflow with existing compilation tools + +## Risks and Mitigations + +### Technical Risks +- **API Changes**: Compiler Explorer tool API may evolve + - *Mitigation*: Version-aware client with fallback support +- **Tool Output Variability**: Different tools have inconsistent formats + - *Mitigation*: Robust parsing with error handling +- **Performance Impact**: Multiple tools may slow response times + - *Mitigation*: Async processing and result caching + +### User Experience Risks +- **Information Overload**: Too many tool results may overwhelm users + - *Mitigation*: Intelligent filtering and severity-based presentation +- **Tool Selection Confusion**: Users may not know which tools to use + - *Mitigation*: Smart defaults and guided recommendations + +## Future Opportunities + +1. **Custom Tool Chains**: Allow users to define tool sequences +2. **Code Quality Trends**: Track improvement over time +3. **Team Analytics**: Aggregate analysis across projects +4. **Integration Partnerships**: Connect with other development tools +5. **Educational Platform**: Teach code quality best practices + +## References + +- [Compiler Explorer PR #7950](https://github.com/compiler-explorer/compiler-explorer/pull/7950) - New tools API endpoint +- [Clang-Tidy Documentation](https://clang.llvm.org/extra/clang-tidy/) - Comprehensive check reference +- [Cppcheck Manual](https://cppcheck.sourceforge.io/manual.pdf) - Static analysis capabilities +- [GCC Static Analyzer](https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html) - Built-in analysis options +- [MCP Specification](https://spec.modelcontextprotocol.io/) - Protocol requirements for tool integration + +--- + +**Status**: Planning phase - awaiting PR #7950 merge +**Priority**: High - significant enhancement to ce-mcp capabilities +**Estimated Implementation Time**: 3-4 weeks across all phases \ No newline at end of file diff --git a/uv.lock b/uv.lock index 673f19e..ca833d5 100644 --- a/uv.lock +++ b/uv.lock @@ -216,6 +216,7 @@ dependencies = [ { name = "aiohttp" }, { name = "click" }, { name = "mcp" }, + { name = "packaging" }, { name = "pydantic" }, { name = "pyyaml" }, ] @@ -224,7 +225,6 @@ dependencies = [ dev = [ { name = "aioresponses" }, { name = "black" }, - { name = "flake8" }, { name = "isort" }, { name = "mypy" }, { name = "pytest" }, @@ -238,10 +238,10 @@ requires-dist = [ { name = "aioresponses", marker = "extra == 'dev'", specifier = ">=0.7.6" }, { name = "black", marker = "extra == 'dev'", specifier = ">=23.0" }, { name = "click", specifier = ">=8.0" }, - { name = "flake8", marker = "extra == 'dev'", specifier = ">=6.0" }, { name = "isort", marker = "extra == 'dev'", specifier = ">=5.0" }, { name = "mcp", specifier = ">=0.1.0" }, { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0" }, + { name = "packaging", specifier = ">=23.0" }, { name = "pydantic", specifier = ">=2.0" }, { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0" }, { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21" }, @@ -361,20 +361,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/36/f4/c6e662dade71f56cd2f3735141b265c3c79293c109549c1e6933b0651ffc/exceptiongroup-1.3.0-py3-none-any.whl", hash = "sha256:4d111e6e0c13d0644cad6ddaa7ed0261a0b36971f6d23e7ec9b4b9097da78a10", size = 16674, upload-time = "2025-05-10T17:42:49.33Z" }, ] -[[package]] -name = "flake8" -version = "7.3.0" -source = { registry = "https://pypi.org/simple" } -dependencies = [ - { name = "mccabe" }, - { name = "pycodestyle" }, - { name = "pyflakes" }, -] -sdist = { url = "https://files.pythonhosted.org/packages/9b/af/fbfe3c4b5a657d79e5c47a2827a362f9e1b763336a52f926126aa6dc7123/flake8-7.3.0.tar.gz", hash = "sha256:fe044858146b9fc69b551a4b490d69cf960fcb78ad1edcb84e7fbb1b4a8e3872", size = 48326, upload-time = "2025-06-20T19:31:35.838Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/9f/56/13ab06b4f93ca7cac71078fbe37fcea175d3216f31f85c3168a6bbd0bb9a/flake8-7.3.0-py2.py3-none-any.whl", hash = "sha256:b9696257b9ce8beb888cdbe31cf885c90d31928fe202be0889a7cdafad32f01e", size = 57922, upload-time = "2025-06-20T19:31:34.425Z" }, -] - [[package]] name = "frozenlist" version = "1.7.0" @@ -569,15 +555,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/01/0e/b27cdbaccf30b890c40ed1da9fd4a3593a5cf94dae54fb34f8a4b74fcd3f/jsonschema_specifications-2025.4.1-py3-none-any.whl", hash = "sha256:4653bffbd6584f7de83a67e0d620ef16900b390ddc7939d56684d6c81e33f1af", size = 18437, upload-time = "2025-04-23T12:34:05.422Z" }, ] -[[package]] -name = "mccabe" -version = "0.7.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/e7/ff/0ffefdcac38932a54d2b5eed4e0ba8a408f215002cd178ad1df0f2806ff8/mccabe-0.7.0.tar.gz", hash = "sha256:348e0240c33b60bbdf4e523192ef919f28cb2c3d7d5c7794f74009290f236325", size = 9658, upload-time = "2022-01-24T01:14:51.113Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/27/1a/1f68f9ba0c207934b35b86a8ca3aad8395a3d6dd7921c0686e23853ff5a9/mccabe-0.7.0-py2.py3-none-any.whl", hash = "sha256:6c2d30ab6be0e4a46919781807b4f0d834ebdd6c6e3dca0bda5a15f863427b6e", size = 7350, upload-time = "2022-01-24T01:14:49.62Z" }, -] - [[package]] name = "mcp" version = "1.12.1" @@ -875,15 +852,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/cc/35/cc0aaecf278bb4575b8555f2b137de5ab821595ddae9da9d3cd1da4072c7/propcache-0.3.2-py3-none-any.whl", hash = "sha256:98f1ec44fb675f5052cccc8e609c46ed23a35a1cfd18545ad4e29002d858a43f", size = 12663, upload-time = "2025-06-09T22:56:04.484Z" }, ] -[[package]] -name = "pycodestyle" -version = "2.14.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/11/e0/abfd2a0d2efe47670df87f3e3a0e2edda42f055053c85361f19c0e2c1ca8/pycodestyle-2.14.0.tar.gz", hash = "sha256:c4b5b517d278089ff9d0abdec919cd97262a3367449ea1c8b49b91529167b783", size = 39472, upload-time = "2025-06-20T18:49:48.75Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/d7/27/a58ddaf8c588a3ef080db9d0b7e0b97215cee3a45df74f3a94dbbf5c893a/pycodestyle-2.14.0-py2.py3-none-any.whl", hash = "sha256:dd6bf7cb4ee77f8e016f9c8e74a35ddd9f67e1d5fd4184d86c3b98e07099f42d", size = 31594, upload-time = "2025-06-20T18:49:47.491Z" }, -] - [[package]] name = "pydantic" version = "2.11.7" @@ -1000,15 +968,6 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/58/f0/427018098906416f580e3cf1366d3b1abfb408a0652e9f31600c24a1903c/pydantic_settings-2.10.1-py3-none-any.whl", hash = "sha256:a60952460b99cf661dc25c29c0ef171721f98bfcb52ef8d9ea4c943d7c8cc796", size = 45235, upload-time = "2025-06-24T13:26:45.485Z" }, ] -[[package]] -name = "pyflakes" -version = "3.4.0" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/45/dc/fd034dc20b4b264b3d015808458391acbf9df40b1e54750ef175d39180b1/pyflakes-3.4.0.tar.gz", hash = "sha256:b24f96fafb7d2ab0ec5075b7350b3d2d2218eab42003821c06344973d3ea2f58", size = 64669, upload-time = "2025-06-20T18:45:27.834Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/c2/2f/81d580a0fb83baeb066698975cb14a618bdbed7720678566f1b046a95fe8/pyflakes-3.4.0-py2.py3-none-any.whl", hash = "sha256:f742a7dbd0d9cb9ea41e9a24a918996e8170c799fa528688d40dd582c8265f4f", size = 63551, upload-time = "2025-06-20T18:45:26.937Z" }, -] - [[package]] name = "pygments" version = "2.19.2"