Get current per-path file lock status (diagnostic tool).

Returns which file paths currently have active locks - useful for debugging concurrent write contention between Claude Desktop, Cursor, and Windsurf sessions.

Return Format

{"locked_paths": [str], "lock_count": int}

Examples

get_lock_status()

Test that file_ops write/edit locking prevents data corruption under concurrent load.

Simulates num_clients simultaneously writing or editing the same temp file. All should succeed without data corruption if locking is working correctly.

Return Format

{"test_operation": str, "num_clients": int, "successful": int, "errors": [str], "concurrency_safe": bool}

Examples

test_concurrency_safety(operation="write", num_clients=5) test_concurrency_safety(operation="edit", num_clients=10)

Comprehensive file system operations with concurrency-safe writes.

Operations: read_file, write_file, edit_file, delete_file, move_file, copy_file, read_file_lines, read_multiple_files, file_exists, get_file_info, head_file, tail_file, undo_edit, get_file_hash, append_file, touch_file, compress, decompress.

Line indexing: read_file_lines offset is a 0-based line index (0 = first line of the file). The response echoes offset/limit plus first_line_number (1-based number of the first returned line, null when empty) so callers can chain pages via next_steps without guessing.

Write operations (write_file, edit_file, move_file, copy_file) use per-path asyncio.Lock + atomic os.replace() to prevent corruption under concurrent access.

Args: See Parameters block.

Return Format

{"success": bool, "action": str, "message": str, "result": {...}}

• success: whether the operation succeeded

• action: the operation performed (e.g. "read_file")

• message: natural-language summary for the user

• result: operation-specific payload (file content, info dict, moved path, etc.) On failure, returns {"success": false, "error": str, "error_type": str, "suggestions": [...]}.

Examples

file_ops(operation="read_file", path="C:/Users/me/notes.md") file_ops(operation="write_file", path="D:/data/out.txt", content="hello") file_ops(operation="edit_file", path="D:/data/app.py", old_string="foo", new_string="bar") file_ops(operation="copy_file", path="a.txt", destination_path="b.txt")

Directory structure and management operations.

Operations: list_directory, create_directory, remove_directory, directory_tree, calculate_directory_size, find_empty_directories, copy_tree, move_directory.

Args: See Parameters block.

Return Format

{"success": bool, "action": str, "message": str, "result": {...}}

• result for list_directory: {"items": [...], "total": int}

• result for calculate_directory_size: {"size_bytes": int, "human_readable": str}

Examples

dir_ops(operation="list_directory", path="D:/Dev/repos", recursive=True) dir_ops(operation="directory_tree", path="D:/Dev/repos/arxiv-mcp/src", max_depth=2) dir_ops(operation="calculate_directory_size", path="D:/data", human_readable=True)

Content Analysis, Grep, and Comparison operations.

Operations: grep_file, count_pattern, search_files, extract_log_lines, compare_files, find_duplicate_files, find_large_files, find_todos, find_symbols, validate_json, analyze_project, run_linter, validate_config. find_todos, find_symbols, validate_json.

Pattern semantics (read this before picking an operation):

• grep_file / count_pattern take a CONTENT regex searched inside file text.

• search_files takes a FILENAME glob (fnmatch, e.g. ".py", "test_") matched against file names only — it never looks at file content. For content search across a tree, use grep_file with recursive=True.

Args: See Parameters block.

Return Format

{"success": bool, "action": str, "message": str, "result": {...}}

• grep_file: {"matches": [{"file": str, "line": int, "text": str}], "count": int}

• count_pattern: {"count": int}

• compare_files: {"diff": str, "lines": int}

Examples

search_ops(operation="grep_file", path="D:/Dev/repos", search_pattern="assfix", recursive=True) search_ops(operation="find_large_files", path="D:/data", min_size_mb=500) search_ops(operation="compare_files", path="a.txt", path2="b.txt")

Docker Container Lifecycle operations.

Operations: list_containers, get_container, create_container, start_container, stop_container, restart_container, remove_container, container_exec, container_logs, container_stats.

Args: See Parameters block.

Return Format

{"success": bool, "action": str, "message": str, "result": {...}}

• list_containers: {"containers": [{"id", "name", "image", "status", ...}]}

• container_logs: {"logs": str}

• container_stats: {"stats": {...}}

Examples

container_ops(operation="list_containers", show_stats=True) container_ops(operation="container_logs", container_id="my-app", tail=50) container_ops(operation="restart_container", container_id="db", timeout=10)

Docker Images, Networks, and Volumes operations.

Operations: list_images, get_image, pull_image, build_image, remove_image, prune_images, list_networks, get_network, create_network, remove_network, prune_networks, list_volumes, get_volume, create_volume, remove_volume, prune_volumes.

Args: See Parameters block.

Return Format

{"success": bool, "action": str, "message": str, "result": {...}}

• list_images: {"images": [{"id", "name", "tag", "size", ...}]}

• pull_image: {"status": str, "image": str}

• list_volumes: {"volumes": [{"name", "driver", ...}]}

Examples

infra_ops(operation="list_images", all_images=True) infra_ops(operation="pull_image", image="nginx", tag="alpine") infra_ops(operation="create_network", name="app-net", driver="bridge")

Start Compose services (docker compose up).

Recovery: If build fails, fix Dockerfile/context; if ports conflict, edit compose or stop conflicting services.

Idempotency: Re-running up is generally safe; may recreate containers per compose semantics.

Return Format

{"success": bool, "action": str, "message": str, "result": {"output": str, "stderr": str}} On failure: {"success": false, "error": str, "recovery_options": [...]}

Examples

compose_up(path="D:/dev/myapp") compose_up(path="D:/dev/myapp", services=["web", "db"], build=True)

Stop and remove Compose containers (docker compose down).

Recovery: If down fails (e.g. bind mounts in use), stop consumers or use docker CLI for force removal.

Return Format

{"success": bool, "action": str, "message": str, "result": {"output": str, "stderr": str}} On failure: {"success": false, "error": str, "recovery_options": [...]}

Examples

compose_down(path="D:/dev/myapp") compose_down(path="D:/dev/myapp", volumes_prune=True)

List compose services as JSON (docker compose ps --format json).

Return Format

{"success": bool, "action": str, "message": str, "result": {"output": str, "stderr": str}} result.output: JSON string from docker compose.

Examples

compose_ps(path="D:/dev/myapp") compose_ps(path="D:/dev/myapp", all_services=True)

Fetch service logs (docker compose logs).

Recovery: If logs empty, verify service names with compose_ps.

Return Format

{"success": bool, "action": str, "message": str, "result": {"output": str, "stderr": str}} On failure: {"success": false, "error": str, "recovery_options": [...]}

Examples

compose_logs(path="D:/dev/myapp", tail=100) compose_logs(path="D:/dev/myapp", services=["web"], since="2026-08-01T00:00:00")

Render and validate compose configuration (docker compose config).

Args: See Parameters block.

Return Format

{"success": bool, "action": str, "message": str, "result": {"output": str, "stderr": str}} result.output: rendered YAML.

Examples

compose_config(path="D:/dev/myapp") compose_config(path="D:/dev/myapp", validate=False)

Restart compose services (docker compose restart).

Return Format

{"success": bool, "action": str, "message": str, "result": {"output": str, "stderr": str}} On failure: {"success": false, "error": str, "recovery_options": [...]}

Examples

compose_restart(path="D:/dev/myapp") compose_restart(path="D:/dev/myapp", services=["web"])

Snapshot of OS, CPU count, load, memory, optional disk/network and top processes.

Recovery: If psutil raises AccessDenied, retry with fewer options or run with appropriate permissions.

Return Format

{"success": bool, "result": {"timestamp": str, "system": str, "release": str, "cpu_count": int, "cpu_usage_percent": float, "memory": {...}, "disk": {...}, "processes": [...], "network": {...}}}

Examples

monitor_get_system_status() monitor_get_system_status(include_processes=True, max_processes=20)

CPU, memory, root disk usage, and boot time.

Idempotency: Read-only; safe to retry.

Return Format

{"success": bool, "result": {"cpu_percent": float, "memory": {...}, "disk": {...}, "boot_time": str}}

Examples

monitor_get_resource_usage()

List running processes with optional substring filter on the process name.

Args: See Parameters block.

Recovery: AccessDenied on some PIDs is normal; total_matching reflects filtered list.

Return Format

{"success": bool, "result": {"processes": [{"pid", "name", "cpu_percent", "memory_percent"}], "total_matching": int}}

Examples

monitor_get_process_info(max_processes=10, sort_by="memory_percent") monitor_get_process_info(filter_pattern="python", max_processes=20)

Detailed CPU times, memory, swap, disk I/O, and network I/O counters.

Return Format

{"success": bool, "result": {"cpu_times": {...}, "virtual_memory": {...}, "swap_memory": {...}, "disk_io": {...}, "net_io": {...}}}

Examples

monitor_get_performance_metrics()

Virtual and swap memory breakdown.

Return Format

{"success": bool, "result": {"virtual": {...}, "swap": {...}}}

Examples

monitor_get_memory_info()

Core counts, optional frequency, and per-CPU usage.

Return Format

{"success": bool, "result": {"physical_cores": int, "total_cores": int, "frequency": {...} | None, "usage_per_cpu": [float]}}

Examples

monitor_get_cpu_info()

Per-partition usage (skips mounts that raise PermissionError).

Return Format

{"success": bool, "result": {"partitions": [{"device", "mountpoint", "usage"}]}}

Examples

monitor_get_disk_usage()

Aggregate I/O counters and per-interface addresses and stats.

Return Format

{"success": bool, "result": {"io_counters": {...}, "addresses": {...}, "stats": {...}}}

Examples

monitor_get_network_info()

Host System Context (Info, Env, Help, User).

Operations: get_help, get_system_info, get_environment_info, get_security_info, get_hardware_info, get_software_info, get_time_info, get_locale_info, get_user_info, get_session_info, get_service_status, get_log_info.

Args: See Parameters block.

Return Format

{"success": bool, "action": str, "message": str, "result": {...}}

• result for get_system_info: {"platform", "python", "machine", "cpu_cores", "memory_total"}

• result for get_environment_info: {"variables": {...}}

Examples

host_ops(operation="get_help", category="filesystem") host_ops(operation="get_system_info", detailed=True) host_ops(operation="get_environment_info")

Execute agentic file workflows using FastMCP 2.14.5+ sampling (no tools).

Gathers file system context server-side, then uses ctx.sample() to have the LLM analyze and reason about it. Compatible with Claude Desktop which supports basic sampling but not sampling.tools capability.

Args: See Parameters block.

Return Format

{"success": bool, "operation": str, "summary": str, "result": {"workflow_prompt", "steps_executed", "results", "notes", "execution_summary"}, "quality_metrics": {...}, "recommendations": [...], "next_steps": [...]} On failure: {"success": false, "error": str, "error_type": str, "recovery_options": [...], "diagnostic_info": {...}}

Recovery: If NO_CONTEXT, run from an MCP client that injects Context. If SAMPLING_ERROR, shorten the prompt or check server logs; verify the host supports ctx.sample().

Examples

agentic_file_workflow(workflow_prompt="Find and summarize all TODO comments in src/", available_tools=["search_ops"]) agentic_file_workflow(workflow_prompt="Rename all .bak files in D:/data to .old", available_tools=["file_ops", "dir_ops"])

Shut down the filesystem-mcp server process gracefully.

Schedules an orderly exit after a short delay so in-flight responses can flush. Intended for the HTTP daemon; stdio instances exit when the parent closes the stream anyway.

Return Format

{"success": bool, "operation": "shutdown", "result": {"shutdown_in_seconds": int}}

Examples

server_shutdown(confirm=True)