Venira Mcp

List files/directories in the workspace. depth 1..3 shows the tree in a single call. Use when: you need to see the directory tree, check a path, or list files before reading. Avoid when: you only need one file's metadata (project_get_file_info) or one file's contents (project_read_file). Speed: fast; TTL cache 1.5s, auto-wiped on write/edit/delete. Output: file_list: entries, truncated, hint. Batch-safe: yes

Read a text file, optionally by line range (1-based). The result carries next_start_line when truncated. Use when: you need the contents of one file, or one line range of a large file. Avoid when: you need to read 2+ files (project_read_batch) or only need metadata (project_get_file_info). Speed: very fast on repeat; cache validated by mtime+size. Output: file_read: text, first_line, last_line, total_bytes, next_start_line. Batch-safe: yes

File/directory metadata (kind, size, modification time). Use when: you only need size/mtime/kind, or want to check that a path exists. Avoid when: you need the file's contents (project_read_file). Speed: very fast; cache validated by mtime+size. Output: file_info: relative_path, kind, size_bytes, modified_unix_seconds. Batch-safe: yes

Search by file name, directory name, content (literal or regex=1), or symbol declaration lines (definition). Use when: you need to find code/strings/symbols before reading; use kind=literal_content or definition. Avoid when: you already know the exact path to read. Speed: medium (file scan); TTL cache 3s for the same query. Output: search: hits (source+confidence when hybrid:1), complete, diagnostics, hint. Batch-safe: yes

List files modified most recently in the workspace, newest first, plus session_edits (files you already wrote this session). Cheap orientation call: use it at the start of a task, when resuming, before editing a file the user may have changed, and after shell/build/git steps to see what really changed (bounded filesystem scan, skips node_modules/target/.git). Use when: starting or resuming a task, checking what the user or a command just changed (after shell/build/format/git), re-orienting after context loss, or picking the next files to feed into project_read_batch. Prefer it over listing a whole tree. Avoid when: you need the full list / by name (project_list_files) or content search (project_search). Speed: medium (filesystem walk); TTL cache 2s, bounded to 4000 files / 300 directories. Output: recent_files: entries[] sorted by mtime desc, scanned_files, truncated. Batch-safe: no

Run up to 8 READ-ONLY ops (list_files, read_file, get_file_info, search) in one call; read/info use the cache so repeats are very fast. Each item takes the same arguments as the standalone tool, including numeric 0/1 flags (e.g. search regex, case_sensitive, hybrid). Use when: you need to read 2+ files/ops in the same step (reading context, scanning several files). Avoid when: there is only a single op; or you need a mutating op (use the corresponding tool). Speed: fastest for read-heavy work; sequential + cached, with a response budget. Output: read_batch: responses[] (each item is an ok/error envelope). Batch-safe: yes

Write a file. mode=create errors if it exists; overwrite replaces existing contents; append concatenates. Create and verify a scoped project_snapshot before overwriting existing file contents. Use when: create a new file or append content; before mode=overwrite on an existing file, create a scoped project_snapshot, confirm it captured the target, and keep the returned id. Avoid when: only a small section needs to change (project_edit_file), or an existing file would be overwritten without a verified pre-write project_snapshot. Speed: fast; clears the read/list/search cache for the affected path. Output: file_written: action, bytes_written, sha256_after. Batch-safe: no

Edit a file by exact text replacement: one old_text/new_text pair, or edits[] for multiple sections. Supports TOCTOU guard mode (guard=sha256) for atomic read-edit-verify cycle. Use when: change one or a few text sections whose exact content you know; pair with expected_sha256 to guard against blind overwrites. Use guard=sha256 for atomic read-edit-verify. Before editing 2+ files or 2+ sections, create a scoped project_snapshot and confirm coverage. Avoid when: the whole file must change (project_write_file), or you have not read the file to know old_text. Speed: fast; clears the read/list/search cache for the affected path. Output: file_written: replacements, sha256_before/after, verified (with guard=sha256). Batch-safe: no

Apply multiple edit_file operations atomically in one call; aborts after the first failure and restores the pre-batch snapshot when possible. Use when: before editing existing files in a multi-edit batch, create a scoped project_snapshot when it spans multiple files/sections or needs rollback after later checks. Batch rollback covers an in-batch failure only; it does not undo a successful batch after tests fail. Avoid when: a single edit (project_edit_file) or a whole-file rewrite (project_write_file). Speed: depends on item count; each runs edit_file and clears caches. Output: batch: responses[] {ok, response|error}, atomic metadata with executed/skipped indexes and rollback status. Batch-safe: no

Delete a file or directory (directories require recursive=1). Create and verify a scoped snapshot before using this irreversible tool; do not delete if the checkpoint is incomplete. Use when: only after creating a scoped project_snapshot for the exact target, confirming file_count/truncated/skipped cover the intended files, and keeping its id for recovery. Avoid when: the target is ambiguous or a pre-delete snapshot is missing, truncated, or skipped the target. This op is not undoable; capture and verify a checkpoint first. Speed: fast; clears the read/list/search cache. Output: path_deleted: entries_deleted, bytes_deleted. Batch-safe: no

Run a shell command (cwd defaults to /workspace/mcp-validate). Asynchronous by default: returns run_id immediately, so poll project_shell_status for the output. Pass background=0 (or false) for a foreground run: the call blocks until the command exits and returns the final stdout/stderr. For commands that overwrite/delete existing workspace source files, create and verify a scoped project_snapshot first; prefer project file tools for targeted edits. Commands pass a policy gate: risky ones return an approval_required error with a pending approval_id; catastrophic ones are denied outright. Named overrides require operator allowlisting and a per-call reason. Use when: build/test/lint/long-running commands. For hard-to-reverse workspace file changes, checkpoint first. Default (background=1) returns run_id immediately so it never blocks other tools; set background=0 when you need the final output in this call — it blocks until the command exits, and you must not start other work while waiting. After approval_required, ask the user to approve the approval_id in an interactive terminal, then retry. Avoid when: a command that may never finish: use the async default plus project_shell_status/project_shell_cancel. Speed: background=1 returns in ~5 ms, run time is up to the command; background=0 blocks for the whole run (bounded by timeout_ms, default 10 min). Output: shell_run: run_id/shell_id, running, exit_code, background/foreground, stdout_tail/stderr_tail, timed_out, policy; background=0 also returns bounded stdout/stderr. approval_required: rule, reason, approval_id, retry_with. Batch-safe: no

Check status + output of a running command. wait_seconds (0..30) is an observation window, not a timeout. Use when: after project_shell_run; poll until running=false. Avoid when: no run_id available yet. Speed: fast; not queued so it never blocks other tools. Output: shell_run: running, exit_code, stdout_tail/stderr_tail. Batch-safe: no

Cancel a running shell command by run_id. Use when: the command is running too long or its result is no longer needed. Avoid when: the command already finished (check with project_shell_status). Speed: fast; kills the whole process tree so grandchildren do not keep running. Output: cancellation: accepted, cleanup_complete. Batch-safe: no

Create a directory OR a file in ONE call. For an existing file, mode=overwrite replaces its contents: create and verify a scoped project_snapshot first. Use when: create a directory or new file; if replacing an existing file, first create a scoped project_snapshot, confirm it captured the target, and keep its id. Avoid when: editing an existing file (project_edit_file/project_write_file); never use mode=overwrite unless a pre-write project_snapshot covers the existing contents. Speed: fast; triggers cache invalidation on write / new directory. Output: directory_created or file_written (data kind depends on the op). Batch-safe: no

Server diagnostics: corehost/data dir/audit DB, capability, queue depth, cache hit-rate, running shells, p50/p95 metrics, plus a security-limit notice (guard rail, not sandbox). Use when: debugging slowness/errors, checking the backend/DB/audit before reporting, or inspecting this session's cache/metrics. Avoid when: you just need to read/write files normally. Speed: fast (~a few ms + 1 audit DB query); set include_audit=0 to skip the DB query. Output: health: notice, server, corehost, capability, queue, caches, shells, metrics, audit. Batch-safe: no

Clear in-process read/search/list/recent/search/shell/graph caches. Use after a toolchain generates files outside normal write flow, or to force fresh reads. Use when: force-fresh reads after external tooling mutated files, or the cache stats show high hit/miss pressure. Avoid when: normal flow (cache invalidates on write/edit/delete). Speed: instant; clears LRU/TTL maps only (no backend call). Output: cache_clear: type, cleared per-cache entry counts. Batch-safe: no

Show the most recent traced tool calls from the in-memory buffer (last N) plus the trace configuration. Use when: VENIRA_TRACE=1 and you want to see what ran recently without reading the log file. Avoid when: tracing is disabled (returns an empty buffer) or you need the full on-disk log (read VENIRA_TRACE_FILE instead). Speed: instant; in-memory buffer only, no I/O. Output: trace_status: enabled, file, buffered, recent[] (newest last). Batch-safe: yes

Read recent rows from the SQLite audit log (WAL). Filter by session/operation/outcome; bounded by limit. Use when: you need to inspect what operations were recorded (audit trail) — e.g. compliance or debugging a prior action. Avoid when: you only need the live cache/metric report (project_health include_audit=1) — that one is faster. Speed: fast; one bounded SQLite read (readonly, WAL-safe). Output: audit_read: rows[] (newest first), count, truncated, db_path. Batch-safe: yes

Cancel ALL shell runs tracked in this session (kills every process tree). Use to cleanly tear down a session. Use when: a session is ending or a stuck session has many running commands and they must all be stopped. Avoid when: only one run needs cancelling (project_shell_cancel by run_id). Destructive: running commands are killed. Speed: fast; iterates the in-process shell run table and kills each tree. Output: shell_cancel_session: cancelled_run_ids[], count. Batch-safe: no

Takes no parameters.

Parse a source file and return its symbol outline (functions, classes, types, interfaces) with line numbers. Use when: you need to see the structure / top-level symbols of a file before reading or refactoring it. Avoid when: you need every usage of a symbol (project_symbol_references) or a text-only diff (project_diff_files). Speed: fast; single-file regex scan, no external indexer. Output: outline_symbol: total_symbols, symbols[] {name, kind, line, signature}. Batch-safe: yes

Unified (git-style) diff between two workspace files. Reports lines_added/lines_removed and the full hunk text. Use when: comparing two versions of a file, or reviewing changes before/after an edit. Avoid when: the two files are in different languages or one is binary; large binaries are not supported. Speed: medium; LCS-based diff over the two full texts, bounded by max_lines. Output: diff_files: lines_added, lines_removed, unified_diff, truncated. Batch-safe: yes

Find every occurrence of a named symbol. scope=file (fast, single file) or scope=workspace (uses content search). Use when: you need to know where a symbol is used before renaming/refactoring it. Avoid when: you only need its declaration (project_outline_symbol) or an arbitrary string (project_search). Speed: fast for scope=file; medium for scope=workspace (single search call). Output: symbol_references: count, references[] {relative_path, line_number, context}. Batch-safe: yes

Smart multi-query search: combine several patterns with AND/OR/NOT + fuzzy scoring. Bounded to a file set you pass in. Use when: you need to rank many files by how well they match several keywords at once (e.g. locating the right module among candidates). Avoid when: you need a single exact literal (project_search) or to inspect one file's content (project_read_file). Speed: medium; reads a bounded set of files (files_hint or a shallow listing) and scores each line. Output: selective_search: hits[] {relative_path, line_number, text, score, matched}, total_files, total_hits, truncated. Batch-safe: yes

Build a deterministic file/symbol dependency graph for TypeScript/JavaScript, Python, Rust, Go, Java and Kotlin (module declarations, pub mod, use crate::/super::, extern crate, go.mod module resolution, import (...) blocks, relative imports, require(), dynamic import(), extends/implements, cross-file symbol references). Renders as JSON, DOT or Mermaid. Use when: you need the import graph, a module map to render, or the files/symbols a change can reach before refactoring. Avoid when: you only need usages of one symbol in one file (project_symbol_references) or a text search (project_search). Speed: medium; bounded walk (<=5000 files / 64 MB), parser-lite line scan, 5 s index cache invalidated on writes. No network. Output: dependency_graph: nodes[] {id, type, language, loc}, edges[] {from, to, type (import|extends|implements|references), confidence, line, via}, external[] {id, used_by}, unresolved[], stats, truncated; format=dot|mermaid returns data.graph. Batch-safe: yes

Answer "if I change these files/symbols, what depends on them?" with a bounded reverse (or forward) closure: affected files, distance, path, reason and confidence, plus affected symbols and a separate test count. Use when: before renaming/changing a function or file, to list the dependents you should read/test (direction=dependents), or the dependencies a module relies on. Avoid when: you need the whole graph (project_dependency_graph) or exact textual usages in one file (project_symbol_references). Speed: medium; reuses the dependency index (5 s cache, invalidated on writes), BFS bounded by depth. No network. Output: change_impact: seed {files, symbols}, affected[] {id, distance, path, reason, confidence, symbols?}, unresolved[], summary {affected_files, affected_symbols, max_distance, tests_affected}, truncated; format=mermaid returns data.graph. Batch-safe: yes

Detect which MCP-client harnesses (OpenCode/Claude/Cursor/Codex/Kimi/DeepSeek/Antigravity) have a config on this machine. Use when: before installing venira, to know which client configs exist and can be updated. Avoid when: you already know the config path (skip straight to project_install_self). Speed: fast; filesystem checks, no writes. Output: harness_detect: detected[] (found harnesses), harnesses[] {harness, detected, config_path, format, note}. Batch-safe: yes

Takes no parameters.

Add the venira MCP entry to a target client's config (OpenCode/Claude/Cursor/Codex/Kimi/DeepSeek/Antigravity). Atomic + backup. Use when: a user asks to 'install venira into <client>' — add the MCP server block to that client's config file. Avoid when: the config path is unknown (run project_detect_harnesses first), or the user wants a dry-run (set dry_run=1). Speed: fast; one atomic write per config. Always backs up the original to <file>.venira-bak. Output: install_self: {harness, config_path, status (installed|already_present|config_missing|error), needs_restart, error?}. Batch-safe: no

Diagnose a failure from its error text / log tail: known signatures (errno, TypeScript, Python, git, npm, GitHub, venira codes) → likely cause + ready-to-send next tool calls. Rule-based, offline, instant. Use when: a command, test, build or provider call failed and you want the fastest route to the fix (feed it the stderr tail or the CI log tail). Avoid when: you already know the cause and only need the file contents (use project_read_file, which also accepts ranges). Speed: pure local rules, < 1 ms; no network and no model call. Output: explain_error: matched, summary, error_line, language, diagnoses[] {rule_id, title, likely_cause, suggested_fix[], retry_hint?, next_actions[]}, next_actions[]. Batch-safe: yes

Plan a read: extract keywords from the task, run bounded content + file-name searches (+recent files), rank candidate source files by hits, path/name match and prose weight (build output, DB/log artifacts excluded), and return a ready project_read_batch call with a calibrated estimate. Deterministic planner, no model call. Use when: starting a task in an unfamiliar area and you do not know which files matter yet (one call instead of guess-read-repeat). Avoid when: you already know the exact files (call project_read_batch directly), or the task is a one-line lookup (project_search). Speed: 1-3 bounded content searches (~20 ms each) + local ranking; no file contents are returned. Output: plan_read_batch: task, keywords[], searched, candidates[] {relative_path, reason, hits}, steps[] {tool, arguments, why}, estimated_ms, notes. Batch-safe: yes

Checkpoint/rollback for the workspace: create a labeled, scoped snapshot before multi-file or hard-to-reverse edits; keep its returned id. For rollback, preview with restore dry_run=1 (size-based preview only; it cannot detect same-size content changes), inspect newer user edits, then restore that exact id with verify=1 and delete_extra=0. Content-addressed and deduplicated. Use when: before multi-file, cross-file, refactor/rename or hard-to-reverse edits: create with a descriptive label, scope paths to the affected area, retain the exact returned id, and confirm required files were captured. For rollback, run restore dry_run=1 to preview path/size changes (same-size content differences are not detected); inspect files with newer user edits, then restore the exact id with verify=1 and delete_extra=0. Example: checkpoint → edit 3 files → tests fail → inspect scope → restore. Avoid when: a tiny, easily recreated single-file edit, generated build output, or a commit already provides the needed recovery point; do not restore over newer user changes without inspecting them. Speed: create walks/hashes the captured files (skips .git/node_modules/dist, symlinks, huge files); repeats only store new blobs. restore is atomic per file, concurrency 4, SHA-256 verified by default; dry_run previews path/size only, not same-size content changes. Output: snapshot_create: id, label, file_count, total_bytes, new_blob_bytes, skipped[], truncated; snapshot_list: checkpoints[]; snapshot_restore: restored_count/restored[], deleted_count, skipped[]; snapshot_delete: deleted, bytes_freed; snapshot_mirror: status, copied_blobs, copied_indexes, bytes, failed[] (needs VENIRA_SNAPSHOT_MIRROR_DIR); snapshot_create adds mirror{} when configured. Batch-safe: no

Connect GitHub through its Device Flow. The user authorizes at github.com; access and refresh tokens are saved in the encrypted local vault and are never returned. Use when: the user wants to connect or replace the local GitHub credential without pasting a token into chat. Avoid when: the user only needs GitHub public read access or has already configured a token. Speed: start returns a short-lived verification code; poll only at the interval GitHub specifies. Output: github_connect: start returns verification_uri, user_code, pending_id and expiry; poll returns pending, denied, expired or connected (never a token). Batch-safe: no

Manage API tokens/credentials without leaking them: values are encrypted at rest and never returned by default. Inject them into commands with project_shell_run secret_env=["NAME"] instead of pasting them into a command line. Rotation metadata (expiry, last use, use count) is tracked by default and expired secrets are refused. Use when: storing a non-GitHub token (action=set), checking whether one exists or is due for rotation (action=get / action=list), removing one (action=delete). Then use secret_env on project_shell_run or the built-in GitHub tools. Avoid when: the value is a normal, non-secret config (put it in .env or the config file); or you need the plaintext printed (only with reveal=1 + VENIRA_SECRET_ALLOW_REVEAL=1). Speed: fast; encrypted AES-256-GCM store, atomic writes, values decrypted only when injected. Expiry/use fields are metadata only. Output: secret_set: name, length, sha256_12, updated_at, expires_at, days_left, created, rotated; secret_get/list: metadata only (expires_at, expired, days_left, last_used_at, use_count, rotated_at); secret_delete: deleted. Batch-safe: no