MCP Server for Splunk

# Architecture Documentation This section provides comprehensive technical documentation about the MCP Server for Splunk architecture, design patterns, and extensibility. ## 📋 Architecture Overview | Document | Description | Audience | |----------|-------------|----------| | **[System Overview](overview.md)** | High-level architecture and design principles | Architects, Tech Leads | | Component Design (coming soon) | Detailed component breakdown and interactions | Developers | | Extension Guide (coming soon) | How to extend and customize the system | Contributors | | Data Flow (coming soon) | Request flow and data processing patterns | Developers, Debuggers | ## 🏗️ Quick Architecture Summary ### Core Components ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI Client │ │ MCP Server │ │ Splunk API │ │ │ │ │ │ │ │ • Claude │◄──►│ • FastMCP │◄──►│ • REST API │ │ • Cursor │ │ • Tool Registry │ │ • Search API │ │ • Custom Apps │ │ • Discovery │ │ • Admin API │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ### Key Design Principles - **🔍 Auto-Discovery**: Tools and resources are automatically discovered and loaded - **🔌 Modular**: Each tool is independent and self-contained - **🛡️ Secure**: Client-scoped access with no credential exposure - **🚀 Extensible**: Easy to add new tools and capabilities - **🌐 Transport Agnostic**: Works with stdio and HTTP transports ### Directory Structure ``` src/ ├── core/ # Core framework │ ├── base.py # Base classes and interfaces │ ├── discovery.py # Automatic component discovery │ ├── registry.py # Component registration │ └── loader.py # Dynamic loading into FastMCP │ ├── tools/ # Core tools (project-maintained) │ ├── search/ # Search and analytics tools │ ├── metadata/ # Data discovery tools │ ├── admin/ # Administration tools │ ├── kvstore/ # KV Store operations │ └── health/ # System monitoring tools │ ├── resources/ # Information resources │ ├── splunk_config.py # Configuration access │ ├── splunk_docs.py # Documentation resources │ └── processors/ # Content processing │ ├── prompts/ # Reusable prompt templates └── client/ # Splunk client abstraction contrib/ # Community contributions ├── tools/ # Community-contributed tools ├── scripts/ # Development and testing scripts └── examples/ # Usage examples and templates ``` ## 🔧 Technical Concepts ### Tool Discovery and Loading 1. **Scan Phase**: Discover all Python modules in `src/tools/` and `contrib/tools/` 2. **Registration Phase**: Register tools with metadata validation 3. **Loading Phase**: Dynamically load into FastMCP server 4. **Runtime Phase**: Tools available for MCP client invocation ### Configuration Management The system supports multiple configuration sources with precedence: 1. **HTTP Headers** (highest priority) - Multi-tenant scenarios 2. **Client Environment Variables** - MCP client configuration 3. **Server Environment Variables** - Traditional server config 4. **Configuration Files** - `.env` files and config objects ### Security Model - **No Credential Storage**: Credentials provided by clients - **Client Scoping**: Each client can connect to different Splunk instances - **Minimal Permissions**: Tools request only necessary Splunk permissions - **Transport Security**: HTTPS for network transport, secure stdio for local ## 🎯 Use Cases ### Development Patterns **Tool Development:** - Inherit from `BaseTool` for standard functionality - Use `ToolMetadata` for discovery and documentation - Implement async `execute()` method for tool logic **Resource Development:** - Inherit from `BaseResource` for information resources - Implement content processors for different data types - Use URI patterns for resource identification **Integration Patterns:** - stdio transport for local AI clients (Claude, Cursor) - HTTP transport for web applications and remote access - Multi-tenant deployment for serving multiple clients ## 📊 Performance Characteristics ### Startup Performance - **Local Mode**: ~10 seconds (single Python process) - **Docker Mode**: ~2 minutes (full stack with containers) - **Tool Loading**: ~1-2 seconds for 20+ tools ### Runtime Performance - **Simple Tools**: <100ms response time - **Search Operations**: 1-30 seconds (depends on Splunk query complexity) - **Memory Usage**: ~50-100MB for server process ### Scalability - **Concurrent Clients**: 10-100+ depending on transport mode - **Tool Capacity**: Unlimited (dynamic loading) - **Splunk Connections**: Pooled and reused per client configuration ## 🔍 Debugging and Observability ### Logging Levels - **ERROR**: Critical issues and failures - **WARNING**: Important issues that don't stop operation - **INFO**: General operational information - **DEBUG**: Detailed execution tracing ### Monitoring Points - Tool execution times and success rates - Splunk connection health and response times - Client connection patterns and usage - Resource utilization and performance metrics ### Debug Features - **Interactive Testing**: MCP Inspector for tool validation - **Detailed Logging**: Configurable log levels and output - **Health Endpoints**: Service health and status monitoring - **Error Handling**: Graceful degradation and error reporting ## 🚀 Getting Started ### For Architects 1. Review [System Overview](overview.md) for high-level design 2. Component Design (coming soon) for implementation details 3. Extension Patterns (coming soon) for customization needs ### For Developers 1. Component Design (coming soon) for development patterns 2. Extension Guide (coming soon) to add new functionality 3. Data Flow (coming soon) for debugging and optimization ### For Operators 1. Understand deployment patterns in [System Overview](overview.md) 2. Review monitoring and observability features 3. Plan capacity and scaling based on performance characteristics --- **Next Steps**: Choose the specific architecture topic that matches your role and needs!