# Vinv (npm · vinv-mcp)

Vinv runs, tests, and finds issues in your services — with zero code changes.

- Trust score: 44/100 (low)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-22

## Components

- npm · `vinv-mcp`: 44/100 (this document), [markdown](https://verifymcp.io/servers/vinvai-vinv/vinv-mcp.md), [page](https://verifymcp.io/servers/vinvai-vinv/vinv-mcp)

## Channel facts

- Registry: `npm`
- Package: `vinv-mcp`
- Version: `0.0.5`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-22.

- **Supply Chain Security**: 13/100
  - Malware scan not yet available for this package.
  - Known CVEs could not be checked: the version this server declares is not published in its registry.
  - No install/post-install scripts declared.
  - Dependency health could not be checked: the version this server declares is not published in its registry.
- **Provenance & Transparency**: 48/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 0 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 78/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2069 tokens (~129/item across 16 items; 16 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 3/100
  - Stability observed for 1 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 98/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 94% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add vinvai-vinv -- npx -y vinv-mcp
```

### Codex

```bash
codex mcp add vinvai-vinv -- npx -y vinv-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vinvai-vinv": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "vinv-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add vinvai-vinv --command npx --arg -y --arg vinv-mcp
```

### Hermes

```yaml
mcp_servers:
  vinvai-vinv:
    command: "npx"
    args: ["-y", "vinv-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "vinvai-vinv": {
      "command": "npx",
      "args": [
        "-y",
        "vinv-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-22 (score 44, −11)

- [security regression] Known CVEs: pass → unverified
- [functional regression] Dependency health: pass → unverified
- [functional improvement] Stability: unverified → 0.03
- [functional] Package version: 0.0.3 → 0.0.5
- [functional] Package version: 0.0.3 → 0.0.4

### 2026-08-21 (score 55)

First indexed and scored.

## MCP tools (16)

### `vinv_query` (~106 tokens)

Semantic code search over the prebuilt index of this workspace. Use INSTEAD of grep/glob when looking for code by meaning or behavior rather than an exact string — e.g. "where are auth tokens refreshed", "what validates uploads". Returns the most relevant symbols (functions/classes) ranked, with file paths and scores, in a single call.

Input parameters:

- `query` (string, required): Natural-language search query.
- `top_k` (number): Number of results (default 5).

### `vinv_index` (~129 tokens)

Build or refresh Vinv's semantic code index for THIS workspace. The build runs in the BACKGROUND and this call returns IMMEDIATELY with status — it never blocks. Call with no arguments to start/refresh the index and read its status; pass rebuild=true to force a full rebuild from scratch. Until the first build completes, vinv_query returns a "still indexing" notice, so call this once up front on a fresh workspace, then poll it for readiness.

Input parameters:

- `rebuild` (boolean): Force a full rebuild from scratch (default false: incremental update when an index already exists).

### `vinv_deadcode` (~177 tokens)

List Python definitions (functions, classes, methods) that NOTHING in the repository references — dead code — found by static analysis of the source. Needs no prebuilt index and no runtime, so it works immediately on any workspace and returns each unused symbol with its file and line. Use it to find safe-to-remove code; before deleting a reported symbol, still confirm it is not referenced dynamically (by name) or exported as public API.

Input parameters:

- `include` (string): Only report definitions under this path prefix (e.g. "src/").
- `reasons` (boolean): Date each symbol from git history and classify it as never-wired vs lost-its-callers (slower; needs git).
- `show_probable` (boolean): Also include methods that may be overrides or duck-typed (higher recall, more false positives).

### `vinv_feedback` (~100 tokens)

After you have acted on vinv_query results (opened the files, made the edit), call this once to record whether they helped, passing the vinv_decision_id from that response. Use reward in [-1,1], where 1 is fully useful and -1 is harmful. This trains retrieval for this workspace.

Input parameters:

- `decision_id` (string, required)
- `outcome` (string): Optional short outcome label.
- `reward` (number, required)

### `vinv_session` (~524 tokens)

Read what Vinv has observed about this workspace at runtime, and drive its automated fix/optimize runs ("episodes"), from chat. READ: action="requests" (what became of each sweep/fix you QUEUED — a queued sweep does not always dispatch, and this is the only durable record of why one did not), action="trajectory" (every episode so far — what was tried, whether it verified, the reward, the standing goal, any disputes), action="status" (one-paragraph session summary), action="issues" (functions observed raising errors in captured runtime traces), action="hotspots" (the few functions where most traced runtime concentrates), action="memory_trends" (symbols retaining more memory every capture session — leak suspects), action="cache_candidates" (functions recomputing identical inputs — memoization sites with measured reclaimable time), action="opportunities" (the live optimization opportunity board with per-entry lifecycle status: posted entries are dispatchable, dispatched/resolved never re-dispatch until they expire), action="playbook" with kind (distilled how-to-fix guidance for one kind of performance waste — fix patterns, traps, verification discipline — plus the file paths holding this workspace’s current evidence of that kind: board entries, prior optimization attempts, learned prediction calibration). ACT: action="fix" with issue (and optional service) queues an automated fix run that a coding agent executes and Vinv verifies; action="run_sweep" with sweep queues a run pre-seeded with the named evidence (error clusters, hotspots, leak trends, or cache sites); action="set_goal"/"set_budget" steer future runs. Queued runs are picked up by the Vinv extension in the editor.

Input parameters:

- `action` (string, required): Operation to perform.
- `budget` (number): Episode budget for set_budget.
- `goal` (string): Standing goal for set_goal; an empty string clears it.
- `issue` (string): For action="fix": what to investigate and fix.
- `kind` (string): For action="playbook": which waste kind to get guidance and live evidence paths for.
- `service` (string): For action="fix": optional service name — the fix is then verified by replaying that service.
- `sweep` (string): For action="run_sweep": which evidence seeds the queued run — runtime_errors (fix functions observed raising errors), hotspots (optimize where traced time concentrates), memory_trends (investigate le…

### `values_of` (~89 tokens)

Value profile for a symbol across the captured run(s): per-argument and return type mix, null-rate, numeric/length ranges, and most-common values. Answers "what does this function actually receive and return at runtime" — use this for ground truth instead of inferring inputs/outputs from source.

Input parameters:

- `symbol` (string, required): Symbol to inspect: a dotted qualname or a unique short name.

### `rank_suspects` (~85 tokens)

Call FIRST when investigating a bug, error, or failing request/test: ranks symbols by fault suspiciousness (Ochiai SBFL) over the pass/fail spectra of all captured requests. Answers "which functions should I look at first for this failure" — cheaper and more targeted than reading source files.

Input parameters:

- `limit` (number): Max suspects to return (default 20).

### `slice` (~82 tokens)

Backward dynamic slice to a symbol: the caller chain from the request root down to it, annotated with the argument/return values observed at each frame. Answers "what flowed in to reach this call" — use when tracing how a bad value or state reached a function.

Input parameters:

- `symbol` (string, required): Symbol to inspect: a dotted qualname or a unique short name.

### `relevant_to` (~193 tokens)

Rank the codebase by graph relevance to one or more symbols you name — the SAME typed-edge personalized-PageRank walk that composed your context pack, re-anchored on your choice. Use when you have found symbols that matter and want what surrounds them, ranked: it answers "what else is relevant to THESE", which semantic search (vinv_query) and plain traversal (blast_radius) cannot. Returns walk mass per symbol so the ranking is auditable, and reports how many symbols it reached versus returned.

Input parameters:

- `budget` (number): Max symbols to return (default 40, ceiling 200).
- `max_hops` (number): Optional admission bound: only symbols within this many hops of an anchor may enter. Ranking is by walk mass regardless. Omit for unbounded.
- `symbols` (array, required): Anchor symbols — a bare name, a dotted qualname, or file:name to disambiguate.

### `blast_radius` (~86 tokens)

Transitive callers (upstream) and callees (downstream) of a symbol in the observed call graph. Answers "if this is wrong, what could be implicated or affected".

Input parameters:

- `direction` (string): up = callers only, down = callees only, both (default).
- `symbol` (string, required): Symbol to inspect: a dotted qualname or a unique short name.

### `why_did_this_run` (~53 tokens)

The entry-point triggers and call paths that led to a symbol running. Answers "why was this function invoked".

Input parameters:

- `symbol` (string, required): Symbol to inspect: a dotted qualname or a unique short name.

### `coverage_of` (~59 tokens)

Execution coverage: with a symbol, its call count / ok-error / timing; without one, every executed symbol ranked by call volume. Answers "what ran and how much".

Input parameters:

- `symbol` (string): Optional symbol; omit for a whole-run overview.

### `callers_of` (~48 tokens)

The observed direct callers of a symbol, with call counts. Answers "who calls this at runtime".

Input parameters:

- `symbol` (string, required): Symbol to inspect: a dotted qualname or a unique short name.

### `vinv_ingest_run` (~163 tokens)

Report a test run you performed, so it appears in the Journey and Findings views. Supply one entry per check with the unit you exercised, a scenario name, and the pass/fail verdict — the verdict is the one thing traces cannot supply. A unit is usually an HTTP endpoint ("METHOD /path"), but a repo with no service has units too: a CLI invocation ("RUN <command>") or a driven function ("CALL module.function"). Per-unit code coverage is joined automatically from the captures. Run this AFTER the work has been captured by tracelens.

Input parameters:

- `checks` (array, required): One entry per check performed.
- `source` (string): Who produced this run, recorded as provenance (e.g. "claude-code e2e suite").

### `vinv_list_candidates` (~121 tokens)

Ranked optimization candidates from the captured traces, each with the evidence behind it and a playbook for that class of waste (cache, fanout, n-plus-1, per-call, serial-async, wait, gc-pressure, alloc-churn, mem-leak). Read this before attempting any performance work — it reports what the traces actually measured, not a static guess.

Input parameters:

- `include_playbook` (boolean): Include the full playbook text for each candidate (default true).
- `limit` (number): Max candidates to return (default 10).

### `vinv_run_status` (~54 tokens)

What vinv currently holds for this workspace: capture sessions, whether an external run has been ingested, endpoint/coverage/issue counts, and the number of ranked candidates. Call this to check whether an ingest landed.

## Diagnostics

Captured diagnostic sections: Provenance. The full working is on the page: https://verifymcp.io/servers/vinvai-vinv/vinv-mcp#diagnostics

## Score history

- 2026-08-22: 44
- 2026-08-21: 55

## Links

- npm package: https://www.npmjs.com/package/vinv-mcp
- Socket report: https://socket.dev/npm/package/vinv-mcp
- Repository: https://github.com/VinvAI/VinvAI
- Website: https://vinv.ai/
- Changelog RSS feed: https://verifymcp.io/servers/vinvai-vinv/vinv-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/vinvai-vinv/vinv-mcp.json
- HTML version of this page: https://verifymcp.io/servers/vinvai-vinv/vinv-mcp