ABSD DevOps MCP Server

# ABSD DevOps MCP Server Local-first Model Context Protocol (MCP) server providing secure filesystem and terminal operations for AI assistants. ## Features - **22 Powerful Tools**: 9 filesystem + 4 streaming search + 7 terminal + 2 meta operations - **Filesystem Operations**: Read (files/URLs/images), write, list, create, move/rename, search (ripgrep), edit (surgical), multi-read - **Streaming Search**: Background ripgrep with pagination, session management, and early termination - **Terminal Sessions**: Interactive REPLs (Python, Node.js) with ANSI-aware prompt detection - **Process Management**: List system processes, kill with confirmation tokens - **Image Support**: MCP native ImageContent for PNG, JPEG, GIF, WebP, BMP (SVG as text for security) - **URL Fetching**: HTTP/HTTPS with configurable timeout and denylist protection - **MCP Primitives**: Resources (server state) + Prompts (workflow templates) - **Security-First**: Path traversal protection, command filtering, input sanitization, unrestricted mode with warnings - **Type-Safe**: Built with TypeScript strict mode and Zod schema validation - **Local-Only**: Runs entirely on your machine via stdio transport ⚠️ **v0.3.3 Compatibility Update:** Node.js requirement lowered to **>= 20.0.0** and native modules are now built against Node 20 so Claude Desktop can load the server without module-version errors. If you installed before v0.3.3, reinstall globally and restart Claude Desktop. ⚠️ **v0.3.2 Security Update:** Default blocked commands expanded from 6 to 31 (destructive disk operations, system/network modifications, package manager removals, data destruction). **Existing installations:** Review your `~/ABSD_MCP/config.json` and merge new blocked commands from [config.example.json](config.example.json) to benefit from enhanced security. ## Installation ### Quick Start (Recommended) ```bash # 1. Install globally npm install -g @anthonybir/devops-mcp # 2. Run setup (interactive) absd-mcp-setup ``` The setup command will: - ✅ Add MCP server to Claude Desktop config - ✅ Create default config at `~/ABSD_MCP/config.json` - ✅ Backup your existing Claude config with timestamp **⚠️ Security Warning:** Default config allows access to your entire home directory. Review and restrict `allowedDirectories` immediately after setup. **Next steps:** 1. Review config: `~/ABSD_MCP/config.json` (macOS) or `%USERPROFILE%\ABSD_MCP\config.json` (Windows) 2. Restrict `allowedDirectories` to only needed paths 3. Restart Claude Desktop ### Uninstall ```bash # Remove from Claude Desktop config absd-mcp-unregister # Uninstall package npm uninstall -g @anthonybir/devops-mcp ``` ### Manual Setup If you prefer manual configuration, see [Claude Desktop Setup](#claude-desktop-setup) below. ### Using npx (No Installation) ```bash npx @anthonybir/devops-mcp@latest ``` Requires manual Claude Desktop configuration (see below). ### Codex CLI Setup (TOML) If you run the [Codex CLI](https://github.com/openai/codex), install the package globally first and then add an MCP entry to your `codex.toml`: ```toml [[mcp]] name = "absd-devops" command = "absd-mcp" args = [] working_directory = "/Users/yourusername" env = { ABSD_MCP_CONFIG = "/Users/yourusername/ABSD_MCP/config.json" } ``` After saving the file run `codex mcp reload` (or restart Codex) so the new server is picked up. Update the paths to match your environment. ### From Source ```bash git clone https://github.com/anthonybir/ABSD_MCP.git cd ABSD_MCP pnpm install pnpm build ``` ## Configuration Create a `config.json` file (or copy from `config.example.json`): ```json { "allowedDirectories": [ "/Users/yourusername/Projects", "/Users/yourusername/Documents" ], "blockedCommands": [ "rm -rf /", "dd if=/dev/zero", "mkfs", "shutdown", "reboot" // ... see config.example.json for full list of 31 default blocked commands ], "fileReadLineLimit": 2000, "fileWriteLineLimit": 75, "sessionTimeout": 1800000, "logLevel": "info", "urlDenylist": ["localhost", "127.0.0.1", "0.0.0.0", "::1"], "urlTimeout": 10000 } ``` ### Configuration Options - **allowedDirectories**: Array of absolute paths where file operations are permitted (empty array = unrestricted access) - **blockedCommands**: Array of dangerous commands to reject (default: []) - **fileReadLineLimit**: Maximum lines to read per file operation (default: 1000) - **fileWriteLineLimit**: Maximum lines to write per operation (default: 50) - **sessionTimeout**: Process session timeout in milliseconds (default: 1800000 = 30 minutes) - **logLevel**: Logging level (`debug` | `info` | `warn` | `error`) (default: `info`) - **urlDenylist**: Array of hostnames to block for URL fetching (default: `["localhost", "127.0.0.1", "0.0.0.0", "::1"]`) - **urlTimeout**: URL fetch timeout in milliseconds (default: 10000 = 10 seconds) #### Enable Full Filesystem Access (Advanced) Set `allowedDirectories` to an empty array (`[]`) if you want ABSD to access every path on your machine. **You must keep `blockedCommands` populated**—the server will refuse to start if both lists are empty. ```json { "allowedDirectories": [], "blockedCommands": [ "rm -rf /", "dd if=/dev/zero", "mkfs", "shutdown", "reboot", "init 0" // ...and the rest from config.example.json ] } ``` Only use unrestricted mode on trusted local machines and keep the expanded blocked-commands list (31 entries) to avoid accidental destructive commands. ### Path Formatting **Windows users:** Use forward slashes in JSON to avoid escaping issues: - ✅ `"C:/Users/yourusername/Projects"` - ✅ `"C:\\\\Users\\\\yourusername\\\\Projects"` (double-escaped backslashes) - ❌ `"C:\Users\yourusername\Projects"` (breaks JSON) **macOS/Linux users:** Standard absolute paths: - ✅ `"/Users/yourusername/Projects"` - ✅ `"/home/username/projects"` ## Claude Desktop Setup **Config File Locations:** - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ### Option 1: Using Installed Package (Offline-Compatible) If you installed globally, reference the bin entry: ```json { "mcpServers": { "absd-devops": { "command": "absd-mcp", "args": [], "env": { "ABSD_MCP_CONFIG": "/path/to/your/config.json" } } } } ``` ### Option 2: Using npx (Online-Only) If using npx or want latest version: ```json { "mcpServers": { "absd-devops": { "command": "npx", "args": ["-y", "@anthonybir/devops-mcp@latest"], "env": { "ABSD_MCP_CONFIG": "/path/to/your/config.json" } } } } ``` **ABSD_MCP_CONFIG paths:** - **macOS:** Use full path like `/Users/yourusername/ABSD_MCP/config.json` - **Windows:** Use forward slashes like `C:/Users/yourusername/ABSD_MCP/config.json` Restart Claude Desktop to activate the server. ## Available Tools ### Filesystem Tools (9) - **read_file**: Read files or URLs with image support (PNG, JPEG, GIF, WebP, BMP), optional chunking, and offset support (SVG treated as text for security) - **read_multiple_files**: Read multiple files simultaneously with size caps (1MB/file, 5MB total) - **write_file**: Create or overwrite files with append mode option - **list_directory**: List directory contents recursively with depth control - **create_directory**: Create directories with recursive parent creation - **move_file**: Move or rename files and directories (both paths validated for security) - **get_file_info**: Get detailed metadata (size, permissions, timestamps, line count) - **search_files**: Search for patterns using ripgrep (regex, literal, file filtering) - **edit_block**: Surgical text replacement with uniqueness validation ### Streaming Search Tools (4) - **start_search**: Initiate background ripgrep search with files or content mode - `contextLines`: Lines of context around matches (default: 3) - **Tip:** Set `contextLines: 0` for terse output with no surrounding context - **get_more_search_results**: Retrieve paginated results with offset-based navigation - **stop_search**: Terminate running search sessions early - **list_searches**: View all active search sessions with status and result counts ### Terminal Tools (7) - **start_process**: Launch interactive terminal sessions (Python, Node.js, bash) - **interact_with_process**: Send commands with ANSI-aware REPL prompt detection (strip-ansi) - **read_process_output**: Retrieve buffered output from background processes - **list_sessions**: View all active MCP terminal sessions with status - **terminate_process**: Stop MCP sessions by PID - **list_processes**: List all system processes (cross-platform: Windows/macOS/Linux) - **kill_process**: Kill system processes with confirmation token validation ### Meta Tools (2) - **get_config**: Get current server configuration (read-only) with security status and metadata - **get_usage_stats**: Get server usage statistics including uptime, tool call counts (successful calls only), and active sessions/searches. Stats reset when server restarts. ## MCP Primitives ### Resources Expose server state and configuration: - **config://absd-mcp/server**: Current server configuration (allowed directories, limits) - **state://absd-mcp/sessions**: Active terminal sessions with status ### Prompts Pre-configured templates for common workflows: - **analyze_codebase**: Analyze project structure and tech stack - **setup_python_env**: Interactive Python development environment - **search_and_replace**: Pattern search with guided replacement ## Security This MCP server implements multiple security layers: 1. **Path Validation**: All file operations validate against allowed directories 2. **Symlink Resolution**: Prevents symlink-based path traversal attacks 3. **Command Filtering**: Blocks dangerous terminal commands 4. **Input Sanitization**: Removes null bytes and control characters 5. **Zod Validation**: All tool inputs validated against strict schemas ## Development ### Running Tests ```bash pnpm test # Run all tests pnpm test:security # Run security tests only ``` ### Building ```bash pnpm build # Build for production pnpm dev # Development mode with watch ``` ### Testing with MCP Inspector ```bash npx @modelcontextprotocol/inspector pnpm dev ``` ## Troubleshooting ### Server Not Appearing in Claude 1. Check that config.json path is correct in claude_desktop_config.json 2. Restart Claude Desktop completely 3. Check Claude's MCP logs for errors ### Permission Errors Ensure all paths in `allowedDirectories` exist and are accessible by your user account. ### Command Blocked If a legitimate command is being blocked, review the `blockedCommands` array in your config. ## Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass (`pnpm test`) 5. Submit a pull request ## License MIT License - see [LICENSE](LICENSE) file for details. ## Author Anthony Bir <anthonybir@aena.edu.py> ## Links - [MCP Specification](https://modelcontextprotocol.io) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Issue Tracker](https://github.com/anthonybir/ABSD_MCP/issues)