visor-mcp 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- visor_mcp-1.0.0/LICENSE +21 -0
- visor_mcp-1.0.0/PKG-INFO +256 -0
- visor_mcp-1.0.0/README.md +213 -0
- visor_mcp-1.0.0/pyproject.toml +71 -0
- visor_mcp-1.0.0/src/visor/__init__.py +8 -0
- visor_mcp-1.0.0/src/visor/__pycache__/__init__.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/__pycache__/__init__.cpython-312.pyc +0 -0
- visor_mcp-1.0.0/src/visor/__pycache__/cli.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/__pycache__/server.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/cli.py +287 -0
- visor_mcp-1.0.0/src/visor/db/__init__.py +0 -0
- visor_mcp-1.0.0/src/visor/db/__pycache__/__init__.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/db/__pycache__/__init__.cpython-312.pyc +0 -0
- visor_mcp-1.0.0/src/visor/db/__pycache__/client.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/db/__pycache__/client.cpython-312.pyc +0 -0
- visor_mcp-1.0.0/src/visor/db/__pycache__/embeddings.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/db/__pycache__/migration.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/db/client.py +526 -0
- visor_mcp-1.0.0/src/visor/db/embeddings.py +27 -0
- visor_mcp-1.0.0/src/visor/db/migration.py +291 -0
- visor_mcp-1.0.0/src/visor/extension/.gitignore +4 -0
- visor_mcp-1.0.0/src/visor/extension/.vscodeignore +10 -0
- visor_mcp-1.0.0/src/visor/extension/LICENSE +21 -0
- visor_mcp-1.0.0/src/visor/extension/assets/hero.png +0 -0
- visor_mcp-1.0.0/src/visor/extension/assets/visor-icon.svg +4 -0
- visor_mcp-1.0.0/src/visor/extension/build.log +35 -0
- visor_mcp-1.0.0/src/visor/extension/esbuild.js +18 -0
- visor_mcp-1.0.0/src/visor/extension/package-lock.json +1670 -0
- visor_mcp-1.0.0/src/visor/extension/package.json +87 -0
- visor_mcp-1.0.0/src/visor/extension/src/extension.ts +343 -0
- visor_mcp-1.0.0/src/visor/extension/test_connect.mjs +97 -0
- visor_mcp-1.0.0/src/visor/extension/test_mcp.mjs +32 -0
- visor_mcp-1.0.0/src/visor/extension/tsconfig.json +14 -0
- visor_mcp-1.0.0/src/visor/extension/visor-hud-0.10.0.vsix +0 -0
- visor_mcp-1.0.0/src/visor/hud/.gitignore +24 -0
- visor_mcp-1.0.0/src/visor/hud/README.md +73 -0
- visor_mcp-1.0.0/src/visor/hud/dump_dom.mjs +16 -0
- visor_mcp-1.0.0/src/visor/hud/e2e/drift.spec.ts +16 -0
- visor_mcp-1.0.0/src/visor/hud/eslint.config.js +23 -0
- visor_mcp-1.0.0/src/visor/hud/index.html +13 -0
- visor_mcp-1.0.0/src/visor/hud/package-lock.json +4186 -0
- visor_mcp-1.0.0/src/visor/hud/package.json +37 -0
- visor_mcp-1.0.0/src/visor/hud/playwright-report/index.html +90 -0
- visor_mcp-1.0.0/src/visor/hud/playwright.config.ts +30 -0
- visor_mcp-1.0.0/src/visor/hud/public/favicon.svg +1 -0
- visor_mcp-1.0.0/src/visor/hud/public/icons.svg +24 -0
- visor_mcp-1.0.0/src/visor/hud/run_playwright.mjs +27 -0
- visor_mcp-1.0.0/src/visor/hud/src/App.css +184 -0
- visor_mcp-1.0.0/src/visor/hud/src/App.tsx +41 -0
- visor_mcp-1.0.0/src/visor/hud/src/assets/hero.png +0 -0
- visor_mcp-1.0.0/src/visor/hud/src/assets/react.svg +1 -0
- visor_mcp-1.0.0/src/visor/hud/src/assets/vite.svg +1 -0
- visor_mcp-1.0.0/src/visor/hud/src/components/ErrorBoundary.tsx +38 -0
- visor_mcp-1.0.0/src/visor/hud/src/components/GraphCanvas.tsx +832 -0
- visor_mcp-1.0.0/src/visor/hud/src/components/TelemetryHUD.tsx +359 -0
- visor_mcp-1.0.0/src/visor/hud/src/index.css +160 -0
- visor_mcp-1.0.0/src/visor/hud/src/main.tsx +10 -0
- visor_mcp-1.0.0/src/visor/hud/test-results/.last-run.json +4 -0
- visor_mcp-1.0.0/src/visor/hud/test_three.js +7 -0
- visor_mcp-1.0.0/src/visor/hud/tsconfig.app.json +25 -0
- visor_mcp-1.0.0/src/visor/hud/tsconfig.json +7 -0
- visor_mcp-1.0.0/src/visor/hud/tsconfig.node.json +24 -0
- visor_mcp-1.0.0/src/visor/hud/vite.config.ts +8 -0
- visor_mcp-1.0.0/src/visor/parser/__init__.py +0 -0
- visor_mcp-1.0.0/src/visor/parser/__pycache__/__init__.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/parser/__pycache__/__init__.cpython-312.pyc +0 -0
- visor_mcp-1.0.0/src/visor/parser/__pycache__/treesitter.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/parser/__pycache__/watcher.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/parser/__pycache__/watcher.cpython-312.pyc +0 -0
- visor_mcp-1.0.0/src/visor/parser/treesitter.py +263 -0
- visor_mcp-1.0.0/src/visor/parser/watcher.py +261 -0
- visor_mcp-1.0.0/src/visor/server.py +151 -0
- visor_mcp-1.0.0/src/visor/tools/__init__.py +0 -0
- visor_mcp-1.0.0/src/visor/tools/__pycache__/__init__.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/tools/__pycache__/context_engine.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/tools/__pycache__/core.cpython-310.pyc +0 -0
- visor_mcp-1.0.0/src/visor/tools/context_engine.py +342 -0
- visor_mcp-1.0.0/src/visor/tools/core.py +504 -0
visor_mcp-1.0.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Arunav Mandal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
visor_mcp-1.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: visor-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Skill-Orchestrated Context Intelligence Engine for AI coding agents
|
|
5
|
+
Keywords: mcp,context,ai,coding-agent,tree-sitter,embeddings,ast
|
|
6
|
+
Author: Arunav Mandal
|
|
7
|
+
Author-email: Arunav Mandal <dibun75@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
18
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
19
|
+
Requires-Dist: gitpython>=3.1.46
|
|
20
|
+
Requires-Dist: mcp>=1.27.0
|
|
21
|
+
Requires-Dist: networkx>=3.4.2
|
|
22
|
+
Requires-Dist: numpy>=2.2.6
|
|
23
|
+
Requires-Dist: pydantic>=2.12.5
|
|
24
|
+
Requires-Dist: python-dateutil>=2.9.0.post0
|
|
25
|
+
Requires-Dist: sentence-transformers>=5.4.0
|
|
26
|
+
Requires-Dist: sqlite-vec>=0.1.9
|
|
27
|
+
Requires-Dist: tree-sitter>=0.25.2
|
|
28
|
+
Requires-Dist: tree-sitter-javascript>=0.25.0
|
|
29
|
+
Requires-Dist: tree-sitter-python>=0.25.0
|
|
30
|
+
Requires-Dist: tree-sitter-typescript>=0.23.2
|
|
31
|
+
Requires-Dist: tree-sitter-go>=0.23.0
|
|
32
|
+
Requires-Dist: tree-sitter-rust>=0.23.0
|
|
33
|
+
Requires-Dist: tree-sitter-java>=0.23.0
|
|
34
|
+
Requires-Dist: tree-sitter-c>=0.23.0
|
|
35
|
+
Requires-Dist: tree-sitter-cpp>=0.23.0
|
|
36
|
+
Requires-Dist: watchdog>=6.0.0
|
|
37
|
+
Requires-Python: >=3.10
|
|
38
|
+
Project-URL: Homepage, https://github.com/dibun75/visor
|
|
39
|
+
Project-URL: Repository, https://github.com/dibun75/visor
|
|
40
|
+
Project-URL: Documentation, https://github.com/dibun75/visor/tree/main/docs
|
|
41
|
+
Project-URL: Bug Tracker, https://github.com/dibun75/visor/issues
|
|
42
|
+
Description-Content-Type: text/markdown
|
|
43
|
+
|
|
44
|
+
# V.I.S.O.R.
|
|
45
|
+
|
|
46
|
+
> **AI is wasting 60% of your tokens reading the wrong code. V.I.S.O.R. fixes that.**
|
|
47
|
+
|
|
48
|
+
[](https://github.com/dibun75/visor/actions/workflows/ci.yml) [](https://pypi.org/project/visor-mcp/) [](LICENSE) [](pyproject.toml) [](https://modelcontextprotocol.io)
|
|
49
|
+
|
|
50
|
+
**Visual Intelligence System for Orchestrated Reasoning**
|
|
51
|
+
|
|
52
|
+
V.I.S.O.R. is a **Skill-Orchestrated Context Intelligence Engine** — a local-first MCP server that indexes your codebase via Tree-sitter AST parsing, ranks code with a multi-signal scoring engine, and delivers surgical context to AI coding agents. It works with **Antigravity, VS Code, Cursor, and Claude Code**.
|
|
53
|
+
|
|
54
|
+
<div align="center">
|
|
55
|
+
<img src="./docs/assets/hud_overview.png?v=0.10.0" alt="V.I.S.O.R HUD Dashboard" width="800"/>
|
|
56
|
+
</div>
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 🚀 Install in 30 Seconds
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install visor-mcp
|
|
64
|
+
visor init
|
|
65
|
+
# Done. Your AI agent now has V.I.S.O.R.
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
`visor init` auto-detects your IDE (Antigravity, Cursor) and writes the MCP config for you.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Why V.I.S.O.R.?
|
|
73
|
+
|
|
74
|
+
Every time your AI agent searches for context, it burns tokens reading irrelevant files. V.I.S.O.R. eliminates this waste:
|
|
75
|
+
|
|
76
|
+
| Without V.I.S.O.R. | With V.I.S.O.R. |
|
|
77
|
+
|---|---|
|
|
78
|
+
| Agent greps 20+ files blindly | Agent gets 3-5 precise snippets |
|
|
79
|
+
| ~12,000 tokens per context fetch | ~2,300 tokens (80% reduction) |
|
|
80
|
+
| No reasoning — just raw search | Every selection is explainable |
|
|
81
|
+
| Stale context → hallucinations | Drift detection prevents errors |
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## ✨ Key Features
|
|
86
|
+
|
|
87
|
+
### 🧠 Context Intelligence Engine
|
|
88
|
+
The `build_context` tool is the core differentiator. It doesn't just search — it **reasons**:
|
|
89
|
+
- **Intent Classification** — Detects if you're debugging, refactoring, or exploring, and adjusts weights dynamically
|
|
90
|
+
- **5-Signal Scoring** — Combines embedding similarity, exact match, co-location, dependency proximity, and recency
|
|
91
|
+
- **Explainable Decisions** — Every node includes human-readable reasoning for why it was selected
|
|
92
|
+
- **Token Metrics** — Shows exact reduction percentage vs. naive full-file approach
|
|
93
|
+
|
|
94
|
+
### ⚡ Skill Execution Layer
|
|
95
|
+
Pre-loaded strategies that change how V.I.S.O.R. retrieves context:
|
|
96
|
+
|
|
97
|
+
| Skill | Intent | Behavior |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| `bug-fixer` | BUG_FIX | Boosts dependency chains + recently modified files |
|
|
100
|
+
| `architecture-explainer` | EXPLAIN | Heavy embedding similarity for broad understanding |
|
|
101
|
+
| `refactor-assistant` | REFACTOR | Wide dependency graph + exact symbol matching |
|
|
102
|
+
| `performance-optimizer` | BUG_FIX | Hotspot detection via extreme recency weighting |
|
|
103
|
+
|
|
104
|
+
Skills are defined as JSON strategies and stored in SQLite. Create your own via `add_custom_skill`.
|
|
105
|
+
|
|
106
|
+
### 🔍 Semantic AST Indexing
|
|
107
|
+
Powered by Tree-sitter, V.I.S.O.R. indexes **9 languages** out of the box. Symbols are embedded using `all-MiniLM-L6-v2` and stored in a local SQLite + `sqlite-vec` vector store.
|
|
108
|
+
|
|
109
|
+
| Language | Extensions | Status |
|
|
110
|
+
|----------|-----------|--------|
|
|
111
|
+
| Python | `.py` | ✅ |
|
|
112
|
+
| TypeScript | `.ts`, `.tsx` | ✅ |
|
|
113
|
+
| JavaScript | `.js`, `.jsx` | ✅ |
|
|
114
|
+
| Go | `.go` | ✅ |
|
|
115
|
+
| Rust | `.rs` | ✅ |
|
|
116
|
+
| Java | `.java` | ✅ |
|
|
117
|
+
| C | `.c`, `.h` | ✅ |
|
|
118
|
+
| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | ✅ |
|
|
119
|
+
|
|
120
|
+
> **Want more?** Adding a new language is ~15 lines of code. See [CONTRIBUTING.md](./CONTRIBUTING.md#how-to-add-a-new-language-most-common-contribution).
|
|
121
|
+
|
|
122
|
+
### 📊 3D WebGPU Developer HUD
|
|
123
|
+
A real-time force-directed graph visualization of your codebase architecture, embedded directly in your IDE sidebar. Displays live telemetry: Agent Context Burn, Graph Scale, and Drift Alerts.
|
|
124
|
+
|
|
125
|
+
### ⚠️ Drift Detection
|
|
126
|
+
Dual-mode detection (SHA-256 hash comparison or file changelog timestamps) warns agents before they hallucinate from stale context.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 🛠️ CLI
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
visor context "how is authentication handled" # General context query
|
|
134
|
+
visor fix "login crash on null user" # Bug-fixer skill
|
|
135
|
+
visor explain "database client" # Architecture-explainer skill
|
|
136
|
+
visor trace src/auth.py src/db/client.py # Trace architectural path
|
|
137
|
+
visor drift # Check for drift
|
|
138
|
+
visor init # Auto-configure for your IDE
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## 🛠️ MCP Tool Suite
|
|
144
|
+
|
|
145
|
+
V.I.S.O.R. exposes **16 MCP tools** across 5 categories. See [`docs/MCP_TOOLS.md`](./docs/MCP_TOOLS.md) for the full API reference.
|
|
146
|
+
|
|
147
|
+
### 🧠 Intelligence
|
|
148
|
+
| Tool | Description |
|
|
149
|
+
|------|-------------|
|
|
150
|
+
| `build_context(query, skill?)` | Ranked context with scoring, reasoning, metrics, and prompt export |
|
|
151
|
+
|
|
152
|
+
### 🔍 Search
|
|
153
|
+
| Tool | Description |
|
|
154
|
+
|------|-------------|
|
|
155
|
+
| `search_codebase(query)` | Semantic vector search across AST nodes |
|
|
156
|
+
| `get_symbol_context(symbol)` | Find all definitions with file + line range |
|
|
157
|
+
| `get_file_context(path)` | Full AST symbol listing for a file |
|
|
158
|
+
|
|
159
|
+
### 🗺️ Graph Analysis
|
|
160
|
+
| Tool | Description |
|
|
161
|
+
|------|-------------|
|
|
162
|
+
| `get_dependency_chain(symbol)` | Transitive import chain (BFS depth 5) |
|
|
163
|
+
| `impact_analysis(file_path)` | Downstream blast radius |
|
|
164
|
+
| `trace_route(source, target)` | Shortest path between files |
|
|
165
|
+
| `dead_code_detection()` | Files with zero incoming edges |
|
|
166
|
+
|
|
167
|
+
### ⚠️ Drift Detection
|
|
168
|
+
| Tool | Description |
|
|
169
|
+
|------|-------------|
|
|
170
|
+
| `get_drift_report(files, loaded_at, hashes?)` | Hash or timestamp-based drift detection |
|
|
171
|
+
|
|
172
|
+
### 🧩 Memory & Skills
|
|
173
|
+
| Tool | Description |
|
|
174
|
+
|------|-------------|
|
|
175
|
+
| `store_memory(role, content)` | Persist conversation with embedding |
|
|
176
|
+
| `add_custom_skill(name, desc, content, strategy?)` | Create a skill with optional JSON strategy |
|
|
177
|
+
| `list_custom_skills()` | List all skills with strategies |
|
|
178
|
+
| `delete_custom_skill(id)` | Remove a skill |
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 📦 Example Output
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
$ visor fix "authentication crash"
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
============================================================
|
|
190
|
+
V.I.S.O.R. Context Intelligence Engine
|
|
191
|
+
============================================================
|
|
192
|
+
Query: authentication crash
|
|
193
|
+
Intent: BUG_FIX
|
|
194
|
+
Skill: bug-fixer
|
|
195
|
+
────────────────────────────────────────────────────────────
|
|
196
|
+
Tokens without V.I.S.O.R.: 11,400
|
|
197
|
+
Tokens with V.I.S.O.R.: 2,180
|
|
198
|
+
Reduction: 80.9%
|
|
199
|
+
────────────────────────────────────────────────────────────
|
|
200
|
+
Selected 4 nodes (truncated=False):
|
|
201
|
+
|
|
202
|
+
[2.8500] src/auth/jwt.py:verify_token
|
|
203
|
+
→ Matched query token in symbol name
|
|
204
|
+
→ Co-located in same file as top semantic hit
|
|
205
|
+
→ Recently modified file (boosted)
|
|
206
|
+
|
|
207
|
+
[2.1200] src/auth/middleware.py:auth_guard
|
|
208
|
+
→ Reachable via dependency chain
|
|
209
|
+
→ Semantic similarity (score: 0.375)
|
|
210
|
+
|
|
211
|
+
============================================================
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
---
|
|
215
|
+
|
|
216
|
+
## 📚 Documentation
|
|
217
|
+
|
|
218
|
+
| Document | Description |
|
|
219
|
+
|----------|-------------|
|
|
220
|
+
| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | System design, data flow, DB schema |
|
|
221
|
+
| [`docs/MCP_TOOLS.md`](./docs/MCP_TOOLS.md) | Complete MCP tool API reference |
|
|
222
|
+
| [`docs/FAQ.md`](./docs/FAQ.md) | Frequently asked questions |
|
|
223
|
+
| [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Common issues and solutions |
|
|
224
|
+
| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | How to contribute (add languages, tools, skills) |
|
|
225
|
+
| [`CHANGELOG.md`](./CHANGELOG.md) | Release history |
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 🤝 Contributing
|
|
230
|
+
|
|
231
|
+
V.I.S.O.R. welcomes contributions! The easiest way to start is by [adding a new language](./CONTRIBUTING.md#how-to-add-a-new-language-most-common-contribution) — it's ~15 lines and a great first issue.
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
git clone https://github.com/dibun75/visor.git
|
|
235
|
+
cd visor && uv sync --dev
|
|
236
|
+
uv run pytest tests/ -v
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## 🌐 Compatibility
|
|
244
|
+
|
|
245
|
+
| IDE | Support | Method |
|
|
246
|
+
|------|---------|--------|
|
|
247
|
+
| Google Antigravity | ✅ Full | MCP config + Extension |
|
|
248
|
+
| VS Code | ✅ Full | MCP config + Extension |
|
|
249
|
+
| Cursor | ✅ MCP tools | MCP config |
|
|
250
|
+
| Claude Code | ✅ MCP tools | MCP config |
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## License
|
|
255
|
+
|
|
256
|
+
MIT © [Arunav Mandal](https://github.com/dibun75)
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# V.I.S.O.R.
|
|
2
|
+
|
|
3
|
+
> **AI is wasting 60% of your tokens reading the wrong code. V.I.S.O.R. fixes that.**
|
|
4
|
+
|
|
5
|
+
[](https://github.com/dibun75/visor/actions/workflows/ci.yml) [](https://pypi.org/project/visor-mcp/) [](LICENSE) [](pyproject.toml) [](https://modelcontextprotocol.io)
|
|
6
|
+
|
|
7
|
+
**Visual Intelligence System for Orchestrated Reasoning**
|
|
8
|
+
|
|
9
|
+
V.I.S.O.R. is a **Skill-Orchestrated Context Intelligence Engine** — a local-first MCP server that indexes your codebase via Tree-sitter AST parsing, ranks code with a multi-signal scoring engine, and delivers surgical context to AI coding agents. It works with **Antigravity, VS Code, Cursor, and Claude Code**.
|
|
10
|
+
|
|
11
|
+
<div align="center">
|
|
12
|
+
<img src="./docs/assets/hud_overview.png?v=0.10.0" alt="V.I.S.O.R HUD Dashboard" width="800"/>
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 🚀 Install in 30 Seconds
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install visor-mcp
|
|
21
|
+
visor init
|
|
22
|
+
# Done. Your AI agent now has V.I.S.O.R.
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`visor init` auto-detects your IDE (Antigravity, Cursor) and writes the MCP config for you.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Why V.I.S.O.R.?
|
|
30
|
+
|
|
31
|
+
Every time your AI agent searches for context, it burns tokens reading irrelevant files. V.I.S.O.R. eliminates this waste:
|
|
32
|
+
|
|
33
|
+
| Without V.I.S.O.R. | With V.I.S.O.R. |
|
|
34
|
+
|---|---|
|
|
35
|
+
| Agent greps 20+ files blindly | Agent gets 3-5 precise snippets |
|
|
36
|
+
| ~12,000 tokens per context fetch | ~2,300 tokens (80% reduction) |
|
|
37
|
+
| No reasoning — just raw search | Every selection is explainable |
|
|
38
|
+
| Stale context → hallucinations | Drift detection prevents errors |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## ✨ Key Features
|
|
43
|
+
|
|
44
|
+
### 🧠 Context Intelligence Engine
|
|
45
|
+
The `build_context` tool is the core differentiator. It doesn't just search — it **reasons**:
|
|
46
|
+
- **Intent Classification** — Detects if you're debugging, refactoring, or exploring, and adjusts weights dynamically
|
|
47
|
+
- **5-Signal Scoring** — Combines embedding similarity, exact match, co-location, dependency proximity, and recency
|
|
48
|
+
- **Explainable Decisions** — Every node includes human-readable reasoning for why it was selected
|
|
49
|
+
- **Token Metrics** — Shows exact reduction percentage vs. naive full-file approach
|
|
50
|
+
|
|
51
|
+
### ⚡ Skill Execution Layer
|
|
52
|
+
Pre-loaded strategies that change how V.I.S.O.R. retrieves context:
|
|
53
|
+
|
|
54
|
+
| Skill | Intent | Behavior |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| `bug-fixer` | BUG_FIX | Boosts dependency chains + recently modified files |
|
|
57
|
+
| `architecture-explainer` | EXPLAIN | Heavy embedding similarity for broad understanding |
|
|
58
|
+
| `refactor-assistant` | REFACTOR | Wide dependency graph + exact symbol matching |
|
|
59
|
+
| `performance-optimizer` | BUG_FIX | Hotspot detection via extreme recency weighting |
|
|
60
|
+
|
|
61
|
+
Skills are defined as JSON strategies and stored in SQLite. Create your own via `add_custom_skill`.
|
|
62
|
+
|
|
63
|
+
### 🔍 Semantic AST Indexing
|
|
64
|
+
Powered by Tree-sitter, V.I.S.O.R. indexes **9 languages** out of the box. Symbols are embedded using `all-MiniLM-L6-v2` and stored in a local SQLite + `sqlite-vec` vector store.
|
|
65
|
+
|
|
66
|
+
| Language | Extensions | Status |
|
|
67
|
+
|----------|-----------|--------|
|
|
68
|
+
| Python | `.py` | ✅ |
|
|
69
|
+
| TypeScript | `.ts`, `.tsx` | ✅ |
|
|
70
|
+
| JavaScript | `.js`, `.jsx` | ✅ |
|
|
71
|
+
| Go | `.go` | ✅ |
|
|
72
|
+
| Rust | `.rs` | ✅ |
|
|
73
|
+
| Java | `.java` | ✅ |
|
|
74
|
+
| C | `.c`, `.h` | ✅ |
|
|
75
|
+
| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | ✅ |
|
|
76
|
+
|
|
77
|
+
> **Want more?** Adding a new language is ~15 lines of code. See [CONTRIBUTING.md](./CONTRIBUTING.md#how-to-add-a-new-language-most-common-contribution).
|
|
78
|
+
|
|
79
|
+
### 📊 3D WebGPU Developer HUD
|
|
80
|
+
A real-time force-directed graph visualization of your codebase architecture, embedded directly in your IDE sidebar. Displays live telemetry: Agent Context Burn, Graph Scale, and Drift Alerts.
|
|
81
|
+
|
|
82
|
+
### ⚠️ Drift Detection
|
|
83
|
+
Dual-mode detection (SHA-256 hash comparison or file changelog timestamps) warns agents before they hallucinate from stale context.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## 🛠️ CLI
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
visor context "how is authentication handled" # General context query
|
|
91
|
+
visor fix "login crash on null user" # Bug-fixer skill
|
|
92
|
+
visor explain "database client" # Architecture-explainer skill
|
|
93
|
+
visor trace src/auth.py src/db/client.py # Trace architectural path
|
|
94
|
+
visor drift # Check for drift
|
|
95
|
+
visor init # Auto-configure for your IDE
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## 🛠️ MCP Tool Suite
|
|
101
|
+
|
|
102
|
+
V.I.S.O.R. exposes **16 MCP tools** across 5 categories. See [`docs/MCP_TOOLS.md`](./docs/MCP_TOOLS.md) for the full API reference.
|
|
103
|
+
|
|
104
|
+
### 🧠 Intelligence
|
|
105
|
+
| Tool | Description |
|
|
106
|
+
|------|-------------|
|
|
107
|
+
| `build_context(query, skill?)` | Ranked context with scoring, reasoning, metrics, and prompt export |
|
|
108
|
+
|
|
109
|
+
### 🔍 Search
|
|
110
|
+
| Tool | Description |
|
|
111
|
+
|------|-------------|
|
|
112
|
+
| `search_codebase(query)` | Semantic vector search across AST nodes |
|
|
113
|
+
| `get_symbol_context(symbol)` | Find all definitions with file + line range |
|
|
114
|
+
| `get_file_context(path)` | Full AST symbol listing for a file |
|
|
115
|
+
|
|
116
|
+
### 🗺️ Graph Analysis
|
|
117
|
+
| Tool | Description |
|
|
118
|
+
|------|-------------|
|
|
119
|
+
| `get_dependency_chain(symbol)` | Transitive import chain (BFS depth 5) |
|
|
120
|
+
| `impact_analysis(file_path)` | Downstream blast radius |
|
|
121
|
+
| `trace_route(source, target)` | Shortest path between files |
|
|
122
|
+
| `dead_code_detection()` | Files with zero incoming edges |
|
|
123
|
+
|
|
124
|
+
### ⚠️ Drift Detection
|
|
125
|
+
| Tool | Description |
|
|
126
|
+
|------|-------------|
|
|
127
|
+
| `get_drift_report(files, loaded_at, hashes?)` | Hash or timestamp-based drift detection |
|
|
128
|
+
|
|
129
|
+
### 🧩 Memory & Skills
|
|
130
|
+
| Tool | Description |
|
|
131
|
+
|------|-------------|
|
|
132
|
+
| `store_memory(role, content)` | Persist conversation with embedding |
|
|
133
|
+
| `add_custom_skill(name, desc, content, strategy?)` | Create a skill with optional JSON strategy |
|
|
134
|
+
| `list_custom_skills()` | List all skills with strategies |
|
|
135
|
+
| `delete_custom_skill(id)` | Remove a skill |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 📦 Example Output
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
$ visor fix "authentication crash"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
============================================================
|
|
147
|
+
V.I.S.O.R. Context Intelligence Engine
|
|
148
|
+
============================================================
|
|
149
|
+
Query: authentication crash
|
|
150
|
+
Intent: BUG_FIX
|
|
151
|
+
Skill: bug-fixer
|
|
152
|
+
────────────────────────────────────────────────────────────
|
|
153
|
+
Tokens without V.I.S.O.R.: 11,400
|
|
154
|
+
Tokens with V.I.S.O.R.: 2,180
|
|
155
|
+
Reduction: 80.9%
|
|
156
|
+
────────────────────────────────────────────────────────────
|
|
157
|
+
Selected 4 nodes (truncated=False):
|
|
158
|
+
|
|
159
|
+
[2.8500] src/auth/jwt.py:verify_token
|
|
160
|
+
→ Matched query token in symbol name
|
|
161
|
+
→ Co-located in same file as top semantic hit
|
|
162
|
+
→ Recently modified file (boosted)
|
|
163
|
+
|
|
164
|
+
[2.1200] src/auth/middleware.py:auth_guard
|
|
165
|
+
→ Reachable via dependency chain
|
|
166
|
+
→ Semantic similarity (score: 0.375)
|
|
167
|
+
|
|
168
|
+
============================================================
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
## 📚 Documentation
|
|
174
|
+
|
|
175
|
+
| Document | Description |
|
|
176
|
+
|----------|-------------|
|
|
177
|
+
| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | System design, data flow, DB schema |
|
|
178
|
+
| [`docs/MCP_TOOLS.md`](./docs/MCP_TOOLS.md) | Complete MCP tool API reference |
|
|
179
|
+
| [`docs/FAQ.md`](./docs/FAQ.md) | Frequently asked questions |
|
|
180
|
+
| [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Common issues and solutions |
|
|
181
|
+
| [`CONTRIBUTING.md`](./CONTRIBUTING.md) | How to contribute (add languages, tools, skills) |
|
|
182
|
+
| [`CHANGELOG.md`](./CHANGELOG.md) | Release history |
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## 🤝 Contributing
|
|
187
|
+
|
|
188
|
+
V.I.S.O.R. welcomes contributions! The easiest way to start is by [adding a new language](./CONTRIBUTING.md#how-to-add-a-new-language-most-common-contribution) — it's ~15 lines and a great first issue.
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
git clone https://github.com/dibun75/visor.git
|
|
192
|
+
cd visor && uv sync --dev
|
|
193
|
+
uv run pytest tests/ -v
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 🌐 Compatibility
|
|
201
|
+
|
|
202
|
+
| IDE | Support | Method |
|
|
203
|
+
|------|---------|--------|
|
|
204
|
+
| Google Antigravity | ✅ Full | MCP config + Extension |
|
|
205
|
+
| VS Code | ✅ Full | MCP config + Extension |
|
|
206
|
+
| Cursor | ✅ MCP tools | MCP config |
|
|
207
|
+
| Claude Code | ✅ MCP tools | MCP config |
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## License
|
|
212
|
+
|
|
213
|
+
MIT © [Arunav Mandal](https://github.com/dibun75)
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "visor-mcp"
|
|
3
|
+
version = "1.0.0"
|
|
4
|
+
description = "Skill-Orchestrated Context Intelligence Engine for AI coding agents"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
authors = [
|
|
8
|
+
{ name = "Arunav Mandal", email = "dibun75@gmail.com" }
|
|
9
|
+
]
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
keywords = ["mcp", "context", "ai", "coding-agent", "tree-sitter", "embeddings", "ast"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 4 - Beta",
|
|
14
|
+
"Intended Audience :: Developers",
|
|
15
|
+
"License :: OSI Approved :: MIT License",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.10",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Programming Language :: Python :: 3.13",
|
|
21
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
22
|
+
"Topic :: Software Development :: Quality Assurance",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"gitpython>=3.1.46",
|
|
26
|
+
"mcp>=1.27.0",
|
|
27
|
+
"networkx>=3.4.2",
|
|
28
|
+
"numpy>=2.2.6",
|
|
29
|
+
"pydantic>=2.12.5",
|
|
30
|
+
"python-dateutil>=2.9.0.post0",
|
|
31
|
+
"sentence-transformers>=5.4.0",
|
|
32
|
+
"sqlite-vec>=0.1.9",
|
|
33
|
+
"tree-sitter>=0.25.2",
|
|
34
|
+
"tree-sitter-javascript>=0.25.0",
|
|
35
|
+
"tree-sitter-python>=0.25.0",
|
|
36
|
+
"tree-sitter-typescript>=0.23.2",
|
|
37
|
+
"tree-sitter-go>=0.23.0",
|
|
38
|
+
"tree-sitter-rust>=0.23.0",
|
|
39
|
+
"tree-sitter-java>=0.23.0",
|
|
40
|
+
"tree-sitter-c>=0.23.0",
|
|
41
|
+
"tree-sitter-cpp>=0.23.0",
|
|
42
|
+
"watchdog>=6.0.0",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[project.urls]
|
|
46
|
+
Homepage = "https://github.com/dibun75/visor"
|
|
47
|
+
Repository = "https://github.com/dibun75/visor"
|
|
48
|
+
Documentation = "https://github.com/dibun75/visor/tree/main/docs"
|
|
49
|
+
"Bug Tracker" = "https://github.com/dibun75/visor/issues"
|
|
50
|
+
|
|
51
|
+
[project.scripts]
|
|
52
|
+
visor-mcp = "visor.server:main"
|
|
53
|
+
visor = "visor.cli:main"
|
|
54
|
+
|
|
55
|
+
[dependency-groups]
|
|
56
|
+
dev = [
|
|
57
|
+
"pytest>=8.0.0",
|
|
58
|
+
"pytest-asyncio>=0.23.0",
|
|
59
|
+
"ruff>=0.11.0",
|
|
60
|
+
]
|
|
61
|
+
|
|
62
|
+
[build-system]
|
|
63
|
+
requires = ["uv_build>=0.11.6,<0.12.0"]
|
|
64
|
+
build-backend = "uv_build"
|
|
65
|
+
|
|
66
|
+
[tool.uv.build-backend]
|
|
67
|
+
module-name = "visor"
|
|
68
|
+
module-root = "src"
|
|
69
|
+
default-excludes = false
|
|
70
|
+
source-include = ["src/visor/**/*.py", "pyproject.toml", "README.md", "LICENSE"]
|
|
71
|
+
source-exclude = ["**/node_modules/**", "**/out/**", "**/dist/**", "**/.venv/**"]
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|