MCP Server for Software Development

An MCP server that provides filesystem and shell access to Claude desktop.

Architecture

Claude ←→ MCP Server ←→ Unix Socket ←→ Filesystem Daemon
       (2 tools)      (JSON RPC)     (file operations, shell)

Key Benefits

• ✅ Single permission prompt (2 tools vs 15+ in original)
• ✅ Environment control (daemon runs with proper venv/directory)
• ✅ Terminal visibility (all operations logged with context)
• ✅ Dynamic discovery (operations auto-documented)
• ✅ Rich error handling (detailed errors with suggestions)
• ✅ Type safety (parameter schemas with validation)

Quick Start

1. Start the filesystem daemon (in your target directory):

   python fs_access.py           # Normal mode
   python fs_access.py --verbose # Verbose mode (shows shell output, file contents, edit details)
   

2. Connect Claude to the MCP server via configuration:

   {
     ...
     "mcpServers": {
       "Dev": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "fastmcp",
           "$path/mcp-server-dev/mcp_server.py"
         ]
       }
     }
   }
   

3. Test the integration:

   • Check that Dev is visible in the "search and tools" menu in Claude Desktop
   • Run the filesystem access server and talk to Claude to see if it can use the tools.

MCP Tools Available to Claude

1. get_available_operations()

• Purpose: Discover available filesystem operations and their schemas
• Returns: Dict with operation schemas including types, descriptions, defaults

2. execute_fs_operation(operation, params)

• Purpose: Execute a filesystem operation via the daemon
• Parameters:
  • operation: Name of operation (string)
  • params: Parameters for the operation (dict)
• Returns: Dict with success status, result/error, and logs

Available Operations

File Operations

ls(path=".")

List files and directories in the specified path.

• Example: execute_fs_operation("ls", {})
• Example: execute_fs_operation("ls", {"path": "/tmp"})

read_file(path)

Read file contents as UTF-8 string.

• Example: execute_fs_operation("read_file", {"path": "README.md"})

write_file(path, content)

Write content to file (creates or overwrites).

• Example: execute_fs_operation("write_file", {"path": "test.txt", "content": "Hello world!"})

edit_file(path, changes)

Apply search/replace operations to file.

• Example:

execute_fs_operation("edit_file", {
    "path": "config.py",
    "changes": [
        ["DEBUG = False", "DEBUG = True"],
        ["localhost", "production.com"]
    ]
})

Directory Management

mkdir(path)

Create directory and any necessary parent directories.

• Example: execute_fs_operation("mkdir", {"path": "project/src/utils"})

rmdir(path)

Remove directory and all its contents recursively (use with caution!).

• Example: execute_fs_operation("rmdir", {"path": "temp_project"})

File & Directory Management

rm(path)

Remove a file or empty directory.

• Example: execute_fs_operation("rm", {"path": "unwanted_file.txt"})
• Example: execute_fs_operation("rm", {"path": "empty_dir"}) (only if empty)

mv(src, dst)

Move or rename files and directories.

• Example: execute_fs_operation("mv", {"src": "old_name.txt", "dst": "new_name.txt"})
• Example: execute_fs_operation("mv", {"src": "temp", "dst": "project/temp"})

Shell Commands

shell(command, args=[], timeout=30)

Execute shell commands and return stdout, stderr, exit_code.

• Example: execute_fs_operation("shell", {"command": "git", "args": ["status"]})
• Example: execute_fs_operation("shell", {"command": "python", "args": ["--version"]})
• Example: execute_fs_operation("shell", {"command": "find", "args": [".", "-name", "*.py"], "timeout": 60})
• Returns: {"stdout": "...", "stderr": "...", "exit_code": 0, "command": "...", "working_directory": "..."}

Error Handling

• Connection errors: Daemon not running → helpful hints provided
• Invalid operations: Lists available operations with signatures
• File errors: Detailed error types (FileNotFoundError, PermissionError, etc.)
• Parameter errors: Type validation and requirements checking

Usage Pattern for Claude

1. Discovery: Call get_available_operations() to see what's available
2. Execution: Call execute_fs_operation(operation_name, params_dict)

Core Files

• fs_access.py - Filesystem daemon with all operations
• mcp_server.py - MCP server providing Claude interface
• socket_protocol.py - Unix socket communication layer
• shell_examples.py - Example shell commands