@wonderwhy-er/desktop-commander 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Eduard Ruzga
+
+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.

package/README.md

@@ -0,0 +1,106 @@
+# Claude Computer Commander
+
+Short version. Two key things. Terminal commands and diff based file editing.
+
+This server that allows Claude desktop app to execute long-running terminal commands on your computer and manage processes through Model Context Protocol (MCP) + Built on top of [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) to provide additional file editing capabilities .
+
+## Features
+
+- Execute terminal commands with output streaming
+- Command timeout and background execution support
+- Process management (list and kill processes)
+- Session management for long-running commands
+- Full filesystem operations:
+  - Read/write files
+  - Create/list directories
+  - Move files/directories
+  - Search files
+  - Get file metadata
+  - Code editing capabilities:
+  - Surgical text replacements for small changes
+  - Full file rewrites for major changes
+  - Multiple file support
+  - Pattern-based replacements
+
+## Setup
+
+1. Clone and build:
+```bash
+git clone https://github.com/wonderwhy-er/ClaudeComputerCommander.git
+cd ClaudeComputerCommander
+npm run setup
+```
+
+The setup command will:
+- Install dependencies
+- Build the server
+- Configure Claude's desktop app
+- Add MCP servers to Claude's config
+
+## Usage
+
+The server provides these tool categories:
+
+### Terminal Tools
+- `execute_command`: Run commands with configurable timeout
+- `read_output`: Get output from long-running commands
+- `force_terminate`: Stop running command sessions
+- `list_sessions`: View active command sessions
+- `list_processes`: View system processes
+- `kill_process`: Terminate processes by PID
+- `block_command`/`unblock_command`: Manage command blacklist
+
+### Filesystem Tools
+- `read_file`/`write_file`: File operations
+- `create_directory`/`list_directory`: Directory management  
+- `move_file`: Move/rename files
+- `search_files`: Pattern-based file search
+- `get_file_info`: File metadata
+
+### Edit Tools
+- `edit_block`: Apply surgical text replacements (best for changes <20% of file size)
+- `write_file`: Complete file rewrites (best for large changes >20% or when edit_block fails)
+
+Search/Replace Block Format:
+```
+filepath.ext
+<<<<<<< SEARCH
+existing code to replace
+=======
+new code to insert
+>>>>>>> REPLACE
+```
+
+Example:
+```
+src/main.js
+<<<<<<< SEARCH
+console.log("old message");
+=======
+console.log("new message");
+>>>>>>> REPLACE
+```
+
+## Handling Long-Running Commands
+
+For commands that may take a while:
+
+1. `execute_command` returns after timeout with initial output
+2. Command continues in background
+3. Use `read_output` with PID to get new output
+4. Use `force_terminate` to stop if needed
+
+## Model Context Protocol Integration
+
+This project extends the MCP Filesystem Server to enable:
+- Local server support in Claude Desktop
+- Full system command execution
+- Process management
+- File operations
+- Code editing with search/replace blocks
+
+Created as part of exploring Claude MCPs: https://youtube.com/live/TlbjFDbl5Us
+
+## License
+
+MIT

package/dist/command-manager.d.ts

@@ -0,0 +1,11 @@
+declare class CommandManager {
+    private blockedCommands;
+    loadBlockedCommands(): Promise<void>;
+    saveBlockedCommands(): Promise<void>;
+    validateCommand(command: string): boolean;
+    blockCommand(command: string): Promise<boolean>;
+    unblockCommand(command: string): Promise<boolean>;
+    listBlockedCommands(): string[];
+}
+export declare const commandManager: CommandManager;
+export {};

package/dist/command-manager.js

@@ -0,0 +1,54 @@
+import fs from 'fs/promises';
+import { CONFIG_FILE } from './config.js';
+class CommandManager {
+    constructor() {
+        this.blockedCommands = new Set();
+    }
+    async loadBlockedCommands() {
+        try {
+            const configData = await fs.readFile(CONFIG_FILE, 'utf-8');
+            const config = JSON.parse(configData);
+            this.blockedCommands = new Set(config.blockedCommands);
+        }
+        catch (error) {
+            this.blockedCommands = new Set();
+        }
+    }
+    async saveBlockedCommands() {
+        try {
+            const config = {
+                blockedCommands: Array.from(this.blockedCommands)
+            };
+            await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
+        }
+        catch (error) {
+            // Handle error if needed
+        }
+    }
+    validateCommand(command) {
+        const baseCommand = command.split(' ')[0].toLowerCase().trim();
+        return !this.blockedCommands.has(baseCommand);
+    }
+    async blockCommand(command) {
+        command = command.toLowerCase().trim();
+        if (this.blockedCommands.has(command)) {
+            return false;
+        }
+        this.blockedCommands.add(command);
+        await this.saveBlockedCommands();
+        return true;
+    }
+    async unblockCommand(command) {
+        command = command.toLowerCase().trim();
+        if (!this.blockedCommands.has(command)) {
+            return false;
+        }
+        this.blockedCommands.delete(command);
+        await this.saveBlockedCommands();
+        return true;
+    }
+    listBlockedCommands() {
+        return Array.from(this.blockedCommands).sort();
+    }
+}
+export const commandManager = new CommandManager();

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+export declare const CONFIG_FILE: string;
+export declare const LOG_FILE: string;
+export declare const ERROR_LOG_FILE: string;
+export declare const DEFAULT_COMMAND_TIMEOUT = 1000;

package/dist/config.js

@@ -0,0 +1,6 @@
+import path from 'path';
+import process from 'process';
+export const CONFIG_FILE = path.join(process.cwd(), 'config.json');
+export const LOG_FILE = path.join(process.cwd(), 'server.log');
+export const ERROR_LOG_FILE = path.join(process.cwd(), 'error.log');
+export const DEFAULT_COMMAND_TIMEOUT = 1000; // milliseconds

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { server } from './server.js';
+import { commandManager } from './command-manager.js';
+async function runServer() {
+    try {
+        // Handle uncaught exceptions
+        process.on('uncaughtException', async (error) => {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            process.exit(1);
+        });
+        // Handle unhandled rejections
+        process.on('unhandledRejection', async (reason) => {
+            const errorMessage = reason instanceof Error ? reason.message : String(reason);
+            process.exit(1);
+        });
+        const transport = new StdioServerTransport();
+        // Load blocked commands from config file
+        await commandManager.loadBlockedCommands();
+        await server.connect(transport);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        process.stderr.write(JSON.stringify({
+            type: 'error',
+            timestamp: new Date().toISOString(),
+            message: `Failed to start server: ${errorMessage}`
+        }) + '\n');
+        process.exit(1);
+    }
+}
+runServer().catch(async (error) => {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    process.stderr.write(JSON.stringify({
+        type: 'error',
+        timestamp: new Date().toISOString(),
+        message: `Fatal error running server: ${errorMessage}`
+    }) + '\n');
+    process.exit(1);
+});

package/dist/logging.d.ts

@@ -0,0 +1,2 @@
+export declare function logToFile(message: string): Promise<void>;
+export declare function logError(message: string): Promise<void>;

package/dist/logging.js

@@ -0,0 +1,28 @@
+import { appendFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const LOG_FILE = join(__dirname, '..', 'server.log');
+const ERROR_LOG_FILE = join(__dirname, '..', 'error.log');
+export async function logToFile(message) {
+    const timestamp = new Date().toISOString();
+    const logMessage = `${timestamp} - ${message}\n`;
+    try {
+        appendFileSync(LOG_FILE, logMessage);
+    }
+    catch (err) {
+        console.error('Failed to write to log file:', err);
+    }
+}
+export async function logError(message) {
+    const timestamp = new Date().toISOString();
+    const logMessage = `${timestamp} - ERROR: ${message}\n`;
+    try {
+        appendFileSync(ERROR_LOG_FILE, logMessage);
+    }
+    catch (err) {
+        console.error('Failed to write to error log file:', err);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,20 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare const server: Server<{
+    method: string;
+    params?: import("zod").objectOutputType<{
+        _meta: import("zod").ZodOptional<import("zod").ZodObject<{
+            progressToken: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>>;
+        }, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{
+            progressToken: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>>;
+        }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
+            progressToken: import("zod").ZodOptional<import("zod").ZodUnion<[import("zod").ZodString, import("zod").ZodNumber]>>;
+        }, import("zod").ZodTypeAny, "passthrough">>>;
+    }, import("zod").ZodTypeAny, "passthrough"> | undefined;
+}, {
+    method: string;
+    params?: import("zod").objectOutputType<{
+        _meta: import("zod").ZodOptional<import("zod").ZodObject<{}, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{}, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{}, import("zod").ZodTypeAny, "passthrough">>>;
+    }, import("zod").ZodTypeAny, "passthrough"> | undefined;
+}, import("zod").objectOutputType<{
+    _meta: import("zod").ZodOptional<import("zod").ZodObject<{}, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{}, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{}, import("zod").ZodTypeAny, "passthrough">>>;
+}, import("zod").ZodTypeAny, "passthrough">>;

package/dist/server.js

@@ -0,0 +1,287 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { commandManager } from './command-manager.js';
+import { ExecuteCommandArgsSchema, ReadOutputArgsSchema, ForceTerminateArgsSchema, ListSessionsArgsSchema, KillProcessArgsSchema, BlockCommandArgsSchema, UnblockCommandArgsSchema, ReadFileArgsSchema, ReadMultipleFilesArgsSchema, WriteFileArgsSchema, CreateDirectoryArgsSchema, ListDirectoryArgsSchema, MoveFileArgsSchema, SearchFilesArgsSchema, GetFileInfoArgsSchema, EditBlockArgsSchema, } from './tools/schemas.js';
+import { executeCommand, readOutput, forceTerminate, listSessions } from './tools/execute.js';
+import { listProcesses, killProcess } from './tools/process.js';
+import { readFile, readMultipleFiles, writeFile, createDirectory, listDirectory, moveFile, searchFiles, getFileInfo, listAllowedDirectories, } from './tools/filesystem.js';
+import { parseEditBlock, performSearchReplace } from './tools/edit.js';
+export const server = new Server({
+    name: "secure-terminal-server",
+    version: "0.2.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            // Terminal tools
+            {
+                name: "execute_command",
+                description: "Execute a terminal command with timeout. Command will continue running in background if it doesn't complete within timeout.",
+                inputSchema: zodToJsonSchema(ExecuteCommandArgsSchema),
+            },
+            {
+                name: "read_output",
+                description: "Read new output from a running terminal session.",
+                inputSchema: zodToJsonSchema(ReadOutputArgsSchema),
+            },
+            {
+                name: "force_terminate",
+                description: "Force terminate a running terminal session.",
+                inputSchema: zodToJsonSchema(ForceTerminateArgsSchema),
+            },
+            {
+                name: "list_sessions",
+                description: "List all active terminal sessions.",
+                inputSchema: zodToJsonSchema(ListSessionsArgsSchema),
+            },
+            {
+                name: "list_processes",
+                description: "List all running processes. Returns process information including PID, " +
+                    "command name, CPU usage, and memory usage.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "kill_process",
+                description: "Terminate a running process by PID. Use with caution as this will " +
+                    "forcefully terminate the specified process.",
+                inputSchema: zodToJsonSchema(KillProcessArgsSchema),
+            },
+            {
+                name: "block_command",
+                description: "Add a command to the blacklist. Once blocked, the command cannot be executed until unblocked.",
+                inputSchema: zodToJsonSchema(BlockCommandArgsSchema),
+            },
+            {
+                name: "unblock_command",
+                description: "Remove a command from the blacklist. Once unblocked, the command can be executed normally.",
+                inputSchema: zodToJsonSchema(UnblockCommandArgsSchema),
+            },
+            {
+                name: "list_blocked_commands",
+                description: "List all currently blocked commands.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            // Filesystem tools
+            {
+                name: "read_file",
+                description: "Read the complete contents of a file from the file system. " +
+                    "Handles various text encodings and provides detailed error messages " +
+                    "if the file cannot be read. Only works within allowed directories.",
+                inputSchema: zodToJsonSchema(ReadFileArgsSchema),
+            },
+            {
+                name: "read_multiple_files",
+                description: "Read the contents of multiple files simultaneously. " +
+                    "Each file's content is returned with its path as a reference. " +
+                    "Failed reads for individual files won't stop the entire operation. " +
+                    "Only works within allowed directories.",
+                inputSchema: zodToJsonSchema(ReadMultipleFilesArgsSchema),
+            },
+            {
+                name: "write_file",
+                description: "Completely replace file contents. Best for large changes (>20% of file) or when edit_block fails. " +
+                    "Use with caution as it will overwrite existing files. Only works within allowed directories.",
+                inputSchema: zodToJsonSchema(WriteFileArgsSchema),
+            },
+            {
+                name: "create_directory",
+                description: "Create a new directory or ensure a directory exists. Can create multiple " +
+                    "nested directories in one operation. Only works within allowed directories.",
+                inputSchema: zodToJsonSchema(CreateDirectoryArgsSchema),
+            },
+            {
+                name: "list_directory",
+                description: "Get a detailed listing of all files and directories in a specified path. " +
+                    "Results distinguish between files and directories with [FILE] and [DIR] prefixes. " +
+                    "Only works within allowed directories.",
+                inputSchema: zodToJsonSchema(ListDirectoryArgsSchema),
+            },
+            {
+                name: "move_file",
+                description: "Move or rename files and directories. Can move files between directories " +
+                    "and rename them in a single operation. Both source and destination must be " +
+                    "within allowed directories.",
+                inputSchema: zodToJsonSchema(MoveFileArgsSchema),
+            },
+            {
+                name: "search_files",
+                description: "Recursively search for files and directories matching a pattern. " +
+                    "Searches through all subdirectories from the starting path. " +
+                    "Only searches within allowed directories.",
+                inputSchema: zodToJsonSchema(SearchFilesArgsSchema),
+            },
+            {
+                name: "get_file_info",
+                description: "Retrieve detailed metadata about a file or directory including size, " +
+                    "creation time, last modified time, permissions, and type. " +
+                    "Only works within allowed directories.",
+                inputSchema: zodToJsonSchema(GetFileInfoArgsSchema),
+            },
+            {
+                name: "list_allowed_directories",
+                description: "Returns the list of directories that this server is allowed to access.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+            {
+                name: "edit_block",
+                description: "Apply surgical text replacements to files. Best for small changes (<20% of file size). " +
+                    "Multiple blocks can be used for separate changes. Will verify changes after application. " +
+                    "Format: filepath, then <<<<<<< SEARCH, content to find, =======, new content, >>>>>>> REPLACE.",
+                inputSchema: zodToJsonSchema(EditBlockArgsSchema),
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        const { name, arguments: args } = request.params;
+        switch (name) {
+            // Terminal tools
+            case "execute_command": {
+                const parsed = ExecuteCommandArgsSchema.parse(args);
+                return executeCommand(parsed);
+            }
+            case "read_output": {
+                const parsed = ReadOutputArgsSchema.parse(args);
+                return readOutput(parsed);
+            }
+            case "force_terminate": {
+                const parsed = ForceTerminateArgsSchema.parse(args);
+                return forceTerminate(parsed);
+            }
+            case "list_sessions":
+                return listSessions();
+            case "list_processes":
+                return listProcesses();
+            case "kill_process": {
+                const parsed = KillProcessArgsSchema.parse(args);
+                return killProcess(parsed);
+            }
+            case "block_command": {
+                const parsed = BlockCommandArgsSchema.parse(args);
+                const blockResult = await commandManager.blockCommand(parsed.command);
+                return {
+                    content: [{ type: "text", text: blockResult }],
+                };
+            }
+            case "unblock_command": {
+                const parsed = UnblockCommandArgsSchema.parse(args);
+                const unblockResult = await commandManager.unblockCommand(parsed.command);
+                return {
+                    content: [{ type: "text", text: unblockResult }],
+                };
+            }
+            case "list_blocked_commands": {
+                const blockedCommands = await commandManager.listBlockedCommands();
+                return {
+                    content: [{ type: "text", text: blockedCommands.join('\n') }],
+                };
+            }
+            // Filesystem tools
+            case "edit_block": {
+                const parsed = EditBlockArgsSchema.parse(args);
+                const { filePath, searchReplace } = await parseEditBlock(parsed.blockContent);
+                await performSearchReplace(filePath, searchReplace);
+                return {
+                    content: [{ type: "text", text: `Successfully applied edit to ${filePath}` }],
+                };
+            }
+            case "read_file": {
+                const parsed = ReadFileArgsSchema.parse(args);
+                const content = await readFile(parsed.path);
+                return {
+                    content: [{ type: "text", text: content }],
+                };
+            }
+            case "read_multiple_files": {
+                const parsed = ReadMultipleFilesArgsSchema.parse(args);
+                const results = await readMultipleFiles(parsed.paths);
+                return {
+                    content: [{ type: "text", text: results.join("\n---\n") }],
+                };
+            }
+            case "write_file": {
+                const parsed = WriteFileArgsSchema.parse(args);
+                await writeFile(parsed.path, parsed.content);
+                return {
+                    content: [{ type: "text", text: `Successfully wrote to ${parsed.path}` }],
+                };
+            }
+            case "create_directory": {
+                const parsed = CreateDirectoryArgsSchema.parse(args);
+                await createDirectory(parsed.path);
+                return {
+                    content: [{ type: "text", text: `Successfully created directory ${parsed.path}` }],
+                };
+            }
+            case "list_directory": {
+                const parsed = ListDirectoryArgsSchema.parse(args);
+                const entries = await listDirectory(parsed.path);
+                return {
+                    content: [{ type: "text", text: entries.join('\n') }],
+                };
+            }
+            case "move_file": {
+                const parsed = MoveFileArgsSchema.parse(args);
+                await moveFile(parsed.source, parsed.destination);
+                return {
+                    content: [{ type: "text", text: `Successfully moved ${parsed.source} to ${parsed.destination}` }],
+                };
+            }
+            case "search_files": {
+                const parsed = SearchFilesArgsSchema.parse(args);
+                const results = await searchFiles(parsed.path, parsed.pattern);
+                return {
+                    content: [{ type: "text", text: results.length > 0 ? results.join('\n') : "No matches found" }],
+                };
+            }
+            case "get_file_info": {
+                const parsed = GetFileInfoArgsSchema.parse(args);
+                const info = await getFileInfo(parsed.path);
+                return {
+                    content: [{
+                            type: "text",
+                            text: Object.entries(info)
+                                .map(([key, value]) => `${key}: ${value}`)
+                                .join('\n')
+                        }],
+                };
+            }
+            case "list_allowed_directories": {
+                const directories = listAllowedDirectories();
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Allowed directories:\n${directories.join('\n')}`
+                        }],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${errorMessage}` }],
+            isError: true,
+        };
+    }
+});

package/dist/terminal-manager.d.ts

@@ -0,0 +1,9 @@
+import { CommandExecutionResult, ActiveSession } from './types.js';
+export declare class TerminalManager {
+    private sessions;
+    executeCommand(command: string, timeoutMs?: number): Promise<CommandExecutionResult>;
+    getNewOutput(pid: number): string | null;
+    forceTerminate(pid: number): boolean;
+    listActiveSessions(): ActiveSession[];
+}
+export declare const terminalManager: TerminalManager;