Semantic Cache MCP
Use Semantic Cache MCP to give an AI coding agent token-efficient, hash-aware file access, search, and editing over a local shared cache.
read: token-efficient reads; first read returns content +content_hash; later reads withknown_hashreturnunchangedor a unified diff; supports ranged reads, line numbers, outlines/maps for large files, and binary metadata.batch_read: read multiple files under a shared token budget, honoring known hashes and skipping files that do not fit.read_image: view supported images as MCP image blocks (PNG, JPEG, GIF, TIFF, BMP, WebP).write,edit,batch_edit,edit_preview,delete: create/replace files, exact or scoped edits, atomic multi-edits, anchor previews, dry runs, diffs/formatting, and cache eviction.warm,grep,search,glob: index files into cache, exact/regex search, BM25 keyword search, and glob discovery with cached status.stats,clear: inspect cache health/token savings and reset the cache without touching project files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Semantic Cache MCP Search for code semantically related to the user authentication flow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Coding agents read the same files over and over: before an edit, after an edit, after every context compaction. A built-in Read sends the whole file each time. Semantic Cache MCP knows what your agent already holds. Measured on one 7,891-token file:
Read | Built-in | Semantic Cache MCP |
First read | 7,891 tokens | full file, plus a hash |
Re-read, file unchanged | 7,891 tokens | 77 tokens |
Re-read after a one-line edit | 7,891 tokens | 137 tokens (a diff) |
Across a 48-file project it saves 98.7% of re-read tokens, and an unchanged read takes 0.17 ms. It also gives your agent grep, BM25 search and glob over the cache, atomic edits with dry_run, and token-budgeted batch reads. Three runtime dependencies, no API keys, no GPU.
Quick start
You need uv. In Claude Code:
claude mcp add semantic-cache --scope user -- uvx semantic-cache-mcpAny other client (Cursor, Claude Desktop, and others that take mcpServers JSON):
{
"mcpServers": {
"semantic-cache": {
"command": "uvx",
"args": ["semantic-cache-mcp"]
}
}
}Configs for VS Code, Codex and OpenCode, and how to turn off the built-in file tools so the agent uses the cache: docs/clients.md.
Related MCP server: Ambiance MCP Server
How it works
Every file the server sends comes with a content_hash. The agent passes it back as known_hash on the next read:
flowchart LR
R["read(path, known_hash)"] --> M{"hash matches<br/>the file now?"}
M -- yes --> U["unchanged<br/>~40 tokens"]
M -- "no, older version" --> D["diff of changed lines"]
M -- "no hash" --> F["full file + content_hash"]No stale content. Every read checks the file on disk first.
unchangedonly answers when the hash matches the current bytes.Forgetting is safe. After a compaction, the agent reads without the hash and gets the full file back.
Large files become maps. A file over
max_sizereturns an outline of its definitions, not a blind cut.Everything stays local. The cache is a SQLite file. One background daemon serves every client on your machine.
Tools
read · batch_read · read_image · write · edit · batch_edit · edit_preview · delete · warm · grep · search · glob · stats · clear
Parameters and examples: docs/tools.md.
FAQ
Is the search "semantic" in the embeddings sense? No. search is BM25 keyword ranking and grep is exact. No model to download, no GPU, no API key.
Does it send my code anywhere? No. The only network request is a one-time download of the o200k tokenizer file, checked against a SHA-256 hash.
Does it work on Windows? Yes. CI runs on Linux and macOS.
Documentation
Guide | Covers |
Setup for each client, turning off built-in file tools | |
Every tool, with parameters and examples | |
Every setting, with defaults | |
Benchmarks and methodology | |
Storage, algorithms, the shared daemon | |
Threat model, size limits, path handling | |
Common issues, debug logging | |
Python API |
Contributing
git clone https://github.com/CoderDayton/semantic-cache-mcp.git
cd semantic-cache-mcp
uv sync --extra dev
uv run pytestSee CONTRIBUTING.md. Issues and pull requests are welcome.
License
MIT.
Available Tools
14 toolsbatch_editBatch EditA
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.
Inputs: path (required), edits (required), dry_run, show_diff, +2 more.
batch_readBatch ReadA
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.
Inputs: paths (required), priority, known_hashes, max_total_tokens.
clearClearA
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.
Inputs: no named parameters.
deleteDeleteA
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.
Inputs: path (required), dry_run.
editEditA
Edit one file by exact text replacement.
Three modes:
find/replace:
old_string+new_string(the default).scoped: add
start_line/end_lineto confine the search to a range.line-range: omit
old_stringand 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.
Inputs: path (required), dry_run, end_line, show_diff, +6 more.
edit_previewEdit PreviewA
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.
Inputs: path (required), old_string (required).
globGlobA
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.
Inputs: pattern (required), directory, cached_only.
grepGrepA
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.
Inputs: pattern (required), path, output, max_files, +4 more.
readReadA
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.
Inputs: path (required), limit, offset, outline, +3 more.
read_imageRead ImageA
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.
Inputs: path (required).
searchSearchA
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.
Inputs: query (required), k, directory, show_preview.
statsStatsA
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.
Inputs: no named parameters.
warmWarmA
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.
Inputs: paths (required), max_files.
writeWriteA
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.
Inputs: path (required), content (required), append, dry_run, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Tools are largely distinct: read vs batch_read (one vs many), edit vs batch_edit (one vs many), edit vs edit_preview (apply vs probe), search (BM25 concept) vs grep (exact/regex), read (text) vs read_image (images). The main soft spot is the discovery cluster (warm, glob, search, grep), which all deal with cached files, but the descriptions draw clear boundaries between indexing and searching.
Names are consistently snake_case and mostly verb-led (read, write, edit, delete, search, warm, grep, clear), with predictable batch_ and edit_preview qualifiers. Minor deviations are the noun-style names stats and glob, which break the verb pattern but remain readable and unambiguous.
14 tools sit comfortably in the well-scoped 3-15 range, and each earns its place by covering a distinct slice of file I/O plus cache management. No redundant or filler tools are present.
Core lifecycle is covered: create (write), read (read/batch_read), update (edit/batch_edit), delete, plus discovery (glob/grep/search/warm) and diagnostics (stats/clear). Gaps like directory creation, move/rename, and symlink operations are minor and workable, but agents needing those will hit dead ends.
Maintenance
Related MCP Connectors
Reduce your AI bills by up to 99% locally: focused code, warm prompt caches & zero secret leaks.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Cuts coding agent token burn up to 72% continuously via contradiction-free memory & verification.
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI coding assistants with context optimization tools including targeted file analysis, intelligent terminal command execution with LLM-powered output extraction, and web research capabilities. Helps reduce token usage by extracting only relevant information instead of processing entire files and command outputs.544 npm63TypeScriptMIT
- AlicenseAqualityDmaintenanceProvides intelligent code context and analysis through semantic compression, AST parsing, and multi-language support. Offers 60-80% token reduction while enabling AI assistants to understand codebases through local analysis, OpenAI-enhanced insights, and GitHub repository integration.626 npm3MIT
- AlicenseNot gradedqualityDmaintenanceProvides file caching and diff tracking for AI coding agents, reducing token usage by returning changes or confirming no changes instead of full file contents on repeated reads.55 npm220MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to query a pre-built semantic knowledge graph of code, reducing token usage and tool calls. Supports 16 tools for code exploration, analysis, and context building.24 npm9MIT