dynamic-mcp 0.2.0__tar.gz

dynamic_mcp-0.2.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 42Research Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

dynamic_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,387 @@
+Metadata-Version: 2.4
+Name: dynamic-mcp
+Version: 0.2.0
+Summary: MCP server for crash dump analysis
+Author-email: 42Research Ltd <software@42research.co.uk>
+License: MIT
+Project-URL: Homepage, https://github.com/ablagodarenko/42Research
+Project-URL: Repository, https://github.com/ablagodarenko/42Research
+Project-URL: Documentation, https://github.com/ablagodarenko/42Research/tree/main/dynamic_mcp
+Project-URL: Issues, https://github.com/ablagodarenko/42Research/issues
+Keywords: mcp,crash,analysis,debugging,kernel
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: starlette>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pexpect>=4.8.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: aiohttp>=3.9.0
+Dynamic: license-file
+
+# Dynamic MCP Server
+
+A professional MCP (Model Context Protocol) server for crash dump analysis and kernel debugging.
+
+## Features
+
+- **Real Crash Utility Integration**: Execute actual crash utility commands with real output
+- **Automatic Crash Dump Discovery**: Find and list crash dumps in `/var/crash`
+- **Intelligent Kernel Matching**: Automatic kernel debug symbol detection and matching
+- **Session Management**: Robust crash analysis session lifecycle management
+- **Multiple Dump Formats**: Support for vmcore, core, crash, and dump files
+- **Professional Forensics**: Real kernel debugging and system forensics capabilities
+
+## Requirements
+
+- **Crash Utility**: Version 8.0.4+ (system package: `crash`)
+- **Python**: 3.10+ (3.11+ recommended)
+- **Kernel Debug Symbols**: Available in `/usr/lib/debug/lib/modules/`
+- **Crash Dumps**: Accessible in `/var/crash/` or custom location
+- **Permissions**: Read access to crash dumps and kernel files
+
+## Installation
+
+### Quick Install (Recommended)
+
+```bash
+# Install directly from source
+pip install -e .
+```
+
+### Development Install
+
+```bash
+# Create virtual environment (optional but recommended)
+python3 -m venv dynamic_mcp_env
+source dynamic_mcp_env/bin/activate
+
+# Install dependencies and package
+pip install -e .
+```
+
+### System Install
+
+```bash
+# Install system-wide (requires sudo)
+sudo pip install .
+```
+
+### System Install with Systemd Service
+
+```bash
+# Install system-wide with automatic systemd service setup
+sudo pip install .
+```
+
+This automatically:
+- Installs the package
+- Copies the systemd service file
+- Creates the dynamic-mcp user and group
+- Creates required directories
+- Registers the service with systemd
+
+See [SYSTEMD_INSTALLATION.md](SYSTEMD_INSTALLATION.md) for detailed systemd setup instructions.
+
+## Usage
+
+### Running the MCP Server
+
+#### Stdio Mode (Default)
+```bash
+# Run the server with stdio transport
+dynamic-mcp
+
+# Or with module syntax
+python -m dynamic_mcp.server
+```
+
+#### HTTP/SSE Mode
+```bash
+# Run the server with HTTP transport on default port 8080
+dynamic-mcp-http
+
+# Or with module syntax
+python -m dynamic_mcp.server --http
+
+# Access the server at: http://localhost:8080/sse
+```
+
+### MCP Client Configuration
+
+#### For Stdio Transport
+Add to your MCP client configuration (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mcp": {
+      "command": "python",
+      "args": ["-m", "dynamic_mcp.server"],
+      "env": {
+        "LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+#### For HTTP/SSE Transport
+Configure your MCP client to connect to the HTTP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mcp": {
+      "url": "http://localhost:8080/sse",
+      "env": {
+        "LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+### Testing
+
+```bash
+# Run crash analysis tests
+pytest tests/crash/
+
+# Test crash utility integration
+python tests/crash/test_crash_server.py
+
+# Run all tests
+pytest
+```
+
+## Configuration
+
+Create a `.env` file with optional configuration:
+
+```bash
+# Crash dump paths
+CRASH_DUMP_PATH=/var/crash
+KERNEL_PATH=/boot
+
+# Session timeouts
+CRASH_SESSION_TIMEOUT=180
+CRASH_COMMAND_TIMEOUT=120
+
+# Logging configuration
+LOG_LEVEL=INFO
+SUPPRESS_MCP_WARNINGS=true
+```
+
+## MCP Tools
+
+The server provides 5 comprehensive crash analysis tools:
+
+### 1. crash_command
+Execute crash utility commands with real output.
+
+**Parameters:**
+- `command` (string): Crash utility command to execute
+- `timeout` (integer, optional): Command timeout in seconds (default: 120)
+
+**Example:**
+```json
+{
+  "command": "sys",
+  "timeout": 60
+}
+```
+
+### 2. get_crash_info
+Get information about current crash dump and session.
+
+**Returns:**
+- Active session details
+- Available crash dumps
+- System requirements status
+
+### 3. list_crash_dumps
+List all available crash dumps.
+
+**Parameters:**
+- `max_dumps` (integer, optional): Maximum number of dumps to return (default: 10)
+
+**Returns:**
+- Crash dump details (name, path, size, timestamp)
+- Readability status
+
+### 4. start_crash_session
+Start a new crash analysis session.
+
+**Parameters:**
+- `dump_name` (string, optional): Specific dump name (uses latest if not specified)
+- `timeout` (integer, optional): Session startup timeout (default: 180)
+
+**Returns:**
+- Session startup status
+- Matched kernel information
+
+### 5. close_crash_session
+Close the active crash analysis session.
+
+**Returns:**
+- Session closure status
+
+## Example Usage
+
+### Basic Crash Analysis Workflow
+
+1. **List available crash dumps:**
+   ```bash
+   # Use the list_crash_dumps tool
+   ```
+
+2. **Start a crash session:**
+   ```bash
+   # Use start_crash_session tool (auto-selects latest dump)
+   ```
+
+3. **Execute crash commands:**
+   ```bash
+   # System information
+   crash_command: "sys"
+
+   # Backtrace
+   crash_command: "bt"
+
+   # Process list
+   crash_command: "ps"
+
+   # Kernel log
+   crash_command: "log"
+
+   # Module information
+   crash_command: "mod"
+   ```
+
+4. **Close session when done:**
+   ```bash
+   # Use close_crash_session tool
+   ```
+
+## Troubleshooting
+
+### System Requirements
+
+**Crash utility not found:**
+```bash
+# Install crash utility (RHEL/CentOS/Fedora)
+sudo yum install crash
+# or
+sudo dnf install crash
+
+# Install crash utility (Ubuntu/Debian)
+sudo apt-get install crash
+```
+
+**No crash dumps found:**
+- Check `/var/crash/` directory exists and has crash dumps
+- Ensure read permissions on crash dump files
+- Verify crash dumps are valid format (vmcore, core, etc.)
+
+**Kernel debug symbols missing:**
+- Install kernel debug packages
+- Check `/usr/lib/debug/lib/modules/` for debug symbols
+- Ensure kernel version matches crash dump
+
+### MCP Initialization Warnings
+
+You may see warnings like:
+```
+WARNING - Failed to validate request: Received request before initialization was complete
+```
+
+**This is normal MCP protocol behavior** and doesn't affect functionality.
+
+**To suppress these warnings:**
+```bash
+export SUPPRESS_MCP_WARNINGS=true
+```
+
+## How It Works
+
+1. **Crash Dump Discovery**: Automatically scans `/var/crash/` for crash dumps
+2. **Kernel Matching**: Finds matching kernel debug symbols in `/usr/lib/debug/`
+3. **Session Management**: Starts crash utility process with proper kernel and dump
+4. **Command Execution**: Uses pexpect to interact with crash utility process
+5. **Output Capture**: Returns real crash utility output with proper formatting
+
+## Supported Crash Analysis
+
+### Crash Commands
+- **System Info**: `sys`, `mach`, `help`
+- **Process Analysis**: `ps`, `task`, `files`
+- **Memory Analysis**: `kmem`, `vm`, `search`
+- **Stack Analysis**: `bt`, `bt -a`, `bt -f`
+- **Kernel Analysis**: `log`, `dmesg`, `mod`
+- **Disassembly**: `dis`, `gdb`
+- **Lustre Analysis**: Lustre-specific commands for filesystem debugging
+
+### Crash Dump Formats
+- **vmcore**: Standard Linux kernel crash dumps
+- **core**: Core dump files
+- **crash**: Crash utility format
+- **dump**: Generic dump files
+
+### Kernel Support
+- **Debug Symbols**: Automatic detection from `/usr/lib/debug/`
+- **Kernel Versions**: Support for multiple kernel versions
+- **Lustre Kernels**: Special support for Lustre filesystem kernels
+
+## Architecture
+
+- **MCP Protocol**: Full compliance with Model Context Protocol
+- **Real Integration**: Uses actual crash utility (not simulation)
+- **Session Management**: Robust process lifecycle management
+- **Error Handling**: Comprehensive error handling and recovery
+- **Logging**: Detailed logging for debugging and monitoring
+
+## License
+
+This project is licensed under the MIT License.
+
+Copyright © 2025 42Research Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software.
+
+For full license terms, see the [LICENSE](LICENSE) file.
+
+**Contact**: Email: software@42research.co.uk | Website: https://42research.co.uk
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
+
+## Support
+
+For issues and questions:
+- Check the troubleshooting section above
+- Review system requirements
+- Ensure crash utility and debug symbols are properly installed