# 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)