gitnexus 1.1.1 → 1.1.3
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.
- package/README.md +196 -196
- package/dist/cli/ai-context.js +89 -89
- package/dist/cli/mcp.js +28 -0
- package/dist/cli/setup.js +1 -1
- package/dist/core/ingestion/pipeline.js +4 -1
- package/dist/core/ingestion/process-processor.js +27 -3
- package/dist/core/search/bm25-index.js +5 -5
- package/dist/mcp/local/local-backend.d.ts +6 -0
- package/dist/mcp/local/local-backend.js +135 -79
- package/dist/mcp/resources.js +55 -38
- package/dist/mcp/tools.js +82 -82
- package/package.json +80 -80
- package/skills/debugging.md +106 -106
- package/skills/exploring.md +126 -126
- package/skills/impact-analysis.md +117 -117
- package/skills/refactoring.md +120 -120
package/README.md
CHANGED
|
@@ -1,196 +1,196 @@
|
|
|
1
|
-
# GitNexus
|
|
2
|
-
|
|
3
|
-
**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
|
|
4
|
-
|
|
5
|
-
Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/gitnexus)
|
|
8
|
-
[](https://polyformproject.org/licenses/noncommercial/1.0.0/)
|
|
9
|
-
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
## Why?
|
|
13
|
-
|
|
14
|
-
AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
|
|
15
|
-
|
|
16
|
-
**Three commands to give your AI agent full codebase awareness.**
|
|
17
|
-
|
|
18
|
-
## Quick Start
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
# Install
|
|
22
|
-
npm install -g gitnexus
|
|
23
|
-
|
|
24
|
-
# One-time: configure MCP for your editors
|
|
25
|
-
gitnexus setup
|
|
26
|
-
|
|
27
|
-
# Index your repository (run from repo root)
|
|
28
|
-
gitnexus analyze
|
|
29
|
-
|
|
30
|
-
# Done! Open your editor — MCP connects automatically.
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
Or without installing globally:
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
npx gitnexus setup # one-time
|
|
37
|
-
npx gitnexus analyze # per repo
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
The `setup` command auto-detects Cursor, Claude Code, and OpenCode, then writes the correct global MCP config. You only run it once.
|
|
41
|
-
|
|
42
|
-
## MCP Setup (manual)
|
|
43
|
-
|
|
44
|
-
If you prefer to configure manually instead of using `gitnexus setup`:
|
|
45
|
-
|
|
46
|
-
### Cursor / Windsurf
|
|
47
|
-
|
|
48
|
-
Add to `~/.cursor/mcp.json` (global — works for all projects):
|
|
49
|
-
|
|
50
|
-
```json
|
|
51
|
-
{
|
|
52
|
-
"mcpServers": {
|
|
53
|
-
"gitnexus": {
|
|
54
|
-
"command": "npx",
|
|
55
|
-
"args": ["-y", "gitnexus", "mcp"]
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
### Claude Code
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
claude mcp add gitnexus -- npx -y gitnexus mcp
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### OpenCode
|
|
68
|
-
|
|
69
|
-
Add to `~/.config/opencode/config.json`:
|
|
70
|
-
|
|
71
|
-
```json
|
|
72
|
-
{
|
|
73
|
-
"mcp": {
|
|
74
|
-
"gitnexus": {
|
|
75
|
-
"command": "npx",
|
|
76
|
-
"args": ["-y", "gitnexus", "mcp"]
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
}
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
## What It Does
|
|
83
|
-
|
|
84
|
-
GitNexus indexes your codebase through 7 phases:
|
|
85
|
-
|
|
86
|
-
1. **Structure** — File/folder tree
|
|
87
|
-
2. **Parse** — AST extraction via Tree-sitter (9 languages)
|
|
88
|
-
3. **Imports** — Resolve import paths (including TS path aliases, Rust modules, Java wildcards, Go packages)
|
|
89
|
-
4. **Calls** — Function call resolution with confidence scoring (0.3-0.9)
|
|
90
|
-
5. **Heritage** — Class extends/implements chains
|
|
91
|
-
6. **Communities** — Leiden algorithm clusters related code into functional groups
|
|
92
|
-
7. **Processes** — Entry point detection and execution flow tracing
|
|
93
|
-
|
|
94
|
-
The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
|
|
95
|
-
|
|
96
|
-
## MCP Tools
|
|
97
|
-
|
|
98
|
-
Your AI agent gets these tools automatically:
|
|
99
|
-
|
|
100
|
-
| Tool | What It Does | `repo` Param |
|
|
101
|
-
|------|-------------|--------------|
|
|
102
|
-
| `list_repos` | Discover all indexed repositories | — |
|
|
103
|
-
| `search` | Hybrid search (BM25 + semantic) with cluster context | Optional |
|
|
104
|
-
| `overview` | List all clusters and processes | Optional |
|
|
105
|
-
| `explore` | Deep dive on a symbol, cluster, or process | Optional |
|
|
106
|
-
| `impact` | Blast radius analysis | Optional |
|
|
107
|
-
| `cypher` | Raw Cypher graph queries | Optional |
|
|
108
|
-
| `analyze` | Index or re-index a repository | Optional |
|
|
109
|
-
|
|
110
|
-
> With one indexed repo, the `repo` param is optional. With multiple, specify which: `search({query: "auth", repo: "my-app"})`.
|
|
111
|
-
|
|
112
|
-
## MCP Resources
|
|
113
|
-
|
|
114
|
-
| Resource | Purpose |
|
|
115
|
-
|----------|---------|
|
|
116
|
-
| `gitnexus://repos` | List all indexed repositories (read first) |
|
|
117
|
-
| `gitnexus://repo/{name}/context` | Codebase stats and overview |
|
|
118
|
-
| `gitnexus://repo/{name}/clusters` | All functional clusters |
|
|
119
|
-
| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details |
|
|
120
|
-
| `gitnexus://repo/{name}/processes` | All execution flows |
|
|
121
|
-
| `gitnexus://repo/{name}/process/{name}` | Full process trace |
|
|
122
|
-
| `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
|
|
123
|
-
|
|
124
|
-
## CLI Commands
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
gitnexus setup # Configure MCP for your editors (one-time)
|
|
128
|
-
gitnexus analyze [path] # Index a repository (or update stale index)
|
|
129
|
-
gitnexus analyze --force # Force full re-index
|
|
130
|
-
gitnexus mcp # Start MCP server (stdio) — serves all indexed repos
|
|
131
|
-
gitnexus serve # Start HTTP server for web UI
|
|
132
|
-
gitnexus list # List all indexed repositories
|
|
133
|
-
gitnexus status # Show index status for current repo
|
|
134
|
-
gitnexus clean # Delete index for current repo
|
|
135
|
-
gitnexus clean --all # Delete all indexes
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
## Multi-Repo Support
|
|
139
|
-
|
|
140
|
-
GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections.
|
|
141
|
-
|
|
142
|
-
## Supported Languages
|
|
143
|
-
|
|
144
|
-
TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
|
|
145
|
-
|
|
146
|
-
## How Impact Analysis Works
|
|
147
|
-
|
|
148
|
-
```
|
|
149
|
-
gitnexus_impact({target: "UserService", direction: "upstream", repo: "my-app"})
|
|
150
|
-
|
|
151
|
-
TARGET: Class UserService (src/services/user.ts)
|
|
152
|
-
|
|
153
|
-
UPSTREAM (what depends on this):
|
|
154
|
-
Depth 1 (direct callers):
|
|
155
|
-
handleLogin [CALLS 90%] → src/api/auth.ts:45
|
|
156
|
-
handleRegister [CALLS 90%] → src/api/auth.ts:78
|
|
157
|
-
Depth 2:
|
|
158
|
-
authRouter [IMPORTS] → src/routes/auth.ts
|
|
159
|
-
|
|
160
|
-
8 files affected, 3 clusters touched
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
Options: `maxDepth`, `minConfidence`, `relationTypes`, `includeTests`
|
|
164
|
-
|
|
165
|
-
## Agent Skills
|
|
166
|
-
|
|
167
|
-
GitNexus ships with skill files that teach AI agents how to use the tools effectively:
|
|
168
|
-
|
|
169
|
-
- **Exploring** — Navigate unfamiliar code using the knowledge graph
|
|
170
|
-
- **Debugging** — Trace bugs through call chains
|
|
171
|
-
- **Impact Analysis** — Analyze blast radius before changes
|
|
172
|
-
- **Refactoring** — Plan safe refactors using dependency mapping
|
|
173
|
-
|
|
174
|
-
These are installed automatically to `.claude/skills/` when you run `gitnexus analyze`.
|
|
175
|
-
|
|
176
|
-
## Requirements
|
|
177
|
-
|
|
178
|
-
- Node.js >= 18
|
|
179
|
-
- Git repository (uses git for commit tracking)
|
|
180
|
-
|
|
181
|
-
## Privacy
|
|
182
|
-
|
|
183
|
-
- All processing happens locally on your machine
|
|
184
|
-
- No code is sent to any server
|
|
185
|
-
- Index stored in `.gitnexus/` inside your repo (gitignored)
|
|
186
|
-
- Global registry at `~/.gitnexus/` stores only paths and metadata
|
|
187
|
-
|
|
188
|
-
## Web UI
|
|
189
|
-
|
|
190
|
-
GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
|
|
191
|
-
|
|
192
|
-
## License
|
|
193
|
-
|
|
194
|
-
[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
|
|
195
|
-
|
|
196
|
-
Free for non-commercial use. Contact for commercial licensing.
|
|
1
|
+
# GitNexus
|
|
2
|
+
|
|
3
|
+
**Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
|
|
4
|
+
|
|
5
|
+
Works with **Cursor**, **Claude Code**, **Windsurf**, **Cline**, **OpenCode**, and any MCP-compatible tool.
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/gitnexus)
|
|
8
|
+
[](https://polyformproject.org/licenses/noncommercial/1.0.0/)
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Why?
|
|
13
|
+
|
|
14
|
+
AI coding tools don't understand your codebase structure. They edit a function without knowing 47 other functions depend on it. GitNexus fixes this by **precomputing every dependency, call chain, and relationship** into a queryable graph.
|
|
15
|
+
|
|
16
|
+
**Three commands to give your AI agent full codebase awareness.**
|
|
17
|
+
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# Install
|
|
22
|
+
npm install -g gitnexus
|
|
23
|
+
|
|
24
|
+
# One-time: configure MCP for your editors
|
|
25
|
+
gitnexus setup
|
|
26
|
+
|
|
27
|
+
# Index your repository (run from repo root)
|
|
28
|
+
gitnexus analyze
|
|
29
|
+
|
|
30
|
+
# Done! Open your editor — MCP connects automatically.
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Or without installing globally:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npx gitnexus setup # one-time
|
|
37
|
+
npx gitnexus analyze # per repo
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The `setup` command auto-detects Cursor, Claude Code, and OpenCode, then writes the correct global MCP config. You only run it once.
|
|
41
|
+
|
|
42
|
+
## MCP Setup (manual)
|
|
43
|
+
|
|
44
|
+
If you prefer to configure manually instead of using `gitnexus setup`:
|
|
45
|
+
|
|
46
|
+
### Cursor / Windsurf
|
|
47
|
+
|
|
48
|
+
Add to `~/.cursor/mcp.json` (global — works for all projects):
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"gitnexus": {
|
|
54
|
+
"command": "npx",
|
|
55
|
+
"args": ["-y", "gitnexus@latest", "mcp"]
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Claude Code
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
claude mcp add gitnexus -- npx -y gitnexus@latest mcp
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### OpenCode
|
|
68
|
+
|
|
69
|
+
Add to `~/.config/opencode/config.json`:
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"mcp": {
|
|
74
|
+
"gitnexus": {
|
|
75
|
+
"command": "npx",
|
|
76
|
+
"args": ["-y", "gitnexus@latest", "mcp"]
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## What It Does
|
|
83
|
+
|
|
84
|
+
GitNexus indexes your codebase through 7 phases:
|
|
85
|
+
|
|
86
|
+
1. **Structure** — File/folder tree
|
|
87
|
+
2. **Parse** — AST extraction via Tree-sitter (9 languages)
|
|
88
|
+
3. **Imports** — Resolve import paths (including TS path aliases, Rust modules, Java wildcards, Go packages)
|
|
89
|
+
4. **Calls** — Function call resolution with confidence scoring (0.3-0.9)
|
|
90
|
+
5. **Heritage** — Class extends/implements chains
|
|
91
|
+
6. **Communities** — Leiden algorithm clusters related code into functional groups
|
|
92
|
+
7. **Processes** — Entry point detection and execution flow tracing
|
|
93
|
+
|
|
94
|
+
The result is a **KuzuDB graph database** stored locally in `.gitnexus/` with full-text search and semantic embeddings.
|
|
95
|
+
|
|
96
|
+
## MCP Tools
|
|
97
|
+
|
|
98
|
+
Your AI agent gets these tools automatically:
|
|
99
|
+
|
|
100
|
+
| Tool | What It Does | `repo` Param |
|
|
101
|
+
|------|-------------|--------------|
|
|
102
|
+
| `list_repos` | Discover all indexed repositories | — |
|
|
103
|
+
| `search` | Hybrid search (BM25 + semantic) with cluster context | Optional |
|
|
104
|
+
| `overview` | List all clusters and processes | Optional |
|
|
105
|
+
| `explore` | Deep dive on a symbol, cluster, or process | Optional |
|
|
106
|
+
| `impact` | Blast radius analysis | Optional |
|
|
107
|
+
| `cypher` | Raw Cypher graph queries | Optional |
|
|
108
|
+
| `analyze` | Index or re-index a repository | Optional |
|
|
109
|
+
|
|
110
|
+
> With one indexed repo, the `repo` param is optional. With multiple, specify which: `search({query: "auth", repo: "my-app"})`.
|
|
111
|
+
|
|
112
|
+
## MCP Resources
|
|
113
|
+
|
|
114
|
+
| Resource | Purpose |
|
|
115
|
+
|----------|---------|
|
|
116
|
+
| `gitnexus://repos` | List all indexed repositories (read first) |
|
|
117
|
+
| `gitnexus://repo/{name}/context` | Codebase stats and overview |
|
|
118
|
+
| `gitnexus://repo/{name}/clusters` | All functional clusters |
|
|
119
|
+
| `gitnexus://repo/{name}/cluster/{name}` | Cluster members and details |
|
|
120
|
+
| `gitnexus://repo/{name}/processes` | All execution flows |
|
|
121
|
+
| `gitnexus://repo/{name}/process/{name}` | Full process trace |
|
|
122
|
+
| `gitnexus://repo/{name}/schema` | Graph schema for Cypher queries |
|
|
123
|
+
|
|
124
|
+
## CLI Commands
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
gitnexus setup # Configure MCP for your editors (one-time)
|
|
128
|
+
gitnexus analyze [path] # Index a repository (or update stale index)
|
|
129
|
+
gitnexus analyze --force # Force full re-index
|
|
130
|
+
gitnexus mcp # Start MCP server (stdio) — serves all indexed repos
|
|
131
|
+
gitnexus serve # Start HTTP server for web UI
|
|
132
|
+
gitnexus list # List all indexed repositories
|
|
133
|
+
gitnexus status # Show index status for current repo
|
|
134
|
+
gitnexus clean # Delete index for current repo
|
|
135
|
+
gitnexus clean --all # Delete all indexes
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Multi-Repo Support
|
|
139
|
+
|
|
140
|
+
GitNexus supports indexing multiple repositories. Each `gitnexus analyze` registers the repo in a global registry (`~/.gitnexus/registry.json`). The MCP server serves all indexed repos automatically with lazy KuzuDB connections.
|
|
141
|
+
|
|
142
|
+
## Supported Languages
|
|
143
|
+
|
|
144
|
+
TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust
|
|
145
|
+
|
|
146
|
+
## How Impact Analysis Works
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
gitnexus_impact({target: "UserService", direction: "upstream", repo: "my-app"})
|
|
150
|
+
|
|
151
|
+
TARGET: Class UserService (src/services/user.ts)
|
|
152
|
+
|
|
153
|
+
UPSTREAM (what depends on this):
|
|
154
|
+
Depth 1 (direct callers):
|
|
155
|
+
handleLogin [CALLS 90%] → src/api/auth.ts:45
|
|
156
|
+
handleRegister [CALLS 90%] → src/api/auth.ts:78
|
|
157
|
+
Depth 2:
|
|
158
|
+
authRouter [IMPORTS] → src/routes/auth.ts
|
|
159
|
+
|
|
160
|
+
8 files affected, 3 clusters touched
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Options: `maxDepth`, `minConfidence`, `relationTypes`, `includeTests`
|
|
164
|
+
|
|
165
|
+
## Agent Skills
|
|
166
|
+
|
|
167
|
+
GitNexus ships with skill files that teach AI agents how to use the tools effectively:
|
|
168
|
+
|
|
169
|
+
- **Exploring** — Navigate unfamiliar code using the knowledge graph
|
|
170
|
+
- **Debugging** — Trace bugs through call chains
|
|
171
|
+
- **Impact Analysis** — Analyze blast radius before changes
|
|
172
|
+
- **Refactoring** — Plan safe refactors using dependency mapping
|
|
173
|
+
|
|
174
|
+
These are installed automatically to `.claude/skills/` when you run `gitnexus analyze`.
|
|
175
|
+
|
|
176
|
+
## Requirements
|
|
177
|
+
|
|
178
|
+
- Node.js >= 18
|
|
179
|
+
- Git repository (uses git for commit tracking)
|
|
180
|
+
|
|
181
|
+
## Privacy
|
|
182
|
+
|
|
183
|
+
- All processing happens locally on your machine
|
|
184
|
+
- No code is sent to any server
|
|
185
|
+
- Index stored in `.gitnexus/` inside your repo (gitignored)
|
|
186
|
+
- Global registry at `~/.gitnexus/` stores only paths and metadata
|
|
187
|
+
|
|
188
|
+
## Web UI
|
|
189
|
+
|
|
190
|
+
GitNexus also has a browser-based UI at [gitnexus.vercel.app](https://gitnexus.vercel.app) — 100% client-side, your code never leaves the browser.
|
|
191
|
+
|
|
192
|
+
## License
|
|
193
|
+
|
|
194
|
+
[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)
|
|
195
|
+
|
|
196
|
+
Free for non-commercial use. Contact for commercial licensing.
|
package/dist/cli/ai-context.js
CHANGED
|
@@ -17,85 +17,85 @@ const GITNEXUS_END_MARKER = '<!-- gitnexus:end -->';
|
|
|
17
17
|
* Generate the full GitNexus context content (resources-first approach)
|
|
18
18
|
*/
|
|
19
19
|
function generateGitNexusContent(projectName, stats) {
|
|
20
|
-
return `${GITNEXUS_START_MARKER}
|
|
21
|
-
# GitNexus MCP
|
|
22
|
-
|
|
23
|
-
This project is indexed as **${projectName}** by GitNexus, providing AI agents with deep code intelligence.
|
|
24
|
-
|
|
25
|
-
## Project: ${projectName}
|
|
26
|
-
|
|
27
|
-
| Metric | Count |
|
|
28
|
-
|--------|-------|
|
|
29
|
-
| Files | ${stats.files || 0} |
|
|
30
|
-
| Symbols | ${stats.nodes || 0} |
|
|
31
|
-
| Relationships | ${stats.edges || 0} |
|
|
32
|
-
| Communities | ${stats.communities || 0} |
|
|
33
|
-
| Processes | ${stats.processes || 0} |
|
|
34
|
-
|
|
35
|
-
## Quick Start
|
|
36
|
-
|
|
37
|
-
\`\`\`
|
|
38
|
-
1. READ gitnexus://repos → Discover all indexed repos
|
|
39
|
-
2. READ gitnexus://repo/${projectName}/context → Get codebase overview (~150 tokens)
|
|
40
|
-
3. READ gitnexus://repo/${projectName}/clusters → See all functional clusters
|
|
41
|
-
4. gitnexus_search({query: "...", repo: "${projectName}"}) → Find code by query
|
|
42
|
-
\`\`\`
|
|
43
|
-
|
|
44
|
-
## Available Resources
|
|
45
|
-
|
|
46
|
-
| Resource | Purpose |
|
|
47
|
-
|----------|---------|
|
|
48
|
-
| \`gitnexus://repos\` | List all indexed repositories |
|
|
49
|
-
| \`gitnexus://repo/${projectName}/context\` | Codebase stats, tools, and resources overview |
|
|
50
|
-
| \`gitnexus://repo/${projectName}/clusters\` | All clusters with symbol counts and cohesion |
|
|
51
|
-
| \`gitnexus://repo/${projectName}/cluster/{name}\` | Cluster members and details |
|
|
52
|
-
| \`gitnexus://repo/${projectName}/processes\` | All execution flows with types |
|
|
53
|
-
| \`gitnexus://repo/${projectName}/process/{name}\` | Full process trace with steps |
|
|
54
|
-
| \`gitnexus://repo/${projectName}/schema\` | Graph schema for Cypher queries |
|
|
55
|
-
|
|
56
|
-
## Available Tools
|
|
57
|
-
|
|
58
|
-
| Tool | Purpose | When to Use |
|
|
59
|
-
|------|---------|-------------|
|
|
60
|
-
| \`list_repos\` | Discover indexed repos | First step with multiple repos |
|
|
61
|
-
| \`search\` | Semantic + keyword search | Finding code by query |
|
|
62
|
-
| \`overview\` | List clusters & processes | Understanding architecture |
|
|
63
|
-
| \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation |
|
|
64
|
-
| \`impact\` | Blast radius analysis | Before making changes |
|
|
65
|
-
| \`cypher\` | Raw graph queries | Complex analysis |
|
|
66
|
-
|
|
67
|
-
> **Multi-repo:** When multiple repos are indexed, pass \`repo: "${projectName}"\` to target this project.
|
|
68
|
-
|
|
69
|
-
## Workflow Examples
|
|
70
|
-
|
|
71
|
-
### Exploring the Codebase
|
|
72
|
-
\`\`\`
|
|
73
|
-
READ gitnexus://repos → Discover repos
|
|
74
|
-
READ gitnexus://repo/${projectName}/context → Stats and overview
|
|
75
|
-
READ gitnexus://repo/${projectName}/clusters → Find relevant cluster
|
|
76
|
-
READ gitnexus://repo/${projectName}/cluster/Auth → Explore Auth cluster
|
|
77
|
-
gitnexus_explore({name: "validateUser", type: "symbol", repo: "${projectName}"})
|
|
78
|
-
\`\`\`
|
|
79
|
-
|
|
80
|
-
### Planning a Change
|
|
81
|
-
\`\`\`
|
|
82
|
-
gitnexus_impact({target: "UserService", direction: "upstream", repo: "${projectName}"})
|
|
83
|
-
READ gitnexus://repo/${projectName}/processes → Check affected flows
|
|
84
|
-
gitnexus_explore({name: "LoginFlow", type: "process", repo: "${projectName}"})
|
|
85
|
-
\`\`\`
|
|
86
|
-
|
|
87
|
-
## Graph Schema
|
|
88
|
-
|
|
89
|
-
**Nodes:** File, Function, Class, Interface, Method, Community, Process
|
|
90
|
-
|
|
91
|
-
**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
|
|
92
|
-
|
|
93
|
-
\`\`\`cypher
|
|
94
|
-
// Example: Find callers of a function
|
|
95
|
-
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
|
|
96
|
-
RETURN caller.name, caller.filePath
|
|
97
|
-
\`\`\`
|
|
98
|
-
|
|
20
|
+
return `${GITNEXUS_START_MARKER}
|
|
21
|
+
# GitNexus MCP
|
|
22
|
+
|
|
23
|
+
This project is indexed as **${projectName}** by GitNexus, providing AI agents with deep code intelligence.
|
|
24
|
+
|
|
25
|
+
## Project: ${projectName}
|
|
26
|
+
|
|
27
|
+
| Metric | Count |
|
|
28
|
+
|--------|-------|
|
|
29
|
+
| Files | ${stats.files || 0} |
|
|
30
|
+
| Symbols | ${stats.nodes || 0} |
|
|
31
|
+
| Relationships | ${stats.edges || 0} |
|
|
32
|
+
| Communities | ${stats.communities || 0} |
|
|
33
|
+
| Processes | ${stats.processes || 0} |
|
|
34
|
+
|
|
35
|
+
## Quick Start
|
|
36
|
+
|
|
37
|
+
\`\`\`
|
|
38
|
+
1. READ gitnexus://repos → Discover all indexed repos
|
|
39
|
+
2. READ gitnexus://repo/${projectName}/context → Get codebase overview (~150 tokens)
|
|
40
|
+
3. READ gitnexus://repo/${projectName}/clusters → See all functional clusters
|
|
41
|
+
4. gitnexus_search({query: "...", repo: "${projectName}"}) → Find code by query
|
|
42
|
+
\`\`\`
|
|
43
|
+
|
|
44
|
+
## Available Resources
|
|
45
|
+
|
|
46
|
+
| Resource | Purpose |
|
|
47
|
+
|----------|---------|
|
|
48
|
+
| \`gitnexus://repos\` | List all indexed repositories |
|
|
49
|
+
| \`gitnexus://repo/${projectName}/context\` | Codebase stats, tools, and resources overview |
|
|
50
|
+
| \`gitnexus://repo/${projectName}/clusters\` | All clusters with symbol counts and cohesion |
|
|
51
|
+
| \`gitnexus://repo/${projectName}/cluster/{name}\` | Cluster members and details |
|
|
52
|
+
| \`gitnexus://repo/${projectName}/processes\` | All execution flows with types |
|
|
53
|
+
| \`gitnexus://repo/${projectName}/process/{name}\` | Full process trace with steps |
|
|
54
|
+
| \`gitnexus://repo/${projectName}/schema\` | Graph schema for Cypher queries |
|
|
55
|
+
|
|
56
|
+
## Available Tools
|
|
57
|
+
|
|
58
|
+
| Tool | Purpose | When to Use |
|
|
59
|
+
|------|---------|-------------|
|
|
60
|
+
| \`list_repos\` | Discover indexed repos | First step with multiple repos |
|
|
61
|
+
| \`search\` | Semantic + keyword search | Finding code by query |
|
|
62
|
+
| \`overview\` | List clusters & processes | Understanding architecture |
|
|
63
|
+
| \`explore\` | Deep dive on symbol/cluster/process | Detailed investigation |
|
|
64
|
+
| \`impact\` | Blast radius analysis | Before making changes |
|
|
65
|
+
| \`cypher\` | Raw graph queries | Complex analysis |
|
|
66
|
+
|
|
67
|
+
> **Multi-repo:** When multiple repos are indexed, pass \`repo: "${projectName}"\` to target this project.
|
|
68
|
+
|
|
69
|
+
## Workflow Examples
|
|
70
|
+
|
|
71
|
+
### Exploring the Codebase
|
|
72
|
+
\`\`\`
|
|
73
|
+
READ gitnexus://repos → Discover repos
|
|
74
|
+
READ gitnexus://repo/${projectName}/context → Stats and overview
|
|
75
|
+
READ gitnexus://repo/${projectName}/clusters → Find relevant cluster
|
|
76
|
+
READ gitnexus://repo/${projectName}/cluster/Auth → Explore Auth cluster
|
|
77
|
+
gitnexus_explore({name: "validateUser", type: "symbol", repo: "${projectName}"})
|
|
78
|
+
\`\`\`
|
|
79
|
+
|
|
80
|
+
### Planning a Change
|
|
81
|
+
\`\`\`
|
|
82
|
+
gitnexus_impact({target: "UserService", direction: "upstream", repo: "${projectName}"})
|
|
83
|
+
READ gitnexus://repo/${projectName}/processes → Check affected flows
|
|
84
|
+
gitnexus_explore({name: "LoginFlow", type: "process", repo: "${projectName}"})
|
|
85
|
+
\`\`\`
|
|
86
|
+
|
|
87
|
+
## Graph Schema
|
|
88
|
+
|
|
89
|
+
**Nodes:** File, Function, Class, Interface, Method, Community, Process
|
|
90
|
+
|
|
91
|
+
**Relationships:** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS
|
|
92
|
+
|
|
93
|
+
\`\`\`cypher
|
|
94
|
+
// Example: Find callers of a function
|
|
95
|
+
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
|
|
96
|
+
RETURN caller.name, caller.filePath
|
|
97
|
+
\`\`\`
|
|
98
|
+
|
|
99
99
|
${GITNEXUS_END_MARKER}`;
|
|
100
100
|
}
|
|
101
101
|
/**
|
|
@@ -179,16 +179,16 @@ async function installSkills(repoPath) {
|
|
|
179
179
|
}
|
|
180
180
|
catch {
|
|
181
181
|
// Fallback: generate minimal skill content
|
|
182
|
-
skillContent = `---
|
|
183
|
-
name: gitnexus-${skill.name}
|
|
184
|
-
description: ${skill.description}
|
|
185
|
-
---
|
|
186
|
-
|
|
187
|
-
# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
|
|
188
|
-
|
|
189
|
-
${skill.description}
|
|
190
|
-
|
|
191
|
-
Use GitNexus tools to accomplish this task.
|
|
182
|
+
skillContent = `---
|
|
183
|
+
name: gitnexus-${skill.name}
|
|
184
|
+
description: ${skill.description}
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
# ${skill.name.charAt(0).toUpperCase() + skill.name.slice(1)}
|
|
188
|
+
|
|
189
|
+
${skill.description}
|
|
190
|
+
|
|
191
|
+
Use GitNexus tools to accomplish this task.
|
|
192
192
|
`;
|
|
193
193
|
}
|
|
194
194
|
await fs.writeFile(skillPath, skillContent, 'utf-8');
|
package/dist/cli/mcp.js
CHANGED
|
@@ -8,7 +8,35 @@
|
|
|
8
8
|
import { startMCPServer } from '../mcp/server.js';
|
|
9
9
|
import { LocalBackend } from '../mcp/local/local-backend.js';
|
|
10
10
|
import { listRegisteredRepos } from '../storage/repo-manager.js';
|
|
11
|
+
/**
|
|
12
|
+
* Protect MCP stdio protocol from library stdout pollution.
|
|
13
|
+
*
|
|
14
|
+
* Libraries like @huggingface/transformers, ONNX Runtime, and kuzu may
|
|
15
|
+
* write progress bars, warnings, or init messages to stdout.
|
|
16
|
+
* MCP uses stdout exclusively for JSON-RPC — any foreign output corrupts
|
|
17
|
+
* the protocol and causes Cursor to kill the connection.
|
|
18
|
+
*
|
|
19
|
+
* This intercept redirects all non-JSON-RPC stdout writes to stderr.
|
|
20
|
+
*/
|
|
21
|
+
function installStdoutGuard() {
|
|
22
|
+
const origWrite = process.stdout.write.bind(process.stdout);
|
|
23
|
+
process.stdout.write = ((chunk, encodingOrCb, cb) => {
|
|
24
|
+
const text = typeof chunk === 'string'
|
|
25
|
+
? chunk
|
|
26
|
+
: Buffer.isBuffer(chunk)
|
|
27
|
+
? chunk.toString('utf-8')
|
|
28
|
+
: '';
|
|
29
|
+
// MCP SDK messages always contain "jsonrpc" — let them through
|
|
30
|
+
if (text.includes('"jsonrpc"')) {
|
|
31
|
+
return origWrite(chunk, encodingOrCb, cb);
|
|
32
|
+
}
|
|
33
|
+
// Redirect everything else to stderr (library noise)
|
|
34
|
+
return process.stderr.write(chunk, encodingOrCb, cb);
|
|
35
|
+
});
|
|
36
|
+
}
|
|
11
37
|
export const mcpCommand = async () => {
|
|
38
|
+
// Must be first — before any library can pollute stdout
|
|
39
|
+
installStdoutGuard();
|
|
12
40
|
// Load all registered repos
|
|
13
41
|
const entries = await listRegisteredRepos({ validate: true });
|
|
14
42
|
if (entries.length === 0) {
|
package/dist/cli/setup.js
CHANGED
|
@@ -169,6 +169,9 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
|
|
|
169
169
|
message: 'Detecting execution flows...',
|
|
170
170
|
stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
|
|
171
171
|
});
|
|
172
|
+
// Dynamic process cap based on codebase size
|
|
173
|
+
const symbolCount = graph.nodes.filter(n => n.label !== 'File').length;
|
|
174
|
+
const dynamicMaxProcesses = Math.max(20, Math.min(300, Math.round(symbolCount / 10)));
|
|
172
175
|
const processResult = await processProcesses(graph, communityResult.memberships, (message, progress) => {
|
|
173
176
|
const processProgress = 98 + (progress * 0.01);
|
|
174
177
|
onProgress({
|
|
@@ -177,7 +180,7 @@ export const runPipelineFromRepo = async (repoPath, onProgress) => {
|
|
|
177
180
|
message,
|
|
178
181
|
stats: { filesProcessed: files.length, totalFiles: files.length, nodesCreated: graph.nodeCount },
|
|
179
182
|
});
|
|
180
|
-
});
|
|
183
|
+
}, { maxProcesses: dynamicMaxProcesses, minSteps: 3 });
|
|
181
184
|
if (isDev) {
|
|
182
185
|
console.log(`🔄 Process detection: ${processResult.stats.totalProcesses} processes found (${processResult.stats.crossCommunityCount} cross-community)`);
|
|
183
186
|
}
|