linux-mcp-server 0.1.0.dev0__tar.gz

linux_mcp_server-0.1.0.dev0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+.uv/
+
+# Configuration files (user-specific)
+config.sh
+

linux_mcp_server-0.1.0.dev0/.python-version

@@ -0,0 +1 @@
+linux-mcp

linux_mcp_server-0.1.0.dev0/CONTRIBUTING.md

@@ -0,0 +1,350 @@
+# Contributing to Linux MCP Server
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the Linux MCP Server project.
+
+## Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone <repository-url>
+   cd linux-mcp-server
+   ```
+
+2. **Set up development environment:**
+   ```bash
+   uv venv
+   source .venv/bin/activate
+   uv pip install -e ".[dev]"
+   ```
+
+3. **Verify setup:**
+   ```bash
+   pytest
+   ```
+
+## Development Workflow
+
+We follow Test-Driven Development (TDD) principles:
+
+### 1. RED - Write a Failing Test
+```python
+# tests/test_new_feature.py
+import pytest
+from linux_mcp_server.tools import new_module
+
+@pytest.mark.asyncio
+async def test_new_feature():
+    result = await new_module.new_function()
+    assert "expected" in result
+```
+
+### 2. GREEN - Implement Minimal Code to Pass
+```python
+# src/linux_mcp_server/tools/new_module.py
+async def new_function():
+    return "expected result"
+```
+
+### 3. REFACTOR - Improve Code Quality
+- Improve readability
+- Remove duplication
+- Ensure all tests still pass
+
+### 4. Commit
+```bash
+git add .
+git commit -m "feat: add new feature
+
+- Detailed description of what was added
+- Tests included
+- All tests passing"
+```
+
+## Code Standards
+
+### Style Guidelines
+- Follow PEP 8 for Python code
+- Use type hints for function parameters and return values
+- Use async/await for I/O operations
+- Maximum line length: 100 characters
+
+### Documentation
+- Add docstrings to all public functions
+- Use clear, descriptive variable names
+- Comment complex logic
+
+### Testing
+- Write tests for all new features
+- Maintain test coverage above 80%
+- Use descriptive test names that explain what is being tested
+
+## Adding New Tools
+
+When adding a new diagnostic tool:
+
+1. **Create the tool function in appropriate module:**
+   ```python
+   # src/linux_mcp_server/tools/my_tool.py
+   from typing import Optional
+   from .ssh_executor import execute_command
+   
+   async def my_diagnostic_function(
+       host: Optional[str] = None, 
+       username: Optional[str] = None
+   ) -> str:
+       """
+       Brief description of what this tool does.
+       
+       Args:
+           host: Optional remote host to connect to via SSH
+           username: Optional SSH username (required if host is provided)
+       
+       Returns:
+           Formatted string with diagnostic information
+       """
+       try:
+           # Implementation using execute_command for local/remote execution
+           returncode, stdout, stderr = await execute_command(
+               ["your", "command"],
+               host=host,
+               username=username
+           )
+           
+           if returncode != 0:
+               return f"Error: {stderr}"
+           
+           return stdout
+       except Exception as e:
+           return f"Error: {str(e)}"
+   ```
+
+2. **Register the tool in server.py using FastMCP decorator:**
+   ```python
+   # Import your tool module at the top
+   from .tools import my_tool
+   
+   # Add decorated function
+   @mcp.tool()
+   async def my_tool_name(
+       param1: str,
+       host: Optional[str] = None, 
+       username: Optional[str] = None
+   ) -> str:
+       """Description for LLM to understand the tool.
+       
+       Args:
+           param1: Description of the parameter
+           host: Remote host to connect to via SSH (optional)
+           username: SSH username for remote host (required if host is provided)
+       """
+       return await _execute_tool(
+           "my_tool_name", 
+           my_tool.my_diagnostic_function,
+           param1=param1,
+           host=host, 
+           username=username
+       )
+   ```
+
+3. **Write tests:**
+   ```python
+   # tests/test_my_tool.py
+   import pytest
+   from linux_mcp_server.tools import my_tool
+   
+   @pytest.mark.asyncio
+   async def test_my_tool():
+       result = await my_tool.my_diagnostic_function()
+       assert isinstance(result, str)
+       assert "expected content" in result.lower()
+   
+   # Test server integration
+   @pytest.mark.asyncio
+   async def test_server_has_my_tool():
+       from linux_mcp_server.server import mcp
+       tools = await mcp.list_tools()
+       tool_names = [t.name for t in tools]
+       assert "my_tool_name" in tool_names
+   ```
+
+4. **Update documentation:**
+   - Add tool description to README.md
+   - Add usage examples to USAGE.md
+
+## Commit Message Format
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only changes
+- `test`: Adding missing tests
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `perf`: Performance improvement
+- `chore`: Changes to build process or auxiliary tools
+
+### Examples:
+```
+feat(tools): add disk smart status tool
+
+- Implement smart status checking
+- Add tests for SMART data parsing
+- Update documentation
+
+Closes #123
+```
+
+```
+fix(network): handle missing network interfaces gracefully
+
+Previously crashed when network interface disappeared
+during enumeration. Now catches exception and continues.
+```
+
+## Security Guidelines
+
+### Read-Only Operations
+- All tools MUST be read-only
+- Never implement any function that modifies system state
+- Use subprocess with caution; validate all inputs
+
+### Input Validation
+- Always validate user input
+- Use whitelists for file paths (see `read_log_file`)
+- Sanitize parameters passed to shell commands
+
+### Error Handling
+- Never expose sensitive information in error messages
+- Catch broad exceptions at the function level
+- Return user-friendly error messages
+
+## Testing Guidelines
+
+### Unit Tests
+Test individual functions in isolation:
+```python
+@pytest.mark.asyncio
+async def test_function_returns_correct_format():
+    result = await module.function()
+    assert isinstance(result, str)
+    assert "expected" in result
+```
+
+### Integration Tests
+Test that tools work with the MCP server:
+```python
+@pytest.mark.asyncio
+async def test_server_has_tool():
+    from linux_mcp_server.server import mcp
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+    assert "tool_name" in tool_names
+
+@pytest.mark.asyncio
+async def test_server_calls_tool():
+    from linux_mcp_server.server import mcp
+    result = await mcp.call_tool("tool_name", {})
+    assert isinstance(result, str)
+```
+
+### Running Tests
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_services.py
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+
+# Run with verbose output
+pytest -v
+```
+
+## Documentation
+
+### Code Documentation
+- Use docstrings for all public functions
+- Include parameter descriptions
+- Document return values
+- Add usage examples for complex functions
+
+### User Documentation
+- Update README.md for new features
+- Add examples to USAGE.md
+- Document configuration options
+- Include troubleshooting tips
+
+## Pull Request Process
+
+1. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make changes following TDD:**
+   - Write tests first
+   - Implement feature
+   - Ensure all tests pass
+
+3. **Update documentation:**
+   - Update README.md if needed
+   - Update USAGE.md with examples
+   - Update CONTRIBUTING.md if changing development process
+
+4. **Run all tests:**
+   ```bash
+   pytest
+   ```
+
+5. **Commit with conventional commit messages:**
+   ```bash
+   git commit -m "feat: add new diagnostic tool"
+   ```
+
+6. **Push and create pull request:**
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+7. **PR Description should include:**
+   - What the change does
+   - Why it's needed
+   - How to test it
+   - Screenshots/examples if applicable
+
+## Code Review Checklist
+
+- [ ] Tests added and passing
+- [ ] Code follows style guidelines
+- [ ] Documentation updated
+- [ ] Commit messages follow conventional format
+- [ ] No security vulnerabilities introduced
+- [ ] All operations are read-only
+- [ ] Error handling is appropriate
+- [ ] Input validation is present
+
+## Questions or Issues?
+
+- Open an issue on GitHub
+- Check existing issues first
+- Provide detailed information:
+  - System information (OS, version)
+  - Steps to reproduce
+  - Expected vs actual behavior
+  - Relevant logs
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+

linux_mcp_server-0.1.0.dev0/DEBUGGING.md

@@ -0,0 +1,133 @@
+# Debug Logging and Diagnostics
+
+This document describes how to enable and use logging to debug and monitor the MCP server operations.
+
+## Overview
+
+The Linux MCP Server provides comprehensive logging for:
+- Tool invocations with parameters
+- SSH connection events
+- Command execution (local and remote)
+- Tool execution timing
+- Errors and exceptions
+
+Logging is centralized in the server layer with tiered verbosity based on log level.
+
+## Enabling Debug Logging
+
+Set the `LINUX_MCP_LOG_LEVEL` environment variable to `DEBUG`:
+
+```bash
+export LINUX_MCP_LOG_LEVEL=DEBUG
+```
+
+## Log Output Locations
+
+Logs are written to two formats:
+
+1. **Human-readable**: `~/.local/share/linux-mcp-server/logs/server.log`
+2. **JSON format**: `~/.local/share/linux-mcp-server/logs/server.json`
+
+You can customize the log directory with:
+
+```bash
+export LINUX_MCP_LOG_DIR=/path/to/your/logs
+```
+
+## Example Log Output
+
+### Human-Readable Format (INFO level)
+
+```
+2025-10-10 15:30:45.123 | INFO | linux_mcp_server.audit | TOOL_CALL: list_directories_by_size | path=/home/user, top_n=10 | event=TOOL_CALL | tool=list_directories_by_size | execution_mode=local
+2025-10-10 15:30:45.456 | INFO | linux_mcp_server.audit | TOOL_COMPLETE: list_directories_by_size | event=TOOL_COMPLETE | tool=list_directories_by_size | status=success | duration=0.333s
+```
+
+### Human-Readable Format (DEBUG level - shows command execution)
+
+```
+2025-10-10 15:30:45.123 | INFO | linux_mcp_server.audit | TOOL_CALL: list_directories_by_size | path=/home/user, top_n=10 | event=TOOL_CALL | tool=list_directories_by_size | execution_mode=local
+2025-10-10 15:30:45.234 | DEBUG | linux_mcp_server.tools.ssh_executor | LOCAL_EXEC completed: du -b --max-depth=1 /home/user | exit_code=0 | duration=0.200s
+2025-10-10 15:30:45.456 | INFO | linux_mcp_server.audit | TOOL_COMPLETE: list_directories_by_size | event=TOOL_COMPLETE | tool=list_directories_by_size | status=success | duration=0.333s
+```
+
+### JSON Format
+
+```json
+{
+  "timestamp": "2025-10-10T15:30:45",
+  "level": "INFO",
+  "logger": "linux_mcp_server.audit",
+  "message": "TOOL_CALL: list_directories_by_size | path=/home/user, top_n=10",
+  "event": "TOOL_CALL",
+  "tool": "list_directories_by_size",
+  "execution_mode": "local"
+}
+```
+
+## Implementation
+
+Logging is centralized in `src/linux_mcp_server/server.py` using the `_execute_tool()` helper:
+
+```python
+async def _execute_tool(tool_name: str, handler, **kwargs):
+    """Execute a tool with logging and error handling."""
+    log_tool_call(tool_name, kwargs)  # Log invocation
+    
+    start_time = time.time()
+    try:
+        result = await handler(**kwargs)
+        duration = time.time() - start_time
+        log_tool_complete(tool_name, status="success", duration=duration)
+        return result
+    except Exception as e:
+        duration = time.time() - start_time
+        log_tool_complete(tool_name, status="error", duration=duration, error=str(e))
+        raise
+```
+
+All tools are registered using FastMCP decorators:
+```python
+@mcp.tool()
+async def list_directories_by_size(path: str, top_n: int, ...) -> str:
+    return await _execute_tool("list_directories_by_size", 
+                               storage.list_directories_by_size,
+                               path=path, top_n=top_n, ...)
+```
+
+The `audit.py` module provides structured logging functions:
+- `log_tool_call()`: Logs tool invocation with parameters
+- `log_tool_complete()`: Logs completion with timing and status
+- `log_ssh_connect()`: Logs SSH connection events
+- `log_ssh_command()`: Logs remote command execution
+
+## Log Levels
+
+### INFO Level
+- Tool invocations with parameters
+- Tool completion with status and timing
+- SSH connection success/failure
+- Remote command execution
+
+### DEBUG Level
+- Detailed command execution timing
+- SSH connection pool state
+- Local command execution details
+- All INFO level events plus detailed diagnostics
+
+## Benefits
+
+1. **Centralized Logging**: All logging happens in one place (server.py + audit.py)
+2. **Structured Data**: Both human-readable and JSON formats available
+3. **Audit Trail**: Complete record of all operations with timing
+4. **SSH Monitoring**: Track remote connections and command execution
+5. **Performance Insights**: Execution duration for every tool call
+
+## Use Cases
+
+- **Debugging**: Track tool invocations and identify issues
+- **Auditing**: Complete record of all operations
+- **Performance**: Monitor execution times
+- **SSH Troubleshooting**: Debug connection and authentication issues
+- **Development**: Understand tool behavior during testing
+

linux_mcp_server-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nicolás M.
+
+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.