fs_replace
Find-and-replace text in a single file, server-side. No read-modify-write cycle from the client. Archives the current contents as a new version before writing (same retention as fs_write), so fs_restore can roll back.
Literal string match (not regex). Only works on text files. A single find that matches nothing returns replacements: 0 and writes nothing.
Several edits to one file: pass edits, an ordered array of { "find", "replace", "expect"? } (at most 200), instead of top-level find/replace. They apply in order (a later edit sees the earlier ones) and save as ONE new version. In the array every edit must match: the first that does not returns FIND_NOT_FOUND with zero-based data.edit_index and writes nothing; expect: n requires exactly n matches, else FIND_COUNT_MISMATCH with data.expected and data.actual. One call edits one file.
Example:
{ "project_id": "my-saas", "path": "/src/config.ts", "find": "API_URL = 'https://staging...'", "replace": "API_URL = 'https://api...'" }
// Returns: { "ok": true, "replacements": 1, "version": 4 }
{ "project_id": "my-saas", "path": "/notes/todo.md", "edits": [{ "find": "- [ ] ship", "replace": "- [x] ship", "expect": 1 }, { "find": "Status: draft", "replace": "Status: done" }] }
// Returns: { "ok": true, "replacements": 2, "edits": [{ "edit_index": 0, "replacements": 1 }, { "edit_index": 1, "replacements": 1 }], "version": 5 }Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project_id": "<project_id>",
"path": "<path>"
},
"name": "fs_replace"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| find | No | Exact string to find (non-empty). Omitted when `edits` is sent. | |
| path | Yes | Full path to the file with leading slash. | |
| edits | No | Ordered edits to this one file, saved as one new version. Every edit must match or nothing is written (FIND_NOT_FOUND with data.edit_index). Exclusive with top-level find/replace. | |
| replace | No | Replacement string (may be empty to delete matches). Omitted when `edits` is sent. | |
| project_id | Yes | Project ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them). |