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.
- nexus_dev/__init__.py +4 -0
- nexus_dev/agent_templates/__init__.py +26 -0
- nexus_dev/agent_templates/api_designer.yaml +26 -0
- nexus_dev/agent_templates/code_reviewer.yaml +26 -0
- nexus_dev/agent_templates/debug_detective.yaml +26 -0
- nexus_dev/agent_templates/doc_writer.yaml +26 -0
- nexus_dev/agent_templates/performance_optimizer.yaml +26 -0
- nexus_dev/agent_templates/refactor_architect.yaml +26 -0
- nexus_dev/agent_templates/security_auditor.yaml +26 -0
- nexus_dev/agent_templates/test_engineer.yaml +26 -0
- nexus_dev/agents/__init__.py +20 -0
- nexus_dev/agents/agent_config.py +97 -0
- nexus_dev/agents/agent_executor.py +197 -0
- nexus_dev/agents/agent_manager.py +104 -0
- nexus_dev/agents/prompt_factory.py +91 -0
- nexus_dev/chunkers/__init__.py +168 -0
- nexus_dev/chunkers/base.py +202 -0
- nexus_dev/chunkers/docs_chunker.py +291 -0
- nexus_dev/chunkers/java_chunker.py +343 -0
- nexus_dev/chunkers/javascript_chunker.py +312 -0
- nexus_dev/chunkers/python_chunker.py +308 -0
- nexus_dev/cli.py +1673 -0
- nexus_dev/config.py +253 -0
- nexus_dev/database.py +558 -0
- nexus_dev/embeddings.py +585 -0
- nexus_dev/gateway/__init__.py +10 -0
- nexus_dev/gateway/connection_manager.py +348 -0
- nexus_dev/github_importer.py +247 -0
- nexus_dev/mcp_client.py +281 -0
- nexus_dev/mcp_config.py +184 -0
- nexus_dev/schemas/mcp_config_schema.json +166 -0
- nexus_dev/server.py +1866 -0
- nexus_dev/templates/pre-commit-hook +33 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/__init__.py +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/api_designer.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/code_reviewer.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/debug_detective.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/doc_writer.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/performance_optimizer.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/refactor_architect.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/security_auditor.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/agent_templates/test_engineer.yaml +26 -0
- nexus_dev-3.2.0.data/data/nexus_dev/templates/pre-commit-hook +33 -0
- nexus_dev-3.2.0.dist-info/METADATA +636 -0
- nexus_dev-3.2.0.dist-info/RECORD +48 -0
- nexus_dev-3.2.0.dist-info/WHEEL +4 -0
- nexus_dev-3.2.0.dist-info/entry_points.txt +12 -0
- 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
|
+
[](https://github.com/mmornati/nexus-dev/actions/workflows/ci.yml)
|
|
55
|
+
[](https://codecov.io/gh/mmornati/nexus-dev)
|
|
56
|
+
[](https://www.python.org/downloads/)
|
|
57
|
+
[](https://opensource.org/licenses/MIT)
|
|
58
|
+
[](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,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
|