{"id":"9806ab96-b811-4bdd-aac6-29d28bbf7064","slug":"sandraschi-filesystem-mcp","kind":"mcp","name":"filesystem-mcp","summary":"FastMCP 3.2.0+ server plus webapp for comprehensive file system operations, Git repository management, Docker container control, and developer tools for Claude Desktop integration.","owner":"sandraschi","repoUrl":"https://github.com/sandraschi/filesystem-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":7,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-09-23T21:00:34.000Z","addedAt":"2026-10-21T04:06:00.565Z","logoUrl":"https://avatars.githubusercontent.com/u/34750307?u=166281f79cd1114c24ba073dc02fd578660cbff0&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","files-documents","developer-tools"],"tags":["fastmcp-3","webapp"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T18:37:16.786Z","sample":false,"url":"https://conduits.dev/tools/sandraschi-filesystem-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"filesystem-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Filesystem MCP\n\n

\n \"Just\"\n \"Ruff\"\n \"Python\"\n \"Biome\"\n \"FastMCP\"\n

\n\n\n> ๐Ÿ“– **[Installation Guide](INSTALL.md)** โ€” quick start, manual setup, and troubleshooting\n\n> **Status**: Production-ready ยท 24 tools ยท Dual transport (stdio + HTTP) ยท Port 10742\n> **Reliability**: Self-cleaning startup โ€” kills orphaned stdio processes from stale IDE sessions\n\nA **FastMCP 3.2.0+ compliant** MCP server using the **portmanteau pattern** for comprehensive file system operations, content search, and code intelligence with concurrency safety. Git lives in `git-github-mcp`; Docker is deprecated here in favor of `docker-mcp`.\n\n> [!IMPORTANT]\n> **Dual Architecture**: Filesystem MCP operates as both a high-concurrency **stdio/HTTP MCP Server** and a dedicated **React Webapp** (Port 10743) for real-time visualization and management.\n\n## Quick Start\n\n```powershell\ngit clone https://github.com/sandraschi/filesystem-mcp\ncd filesystem-mcp\njust\n```\n\nThis opens an interactive dashboard showing all available commands. Run `just bootstrap` to install dependencies, then `just serve` or `just dev` to start.\n\n### Manual Setup\n\nIf you don't have `just` installed:\n\n## What can you do with it?\n\nBeyond read/write/list โ€” the nonobvious actions agents reach for:\n\n**Verify instead of trusting**\n```python\nfile_ops(operation=\"get_file_hash\", path=\"dist/app.zip\") # streamed sha256, never loads whole file\nsearch_ops(operation=\"validate_config\", path=\"config.yaml\") # json/yaml/toml/ini, precise error + line\nsearch_ops(operation=\"run_linter\", path=\"src/\", fix=True) # ruff check --fix, read-only unless fix=True\n```\n\n**Understand a codebase in two calls**\n```python\nsearch_ops(operation=\"analyze_project\", path=\".\") # type, markers, frameworks, top extensions\nsearch_ops(operation=\"find_symbols\", path=\"src\", search_pattern=\"auth\", recursive=True) # defs, not grep noise\nsearch_ops(operation=\"find_todos\", path=\"src\", recursive=True) # TODO/FIXME/HACK/XXX/BUG with file:line\n```\n\n**Move bulk safely**\n```python\ndir_ops(operation=\"copy_tree\", path=\"D:/data\", destination_path=\"E:/backup\", dry_run=True) # preview first\ndir_ops(operation=\"copy_tree\", path=\"D:/data\", destination_path=\"E:/backup\", engine=\"robocopy\") # fast lane, Windows\nfile_ops(operation=\"compress\", path=\"D:/data\") # zip without shelling out\nfile_ops(operation=\"append_file\", path=\"app.log\", content=\"line\") # locked append, no read-modify-write race\n```\n\n**Undo and self-help**\n```python\nfile_ops(operation=\"undo_edit\", path=\"config.json\") # restore pre-edit .bak in one call\nhost_ops(operation=\"get_help\", tool_name=\"search_ops\") # every tool documents itself; try it first\n```\n\n## Deployment & Security\nBuilt with modern Python patterns, enterprise-grade security, and extensive testing for professional deployment.\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| Backend | Python 3.12, FastMCP 3.4+, FastAPI/Starlette, uvicorn, structlog, psutil, GitPython |\n| Frontend | React 19, Vite 7, TailwindCSS 3, Lucide, Framer Motion, Zustand, Radix UI |\n| Desktop | Tauri 2 (Rust), NSIS installer, embedded PyInstaller backend |\n| Tooling | uv, just, ruff, Biome, pytest, pre-commit, Playwright |\n\n## Features\n\n### File System Operations (20+ Tools)\n- **Concurrency-Safe Operations**: Atomic file writes with proper locking for multi-client access\n- **Basic Operations**: Read, write, list, copy, move, and delete files/directories\n- **Advanced Analysis**: Find large files, duplicate detection, directory size calculation\n- **File Comparison**: Side-by-side diff comparison with unified format\n- **Content Search**: Grep pattern matching, line-based reading, log extraction\n- **Batch Operations**: Process multiple files simultaneously\n- **Path Management**: Secure path validation with configurable restrictions\n- **Metadata Analysis**: Comprehensive file information with type detection\n- **Universal Connect**: FastMCP 3.2.0+ support for simultaneous stdio + HTTP access\n\n### Docker Container Management\n- **Container Operations**\n - List, create, start, stop, and remove containers\n - Execute commands inside running containers\n - Stream container logs with filtering options\n - Monitor container resource usage and statistics\n - Inspect container details and configuration\n\n- **Image Management**\n - List available Docker images\n - Pull, build, and remove images\n - Inspect image details and history\n\n- **Network & Volume Management**\n - Create and manage Docker networks\n - Manage Docker volumes and bind mounts\n - Configure container networking\n\n- **Docker Compose Support**\n - Deploy and manage multi-container applications\n - Scale services up and down\n - View service logs and status\n\n### Git Repository Management\n- Clone repositories with branch and depth control\n- Get repository status (staged, unstaged, untracked changes)\n- Commit changes with custom messages\n- Read repository structure and file contents\n- Manage branches and remotes\n\n### System Tools & Help\n- **Multilevel Help System**: Hierarchical documentation with portmanteau tool examples and use cases\n- **System Status Tool**: Comprehensive system monitoring with resource usage metrics\n- **Interactive Guidance**: Context-aware help with parameter validation and suggestions\n\n### Advanced Features\n- **FastMCP 3.2.0+ Compliance**: Modern tool registration with `@app.tool()` decorators\n- **Portmanteau Pattern**: Consolidated tool interfaces reducing complexity while maintaining full functionality\n- **Enterprise Security**: Path traversal protection, permission validation, audit trails\n- **Extensive Testing**: Unit, integration, and performance tests with 80%+ coverage\n- **MCPB Packaging**: Professional drag-and-drop installation for Claude Desktop\n- **Structured Logging**: Comprehensive logging with file output and monitoring\n- **Async Operations**: Full async/await support for optimal concurrency\n- **Pydantic V2**: Modern data validation with `field_validator` and `ConfigDict`\n- **Multilevel Help System**: Interactive guidance with portmanteau tool examples and use cases\n- **System Monitoring**: Resource usage tracking and performance metrics\n- **Cross-Platform**: Windows, macOS, and Linux support\n\n## Installation\n\n### Prerequisites\n- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)\n- Python 3.12+\n\n### Quick Start\nRun immediately via `uvx`:\n```bash\nuvx filesystem-mcp\n```\n\n### Claude Desktop Integration\nAdd to your `claude_desktop_config.json`:\n```json\n\"mcpServers\": {\n \"filesystem-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"D:/Dev/repos/filesystem-mcp\", \"run\", \"filesystem-mcp\"]\n }\n}\n```\n### Prerequisites\n- **Python 3.12+** (FastMCP 3.2.0+ requirement)\n- **Docker Engine** (for container operations)\n- **Git** (for repository operations)\n\n### PyPI Package Install (RECOMMENDED)\n\n**Fastest Installation - Production Ready:**\n\n```bash\npip install filesystem-mcp\n```\n\n**Claude Desktop Integration:**\n- Open Claude Desktop\n- Settings MCP Servers\n- Add new MCP server:\n ```json\n {\n \"mcpServers\": {\n \"filesystem-mcp\": {\n \"command\": \"filesystem-mcp\"\n }\n }\n }\n ```\n\n### Claude Desktop MCPB Package\n\nOne-line install (Claude Desktop):\n\n```powershell\niwr https://github.com/sandraschi/filesystem-mcp/releases/latest/download/install.ps1 -UseBasicParsing | iex\n```\n\nOr manually:\n\n1. **Download** the `filesystem-mcp.mcpb` package from [Releases](https://github.com/sandraschi/filesystem-mcp/releases)\n2. **Drag & Drop** the file to Claude Desktop\n3. **Configure** settings when prompted (working directory, timeouts, etc.)\n4. **Start using** 24 professional tools immediately\n\n## Installation\n\n### Prerequisites\n- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)\n- Python 3.12+\n\n### Quick Start\nRun immediately via `uvx`:\n```bash\nuvx filesystem-mcp\n```\n\n### Claude Desktop Integration\nAdd to your `claude_desktop_config.json`:\n```json\n\"mcpServers\": {\n \"filesystem-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"D:/Dev/repos/filesystem-mcp\", \"run\", \"filesystem-mcp\"]\n }\n}\n```\n## Installation\n\n### Prerequisites\n- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)\n- Python 3.12+\n\n### Quick Start\nRun immediately via `uvx`:\n```bash\nuvx filesystem-mcp\n```\n\n### Claude Desktop Integration\nAdd to your `claude_desktop_config.json`:\n```json\n\"mcpServers\": {\n \"filesystem-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"D:/Dev/repos/filesystem-mcp\", \"run\", \"filesystem-mcp\"]\n }\n}\n```\n### HTTP/HTTPS Mode (For Web Apps)\n\nFor web applications or custom MCP clients, run the server in HTTP mode:\n\n```bash\n# Set environment variables\nexport MCP_TRANSPORT=http\nexport MCP_HOST=127.0.0.1 # or 0.0.0.0 for all interfaces\nexport MCP_PORT=8000\n\n# Run the server\npython -m filesystem_mcp\n```\n\nOr use uvicorn directly with the ASGI app:\n\n```python\nfrom filesystem_mcp import http_app\nimport uvicorn\n\n# Get ASGI app\nasgi_app = http_app()\n\n# Run with uvicorn\nuvicorn.run(asgi_app, host=\"127.0.0.1\", port=8000)\n```\n\nOr via command line:\n```bash\nuvicorn filesystem_mcp:http_app --host 127.0.0.1 --port 8000\n```\n\nThe MCP endpoint will be available at: `http://127.0.0.1:8000/mcp/`\n\n**Quick test:**\n```bash\ncurl http://127.0.0.1:8000/mcp/\n```\n\n### Manual Claude Desktop Configuration\n\nFor manual installation or other MCP clients, add to your Claude Desktop configuration file (`claude_desktop_config.json`):\n\n**Windows:**\n```json\n{\n \"mcpServers\": {\n \"filesystem-mcp\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"filesystem_mcp\"],\n \"env\": {\n \"PYTHONPATH\": \"D:\\\\path\\\\to\\\\filesystem-mcp\\\\src\",\n \"PYTHONUNBUFFERED\": \"1\",\n \"FASTMCP_LOG_LEVEL\": \"INFO\"\n },\n \"cwd\": \"D:\\\\path\\\\to\\\\your\\\\working\\\\directory\"\n }\n }\n}\n```\n\n**macOS/Linux:**\n```json\n{\n \"mcpServers\": {\n \"filesystem-mcp\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"filesystem_mcp\"],\n \"env\": {\n \"PYTHONPATH\": \"/path/to/filesystem-mcp/src\",\n \"PYTHONUNBUFFERED\": \"1\",\n \"FASTMCP_LOG_LEVEL\": \"INFO\"\n },\n \"cwd\": \"/path/to/your/working/directory\"\n }\n }\n}\n```\n\n**Configuration Notes:**\n- Replace `D:\\\\path\\\\to\\\\filesystem-mcp\\\\src` with the actual path to your cloned repository's `src` directory\n- Set `cwd` to your preferred working directory for file operations\n- The server supports the following optional environment variables:\n - `MCP_TRANSPORT`: Set to `\"http\"` for HTTP mode, `\"stdio\"` for stdio mode (default: `\"stdio\"`)\n - `MCP_HOST`: Host address for HTTP mode (default: `\"127.0.0.1\"`)\n - `MCP_PORT`: Port number for HTTP mode (default: `8000`)\n - `FASTMCP_LOG_LEVEL`: Set to `DEBUG`, `INFO`, `WARNING`, or `ERROR`\n - `GIT_USERNAME`: Default Git username for commits\n - `GIT_EMAIL`: Default Git email for commits\n\n## Installation\n\n### Prerequisites\n- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)\n- Python 3.12+\n\n### Quick Start\nRun immediately via `uvx`:\n```bash\nuvx filesystem-mcp\n```\n\n### Claude Desktop Integration\nAdd to your `claude_desktop_config.json`:\n```json\n\"mcpServers\": {\n \"filesystem-mcp\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"D:/Dev/repos/filesystem-mcp\", \"run\", \"filesystem-mcp\"]\n }\n}\n```\n## Help System & Status Tools\n\n### System Operations (portmanteau)\n\n**Unified system tool** with 20+ operations:\n- **Help**: `get_help` - Multilevel help system with tool documentation\n- **Status**: `get_system_status` - Comprehensive system monitoring\n- **Resources**: `get_resource_usage`, `get_cpu_info`, `get_memory_info`, `get_disk_usage`\n- **Processes**: `get_process_info` - Process monitoring and management\n- **Network**: `get_network_info` - Network interface information\n- **System Info**: `get_system_info`, `get_hardware_info`, `get_software_info`\n- **Environment**: `get_environment_info`, `get_locale_info`, `get_time_info`\n- **Security**: `get_security_info` - Basic security information\n- **Performance**: `get_performance_metrics` - System performance monitoring\n\n```python\n# Get comprehensive help\nresult = system_operations(\"get_help\", category=\"filesystem\")\n\n# Monitor system status\nresult = system_operations(\"get_system_status\", include_processes=True, include_disk=True)\n\n# Get resource usage\nresult = system_operations(\"get_resource_usage\")\n```\n\n### Multilevel Help System\nGet comprehensive guidance for all portmanteau tools:\n\n```python\n# Overview of all categories and tools\nsystem_operations(\"get_help\")\n\n# Detailed help for filesystem operations\nsystem_operations(\"get_help\", category=\"filesystem\")\n\n# Specific tool documentation with examples\nsystem_operations(\"get_help\", category=\"filesystem\", tool_name=\"filesystem_operations\")\n```\n\n**Help Categories:**\n- `filesystem` - File reading, writing, directory management, search, analysis\n- `docker` - Container, image, network, and volume management\n- `repository` - Git repository operations (clone, commit, branch, merge, etc.)\n- `system` - System monitoring, status, and help functionality\n\n### System Status Monitoring\nMonitor system resources and server health:\n\n```python\n# Comprehensive system status\nsystem_operations(\"get_system_status\")\n\n# Resource monitoring only\nsystem_operations(\"get_system_status\", include_processes=True, include_disk=True)\n\n# Network and system info\nsystem_operations(\"get_system_status\", include_network=True)\n```\n\n**Status Metrics:**\n- CPU usage (physical/logical cores, frequency, load)\n- Memory statistics (total, available, usage percentage)\n- Disk usage (total, used, free space)\n- Process information (top CPU consumers)\n- Network interfaces (IP addresses, status)\n- Server health (FastMCP version, tool count, status)\n\n## Usage\n\n### Starting the Server\n\n```bash\n# Start the MCP server (default: http://0.0.0.0:8000)\npython -m filesystem_mcp\n\n# With custom host and port\npython -m filesystem_mcp --host 127.0.0.1 --port 8080\n\n# With debug mode enabled\npython -m filesystem_mcp --debug\n```\n\n### Available Portmanteau Tools\n\n#### Filesystem Operations (portmanteau)\n\n**Unified filesystem tool** with 20+ operations:\n- **file_ops**: Comprehensive file management (`read_file`, `write_file`, `edit_file`, `move_file`, `undo_edit`).\n - **Honed Editing**: Support for Regex, Multi-occurrence, Indentation Normalization, and Atomic Batch Edits.\n - **Reversion**: Rapid undo capability via `.bak` file restoration.\n- `calculate_directory_size`, `find_duplicate_files`, `find_large_files`\n- `find_empty_directories`, `compare_files`, `read_multiple_files`\n- `move_file`, `read_file_lines`, `search_files`\n\n#### `edit_file`\nPrecise text replacement with context validation and advanced matching.\n\n**Parameters**:\n- `path` (str): Target file path.\n- `old_string` (str): Text to find.\n- `new_string` (str): Replacement text.\n- `allow_multiple` (bool): If true, replaces all occurrences. Default: `false`.\n- `is_regex` (bool): If true, treats `old_string` as a regex pattern. Default: `false`.\n- `ignore_whitespace` (bool): If true, matches regardless of indentation. Default: `false`.\n- `replacements` (list): Batch mode! List of `{old_string, new_string}` for atomic multi-chunk edits.\n\n#### `undo_edit`\nReverts the most recent edit to a file by restoring its `.bak` backup.\n\n**Parameters**:\n- `path` (str): Target file path.\n\n```python\n# Read a file\nresult = filesystem_operations(\"read_file\", path=\"README.md\")\n\n# List directory contents\nresult = filesystem_operations(\"list_directory\", path=\".\", recursive=True)\n\n# Search for files\nresult = filesystem_operations(\"search_files\", directory_path=\".\", pattern=\"*.py\")\n```\n\n#### Docker Operations (portmanteau)\n\n**Unified Docker tool** with 25+ operations:\n- **Container**: `list_containers`, `get_container`, `create_container`, `start_container`, `stop_container`, `restart_container`, `remove_container`, `container_exec`, `container_logs`, `container_stats`\n- **Images**: `list_images`, `get_image`, `pull_image`, `build_image`, `remove_image`, `prune_images`\n- **Networks**: `list_networks`, `get_network`, `create_network`, `remove_network`, `prune_networks`\n- **Volumes**: `list_volumes`, `get_volume`, `create_volume`, `remove_volume`, `prune_volumes`\n- **Compose**: `compose_up`, `compose_down`, `compose_ps`, `compose_logs`, `compose_config`, `compose_restart`\n\n```python\n# List running containers\nresult = docker_operations(\"list_containers\")\n\n# Create and start a container\nresult = docker_operations(\"create_container\", image=\"nginx:latest\", name=\"web\", ports={\"80/tcp\": 8080})\nresult = docker_operations(\"start_container\", container_id=\"web\")\n\n# Get container logs\nresult = docker_operations(\"container_logs\", container_id=\"web\", tail=100)\n```\n\n#### Repository Operations โ€” moved\n\nGit lives in `git-github-mcp` (`gitops:git_core` / `gitops:github_ops`). No git tools are registered here anymore.\n\n#### Developer Tools โ€” live as search_ops\n\n`find_todos`, `find_symbols`, `validate_json`, `analyze_project`,\n`run_linter` (ruff-only), `validate_config` are live `search_ops` operations\n(read-only, tested). Still roadmap: `analyze_dependencies`, `analyze_imports`;\n`check_file_sizes`/`detect_duplicates` already exist as `find_large_files`/`find_duplicate_files`.\nUsage: `search_ops(operation='find_todos', path='src', recursive=True)` โ€” not `developer_tool(...)`.\n\n| Command | Description | Key Parameters |\n|---------|-------------|----------------|\n| `analyze_dependencies` | Analyze project dependencies from package managers | `path` |\n| `analyze_imports` | Analyze Python import statements and dependencies | `path`, `recursive`, `max_results` |\n| `analyze_project` | Detect project type, frameworks, and structure | `path`, `output_format` |\n| `check_file_sizes` | Analyze file sizes and identify large files | `path`, `recursive`, `max_results` |\n| `detect_duplicates` | Find duplicate files by content hash | `path`, `recursive`, `max_results` |\n| `find_symbols` | Search for function/class definitions and usages | `path`, `pattern`, `recursive` |\n| `find_todos` | Find TODO/FIXME comments in codebase | `path`, `recursive`, `max_results` |\n| `run_linter` | Execute code linting (ruff, flake8, eslint) | `path`, `fix`, `encoding` |\n| `validate_config` | Validate configuration files (JSON/YAML/TOML/INI) | `path` |\n| `validate_json` | Parse and validate JSON files with structure analysis | `path` |\n\n**Usage:**\n```python\n# Find all TODO comments (live)\ntodos = search_ops(operation='find_todos', path='src', recursive=True)\n\n# Find function definitions (live)\nsymbols = search_ops(operation='find_symbols', path='src', search_pattern='auth', recursive=True)\n\n# Validate JSON (live)\nvalid = search_ops(operation='validate_json', path='glama.json')\n\n# Roadmap (not yet): analyze_dependencies, analyze_imports\n```\n\n### Example Usage\n\n```python\nfrom filesystem_mcp import app\n\n# Get a list of available portmanteau tools\ntools = app.list_tools()\nprint(f\"Available portmanteau tools: {', '.join(tools.keys())}\")\n\n# Example: Filesystem operations\ntry:\n # Read a file\n result = tools[\"filesystem_operations\"](\"read_file\", path=\"README.md\")\n print(f\"File content: {result['content'][:200]}...\")\n\n # List directory contents\n result = tools[\"filesystem_operations\"](\"list_directory\", path=\".\", recursive=False)\n print(f\"Directory contents: {len(result['files'])} items\")\n\n # Search for Python files\n result = tools[\"filesystem_operations\"](\"search_files\", directory_path=\".\", pattern=\"*.py\")\n print(f\"Found {result['total_matches']} Python files\")\n\nexcept Exception as e:\n print(f\"Filesystem error: {e}\")\n\n# Example: Docker operations\ntry:\n # List running containers\n result = tools[\"docker_operations\"](\"list_containers\")\n print(f\"Running containers: {len(result['containers'])}\")\n\n # Get container details\n if result['containers']:\n container_id = result['containers'][0]['id']\n details = tools[\"docker_operations\"](\"get_container\", container_id=container_id)\n print(f\"Container {container_id}: {details['container']['status']}\")\n\nexcept Exception as e:\n print(f\"Docker error: {e}\")\n\n# Example: Repository operations live in git-github-mcp (gitops), not here.\n# See gitops:git_core (status, log, diff, commit, push, pull, clone, ...).\n\n# Example: System operations\ntry:\n # Get system status\n result = tools[\"system_operations\"](\"get_system_status\", include_processes=True)\n print(f\"CPU usage: {result['cpu']['usage_percent']}%\")\n print(f\"Memory usage: {result['memory']['percent']}%\")\n\n # Get help information\n result = tools[\"system_operations\"](\"get_help\", category=\"filesystem\")\n print(f\"Available filesystem operations: {len(result.get('tools', {}))}\")\n\nexcept Exception as e:\n print(f\"System error: {e}\")\n```\n\n## Development\n\n### Project Structure\n\n```text\nfilesystem-mcp/\n .github/ # GitHub workflows and templates\n docs/ # Documentation files\n filesystem_mcp/ # Main package\n __init__.py # Package initialization\n app.py # FastAPI application setup\n config.py # Configuration management\n models/ # Pydantic models\n tools/ # Tool implementations\n __init__.py # Tool registration\n file_operations/ # File system tools\n docker_operations/ # Docker management tools\n repo_operations/ # Git repository tools\n utils/ # Utility functions\n tests/ # Test suite\n .gitignore # Git ignore rules\n LICENSE # MIT License\n pyproject.toml # Project configuration and dependencies\n README.md # This file\n requirements-dev.txt # Development dependencies\n```\n\n### Running Tests\n\n```bash\n# Install test dependencies\npip install -r requirements-dev.txt\n\n# Run all tests\npytest\n\n# Run tests with coverage report\npytest --cov=filesystem_mcp --cov-report=term-missing\n\n# Run specific test file\npytest tests/test_docker_operations.py -v\n```\n\n### Code Style & Quality\n\nThis project enforces code quality using:\n\n- **Black** - Code formatting\n- **isort** - Import sorting\n- **mypy** - Static type checking\n- **pylint** - Code quality analysis\n\n```bash\n# Format code with Black\nblack .\n\n# Sort imports with isort\nisort .\n\n# Type checking with mypy\nmypy .\n\n# Lint with pylint\npylint filesystem_mcp/\n```\n\n### Building and Releasing\n\n1. Update the version in `pyproject.toml`\n2. Update `CHANGELOG.md`\n3. Commit changes with a message like \"Bump version to x.y.z\"\n4. Create a git tag: `git tag vx.y.z`\n5. Push the tag: `git push origin vx.y.z`\n6. GitHub Actions will automatically build and publish the package to PyPI\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report issues, or suggest new features.\n\n\n## ๐Ÿ›ก๏ธ Industrial Quality Stack\n\nThis project adheres to **SOTA 14.1** industrial standards for high-fidelity agentic orchestration:\n\n- **Python (Core)**: [Ruff](https://astral.sh/ruff) for linting and formatting. Zero-tolerance for `print` statements in core handlers (`T201`).\n- **Webapp (UI)**: [Biome](https://biomejs.dev/) for sub-millisecond linting. Strict `noConsoleLog` enforcement.\n- **Protocol Compliance**: Hardened `stdout/stderr` isolation to ensure crash-resistant JSON-RPC communication.\n- **Automation**: [Justfile](./justfile) recipes for all fleet operations (`just lint`, `just fix`, `just dev`).\n- **Security**: Automated audits via `bandit` and `safety`.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a history of changes to this project.\n\n## Topics\n\n`filesystem` `mcp-server` `fastmcp` `file-operations` `docker` `system-monitoring`\n`python` `mcp` `model-context-protocol` `portmanteau` `concurrency-safe`\n\n\n## Webapp Dashboard\n\nThis MCP server includes a free, premium web interface for monitoring and control.\nBy default, the web dashboard runs on port **10742**.\n*(Assigned ports: **10742** (Backend (was 13000)), **10743** (Frontend (was 13001)))*\n\nTo start the webapp:\n1. Navigate to the `webapp` (or `web`, `frontend`) directory.\n2. Run `start.bat` (Windows) or `./start.ps1` (PowerShell).\n3. Open `http://localhost:10742` in your browser.\n"}