Read a file, returning as few tokens as possible. For 2+ files, use batch_read.

The first read returns the full numbered content plus a content_hash. A later read of an unchanged file returns "unchanged": true with no body (you already have it); a changed file returns a unified diff. Reading also caches the file so grep, search, and batch_read can see it.

Whenever you re-read a file you have read before, pass back known_hash (the content_hash from your last read of it). It is the server's only proof that you still hold the content, so use it every time you can; the server then skips re-sending unchanged bytes. Use offset/limit to read or recover an exact line range, for example after a large file was summarized. 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.

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.

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), 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.

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, and an update returns a unified diff against the previous content. Writing refreshes the cache so later reads, grep, and search see the new text. The response carries the new content_hash; pass it back as read's known_hash to get unchanged instead of re-reading the file you just wrote. Missing parent directories are created unless create_parents=false.

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, affected line numbers, and a unified diff, and refreshes the cache. For several edits to one file use batch_edit; for a full rewrite use write.

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.

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). 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.

Find cached files by keyword relevance (BM25 ranking).

Searches only files already in the cache — seed them first with read/batch_read (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. 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.

Read several files at once under a shared token budget.

The efficient way to seed the cache before search/grep, and cheaper than many single read calls. New files return full content, changed files return a diff, and files already in your context are reported as unchanged with no body. Smallest files are read first; once the budget is spent the rest are listed under skipped — recover them with read using offset/limit.

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 seed files first with batch_read/read (empty results usually mean the files aren't cached). For concept-level questions where you don't know the exact term, use search instead.