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.
Files changed (78) hide show
  1. visor_mcp-1.0.0/LICENSE +21 -0
  2. visor_mcp-1.0.0/PKG-INFO +256 -0
  3. visor_mcp-1.0.0/README.md +213 -0
  4. visor_mcp-1.0.0/pyproject.toml +71 -0
  5. visor_mcp-1.0.0/src/visor/__init__.py +8 -0
  6. visor_mcp-1.0.0/src/visor/__pycache__/__init__.cpython-310.pyc +0 -0
  7. visor_mcp-1.0.0/src/visor/__pycache__/__init__.cpython-312.pyc +0 -0
  8. visor_mcp-1.0.0/src/visor/__pycache__/cli.cpython-310.pyc +0 -0
  9. visor_mcp-1.0.0/src/visor/__pycache__/server.cpython-310.pyc +0 -0
  10. visor_mcp-1.0.0/src/visor/cli.py +287 -0
  11. visor_mcp-1.0.0/src/visor/db/__init__.py +0 -0
  12. visor_mcp-1.0.0/src/visor/db/__pycache__/__init__.cpython-310.pyc +0 -0
  13. visor_mcp-1.0.0/src/visor/db/__pycache__/__init__.cpython-312.pyc +0 -0
  14. visor_mcp-1.0.0/src/visor/db/__pycache__/client.cpython-310.pyc +0 -0
  15. visor_mcp-1.0.0/src/visor/db/__pycache__/client.cpython-312.pyc +0 -0
  16. visor_mcp-1.0.0/src/visor/db/__pycache__/embeddings.cpython-310.pyc +0 -0
  17. visor_mcp-1.0.0/src/visor/db/__pycache__/migration.cpython-310.pyc +0 -0
  18. visor_mcp-1.0.0/src/visor/db/client.py +526 -0
  19. visor_mcp-1.0.0/src/visor/db/embeddings.py +27 -0
  20. visor_mcp-1.0.0/src/visor/db/migration.py +291 -0
  21. visor_mcp-1.0.0/src/visor/extension/.gitignore +4 -0
  22. visor_mcp-1.0.0/src/visor/extension/.vscodeignore +10 -0
  23. visor_mcp-1.0.0/src/visor/extension/LICENSE +21 -0
  24. visor_mcp-1.0.0/src/visor/extension/assets/hero.png +0 -0
  25. visor_mcp-1.0.0/src/visor/extension/assets/visor-icon.svg +4 -0
  26. visor_mcp-1.0.0/src/visor/extension/build.log +35 -0
  27. visor_mcp-1.0.0/src/visor/extension/esbuild.js +18 -0
  28. visor_mcp-1.0.0/src/visor/extension/package-lock.json +1670 -0
  29. visor_mcp-1.0.0/src/visor/extension/package.json +87 -0
  30. visor_mcp-1.0.0/src/visor/extension/src/extension.ts +343 -0
  31. visor_mcp-1.0.0/src/visor/extension/test_connect.mjs +97 -0
  32. visor_mcp-1.0.0/src/visor/extension/test_mcp.mjs +32 -0
  33. visor_mcp-1.0.0/src/visor/extension/tsconfig.json +14 -0
  34. visor_mcp-1.0.0/src/visor/extension/visor-hud-0.10.0.vsix +0 -0
  35. visor_mcp-1.0.0/src/visor/hud/.gitignore +24 -0
  36. visor_mcp-1.0.0/src/visor/hud/README.md +73 -0
  37. visor_mcp-1.0.0/src/visor/hud/dump_dom.mjs +16 -0
  38. visor_mcp-1.0.0/src/visor/hud/e2e/drift.spec.ts +16 -0
  39. visor_mcp-1.0.0/src/visor/hud/eslint.config.js +23 -0
  40. visor_mcp-1.0.0/src/visor/hud/index.html +13 -0
  41. visor_mcp-1.0.0/src/visor/hud/package-lock.json +4186 -0
  42. visor_mcp-1.0.0/src/visor/hud/package.json +37 -0
  43. visor_mcp-1.0.0/src/visor/hud/playwright-report/index.html +90 -0
  44. visor_mcp-1.0.0/src/visor/hud/playwright.config.ts +30 -0
  45. visor_mcp-1.0.0/src/visor/hud/public/favicon.svg +1 -0
  46. visor_mcp-1.0.0/src/visor/hud/public/icons.svg +24 -0
  47. visor_mcp-1.0.0/src/visor/hud/run_playwright.mjs +27 -0
  48. visor_mcp-1.0.0/src/visor/hud/src/App.css +184 -0
  49. visor_mcp-1.0.0/src/visor/hud/src/App.tsx +41 -0
  50. visor_mcp-1.0.0/src/visor/hud/src/assets/hero.png +0 -0
  51. visor_mcp-1.0.0/src/visor/hud/src/assets/react.svg +1 -0
  52. visor_mcp-1.0.0/src/visor/hud/src/assets/vite.svg +1 -0
  53. visor_mcp-1.0.0/src/visor/hud/src/components/ErrorBoundary.tsx +38 -0
  54. visor_mcp-1.0.0/src/visor/hud/src/components/GraphCanvas.tsx +832 -0
  55. visor_mcp-1.0.0/src/visor/hud/src/components/TelemetryHUD.tsx +359 -0
  56. visor_mcp-1.0.0/src/visor/hud/src/index.css +160 -0
  57. visor_mcp-1.0.0/src/visor/hud/src/main.tsx +10 -0
  58. visor_mcp-1.0.0/src/visor/hud/test-results/.last-run.json +4 -0
  59. visor_mcp-1.0.0/src/visor/hud/test_three.js +7 -0
  60. visor_mcp-1.0.0/src/visor/hud/tsconfig.app.json +25 -0
  61. visor_mcp-1.0.0/src/visor/hud/tsconfig.json +7 -0
  62. visor_mcp-1.0.0/src/visor/hud/tsconfig.node.json +24 -0
  63. visor_mcp-1.0.0/src/visor/hud/vite.config.ts +8 -0
  64. visor_mcp-1.0.0/src/visor/parser/__init__.py +0 -0
  65. visor_mcp-1.0.0/src/visor/parser/__pycache__/__init__.cpython-310.pyc +0 -0
  66. visor_mcp-1.0.0/src/visor/parser/__pycache__/__init__.cpython-312.pyc +0 -0
  67. visor_mcp-1.0.0/src/visor/parser/__pycache__/treesitter.cpython-310.pyc +0 -0
  68. visor_mcp-1.0.0/src/visor/parser/__pycache__/watcher.cpython-310.pyc +0 -0
  69. visor_mcp-1.0.0/src/visor/parser/__pycache__/watcher.cpython-312.pyc +0 -0
  70. visor_mcp-1.0.0/src/visor/parser/treesitter.py +263 -0
  71. visor_mcp-1.0.0/src/visor/parser/watcher.py +261 -0
  72. visor_mcp-1.0.0/src/visor/server.py +151 -0
  73. visor_mcp-1.0.0/src/visor/tools/__init__.py +0 -0
  74. visor_mcp-1.0.0/src/visor/tools/__pycache__/__init__.cpython-310.pyc +0 -0
  75. visor_mcp-1.0.0/src/visor/tools/__pycache__/context_engine.cpython-310.pyc +0 -0
  76. visor_mcp-1.0.0/src/visor/tools/__pycache__/core.cpython-310.pyc +0 -0
  77. visor_mcp-1.0.0/src/visor/tools/context_engine.py +342 -0
  78. visor_mcp-1.0.0/src/visor/tools/core.py +504 -0
@@ -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.
@@ -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
+ [![CI](https://github.com/dibun75/visor/actions/workflows/ci.yml/badge.svg)](https://github.com/dibun75/visor/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/visor-mcp)](https://pypi.org/project/visor-mcp/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10+-blue)](pyproject.toml) [![MCP](https://img.shields.io/badge/protocol-MCP-purple)](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
+ [![CI](https://github.com/dibun75/visor/actions/workflows/ci.yml/badge.svg)](https://github.com/dibun75/visor/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/visor-mcp)](https://pypi.org/project/visor-mcp/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10+-blue)](pyproject.toml) [![MCP](https://img.shields.io/badge/protocol-MCP-purple)](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/**"]
@@ -0,0 +1,8 @@
1
+ """V.I.S.O.R — Visual Intelligence System for Orchestrated Reasoning."""
2
+
3
+ from importlib.metadata import version, PackageNotFoundError
4
+
5
+ try:
6
+ __version__ = version("visor-mcp")
7
+ except PackageNotFoundError:
8
+ __version__ = "0.0.0-dev"