Semantic Cache MCP

Read a file. Automatically returns the most token-efficient response.

Use this for a single file. For 2+ files, prefer batch_read.

Behavior (automatic — no configuration needed):

• First read: returns full content and seeds the cache.

• Unchanged re-read: returns "unchanged": true (content already in context).

• Modified re-read: returns a unified diff of changes.

• External changes: detected automatically via mtime + content hash.

If response contains "unchanged": true, do NOT re-read — you already have the full content from a prior read. Use offset/limit to recover specific line ranges after truncation or context loss.

Args: path: File path (absolute or relative to project root). Use absolute paths for files outside the current project root. max_size: Maximum content size to return before summarization. offset: 1-based starting line number for targeted reads. limit: Number of lines to return from offset.

Inspect cache health, token savings, and runtime diagnostics.

Use this for debugging or measurement, not as a normal step in routine read/edit loops.

Returns cache occupancy, hit rates, token savings, tool-call counts, embedding model info, and process memory usage.

Clear the semantic cache only; does not modify project files.

Use this rarely, mainly to recover from stale cache state or to force cold re-seeding. Prefer normal read/batch_read refresh behavior when possible.

Returns the number of cached entries removed.

Delete one file or one symlink path and evict cache entries for that path.

Use this for explicit single-path removal instead of shelling out.

Normal statuses:

• deleted: file or symlink path was removed

• would_delete: dry-run preview only

• not_found: path did not exist; this is not an error

Constraints:

• No globs

• No recursive delete

• No real-directory delete

• If path is a symlink, deletes the link itself, not the target

Args: path: File or symlink path (absolute or relative to project root). dry_run: Preview without deleting or evicting cache.

Create or replace a file, with cache refresh and overwrite diffs.

Use this when you already know the full new file content. For targeted changes inside an existing file, prefer edit or batch_edit.

Routing rules:

• New file or full replacement: use write.

• Small localized change: use edit.

• Multiple localized changes in one file: use batch_edit.

Behavior:

• Overwrites return a diff when useful.

• New files return creation status.

• append=true supports chunked construction for large files.

• dry_run=true previews without writing.

• auto_format=true is best used near the end of an edit cycle.

Args: path: File path to create or replace. content: Full content to write, or appended content when append=true. create_parents: Create missing parent directories when needed. dry_run: Preview without writing. auto_format: Run formatter after write. append: Append instead of overwrite.

Edit one file using cache-aware exact replacement.

Prefer this over write when you want to preserve the rest of the file. Use line numbers from read whenever possible to keep the edit precise.

Modes:

• Find/replace: old_string + new_string

• Scoped replace: add start_line + end_line

• Line-range replace: omit old_string, provide start_line + end_line

Routing rules:

• One localized change: use edit

• Multiple independent changes in the same file: use batch_edit

• Full-file rewrite: use write

Precision rules:

• Keep old_string exact and as short as possible, ideally one line.

• If a match is ambiguous, add more context or line bounds.

• Use replace_all=true only when every match should change.

Args: path: File path to modify. old_string: Exact text to find. Omit only for line-range replacement. new_string: Replacement text. replace_all: Replace all matches instead of requiring uniqueness. dry_run: Preview without writing. auto_format: Run formatter after editing. start_line: 1-based inclusive start line for scoped or line-range edit. end_line: 1-based inclusive end line for scoped or line-range edit.

Apply multiple exact edits to one file in a single call.

Use this when several independent edits belong in the same file. For one change, prefer edit. For cross-file work, call the relevant tools per file instead of trying to batch across files.

Supported entry forms:

• [old, new] for full-file exact replacement

• [old, new, start_line, end_line] for scoped replacement

• [null, new, start_line, end_line] for line-range replacement

• {"old": ..., "new": ..., "start_line": ..., "end_line": ...}

Behavior:

• Partial success is allowed.

• Failed edits are returned so you can retry only the misses.

• Prefer line-range entries when you already have line numbers from read.

Args: path: File path to modify. edits: JSON array of edit entries for that file. dry_run: Preview without writing. auto_format: Run formatter after edits.

Search cached files by meaning or mixed keyword intent.

This is a cache-only semantic search. If results are empty, the likely cause is that the relevant files were never seeded with read or batch_read.

Routing rules:

• Use search for meaning-based queries such as concepts, behavior, or intent.

• Use grep for exact symbols, strings, or regex patterns.

• Use glob to discover candidate files before seeding the cache.

Usage guidance:

• Seed likely files with batch_read first.

• Start with small k such as 3–5.

• Use directory to keep large codebases focused.

Args: query: Natural-language query, keywords, or a mixture of both. k: Maximum number of matches to return. directory: Optional directory filter applied after retrieval.

Compare two files side by side and return a unified diff.

Use this for explicit file-to-file comparison. For "what changed since I last read this file?", use read instead of diff.

Behavior:

• Returns unified diff plus semantic similarity score.

• Reuses cached content when possible.

• Large diffs may be suppressed to stay within token budget.

Args: path1: First file path. path2: Second file path. context_lines: Number of context lines to include around changes.

Read multiple files under a token budget. Automatically cache-aware.

Use this to seed the cache, gather several files at once, or expand globs before search, similar, or grep. Prefer over repeated read calls.

Behavior (automatic — no configuration needed):

• Unchanged files listed in summary.unchanged (already in context).

• Modified files return diffs.

• New files return full content.

• Large files skipped once token budget is exhausted.

If a file is skipped for budget, use read with offset/limit or raise the budget.

Args: paths: Comma-separated paths, JSON array, or glob patterns. max_total_tokens: Token budget across the batch. priority: Optional paths to read first before the remaining files.

Find cached files semantically similar to one source file.

Use this to discover related implementations, tests, or configs after the surrounding code has already been seeded into the cache.

Important constraint:

• The source file is handled automatically.

• Candidate neighbor files must already be cached, typically via batch_read, or they will not appear.

Usage guidance:

• Seed a directory with batch_read first.

• Start with k=3 to k=5.

• Empty results usually mean either only the source file is cached or the relevant neighbors were never seeded.

Args: path: Source file path. k: Maximum number of similar files to return.

Discover files by glob and show whether each one is already cached.

Use this before batch_read, search, similar, or grep when you need candidate files or want to inspect cache coverage.

Routing rules:

• Use glob to discover paths.

• Use batch_read to seed or read them.

• Use cached_only=true when you want to know what search/grep can already see without more reads.

Usage guidance:

• Keep patterns specific.

• Avoid broad patterns like **/* unless truly necessary.

• Matches can be fed directly into batch_read.

Args: pattern: Glob pattern to expand. directory: Base directory for the glob. cached_only: Restrict results to already cached files.

Search cached files for an exact string or regex, with line numbers.

This is the cache-only exact-search tool. It is intentionally closer to "ripgrep on cached content" than to live filesystem search.

Routing rules:

• Use grep for exact symbols, literals, imports, error strings, or regex.

• Use search for semantic or fuzzy intent.

• Seed candidate files with batch_read first; empty results may simply mean the relevant files are not cached yet.

Usage guidance:

• Set fixed_string=true for literals containing regex metacharacters.

• Add path to limit scope to one file, a suffix, or a glob.

• Add context_lines=2 or 3 when surrounding code matters.

Args: pattern: Regex pattern, or a literal if fixed_string=true. path: Optional exact path, suffix, or glob filter. fixed_string: Treat pattern as a literal instead of regex. case_sensitive: Whether matching is case-sensitive. context_lines: Number of context lines to include around matches. max_matches: Maximum total matches across all files. max_files: Maximum number of files to return.