# vecscope (pypi · vecscope)

Deterministic evidence about embedding spaces and vector indexes: hubness, collapse, ANN recall

- Trust score: 76/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-04

## Components

- pypi · `vecscope`: 76/100 (this document), [markdown](https://verifymcp.io/servers/076923-vecscope/vecscope.md), [page](https://verifymcp.io/servers/076923-vecscope/vecscope)

## Channel facts

- Registry: `pypi`
- Package: `vecscope`
- Version: `0.11.0`
- 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-11-04.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised build step with no custom scripting around it.
  - 1 of 29 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 100/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to 076923/vecscope).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 50/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 2146 tokens (~536/item across 4 items; 4 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 10/100
  - Stability observed for 3 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 67/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 4 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 5 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the vecscope MCP server?

vecscope runs locally as a PyPI package, launched with uvx vecscope. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add 076923-vecscope -- uvx vecscope
```

### Cursor

```json
{
  "mcpServers": {
    "076923-vecscope": {
      "command": "uvx",
      "args": [
        "vecscope"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "076923-vecscope": {
      "command": "uvx",
      "args": [
        "vecscope"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add 076923-vecscope -- uvx vecscope
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "076923-vecscope": {
      "type": "local",
      "command": [
        "uvx",
        "vecscope"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add 076923-vecscope --command uvx --arg vecscope
```

### Hermes

```yaml
mcp_servers:
  076923-vecscope:
    command: "uvx"
    args: ["vecscope"]
```

### Netclaw

```json
{
  "McpServers": {
    "076923-vecscope": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "vecscope"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add 076923-vecscope -t stdio -c uvx -a vecscope
```

### Other

```json
{
  "mcpServers": {
    "076923-vecscope": {
      "command": "uvx",
      "args": [
        "vecscope"
      ]
    }
  }
}
```

## 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-11-04 (score 76, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-11-03 (score 75, +1)

- [functional improvement] Stability: unverified → 0.07

### 2026-11-02 (score 74, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-01 (score 59)

First indexed and scored.

## MCP tools (4)

### `audit_embeddings` (~1074 tokens)

Audit an embedding file: hubness, anisotropy, collapse, rogue dimensions, norms,
metric mismatch, distance concentration, outliers, k-NN graph islands, and optionally
ANN recall and query-side findings. Read-only; the file never leaves the machine.

\`path`: local .npy/.npz/.parquet/.jsonl/.json/.csv with one vector per row, a faiss index
file, or a vector store URI (qdrant://, chroma://, milvus://, weaviate://, or their
\+local forms with a directory). When the server was started with --allow-dir or
VECSCOPE_ALLOWED_DIRS, paths outside those directories are refused; network stores need
the server started with --allow-network. Store rows are in ascending id order and
findings carry `sample_source_ids` next to `sample_ids`.
\`ann_from_source`: query the store's own index for every stored vector and score it as
\`ann_path` (needs `sample=0` above the sample size).
\`qrels_path`: relevance judgments for the queries (.json/.jsonl/.tsv of query row, corpus
row, grade); adds `retrieval` with nDCG, recall, MRR and duplicate share of exact search.
\`ranked_path`: (m x k) corpus row ids per query from the production index, scored with
\`qrels_path` next to exact search.
\`ann_path`: optional (n x k) integer array of neighbor ids from an ANN index (requires
\`sample=0` so row ids line up).
\`queries_path`: optional (m x dim) file of query embeddings; adds query_gap,
query_hubness and the deprecated ood_queries.
\`query_baseline_path`: optional JSON evidence (this tool's response or `vecscope audit
\--json`) from an earlier audit of the same corpus with healthy queries; with
\`queries_path` it adds query_shift, the share of queries farther from the corpus than
that reference's median + 3 MAD.
\`clusters` > 0 attaches a per-cluster map with sample ids (no verdicts); capped at one
cluster per 10 rows.
\`sample`: rows above this are audited on a seeded random subset (0 = audit every row;
exact k-NN is quadratic, minutes for 100k rows on a laptop; peak memory about 2 GiB).
\`sample_repeats`: whe…

Input parameters:

- `ann_from_source` (boolean)
- `ann_path`
- `baseline`
- `clusters` (integer)
- `k` (integer)
- `near_dup_cos` (number)
- `path` (string, required)
- `qrels_path`
- `queries_path`
- `query_baseline_path`
- `ranked_path`
- `sample` (integer)
- `sample_repeats` (integer)
- `thresholds`
- `tolerances`
- `verbose` (boolean)

### `sweep_index` (~410 tokens)

Sweep HNSW (M, ef_search) and IVF (nprobe) parameters on an embedding file and report
recall@k against exact k-NN, build time, queries per second, single-query latency
percentiles (p50/p95/p99 ms) and the serialized index size for each setting, plus the
fastest configuration that reaches `target_recall`. The recommendation carries
\`margin` (recall minus target) and is marked `tight` with a `safer_alternative` when the
margin is under `margin`, because recall at fixed parameters falls as the corpus grows;
relay `caveats` to the user. qps is the median of `timing_repeats` runs. Needs the faiss
extra (`pip install "vecscope[index]"`). Read-only; timings are relative to this machine
and process, not a serving latency.
\`device` is "auto" (GPU when the faiss build has one), "cpu" or "gpu"; HNSW is CPU-only.
\`n_queries` caps the queries timed (sampled from the corpus, or from `queries_path`);
pass real query traffic as `queries_path` whenever it exists, because the best setting
on corpus-drawn queries can differ. `latency_queries` are searched one at a time per
setting for the percentiles (0 = skip). `nlist` fixes the IVF list count; pass the
production index's nlist when tuning its nprobe, since the default follows the row count
(4*sqrt(n)) and gives other lists.

Input parameters:

- `device` (string)
- `k` (integer)
- `latency_queries` (integer)
- `margin` (number)
- `n_queries` (integer)
- `nlist`
- `path` (string, required)
- `queries_path`
- `target_recall` (number)
- `timing_repeats` (integer)

### `compare_embeddings` (~301 tokens)

Compare two embedding files whose rows are the same items in the same order (two
models, or one model before and after a transform). Reports how often the nearest
neighbor and the top-k lists agree, the near-duplicate share in each space and in both,
whether both spaces pick the same duplicate partner, and the rows that disagree most.
No verdicts: duplicates flagged by both spaces with the same partner belong to the items;
duplicates flagged by one space only point at that model. Above `sample` rows a seeded
subset is compared (0 = all rows).

Read `neighbor_scope` before quoting the agreement: "sample" means the neighbors were
recomputed inside the sampled rows, so the numbers describe the sample's own neighbor
graph and are usually higher than the full corpus's. To compare full-corpus rankings,
pass `neighbors_a_path` and `neighbors_b_path` (both): (n x >= k) neighbor ids per row
computed on the full corpus in each space, exact or from the production index; the
rows may still be sampled but their neighbors are not (`neighbor_scope` = "full",
\`neighbor_source` = "supplied").

Input parameters:

- `k` (integer)
- `near_dup_cos` (number)
- `neighbors_a_path`
- `neighbors_b_path`
- `path_a` (string, required)
- `path_b` (string, required)
- `sample` (integer)

### `describe_findings` (~59 tokens)

List every finding vecscope can report with its metric key, default (warn, fail)
thresholds and direction, likely causes, suggested first action and verification step.
Use it to explain a verdict to the user or to decide which thresholds to override.

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/076923-vecscope/vecscope#diagnostics

## Score history

- 2026-11-04: 76
- 2026-11-03: 75
- 2026-11-02: 74
- 2026-11-01: 59

## Common questions

### What is the vecscope MCP server?

vecscope is an MCP server listed in the public MCP registry as io.github.076923/vecscope. Deterministic evidence about embedding spaces and vector indexes: hubness, collapse, ANN recall. This page covers its PyPI package (vecscope).

### Is the vecscope MCP server safe to use?

vecscope scores 76 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 4 November 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the vecscope MCP server expose?

vecscope exposes 4 tools: audit_embeddings, sweep_index, compare_embeddings, describe_findings. Their descriptions and schemas cost roughly 1,844 tokens of context every time the server is loaded.

### Is the vecscope MCP server still maintained?

vecscope is still listed as active in the MCP registry. We last reached this channel on 4 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the vecscope MCP server under?

vecscope declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/vecscope/
- Socket report: https://socket.dev/pypi/package/vecscope
- Repository: https://github.com/076923/vecscope
- Changelog RSS feed: https://verifymcp.io/servers/076923-vecscope/vecscope.xml
- Changelog JSON feed: https://verifymcp.io/servers/076923-vecscope/vecscope.json
- HTML version of this page: https://verifymcp.io/servers/076923-vecscope/vecscope