mnehmos.ooda.mcp (v1.0.0)
A comprehensive MCP (Model Context Protocol) server that provides full computer control capabilities to Claude. Implements the OODA loop (Observe-Orient-Decide-Act) pattern for autonomous computer interaction.
Features
| Category | Tools | Description |
|---|---|---|
| CLI & Files | 23 | Shell commands, file read/write/copy/move/delete, search, diff editing |
| CRUD Database | 9 | Persistent SQLite key-value store with collections |
| Screen (Observe) | 4 | Screenshot, display info, screen change detection |
| Input (Act) | 10 | Keyboard typing/shortcuts, mouse move/click/drag/scroll |
| Window Management | 11 | List/focus/minimize/maximize/close windows, launch apps |
| Clipboard | 4 | Read/write text, HTML, images |
| System | 8 | System info, processes, network, notifications |
| Browser | 9 | Puppeteer/Playwright automation |
| Sessions | 5 | Interactive process sessions (REPLs, SSH) |
| Config & Analytics | 7 | Configuration management, usage stats |
| Search | 4 | Paginated file search |
| Generic Batch | 1 | Universal batch dispatcher for any tool |
Total: 100 tools with batch/parallel execution support for most operations.
Security Warning
This server provides unrestricted system access. Claude will be able to:
- Execute arbitrary shell commands
- Control keyboard and mouse
- Take screenshots
- Read/write files anywhere
- Manage windows and processes
Use at your own risk in trusted environments only.
Installation
From npm (Recommended)
npm install -g mnehmos.ooda.mcp
From Source
git clone https://github.com/Mnehmos/mnehmos.ooda.mcp.git
cd mnehmos.ooda.mcp
npm install
npm run build
Claude Desktop Configuration
Add to your Claude Desktop config file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
If installed via npm:
{
"mcpServers": {
"ooda-computer": {
"command": "npx",
"args": ["mnehmos.ooda.mcp"]
}
}
}
If installed from source:
{
"mcpServers": {
"ooda-computer": {
"command": "node",
"args": ["/absolute/path/to/mnehmos.ooda.mcp/dist/index.js"]
}
}
}
OODA Loop Pattern
The tools are designed around the OODA (Observe-Orient-Decide-Act) loop:
Observe
screenshot- Capture screen or region (returns base64 or saves to file)get_screen_info- Get display/monitor informationwait_for_screen_change- Detect when screen content changeslist_windows- See all open applicationsget_active_window- Know current focusclipboard_read- Check clipboard contents
Orient
- Use CRUD tools to store/retrieve context and state
file_info,search_files- Understand filesystem statelist_processes,get_system_info- Understand system state
Decide
- Built into Claude's reasoning between observations
- CRUD database for persistent decision context
Act
keyboard_type,keyboard_shortcut- Type and use hotkeysmouse_click,mouse_move,mouse_drag- Mouse controlfocus_window,launch_application- Window controlclipboard_write- Set clipboard contentnotify- System notifications
Generic Batch Dispatcher
The batch_tools dispatcher can execute ANY tool in batch mode with unified safety limits:
{
"tool": "batch_tools",
"args": {
"operations": [
{ "tool": "read_file", "args": { "path": "src/index.ts" }, "label": "main" },
{ "tool": "file_info", "args": { "path": "package.json" }, "label": "pkg" },
{ "tool": "exec_cli", "args": { "command": "git status --short" }, "label": "git" }
],
"executionMode": "parallel"
}
}
Execution Modes
| Mode | Description |
|---|---|
parallel | All operations run concurrently (default) |
sequential | Operations run one after another, supports stopOnError |
Safety Limits
Configurable via ~/.mcp/config.json or per-request:
| Limit | Default | Description |
|---|---|---|
maxOperations | 50 | Max operations per batch |
maxAggregateChars | 200000 | Total output size limit |
maxLinesPerFile | 500 | Per-file line truncation |
timeout | 30000 | Per-operation timeout (ms) |
See ADR-003 for full documentation.
API Reference
CLI & File Operations
| Tool | Description |
|---|---|
exec_cli | Execute shell command |
read_file | Read file contents |
write_file | Write content to file |
list_directory | List directory contents |
read_file_lines | Read specific line range (token-efficient) |
search_in_file | Search patterns within a file |
str_replace | Replace unique string in file |
copy_file | Copy file/directory |
move_file | Move/rename file |
delete_file | Delete file/directory |
file_info | Get file metadata |
search_files | Search files by pattern |
batch_* | Parallel versions of above |
Diff-Based Editing
| Tool | Description |
|---|---|
edit_block | Search/replace with fuzzy matching fallback |
apply_diff | Multiple search/replace in atomic operation |
get_diff_preview | Preview changes without applying |
batch_edit_blocks | Sequential edits with partial success |
write_from_line | Replace content from line N to EOF |
CRUD Operations
| Tool | Description |
|---|---|
crud_create | Create record in collection |
crud_read | Read record by ID |
crud_update | Update existing record |
crud_delete | Delete record |
crud_query | Query with filters |
crud_batch_* | Parallel versions |
Screen Operations
| Tool | Description |
|---|---|
screenshot | Capture screen (region optional) |
get_screen_info | Display/monitor info |
wait_for_screen_change | Wait for UI changes |
find_on_screen | Find text/image (requires OCR) |
Input Operations
| Tool | Description |
|---|---|
keyboard_type | Type text |
keyboard_press | Press key with modifiers |
keyboard_shortcut | Execute shortcut (e.g., "ctrl+c") |
mouse_move | Move cursor |
mouse_click | Click at position |
mouse_drag | Drag between points |
mouse_scroll | Scroll wheel |
get_mouse_position | Current cursor position |
batch_keyboard_actions | Sequence of keyboard actions |
batch_mouse_actions | Sequence of mouse actions |
Window Operations
| Tool | Description |
|---|---|
list_windows | All open windows |
get_active_window | Currently focused window |
focus_window | Bring window to front |
minimize_window | Minimize window(s) |
maximize_window | Maximize window |
restore_window | Restore from min/max |
close_window | Close window |
resize_window | Resize window |
move_window | Move window position |
launch_application | Start application |
wait_for_window | Wait for window to appear |
Clipboard Operations
| Tool | Description |
|---|---|
clipboard_read | Read text/HTML/image |
clipboard_write | Write text/HTML |
clipboard_clear | Clear clipboard |
clipboard_has_format | Check format availability |
System Operations
| Tool | Description |
|---|---|
get_system_info | OS, CPU, memory, uptime |
list_processes | Running processes |
kill_process | Kill by PID or name |
get_environment | Environment variables |
set_environment | Set environment variable |
get_network_info | Network interfaces |
wait | Sleep for milliseconds |
notify | System notification |
Browser Automation
| Tool | Description |
|---|---|
launch_browser | Start Puppeteer/Playwright browser |
close_browser | Close browser instance |
navigate_page | Navigate to URL |
get_page_content | Get page HTML/text/markdown |
click_element | Click element by selector |
type_text | Type into input field |
evaluate_js | Execute JavaScript |
screenshot_page | Capture page screenshot |
get_console_logs | Get browser console logs |
Interactive Sessions
| Tool | Description |
|---|---|
start_process | Start interactive process (REPL, SSH) |
interact_with_process | Send input to process |
read_process_output | Read process stdout |
list_sessions | List active sessions |
terminate_process | End process session |
Batch Operations
Most tools have dedicated batch versions for parallel execution:
batch_exec_cli - Multiple commands in parallel
batch_read_files - Multiple files in parallel
batch_write_files - Multiple files in parallel
batch_copy_files - Multiple copies in parallel
crud_batch_create - Multiple records in parallel
...
Or use the generic batch_tools dispatcher to batch ANY tool.
Batch operations return structured results:
{
"summary": { "total": 5, "successful": 4, "failed": 1, "elapsed_ms": 23 },
"results": [
{ "index": 0, "success": true, "result": {...} },
{ "index": 1, "success": false, "error": "..." }
]
}
Platform Support
| Feature | Windows | macOS | Linux |
|---|---|---|---|
| CLI/Files | ✅ | ✅ | ✅ |
| CRUD | ✅ | ✅ | ✅ |
| Screenshot | ✅ PowerShell | ✅ screencapture | ✅ scrot |
| Keyboard | ✅ SendKeys | ✅ osascript | ✅ xdotool |
| Mouse | ✅ user32.dll | ⚠️ Limited | ✅ xdotool |
| Windows | ✅ user32.dll | ✅ osascript | ✅ wmctrl |
| Clipboard | ✅ PowerShell | ✅ pbcopy/paste | ✅ xclip |
Configuration
Optional config file at ~/.mcp/config.json:
{
"storage": {
"type": "sqlite",
"path": "~/.mcp/workspace.db"
},
"cliPolicy": {
"mode": "allow-all",
"extraBlockedPatterns": [],
"timeoutMs": 30000
},
"crud": {
"defaultLimit": 1000
},
"fileReading": {
"maxLines": 500,
"warnAtLines": 100
},
"batchOperations": {
"maxOperations": 50,
"maxAggregateChars": 200000,
"maxLinesPerFile": 500,
"defaultTimeout": 30000,
"toolLimits": {
"exec_cli": { "maxOperations": 20, "timeout": 60000 }
}
}
}
Development
npm install # Install dependencies
npm run build # Build TypeScript
npm run dev # Watch mode
npm test # Run tests
npm start # Run server
Known Limitations
find_on_screenrequires additional OCR dependencies (not included)- macOS mouse position reading returns 0,0 (system limitation)
- Some mouse drag operations may require platform-specific tuning
License
MIT License - see LICENSE file.
Changelog
See CHANGELOG.md for version history.