jungho-git/fs-mcp

• Shared examples and formatting reference: references/EXAMPLE.md.
• Keep new guidance, snippets, and edits aligned with that file.

---

Purpose

• Keep local workspace work on fs-mcp when the task is about files, paths, search sessions, process sessions, config values, or explicit fs-mcp git flows.
• Separate these surfaces from shell-first build, test, runtime, package, and network work.
• Prefer path-safe, batch-oriented, inspect-before-edit workflows.

---

Scope

• file reads, writes, edits, create, rename, move, and metadata checks
• directory listing and workspace analysis
• structured file and content search, including search-session lifecycle
• local process start, read, interact, and kill flows
• fs-mcp config inspection and updates
• explicit git_* workflows when the task uses the fs-mcp git surface
• tasks that need a clear fs-mcp to shell fallback decision

---

Rules

• Use fs-mcp first for local file operations and workspace analysis.
• Prefer absolute paths when ambiguity is possible.
• Inspect non-destructively before modifying.
• Prefer batch-oriented calls over repeated single-path loops.
• Re-read or re-list the touched surface after modification.
• Keep shell and standard CLIs for build, test, runtime, package, and network work.
• If fs-mcp is unavailable, weaker, or materially less reliable for the task, state the fallback briefly and continue.

---

File Surface

• read_files: bounded multi-file reads or pagination
• list_directories: tree scans before path guesses
• get_file_infos: existence, size, and timestamp checks
• start_searches plus get_search_results: structured repo search
• list_searches plus stop_searches: active search management
• edit_blocks: smallest exact replacement in maintained files
• write_files: new files, append-only changes, or controlled rewrites
• create_directories: explicit directory creation
• move_files or rename_files: explicit path changes instead of shell moves

---

Process Surface

• start_processes: local process launch when the task is file-backed analysis or interactive local tooling
• read_process_outputs: bounded output reads
• interact_with_processes: send input to blocked or long-running processes
• list_sessions and list_processes: inspect active process state before guessing
• kill_processes: stop only the exact process you verified

---

Config Surface

• get_configs: inspect fs-mcp server capabilities or active defaults
• set_config_values: change config only when the task explicitly requires it

---

Git Surface

• Use this surface when the task explicitly calls for fs-mcp git tools or when a structured repo session is more reliable than ad-hoc shell git.
• Start with git_set_working_dir before other git_* calls.
• Keep the chosen repo flow on git_* tools instead of mixing random shell git commands into the same stateful sequence.
• Prefer read-first inspection: git_status, git_diff, git_log, git_show, git_branch, git_remote, git_reflog, git_tag, git_blame.
• Use change and history operations only with explicit need: git_add, git_commit, git_checkout, git_merge, git_rebase, git_cherry_pick, git_reset, git_stash, git_clean, git_fetch, git_pull, git_push, git_worktree, git_clone, git_init, git_wrapup_instructions, git_clear_working_dir.
• Use git_changelog_analyze when the task is changelog or release-note review rather than raw history inspection.

---

Validation

• Re-read edited sections after file changes.
• Re-list touched directories after create, move, rename, or delete actions.
• Confirm search-session state when using long-running searches.
• Confirm process state and recent output before assuming a session is idle or hung.
• Confirm repo state with git_status, git_diff, or other matching git_* inspection after git changes.
• Keep verification scoped to the touched surface and chosen tool path.