nexus-dev 3.2.0__py3-none-any.whl

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.

Potentially problematic release.


This version of nexus-dev might be problematic. Click here for more details.

Files changed (48) hide show
  1. nexus_dev/__init__.py +4 -0
  2. nexus_dev/agent_templates/__init__.py +26 -0
  3. nexus_dev/agent_templates/api_designer.yaml +26 -0
  4. nexus_dev/agent_templates/code_reviewer.yaml +26 -0
  5. nexus_dev/agent_templates/debug_detective.yaml +26 -0
  6. nexus_dev/agent_templates/doc_writer.yaml +26 -0
  7. nexus_dev/agent_templates/performance_optimizer.yaml +26 -0
  8. nexus_dev/agent_templates/refactor_architect.yaml +26 -0
  9. nexus_dev/agent_templates/security_auditor.yaml +26 -0
  10. nexus_dev/agent_templates/test_engineer.yaml +26 -0
  11. nexus_dev/agents/__init__.py +20 -0
  12. nexus_dev/agents/agent_config.py +97 -0
  13. nexus_dev/agents/agent_executor.py +197 -0
  14. nexus_dev/agents/agent_manager.py +104 -0
  15. nexus_dev/agents/prompt_factory.py +91 -0
  16. nexus_dev/chunkers/__init__.py +168 -0
  17. nexus_dev/chunkers/base.py +202 -0
  18. nexus_dev/chunkers/docs_chunker.py +291 -0
  19. nexus_dev/chunkers/java_chunker.py +343 -0
  20. nexus_dev/chunkers/javascript_chunker.py +312 -0
  21. nexus_dev/chunkers/python_chunker.py +308 -0
  22. nexus_dev/cli.py +1673 -0
  23. nexus_dev/config.py +253 -0
  24. nexus_dev/database.py +558 -0
  25. nexus_dev/embeddings.py +585 -0
  26. nexus_dev/gateway/__init__.py +10 -0
  27. nexus_dev/gateway/connection_manager.py +348 -0
  28. nexus_dev/github_importer.py +247 -0
  29. nexus_dev/mcp_client.py +281 -0
  30. nexus_dev/mcp_config.py +184 -0
  31. nexus_dev/schemas/mcp_config_schema.json +166 -0
  32. nexus_dev/server.py +1866 -0
  33. nexus_dev/templates/pre-commit-hook +33 -0
  34. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/__init__.py +26 -0
  35. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/api_designer.yaml +26 -0
  36. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/code_reviewer.yaml +26 -0
  37. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/debug_detective.yaml +26 -0
  38. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/doc_writer.yaml +26 -0
  39. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/performance_optimizer.yaml +26 -0
  40. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/refactor_architect.yaml +26 -0
  41. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/security_auditor.yaml +26 -0
  42. nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/test_engineer.yaml +26 -0
  43. nexus_dev-3.2.0.data/data/nexus_dev/templates/pre-commit-hook +33 -0
  44. nexus_dev-3.2.0.dist-info/METADATA +636 -0
  45. nexus_dev-3.2.0.dist-info/RECORD +48 -0
  46. nexus_dev-3.2.0.dist-info/WHEEL +4 -0
  47. nexus_dev-3.2.0.dist-info/entry_points.txt +12 -0
  48. nexus_dev-3.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,636 @@
1
+ Metadata-Version: 2.4
2
+ Name: nexus-dev
3
+ Version: 3.2.0
4
+ Summary: MCP server for persistent AI coding assistant memory with local RAG
5
+ Project-URL: Homepage, https://github.com/mmornati/nexus-dev
6
+ Project-URL: Repository, https://github.com/mmornati/nexus-dev
7
+ Project-URL: Issues, https://github.com/mmornati/nexus-dev/issues
8
+ Author-email: Marco Mornati <marco@mornati.net>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai,assistant,coding,lancedb,mcp,rag,vector-database
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
17
+ Requires-Python: >=3.13
18
+ Requires-Dist: click>=8.1.0
19
+ Requires-Dist: httpx>=0.28.0
20
+ Requires-Dist: jsonschema>=4.18.0
21
+ Requires-Dist: lancedb>=0.26.0
22
+ Requires-Dist: mcp>=1.25.0
23
+ Requires-Dist: openai>=1.60.0
24
+ Requires-Dist: pandas>=2.0.0
25
+ Requires-Dist: pyarrow>=18.0.0
26
+ Requires-Dist: pydantic>=2.10.0
27
+ Requires-Dist: pyyaml>=6.0.0
28
+ Requires-Dist: tree-sitter-language-pack>=0.7.0
29
+ Requires-Dist: tree-sitter>=0.24.0
30
+ Provides-Extra: all
31
+ Requires-Dist: boto3>=1.34.0; extra == 'all'
32
+ Requires-Dist: cohere>=4.37.0; extra == 'all'
33
+ Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == 'all'
34
+ Requires-Dist: voyageai>=0.1.0; extra == 'all'
35
+ Provides-Extra: aws
36
+ Requires-Dist: boto3>=1.34.0; extra == 'aws'
37
+ Provides-Extra: cohere
38
+ Requires-Dist: cohere>=4.37.0; extra == 'cohere'
39
+ Provides-Extra: dev
40
+ Requires-Dist: mypy>=1.14.0; extra == 'dev'
41
+ Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
42
+ Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
43
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
44
+ Requires-Dist: ruff>=0.9.0; extra == 'dev'
45
+ Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
46
+ Provides-Extra: google
47
+ Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == 'google'
48
+ Provides-Extra: voyage
49
+ Requires-Dist: voyageai>=0.1.0; extra == 'voyage'
50
+ Description-Content-Type: text/markdown
51
+
52
+ # Nexus-Dev
53
+
54
+ [![CI](https://github.com/mmornati/nexus-dev/actions/workflows/ci.yml/badge.svg)](https://github.com/mmornati/nexus-dev/actions/workflows/ci.yml)
55
+ [![codecov](https://codecov.io/gh/mmornati/nexus-dev/graph/badge.svg)](https://codecov.io/gh/mmornati/nexus-dev)
56
+ [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
57
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
58
+ [![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
59
+
60
+ **Persistent Memory for AI Coding Agents**
61
+
62
+ Nexus-Dev is an open-source MCP (Model Context Protocol) server that provides a local RAG (Retrieval-Augmented Generation) system for AI coding assistants like GitHub Copilot, Cursor, and Windsurf. It learns from your codebase and mistakes, enabling cross-project knowledge sharing.
63
+
64
+ ## Features
65
+
66
+ - 🧠 **Persistent Memory**: Index your code and documentation for semantic search
67
+ - 📚 **Lesson Learning**: Record problems and solutions that the AI can recall later
68
+ - 🐙 **GitHub Integration**: Import Issues and Pull Requests into your knowledge base (see [docs/github-import.md](docs/github-import.md))
69
+ - 🌐 **Multi-Language Support**: Python, JavaScript/TypeScript, Java (extensible via tree-sitter)
70
+ - 📖 **Documentation Indexing**: Parse and index Markdown/RST documentation
71
+ - 🔄 **Cross-Project Learning**: Share knowledge across all your projects
72
+ - 🏠 **Local-First**: All data stays on your machine with LanceDB
73
+
74
+ ## Installation
75
+
76
+ ### Isolated Global Installation (Recommended)
77
+
78
+ To avoid conflicts with project-specific virtual environments, install Nexus-Dev globally using `pipx` or `uv tool`.
79
+
80
+ ```bash
81
+ # Using pipx
82
+ pipx install nexus-dev
83
+
84
+ # Using uv
85
+ uv tool install nexus-dev
86
+ ```
87
+
88
+ ### Development Installation
89
+
90
+ If you are contributing to Nexus-Dev, you can install it in editable mode:
91
+
92
+ ```bash
93
+ # Using pip
94
+ pip install -e .
95
+
96
+ # Using uv
97
+ uv pip install -e .
98
+ ```
99
+
100
+ ## Quick Start
101
+
102
+ ### 1. Initialize a Project
103
+
104
+ ```bash
105
+ cd your-project
106
+ nexus-init --project-name "my-project" --embedding-provider openai
107
+ ```
108
+
109
+ This creates:
110
+ - `nexus_config.json` - Project configuration
111
+ - `.nexus/lessons/` - Directory for learned lessons
112
+
113
+ ### 2. Set Your API Key (OpenAI only)
114
+
115
+ The CLI commands require the API key in your environment:
116
+
117
+ ```bash
118
+ export OPENAI_API_KEY="sk-..."
119
+ ```
120
+
121
+ > **Tip**: Add this to your shell profile (`~/.zshrc`, `~/.bashrc`) so it's always available.
122
+ >
123
+ > If using **Ollama**, no API key is needed—just ensure Ollama is running locally.
124
+
125
+ ### 3. Index Your Code
126
+
127
+ ```bash
128
+ # Index directories recursively (recommended)
129
+ nexus-index src/ -r
130
+
131
+ # Index multiple directories
132
+ nexus-index src/ docs/ -r
133
+
134
+ # Index specific files (no -r needed)
135
+ nexus-index main.py utils.py
136
+ ```
137
+
138
+ > **Note**: The `-r` flag is required to recursively index subdirectories. Without it, only files directly inside the given folder are indexed.
139
+
140
+ ### 4. Configure Your AI Agent
141
+
142
+ Add to your MCP client configuration (e.g., Claude Desktop):
143
+
144
+ ```json
145
+ {
146
+ "mcpServers": {
147
+ "nexus-dev": {
148
+ "command": "nexus-dev",
149
+ "args": []
150
+ }
151
+ }
152
+ }
153
+ ```
154
+
155
+ ### 5. Verify Your Setup
156
+
157
+ **Check indexed content** via CLI:
158
+ ```bash
159
+ nexus-status
160
+ ```
161
+
162
+ **Test in your AI agent** — copy and paste this prompt:
163
+
164
+ ```
165
+ Search the Nexus-Dev knowledge base for functions related to "embeddings"
166
+ and show me the project statistics.
167
+ ```
168
+
169
+ If the AI uses the `search_code` or `get_project_context` tools and returns results, your setup is complete! 🎉
170
+
171
+ ## MCP Tools
172
+
173
+ Nexus-Dev exposes 7 tools to AI agents:
174
+
175
+ ### Search Tools
176
+
177
+ | Tool | Description |
178
+ |------|-------------|
179
+ | `search_knowledge` | Search all content (code, docs, lessons) with optional `content_type` filter |
180
+ | `search_code` | Search specifically in indexed code (functions, classes, methods) |
181
+ | `search_docs` | Search specifically in documentation (Markdown, RST, text) |
182
+ | `search_lessons` | Search in recorded lessons (problems & solutions) |
183
+
184
+ ### Indexing Tools
185
+
186
+ | Tool | Description |
187
+ |------|-------------|
188
+ | `index_file` | Index a file into the knowledge base |
189
+ | `record_lesson` | Store a problem/solution pair for future reference |
190
+ | `get_project_context` | Get project statistics and recent lessons |
191
+
192
+ ## MCP Gateway Mode
193
+
194
+ Nexus-Dev can act as a gateway to other MCP servers, reducing tool count for AI agents.
195
+
196
+ ### Setup
197
+
198
+ 1. Initialize MCP configuration:
199
+ ```bash
200
+ nexus-mcp init --from-global
201
+ ```
202
+
203
+ 2. Index tools from configured servers:
204
+ ```bash
205
+ nexus-index-mcp --all
206
+ ```
207
+
208
+ ### Usage
209
+
210
+ Instead of configuring 10 MCP servers (50+ tools), configure only Nexus-Dev:
211
+
212
+ ```json
213
+ {
214
+ "mcpServers": {
215
+ "nexus-dev": {
216
+ "command": "nexus-dev"
217
+ }
218
+ }
219
+ }
220
+ ```
221
+
222
+ AI uses these Nexus-Dev tools to access other servers:
223
+
224
+ | Tool | Description |
225
+ |------|-------------|
226
+ | `search_tools` | Find the right tool for a task |
227
+ | `invoke_tool` | Execute a tool on any configured server |
228
+ | `list_servers` | Show available MCP servers |
229
+
230
+ ### Workflow
231
+
232
+ 1. AI searches: `search_tools("create GitHub issue")`
233
+ 2. Nexus-Dev returns: `github.create_issue` with schema
234
+ 3. AI invokes: `invoke_tool("github", "create_issue", {...})`
235
+ 4. Nexus-Dev proxies to GitHub MCP
236
+
237
+ ### Server Configuration
238
+
239
+ You can configure downstream MCP servers in `.nexus/mcp_config.json` using either **Stdio** (local process) or **SSE** (HTTP remote) transports.
240
+
241
+ **Local Server (Stdio):**
242
+ ```json
243
+ {
244
+ "servers": {
245
+ "github-local": {
246
+ "transport": "stdio",
247
+ "command": "npx",
248
+ "args": ["-y", "@modelcontextprotocol/server-github"],
249
+ "env": {
250
+ "GITHUB_PERSONAL_ACCESS_TOKEN": "..."
251
+ }
252
+ }
253
+ }
254
+ }
255
+ ```
256
+
257
+ **Remote Server (SSE):**
258
+ ```json
259
+ {
260
+ "servers": {
261
+ "github-remote": {
262
+ "transport": "sse",
263
+ "url": "https://api.githubcopilot.com/mcp/",
264
+ "headers": {
265
+ "Authorization": "Bearer ..."
266
+ }
267
+ }
268
+ }
269
+ }
270
+ ```
271
+
272
+ ## Configuration
273
+
274
+ `nexus_config.json` example:
275
+
276
+ ```json
277
+ {
278
+ "project_id": "550e8400-e29b-41d4-a716-446655440000",
279
+ "project_name": "my-project",
280
+ "embedding_provider": "openai",
281
+ "embedding_model": "text-embedding-3-small",
282
+ "docs_folders": ["docs/", "README.md"],
283
+ "include_patterns": ["**/*.py", "**/*.js", "**/*.java"],
284
+ "exclude_patterns": ["**/node_modules/**", "**/__pycache__/**"]
285
+ }
286
+ ```
287
+
288
+ ### Project Context & Startup
289
+
290
+ Nexus-Dev needs to know *which* project to load on startup. It determines this in two ways:
291
+
292
+ 1. **Automatic Detection (Recommended)**: If the MCP server process is started with your project root as its **current working directory (cwd)**, it automatically loads `nexus_config.json` and `.nexus/mcp_config.json`.
293
+ 2. **Environment Variable**: Setting `NEXUS_PROJECT_ROOT=/path/to/project` explicitly tells the server where to look.
294
+
295
+ **When to use `refresh_agents`:**
296
+ If the server starts in a generic location (like a global Docker container or default system path) without a project context, it starts "empty". You must then use the `refresh_agents` tool. This tool asks your IDE for the active workspace path and re-initializes the server with that context.
297
+
298
+ > **Pro Tip**: Configure your MCP client (Cursor, Claude Desktop) to set `cwd` or `NEXUS_PROJECT_ROOT` to your project path. This matches the server's lifecycle to your open project and avoids the need for manual refreshing.
299
+ ```
300
+
301
+ 📖 See [docs/adding-mcp-servers.md](docs/adding-mcp-servers.md) for a guide on adding custom MCP servers.
302
+
303
+ ### Supported Embedding Providers
304
+
305
+ Nexus-Dev supports multiple embedding providers. Choose the one that best fits your needs.
306
+
307
+ #### 1. OpenAI (Default)
308
+ - **Best for:** General purpose, ease of use.
309
+ - **Provider:** `openai`
310
+ - **Default Model:** `text-embedding-3-small`
311
+ - **Configuration:**
312
+ ```json
313
+ {
314
+ "embedding_provider": "openai",
315
+ "embedding_model": "text-embedding-3-small"
316
+ }
317
+ ```
318
+ - **Environment:** Set `OPENAI_API_KEY`.
319
+
320
+ #### 2. Local Ollama (Privacy / Offline)
321
+ - **Best for:** Privacy, local execution, cost savings.
322
+ - **Provider:** `ollama`
323
+ - **Default Model:** `nomic-embed-text`
324
+ - **Configuration:**
325
+ ```json
326
+ {
327
+ "embedding_provider": "ollama",
328
+ "embedding_model": "nomic-embed-text",
329
+ "ollama_url": "http://localhost:11434"
330
+ }
331
+ ```
332
+
333
+ #### 3. Google Vertex AI (Enterprise)
334
+ - **Best for:** Enterprise GCP users, high scalability.
335
+ - **Provider:** `google`
336
+ - **Install:** `pip install nexus-dev[google]`
337
+ - **Default Model:** `text-embedding-004`
338
+ - **Configuration:**
339
+ ```json
340
+ {
341
+ "embedding_provider": "google",
342
+ "google_project_id": "your-project-id",
343
+ "google_location": "us-central1"
344
+ }
345
+ ```
346
+ - **Environment:** Uses standard Google Cloud credentials (ADC).
347
+
348
+ #### 4. AWS Bedrock (Enterprise)
349
+ - **Best for:** Enterprise AWS users.
350
+ - **Provider:** `aws`
351
+ - **Install:** `pip install nexus-dev[aws]`
352
+ - **Default Model:** `amazon.titan-embed-text-v1`
353
+ - **Configuration:**
354
+ ```json
355
+ {
356
+ "embedding_provider": "aws",
357
+ "aws_region": "us-east-1"
358
+ }
359
+ ```
360
+
361
+ #### 5. Voyage AI (High Performance)
362
+ - **Best for:** State-of-the-art retrieval quality (RAG specialist).
363
+ - **Provider:** `voyage`
364
+ - **Install:** `pip install nexus-dev[voyage]`
365
+ - **Default Model:** `voyage-large-2`
366
+ - **Configuration:**
367
+ ```json
368
+ {
369
+ "embedding_provider": "voyage",
370
+ "voyage_api_key": "your-key"
371
+ }
372
+ ```
373
+
374
+ #### 6. Cohere (Multilingual)
375
+ - **Best for:** Multilingual search and reranking.
376
+ - **Provider:** `cohere`
377
+ - **Install:** `pip install nexus-dev[cohere]`
378
+ - **Default Model:** `embed-multilingual-v3.0`
379
+ - **Configuration:**
380
+ ```json
381
+ {
382
+ "embedding_provider": "cohere",
383
+ "cohere_api_key": "your-key"
384
+ }
385
+ ```
386
+
387
+ > ⚠️ **Warning**: Embeddings are NOT portable between providers. Changing providers requires re-indexing all documents.
388
+
389
+ ## Optional: Pre-commit Hook
390
+
391
+ Install automatic indexing on commits:
392
+
393
+ ```bash
394
+ nexus-init --project-name "my-project" --install-hook
395
+ ```
396
+
397
+ Or manually add to `.git/hooks/pre-commit`:
398
+
399
+ ```bash
400
+ #!/bin/bash
401
+ MODIFIED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(py|js|ts|java)$')
402
+ if [ -n "$MODIFIED" ]; then
403
+ nexus-index $MODIFIED
404
+ fi
405
+ ```
406
+
407
+ ## Configuring AI Agents
408
+
409
+ To maximize Nexus-Dev's value, configure your AI coding assistant to use its tools automatically.
410
+
411
+ ### Add AGENTS.md to Your Project
412
+
413
+ Copy our template to your project:
414
+
415
+ ```bash
416
+ cp path/to/nexus-dev/docs/AGENTS_TEMPLATE.md your-project/AGENTS.md
417
+ ```
418
+
419
+ This instructs AI agents to:
420
+ - **Search first** before implementing features
421
+ - **Record lessons** after solving bugs
422
+ - Use `get_project_context()` at session start
423
+
424
+ ### Add Workflow Files (Optional)
425
+
426
+ ```bash
427
+ cp -r path/to/nexus-dev/.agent/workflows your-project/.agent/
428
+ ```
429
+
430
+ This adds slash commands: `/start-session`, `/search-first`, `/record-lesson`, `/index-code`
431
+
432
+ 📖 See [docs/configuring-agents.md](docs/configuring-agents.md) for detailed setup instructions.
433
+
434
+ ## Architecture
435
+
436
+ ```mermaid
437
+ flowchart TB
438
+ subgraph Agent["🤖 AI Agent"]
439
+ direction TB
440
+ Cursor["Cursor / Copilot / Windsurf"]
441
+ end
442
+
443
+ subgraph MCP["📡 Nexus-Dev (Gateway)"]
444
+ direction TB
445
+
446
+ subgraph Tools["MCP Tools"]
447
+ direction TB
448
+ search_knowledge["search_knowledge"]
449
+ search_code["search_code"]
450
+ search_docs["search_docs"]
451
+ index_file["index_file"]
452
+ gateway_tools["gateway_tools (new)"]
453
+ end
454
+
455
+ subgraph Chunkers["🔧 RAG Pipeline"]
456
+ Python["Chunkers"]
457
+ Embeddings["Embeddings"]
458
+ DB["LanceDB"]
459
+ end
460
+ end
461
+
462
+ subgraph External["🌍 External MCP Servers"]
463
+ GH["GitHub"]
464
+ PG["PostgreSQL"]
465
+ Other["..."]
466
+ end
467
+
468
+ Agent -->|"stdio"| Tools
469
+ Tools --> Chunkers
470
+ gateway_tools -.->|"invoke_tool"| External
471
+ ```
472
+
473
+ ### Data Flow
474
+
475
+ ```mermaid
476
+ sequenceDiagram
477
+ participant AI as AI Agent
478
+ participant MCP as Nexus-Dev
479
+ participant Embed as Embeddings
480
+ participant DB as LanceDB
481
+
482
+ Note over AI,DB: Indexing Flow
483
+ AI->>MCP: index_file(path)
484
+ MCP->>MCP: Parse with Chunker
485
+ MCP->>Embed: Generate embeddings
486
+ Embed-->>MCP: Vectors
487
+ MCP->>DB: Store chunks + vectors
488
+ DB-->>MCP: OK
489
+ MCP-->>AI: ✅ Indexed
490
+
491
+ Note over AI,DB: Search Flow
492
+ AI->>MCP: search_knowledge(query)
493
+ MCP->>Embed: Embed query
494
+ Embed-->>MCP: Query vector
495
+ MCP->>DB: Vector similarity search
496
+ DB-->>MCP: Results
497
+ MCP-->>AI: Formatted results
498
+ ```
499
+
500
+ ## Development Setup
501
+
502
+ Since Nexus-Dev is not yet published to PyPI/Docker Hub, developers must build from source.
503
+
504
+ ### Option 1: Local Python Installation (Recommended for Development)
505
+
506
+ ```bash
507
+ # Clone repository
508
+ git clone https://github.com/mmornati/nexus-dev.git
509
+ cd nexus-dev
510
+
511
+ # Option A: Use the Makefile (handles pyenv + venv)
512
+ make setup
513
+ source .venv/bin/activate
514
+
515
+ # Option B: Manual setup
516
+ pyenv install 3.13 # or use your preferred Python 3.13+ manager
517
+ python3 -m venv .venv
518
+ source .venv/bin/activate
519
+ pip install -e ".[dev]" # Editable install with dev dependencies
520
+ ```
521
+
522
+ After installation, CLI commands are available:
523
+
524
+ ```bash
525
+ nexus-init --help # Initialize a project
526
+ nexus-index --help # Index files
527
+ nexus-dev # Run MCP server
528
+ ```
529
+
530
+ ### Option 2: Docker Build
531
+
532
+ ```bash
533
+ # Build the image
534
+ make docker-build
535
+ # or: docker build -t nexus-dev:latest .
536
+
537
+ # Run with volume mounts
538
+ docker run -it --rm \
539
+ -v /path/to/your-project:/workspace:ro \
540
+ -v nexus-dev-data:/data/nexus-dev \
541
+ -e OPENAI_API_KEY=$OPENAI_API_KEY \
542
+ nexus-dev:latest
543
+
544
+ # Or use Makefile shortcuts
545
+ make docker-run # Run container
546
+ make docker-logs # View logs
547
+ make docker-stop # Stop container
548
+ ```
549
+
550
+ ### Makefile Commands
551
+
552
+ | Command | Description |
553
+ |---------|-------------|
554
+ | `make setup` | Full dev environment setup (pyenv + venv + deps) |
555
+ | `make install-dev` | Install package with dev dependencies |
556
+ | `make lint` | Run ruff linter |
557
+ | `make format` | Format code + auto-fix lint issues |
558
+ | `make check` | Run all CI checks (lint + format + type-check) |
559
+ | `make test` | Run tests |
560
+ | `make test-cov` | Run tests with coverage report |
561
+ | `make docker-build` | Build Docker image |
562
+ | `make docker-run` | Run Docker container |
563
+ | `make help` | Show all available commands |
564
+
565
+ ### MCP Configuration (Development Mode)
566
+
567
+ Configure your AI agent to use the locally-built server. **This single configuration works for ALL your indexed projects!**
568
+
569
+ **For Claude Desktop / Cursor / Windsurf:**
570
+
571
+ ```json
572
+ {
573
+ "mcpServers": {
574
+ "nexus-dev": {
575
+ "command": "/path/to/nexus-dev/.venv/bin/python",
576
+ "args": ["-m", "nexus_dev.server"],
577
+ "env": {
578
+ "OPENAI_API_KEY": "sk-..."
579
+ }
580
+ }
581
+ }
582
+ }
583
+ ```
584
+
585
+ > **How it works**: The server now defaults to searching **all indexed projects** when no specific project context is active. You don't need to configure `cwd` or create separate MCP entries for each project.
586
+
587
+ > **Tip**: If `OPENAI_API_KEY` is already in your shell profile (`.zshrc`, `.bashrc`), some clients inherit it automatically. Check your client's documentation.
588
+
589
+ **Using Docker:**
590
+
591
+ The `/workspace` mount is the server's working directory. It looks for `nexus_config.json` and `.nexus/lessons/` there. Mount your project (or parent directory) to `/workspace`:
592
+
593
+ ```json
594
+ {
595
+ "mcpServers": {
596
+ "nexus-dev": {
597
+ "command": "docker",
598
+ "args": [
599
+ "run", "-i", "--rm",
600
+ "-v", "/path/to/project:/workspace:ro",
601
+ "-v", "nexus-dev-data:/data/nexus-dev",
602
+ "-e", "OPENAI_API_KEY",
603
+ "nexus-dev:latest"
604
+ ]
605
+ }
606
+ }
607
+ }
608
+ ```
609
+
610
+ **Multi-Project Setup:**
611
+
612
+ For multiple projects, you have two options:
613
+
614
+ 1. **Mount parent directory** containing all projects:
615
+ ```json
616
+ "-v", "/Users/you/Projects:/workspace:ro"
617
+ ```
618
+ Then index paths like `/workspace/project-a/src/`, `/workspace/project-b/src/`. Each project needs its own `nexus_config.json` with a unique `project_id`.
619
+
620
+ 2. **Use local Python install** (recommended): MCP clients automatically set the working directory to the project root, so no path configuration is needed.
621
+
622
+ ### Running Tests
623
+
624
+ ```bash
625
+ make test # Run all tests
626
+ make test-cov # Run with coverage report
627
+ pytest tests/unit/ -v # Run specific test directory
628
+ ```
629
+
630
+ ## Adding Language Support
631
+
632
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on adding new language chunkers.
633
+
634
+ ## License
635
+
636
+ MIT License - see [LICENSE](LICENSE) for details.
@@ -0,0 +1,48 @@
1
+ nexus_dev/__init__.py,sha256=Z3RZGWtZo_sAwvtMsZfZC-DRzLBNFph07RNcGVVqyXs,123
2
+ nexus_dev/cli.py,sha256=KWss6wGYnRZHnCOhi8-l8YvetZjjw6_NUW7eBhxNO1g,55176
3
+ nexus_dev/config.py,sha256=cDX0ytTpIeVXs-Nj8ovFGdAAHzXGM3GNC8eEe0cuWz4,8932
4
+ nexus_dev/database.py,sha256=Vllytiu-LfQcra_N7SyiSlNVMnx_NL2b3Ri4bJ9-pxE,17159
5
+ nexus_dev/embeddings.py,sha256=v7d_UhAQrVN41uu9bVwD2F-a1y_Tb8_ZOVZ9JgF0sJk,18051
6
+ nexus_dev/github_importer.py,sha256=1v9iej6GVBJtHhm0qj2muzNXa03EDs2qGNpdBPbGJF4,8150
7
+ nexus_dev/mcp_client.py,sha256=A_5rXJXRlEReUcLmrtWlm15fDMIAXsCN_ahY9OS9ez0,9814
8
+ nexus_dev/mcp_config.py,sha256=lYeiSBPdRkWvqt6V01YmWKkXCmMgxpPF0GZkPm413ZU,5975
9
+ nexus_dev/server.py,sha256=jh1JiihIphFS3rYo-yET4bdeDSsiXb1y5V9f4Ztvugw,62106
10
+ nexus_dev/agent_templates/__init__.py,sha256=ZP4G-RH2F-qUsN8beymq3lIvsujN-V_O_FZ1oizCNf8,631
11
+ nexus_dev/agent_templates/api_designer.yaml,sha256=Mowp7840GI_6ivcR8JvfQDzvkJ5-qGPNlwM-EZbmeHw,921
12
+ nexus_dev/agent_templates/code_reviewer.yaml,sha256=EbidUX8k_hYkTVFC7c97U9Ra-KYfJ8Y3ChyLqmiOwfc,935
13
+ nexus_dev/agent_templates/debug_detective.yaml,sha256=7wpAgO3G6qKqXq448Niln7o3eQKbN3K5tCuq9fv8yp4,874
14
+ nexus_dev/agent_templates/doc_writer.yaml,sha256=fh0Q1_sBQ6HXy9smxZ3JYfjnz4n0cUNIWl4G2Vs3gFk,868
15
+ nexus_dev/agent_templates/performance_optimizer.yaml,sha256=lZXLhwLEkkOo-vrk1FK6QFtOIAMC0dr4CuAnIBX_MkA,962
16
+ nexus_dev/agent_templates/refactor_architect.yaml,sha256=agi2SQvBPrdfel39bI1XuT_EGyFpLjNaIe7le3enfyA,965
17
+ nexus_dev/agent_templates/security_auditor.yaml,sha256=OEm7f0mAMKh0zDcQ_-1CXGTn_66PtqsPs0NyzskF8cE,949
18
+ nexus_dev/agent_templates/test_engineer.yaml,sha256=dePaMDtiNNG7jANfdEViGfxZhDzRrCxEmrngXxo8Jrk,873
19
+ nexus_dev/agents/__init__.py,sha256=cXbsIFvRY6hsCg1zvn8Bd-fDgHPQXRn8zUfxTca921M,536
20
+ nexus_dev/agents/agent_config.py,sha256=PYSETSfbyGmJFh-demcrbKNSmQ_pJ9ZlFAWxJv346VA,3424
21
+ nexus_dev/agents/agent_executor.py,sha256=mWFyL5NUTdu7lGf4wOc8p1eD-17hxUwtmfJzfMTiWGg,6843
22
+ nexus_dev/agents/agent_manager.py,sha256=tgkmFhvpgZO8UwZ4jcj9DevA81ULlTqvS1X7UOdzblo,3138
23
+ nexus_dev/agents/prompt_factory.py,sha256=Uco3OqqGxnikvGa031ObIQb0pO9UEt-Db64mFuyIW7k,2861
24
+ nexus_dev/chunkers/__init__.py,sha256=raOZ6Iwa5l_NRC2sUF7VC9Hgq1QNy8Kci_YaGpHCscQ,4622
25
+ nexus_dev/chunkers/base.py,sha256=-JyAzbnXNvoicunaVfrkBnmiTN2drgV__FTlbP6vAaY,5885
26
+ nexus_dev/chunkers/docs_chunker.py,sha256=Dc2pYW2ppa4zG8WHvvJb7TdqKx62F7Fc6NecMYgmfhY,10025
27
+ nexus_dev/chunkers/java_chunker.py,sha256=ujS1rifkFWCwShc3UYKVwPCxRpSGGXSC9f5s33k9HGI,11410
28
+ nexus_dev/chunkers/javascript_chunker.py,sha256=dzADmmHGkNJybgQfaRI7NYbc28sIAAYgyMoM2v90Xfk,10549
29
+ nexus_dev/chunkers/python_chunker.py,sha256=OAzodDBEPkZvNnzmQP68T5ktIrT31tx923YpjduGhbQ,10092
30
+ nexus_dev/gateway/__init__.py,sha256=WbXF_2CdqcX0v41OeB4fVWbh8mK_LvAWtcsegqTNkRU,267
31
+ nexus_dev/gateway/connection_manager.py,sha256=MO0W8qWCbM859YxM0vLAfVLL_YLeciQ4UlRfWwOPlu8,13911
32
+ nexus_dev/schemas/mcp_config_schema.json,sha256=xnFyqX8qzF6QxXtGtUUCIs056vxki3p2NQIzO9Utn38,5741
33
+ nexus_dev/templates/pre-commit-hook,sha256=--HmPCpDpUdT_w9FiRPsaEzbHiLDQp8ETmyca_JOsgo,998
34
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/__init__.py,sha256=ZP4G-RH2F-qUsN8beymq3lIvsujN-V_O_FZ1oizCNf8,631
35
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/api_designer.yaml,sha256=Mowp7840GI_6ivcR8JvfQDzvkJ5-qGPNlwM-EZbmeHw,921
36
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/code_reviewer.yaml,sha256=EbidUX8k_hYkTVFC7c97U9Ra-KYfJ8Y3ChyLqmiOwfc,935
37
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/debug_detective.yaml,sha256=7wpAgO3G6qKqXq448Niln7o3eQKbN3K5tCuq9fv8yp4,874
38
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/doc_writer.yaml,sha256=fh0Q1_sBQ6HXy9smxZ3JYfjnz4n0cUNIWl4G2Vs3gFk,868
39
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/performance_optimizer.yaml,sha256=lZXLhwLEkkOo-vrk1FK6QFtOIAMC0dr4CuAnIBX_MkA,962
40
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/refactor_architect.yaml,sha256=agi2SQvBPrdfel39bI1XuT_EGyFpLjNaIe7le3enfyA,965
41
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/security_auditor.yaml,sha256=OEm7f0mAMKh0zDcQ_-1CXGTn_66PtqsPs0NyzskF8cE,949
42
+ nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/test_engineer.yaml,sha256=dePaMDtiNNG7jANfdEViGfxZhDzRrCxEmrngXxo8Jrk,873
43
+ nexus_dev-3.2.0.data/data/nexus_dev/templates/pre-commit-hook,sha256=--HmPCpDpUdT_w9FiRPsaEzbHiLDQp8ETmyca_JOsgo,998
44
+ nexus_dev-3.2.0.dist-info/METADATA,sha256=YJqA4kFNX1nGVx8dn84Kn6lgtguvVs3QhO1yM4VIT-M,18424
45
+ nexus_dev-3.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
46
+ nexus_dev-3.2.0.dist-info/entry_points.txt,sha256=AbEp9EbaXfYtqHvlYUtODU5jsMjobGuuxARXR2ySz7U,518
47
+ nexus_dev-3.2.0.dist-info/licenses/LICENSE,sha256=-GCye_VyFvmidGfl-YXa08gwO7KzI5ACGRoi4BxIJHE,1070
48
+ nexus_dev-3.2.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.28.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,12 @@
1
+ [console_scripts]
2
+ nexus-agent = nexus_dev.cli:agent_command_entry
3
+ nexus-dev = nexus_dev.server:main
4
+ nexus-export = nexus_dev.cli:export_command
5
+ nexus-import-github = nexus_dev.cli:import_github_command
6
+ nexus-index = nexus_dev.cli:index_command
7
+ nexus-index-mcp = nexus_dev.cli:index_mcp_command_entry
8
+ nexus-init = nexus_dev.cli:init_command
9
+ nexus-mcp = nexus_dev.cli:mcp_command_entry
10
+ nexus-reindex = nexus_dev.cli:reindex_command
11
+ nexus-search = nexus_dev.cli:search_command
12
+ nexus-status = nexus_dev.cli:status_command