MCP Server for Splunk

# Contributor Helper Scripts This directory contains helper scripts to streamline the contribution process for MCP Server for Splunk tools. ## Available Scripts ### 🛠️ generate_tool.py Interactive tool generator that follows project guidelines. ```bash # Generate a new tool interactively ./generate_tool.py # Or run with Python python contrib/scripts/generate_tool.py ``` **Features:** - Prompts for all required information - Generates properly structured tool files - Creates corresponding test files - Follows naming conventions automatically - Includes TODO comments for easy completion - **NEW: Splunk Search Template** - Create custom Splunk search tools instantly! **Generated Structure:** - Tool file: `contrib/tools/{category}/{tool_name}.py` - Test file: `tests/contrib/{category}/test_{tool_name}.py` - Proper imports and base class inheritance - Metadata with appropriate tags - Error handling templates **Templates Available:** - `basic`: Standard tool template with TODO placeholders - `splunk_search`: **NEW!** Specialized template for Splunk search tools - Custom SPL query embedding with user-friendly input (single-line or multi-line) - Time range and result limit parameters - Comprehensive Splunk mocking in tests - Based on your working `splunk_search.py` tool See [`SPLUNK_SEARCH_TEMPLATE.md`](SPLUNK_SEARCH_TEMPLATE.md) for detailed Splunk search template documentation. --- ### 📋 list_tools.py Browse and explore existing contrib tools. ```bash # List all tools summary ./list_tools.py # Interactive browser ./list_tools.py --interactive # Show detailed tool information ./list_tools.py --detail contrib/tools/examples/hello_world.py # Show help ./list_tools.py --help ``` **Features:** - Shows tool status (metadata, tests, Splunk requirements) - Groups tools by category - Interactive browsing mode - Detailed file previews - Identifies incomplete tools --- ### ✅ validate_tools.py Validate tools for compliance with project guidelines. ```bash # Validate all contrib tools ./validate_tools.py # Validate specific tool ./validate_tools.py contrib/tools/examples/hello_world.py # Show help ./validate_tools.py --help ``` **Validation Checks:** - Required imports and class structure - METADATA attribute completeness - Proper execute method signature - Naming conventions (snake_case files, PascalCase classes) - Documentation (docstrings, type hints) - Error handling patterns - Test file existence and structure --- ### 🧪 test_contrib.py Test runner specifically for contrib tools. ```bash # Run all contrib tests ./test_contrib.py # Run with verbose output ./test_contrib.py --verbose # Run with coverage report ./test_contrib.py --coverage # Run tests for specific category ./test_contrib.py examples # List available test files ./test_contrib.py --list # Check test environment ./test_contrib.py --check ``` **Features:** - Focused on contrib tools only - Category-specific test runs - Environment validation - Coverage reporting - Clean output formatting ## Quick Start Workflow 1. **Generate a new tool:** ```bash ./generate_tool.py ``` 2. **Implement your tool logic** (replace TODO comments) 3. **Validate your implementation:** ```bash ./validate_tools.py contrib/tools/your_category/your_tool.py ``` 4. **Run tests:** ```bash ./test_contrib.py your_category ``` 5. **Browse existing tools for inspiration:** ```bash ./list_tools.py --interactive ``` ## Development Tips ### Tool Creation Best Practices - Choose the right category (examples, security, devops, analytics) - Use descriptive names and documentation - Follow the error handling patterns - Include comprehensive tests - Use type hints throughout ### Testing Strategy - Test both success and error cases - Mock Splunk connections when needed - Use `@pytest.mark.asyncio` for async tests - Include parameter validation tests ### Validation Guidelines - All tools should pass validation without errors - Warnings are suggestions for improvement - Run validation before submitting pull requests ## Script Requirements These scripts require: - Python 3.8+ - Project dependencies installed (`pip install -e .`) - Running from project root directory ## Contributing to Scripts If you want to improve these helper scripts: 1. Follow the same validation standards 2. Add tests for new functionality 3. Update this documentation 4. Test across different tool categories ## Troubleshooting ### Common Issues **"Module not found" errors:** - Ensure you're running from the project root - Install dependencies: `pip install -e .` **"No tests found":** - Generate tools with test files using `generate_tool.py` - Check that test files follow naming convention: `test_*.py` **Validation failures:** - Review the specific error messages - Check the hello_world.py example for reference - Ensure all required imports are present **Permission errors:** - Make scripts executable: `chmod +x contrib/scripts/*.py` - Or run with: `python contrib/scripts/script_name.py` ## Getting Help - Check the main contrib README: `contrib/README.md` - Review existing examples: `contrib/tools/examples/` - Open an issue on GitHub for bugs or feature requests - Use `--help` flag on any script for usage information