Semantic Cache MCP

Apply many exact edits to one file in a single atomic call. Preferred over repeated `edit` calls on the same file: one response, applied atomically, faster on large files. Partial success is allowed — any failed edits are returned with their reason so you can retry just the misses (status is `edited` when all apply, `partial` when some fail, `no_changes` when none do). A `dry_run` writes nothing and says so: the status becomes `would_edit`/`would_partial` and `dry_run: true` comes back with it. For edits across different files, call the tool once per file. `edits` is a JSON array; each entry is one of: - `[old, new]` — exact find/replace. - `[old, new, start_line, end_line]` — find/replace confined to a range. - `[null, new, start_line, end_line]` — replace that line range wholesale. - `{"old": ..., "new": ..., "start_line": ..., "end_line": ...}` — object form. Prefer line-range entries when you already have line numbers from `read`. Pass `known_hash` and the response carries a claimable `content_hash`, so no read is needed afterwards; without it, or with `auto_format`, you get `file_hash` instead.

Read several files at once under a shared token budget. Cheaper than many single `read` calls. To make files searchable without reading them at all, use `warm` instead — this tool returns their text. Pass `known_hashes` and each file you still hold collapses to an `unchanged` count, or to a diff when it moved on disk; the rest come back in full with their `content_hash`. A file over `max_size` comes back as a map (see `read`) and carries none: a map is not the file. Smallest files are read first, and a file too big for the remaining budget is listed under `skipped` while smaller ones keep being read. Recover anything skipped with `read` using `offset`/`limit`. Paths are relative to the `root` the response names, when there is one worth naming.

Empty the cache. Does not touch any project file. Removes every cached file entry and returns how many were dropped; the next `read`/`batch_read` re-seeds from disk. Use rarely — only to recover from stale cache state or force a cold re-seed. Normal reads already refresh changed files on their own, so this is seldom needed. Takes no arguments.

Delete one file or symlink and evict its cache entries. Use this for explicit single-path removal instead of shelling out. A missing path is reported as status `not_found`, not an error. Statuses: `deleted` (removed), `would_delete` (dry-run preview only, and `dry_run: true` comes back with it), `not_found` (nothing was there). Constraints: one path only — no globs, no recursion, no real-directory deletes. A symlink path deletes the link itself, never its target.

Edit one file by exact text replacement. Three modes: - find/replace: `old_string` + `new_string` (the default). - scoped: add `start_line`/`end_line` to confine the search to a range. - line-range: omit `old_string` and give both lines to replace them wholesale. `old_string` must match exactly — whitespace and indentation included — and, unless `replace_all=true`, must be unique, or the edit fails. Use `edit_preview` first if you're unsure an anchor is unique. Returns the replacement count and the affected line numbers, and refreshes the cache. The diff itself is omitted unless you ask for it with `show_diff`; `diff_state` always tells you which you got. A `dry_run` writes nothing and says so: the status is `would_edit` and `dry_run: true` comes back with it. For several edits to one file use `batch_edit`; for a full rewrite use `write`. Pass `known_hash` and the response carries a claimable `content_hash`, so no read is needed afterwards. Without it, or with `auto_format`, you get `file_hash` instead — editing a file is not the same as having read it.

Show where `old_string` would match in a file, without editing it. Returns the match count, 1-based line numbers, and short snippets so you can confirm an anchor is unique before calling `edit`. Read-only and cheap (kept under ~200 tokens), so use it freely as a probe. Raises an error on a binary file or an empty `old_string`.

List files matching a glob and show which are already cached. Use it to discover files and see what `search`/`grep` can already access before you spend reads. Each match carries a `cached` flag; set `cached_only=true` to list only files already in the cache. Pair it with `batch_read` to pull in whatever isn't cached yet.

Search cached file contents for an exact string or regex. Fast, exact, line-numbered matching over files already in the cache — it does NOT touch disk, so index files first with `warm`, which costs a few dozen tokens however many files it covers (empty results usually mean the files aren't cached). A pattern that is not a valid regex is an error, never an empty result, so zero matches always means zero matches. For concept-level questions where you don't know the exact term, use `search` instead. Counts are complete unless the response says otherwise: if a cap stops the scan, `complete` comes back false with `limit_reached` naming which one, so `total_matches` is never mistaken for the total that exists. Each file's hits come back as `"<line>:<text>"` strings under `lines`, with context lines using `-` instead of `:`. Paths are relative to the `root` the response names, when there is one worth naming. The cache is shared across projects, so a relative `path` — or none — searches only the current project; an absolute `path` reaches files anywhere. A repeated group wrapping an unbounded quantifier (`(a+)+`) is rejected rather than run — it can take exponential time and cannot be interrupted once started. Drop the redundant repeat, or pass `fixed_string=true`.

Read a file, returning as few tokens as possible. For 2+ files, use `batch_read`. The first read returns the file's full content plus a `content_hash`. Echo it back as `known_hash` on every later read: an unchanged file then answers `"unchanged": true` with no body, a changed one returns a unified diff, and without it the file is always sent in full. Reading also caches the file so `grep`, `search`, and `batch_read` can see it. A file larger than `max_size` returns a map instead of its text: the outline below, or for a file with no definitions its first and last lines under `// L<a>-<b>` anchors, flagged `truncated` with `total_lines`. Use `offset`/`limit` to read the exact lines it names. A read that returns only part of a file — a line range, or a map — reports `file_hash` (prefixed `partial:`) rather than `content_hash`, and it cannot be redeemed as `known_hash`. A ranged read also returns a `coverage_token`: pass it back as `known_hash` on your next ranged read and a window you already hold answers `unchanged`; once the windows cover the whole file you get a claimable `content_hash`. For a large or unfamiliar file, `outline=true` is the cheap first read: one line per class/function as `<line>: <signature>`, and every number is an `offset` you can read next. An outline is a map, not the file, so it comes back as `file_hash`. `is_diff` marks a unified diff and `truncated` marks a map. A binary file returns metadata instead of content; for images use `read_image`.

Read an image file so the model can see it. Returns an MCP image block (base64 data + mime type) plus a small JSON metadata sidecar (`size`, `mime`). Use this only when the model needs to view the image; for text or any other file type use `read`. The format is detected from the file's magic bytes, not its extension, so a mis-named image still works and a non-image (e.g. text saved as `.png`) is rejected. Supports PNG, JPEG, GIF, TIFF, BMP, and WebP. Images are never cached — every call re-reads from disk. Oversized images are rejected before encoding; the cap is `SCMCP_MAX_IMAGE_BYTES` (default 5 MiB), bounded by Anthropic's ~5 MB upload limit.

Find cached files by keyword relevance (BM25 ranking). Searches only files already in the cache — index them first with `warm`, which returns counts rather than content (thin results usually mean too few files are cached). Ranks by BM25 term relevance, so multi-word and keyword queries work well; matching is lexical, not embedding-based, so synonyms won't match a word that isn't present. Terms are OR'd — a word the corpus happens not to contain costs you ranking, not the whole result set. For an exact string or regex use `grep`; to pull more of the repo into the cache use `batch_read`. Returns matches with a normalized 0–1 relevance score (best match = 1.0) and a short preview. The cache is shared across projects, so a search with no `directory` ranks the current project only; name one to look elsewhere.

Report cache health, token savings, and runtime diagnostics. Returns storage occupancy (files, tokens, documents, DB size), session and lifetime token savings and cache hit rates, per-tool call counts, and process memory. Use it to measure or debug — not as a routine step in read/edit loops. Takes no arguments.

Index files into the cache so `grep` and `search` can see them, returning counts only. Costs a few dozen tokens however many files it indexes: no content, no previews, no paths for the files that succeeded — just how many were indexed, how many were already current, and how many were not. Anything not indexed is counted in `skipped`, and the first few come back under `failures` with a reason (`not_found`, `not_a_file`, `binary`, `too_large`, `unreadable`, `timeout`). If a cap stopped the walk early you get `truncated` or `incomplete` rather than a short count that looks complete. Use it before searching an unfamiliar tree, then `grep` for the exact string or `search` for the concept, and `read` only what those name.

Create a file or replace its entire contents. Use this for new files or full rewrites; for localized changes prefer `edit` or `batch_edit`. Status is `created` for a new path or `updated` for an existing one; an update reports `diff_state`, and includes the diff against the previous content only when you ask with `show_diff`. A `dry_run` writes nothing and says so: the status is `would_create`/`would_update` and `dry_run: true` comes back with it. Writing refreshes the cache so later reads, `grep`, and `search` see the new text. A full write supplies the whole file, so the `content_hash` it returns is claimable. An append only adds a tail: pass `known_hash` to show you held the rest, or you get `file_hash` instead. `auto_format` reports `file_hash` too — the formatter's output is not what you sent.