MCP Server for Splunk

# Contributing to MCP Server for Splunk This directory contains community-contributed tools, resources, and prompts for the MCP Server for Splunk. We welcome and encourage contributions from the community! ## 🚀 Quick Start for Contributors **New to contributing? Use our helper scripts!** ```bash # Generate a new tool interactively (recommended) ./contrib/scripts/generate_tool.py # Browse existing tools for inspiration ./contrib/scripts/list_tools.py # Validate your tool implementation ./contrib/scripts/validate_tools.py # Run tests for your tools ./contrib/scripts/test_contrib.py ``` See [`contrib/scripts/README.md`](scripts/README.md) for detailed script documentation. ### 1. Project Structure Community contributions are organized by type and domain: ``` contrib/ ├── scripts/ # Helper scripts for contributors │ ├── generate_tool.py # Interactive tool generator │ ├── list_tools.py # Browse existing tools │ ├── validate_tools.py # Validate tool compliance │ ├── test_contrib.py # Run contrib tests │ └── README.md # Script documentation ├── tools/ # Community tools │ ├── examples/ # Example tools for learning │ ├── security/ # Security-focused tools │ ├── devops/ # DevOps/SRE tools │ └── analytics/ # Business analytics tools ├── resources/ # Community resources └── prompts/ # Community prompts ``` ### 2. Creating a New Tool **🎯 Recommended Approach: Use the Tool Generator** ```bash ./contrib/scripts/generate_tool.py ``` This interactive script will guide you through creating a properly structured tool with all requirements. **✨ New: Splunk Search Template!** The generator now includes a specialized **Splunk Search Template** for creating custom Splunk search tools: - 🔍 **Custom SPL queries** with your specific search logic - ⚡ **Instant tool generation** based on your working `splunk_search.py` - 🧪 **Comprehensive tests** with Splunk mocking - 🎯 **Perfect for**: Security tools, DevOps monitoring, Business analytics - 📝 **User-friendly input**: Choose single-line or multi-line input (type 'END' to finish) Select option `2` (splunk_search template) when prompted! See [`contrib/scripts/SPLUNK_SEARCH_TEMPLATE.md`](scripts/SPLUNK_SEARCH_TEMPLATE.md) for details. **Manual Approach:** If you prefer to create tools manually: 1. **Choose the right directory** based on your tool's purpose 2. **Create a new Python file** in the appropriate subdirectory 3. **Inherit from BaseTool** and implement the required methods 4. **Add metadata** to describe your tool 5. **Test your tool** thoroughly #### Example: Simple Hello World Tool ```python # contrib/tools/examples/hello_world.py from typing import Any, Dict from fastmcp import Context from src.core.base import BaseTool, ToolMetadata class HelloWorldTool(BaseTool): """A simple example tool that demonstrates the contribution pattern.""" METADATA = ToolMetadata( name="hello_world", description="A simple hello world example tool", category="examples", tags=["example", "tutorial"], requires_connection=False ) async def execute(self, ctx: Context, name: str = "World") -> Dict[str, Any]: """Say hello to someone.""" message = f"Hello, {name}!" return self.format_success_response({"message": message}) ``` ### 3. Tool Categories #### Security Tools (`contrib/tools/security/`) Tools focused on security analysis, threat hunting, and incident response. #### DevOps Tools (`contrib/tools/devops/`) Tools for monitoring, alerting, and operational tasks. #### Analytics Tools (`contrib/tools/analytics/`) Tools for business intelligence, reporting, and data analysis. ### 4. Development Guidelines #### Tool Requirements - **Inherit from BaseTool**: All tools must extend the `BaseTool` class - **Include Metadata**: Every tool must have a `METADATA` class attribute - **Handle Errors Gracefully**: Use the base class error handling methods - **Document Thoroughly**: Include clear docstrings and examples - **Test Comprehensively**: Include unit tests for your tools #### Naming Conventions - **File names**: Use snake_case (e.g., `threat_hunting.py`) - **Class names**: Use PascalCase (e.g., `ThreatHuntingTool`) - **Tool names**: Use snake_case (e.g., `threat_hunting`) #### Code Quality - Follow PEP 8 style guidelines - Use type hints for all function parameters and return values - Include comprehensive docstrings - Handle edge cases and errors appropriately ### 5. Testing Your Contributions **🧪 Quick Testing with Helper Scripts:** ```bash # Run all contrib tests ./contrib/scripts/test_contrib.py # Validate your tool implementation ./contrib/scripts/validate_tools.py contrib/tools/your_category/your_tool.py # Run tests for specific category ./contrib/scripts/test_contrib.py your_category ``` **Manual Testing:** Before submitting, make sure to: 1. **Run the existing test suite**: `pytest tests/` 2. **Test your tool individually**: Create unit tests in `tests/contrib/` 3. **Test integration**: Ensure your tool works with the MCP server 4. **Validate against live Splunk**: Test with actual Splunk instance if possible ### 6. Submission Process 1. **Fork the repository** on GitHub 2. **Create a feature branch** for your contribution 3. **Add your tool/resource/prompt** in the appropriate directory 4. **Include tests** for your contribution 5. **Update documentation** as needed 6. **Submit a pull request** with a clear description ### 7. Review Process All contributions will be reviewed for: - **Code quality and style** - **Security best practices** - **Documentation completeness** - **Test coverage** - **Compatibility with existing tools** ### 8. Getting Help - **Check the examples** in `contrib/tools/examples/` - **Read the architecture docs** in `ARCHITECTURE.md` - **Open an issue** on GitHub for questions - **Join the discussion** in GitHub Discussions ## Advanced Contribution Patterns ### Custom Resource Example ```python # contrib/resources/examples/sample_data.py from fastmcp import Context from src.core.base import BaseResource, ResourceMetadata class SampleDataResource(BaseResource): """Provides sample Splunk data for testing.""" METADATA = ResourceMetadata( uri="resource://sample_data", name="Sample Data", description="Sample Splunk search data for testing", category="examples" ) async def get_content(self, ctx: Context) -> str: return "Sample data content here..." ``` ### Custom Prompt Example ```python # contrib/prompts/examples/basic_prompts.py from fastmcp import Context from src.core.base import BasePrompt, PromptMetadata class SearchAssistantPrompt(BasePrompt): """Helps users build Splunk search queries.""" METADATA = PromptMetadata( name="search_assistant", description="Assists with building Splunk search queries", category="examples", arguments=[ {"name": "data_type", "description": "Type of data to search for"} ] ) async def get_prompt(self, ctx: Context, data_type: str = "logs") -> Dict[str, Any]: template = f"Help me build a Splunk search query for {data_type}..." return {"template": template, "data_type": data_type} ``` ## Community Resources - **Documentation**: [Project Wiki](link-to-wiki) - **Examples**: See `contrib/tools/examples/` for complete examples - **Best Practices**: Check existing core tools in `src/tools/` - **Issues**: [GitHub Issues](link-to-issues) - **Discussions**: [GitHub Discussions](link-to-discussions) Thank you for contributing to the MCP Server for Splunk community!