Mcp-QadGraph

⚠️ Note: The rest of this repository (code, comments, scripts, docs, commits, issues) is written in French. Only this README is in English.

"See the vector memory, don't just query it." Local dashboard (3D similarity sphere) + MCP server for a Qdrant database. Python stdlib on the server side · 100% local · 0 paid API · 0 Docker.

The problem

A Qdrant collection is thousands of unreadable vectors. The native UI shows the neighborhood of one point, not the global shape of the memory: duplicates, clusters, hub nodes, type distribution.

QadGraph computes cosine similarity server-side, caches the result, and serves:

• a dashboard (3D graph, metrics, search, logs, config);

• an MCP server: any agent (Claude Desktop, Codex, kimi…) inspects the memory read-only.

Related MCP server: trident-mcp

Current state

v0.1.1 — working on local Qdrant, not yet generalized. Security fixes (CORS, proxy, SSRF).

• Verified at runtime (2026-10-22, Windows, Python 3.14, Qdrant 1.19.2): all 9 main dashboard routes answer 200, /api/health returns qdrant: up.

• Automated tests limited to dashboard security: tests/test_security.py (stdlib, without Qdrant); python -m unittest discover -s tests -v.

• No performance benchmark: cosine computation is pure Python, O(n²·dimension), therefore capped (see Limitations).

• Only tested on Windows. Linux/macOS support is unverified.

• Coupled to Qdrant and to an agent memory's payload schema (type, session, text/summary fields). See Known limitations.

Quick start

Prerequisites: Qdrant running on http://127.0.0.1:6333, Python 3.8+ advertised (tested on 3.14).

git clone https://github.com/MlkBlk-IT/Mcp-QadGraph
cd Mcp-QadGraph
$env:QADGRAPH_COLLECTION = "my_collection"
python qadgraph\server.py        # → http://127.0.0.1:8766/

The dashboard has zero dependencies to install. The frontend loads D3 from a CDN: internet is required for the graph view.

MCP server

{
  "mcpServers": {
    "qadgraph": {
      "command": "<PYTHON_WITH_MCP>",
      "args": ["<REPO_PATH>/qadgraph/mcp/qadgraph_mcp.py"],
      "env": {
        "QADGRAPH_QDRANT": "http://127.0.0.1:6333",
        "QADGRAPH_COLLECTION": "my_collection"
      }
    }
  }
}

The MCP server requires the mcp package (FastMCP): pip install -r requirements.txt in the Python used.

Architecture

MCP client / browser
   │                         │
   ▼                         ▼
qadgraph/mcp/qadgraph_mcp.py     qadgraph/web/  (3D UI, app.js)
   │  imports                     │  HTTP
   ▼                              ▼
qadgraph/server.py   ← Store + cache + server-side cosine + HTTP API (:8766)
   │  HTTP JSON
   ▼
Qdrant (:6333)  — /collections, points/scroll

The browser receives a lightweight topology (nodes + edges), never the raw vectors.

Exposed MCP tools (9)

All tools are read-only.

Configuration (environment variables)

Known limitations

Security

• Fixed in v0.1.1 — CORS / CSRF / DNS rebinding. The server no longer sends Access-Control-Allow-Origin: *, and rejects (403) any request whose Host or Origin is not the dashboard's (127.0.0.1, localhost, [::1] + port, plus QADGRAPH_ALLOWED_HOSTS). OPTIONS preflights are refused (405).

• Fixed in v0.1.1 — read-only proxy. POST /api/qdrant/proxy only accepts search, scroll, count, query, recommend, discover and facet. Before the fix, a POST to /collections/<name>/points/delete was relayed to Qdrant (reproduced by a test).

• Fixed in v0.1.1 — proxy paths. Paths must be relative (/...): no more @host, //host or ...

• Still open: no authentication; /api/config returns Qdrant's config.yaml if it exists (it may contain an API key) to any local process reaching the port. Do not run with QADGRAPH_HOST other than 127.0.0.1.

Functional

• Qdrant only. The coupling lives in Store.refresh, Store._scroll and qadgraph_logs, but no other backend is implemented.

• Expected payload schema: type, session, text (or summary). On another collection, these fields will be unknown / empty.

• Similarity matrix capped at QADGRAPH_MAX_MATRIX points (500); beyond that, only point metrics remain available. Pure-Python computation: CPU-bound.

• Logs (/api/logs, qadgraph_logs) read logs/qdrant.stdout.log and logs/qdrant.stderr.log at the repo root. Absent by default: the Logs view will be empty.

• Some config examples (MCP docstring, qadgraph-mcp.json, /api/config, docs/REFERENCE.md, PROGRESS.md) contain the author's Windows paths (C:\AI\EmbeddingDB\...): adapt them. The code itself resolves its paths via __file__.

• No CI, no authentication, no functional tests outside security.

Methodology

• Read-only: the MCP never writes to Qdrant.

• Server-side computation: the browser receives ~40 KB of topology, not 6 MB of vectors.

• stdlib only for the dashboard: starts under any Python with no installation.

• Portable by construction: no proprietary SDK, no paid API, 100% CPU.

Author

Malik — IT Support student (DEP), self-taught Focus: Sysadmin + Cyber + AI + Cloud

⚡ Built on CPU. Proven on disk. ⚡