Add universal GitNexus skills for Cursor and Hermes.
Consolidate connect, graph, and search workflows with mobile endpoint defaults and shared installation docs. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,95 @@
|
||||
---
|
||||
name: gitnexus-connect
|
||||
description: >-
|
||||
Konfiguruje połączenie z GitNexus (MCP dla Cursora, REST/MCP dla Hermesa).
|
||||
Użyj przy setupie MCP, health checku, problemach z połączeniem,
|
||||
lub gdy agent nie widzi serwera gitnexus.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# gitnexus-connect
|
||||
|
||||
Bootstrap połączenia z GitNexus dla **Cursor** (MCP) i **Hermes** (MCP lub REST).
|
||||
|
||||
## Domyślny endpoint (zdalny)
|
||||
|
||||
```text
|
||||
https://gitnexus.mobile.agency-ai.dev/api/mcp
|
||||
```
|
||||
|
||||
## Lokalny override (ten sam host co Docker one-gateway)
|
||||
|
||||
```text
|
||||
http://127.0.0.1:4747/api/mcp
|
||||
```
|
||||
|
||||
Ustaw `GITNEXUS_SERVER_URL=http://127.0.0.1:4747` gdy pracujesz lokalnie na hoście z kontenerem `one-gateway-gitnexus-server`.
|
||||
|
||||
## Cursor — konfiguracja MCP
|
||||
|
||||
Plik `~/.cursor/mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gitnexus": {
|
||||
"url": "https://gitnexus.mobile.agency-ai.dev/api/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Lokalnie zamień URL na `http://127.0.0.1:4747/api/mcp`.
|
||||
|
||||
Po zmianie: **Reload Window** → panel MCP → status `gitnexus` = **Connected**.
|
||||
|
||||
## Hermes — zmienne środowiskowe
|
||||
|
||||
```bash
|
||||
export GITNEXUS_SERVER_URL=https://gitnexus.mobile.agency-ai.dev
|
||||
export GITNEXUS_DEFAULT_REPO=one-gateway # opcjonalnie
|
||||
```
|
||||
|
||||
Hermes może używać MCP HTTP (ten sam URL co Cursor) lub REST fallback przez skrypt z `gitnexus-search`.
|
||||
|
||||
## Procedura agenta
|
||||
|
||||
1. Uruchom health check:
|
||||
|
||||
```bash
|
||||
bash "$SKILLS_ROOT/gitnexus-connect/scripts/gitnexus-health.sh"
|
||||
```
|
||||
|
||||
Domyślnie `SKILLS_ROOT=$HOME/Pulpit/cursor/skills`. Możesz też podać pełną ścieżkę.
|
||||
|
||||
2. Sprawdź `GET /api/repos` — czy docelowe repo jest zaindeksowane (`stats.files > 0`).
|
||||
3. Cursor: Reload Window → MCP panel → `gitnexus` = Connected.
|
||||
4. Jeśli repo **brak na liście** — nie szukaj lokalnie. Operator musi zamontować repo na hoście GitNexus i wykonać `analyze` (szczegóły w [`reference.md`](reference.md)).
|
||||
|
||||
## Szybki test ręczny
|
||||
|
||||
```bash
|
||||
curl -fsS https://gitnexus.mobile.agency-ai.dev/api/health
|
||||
curl -fsS https://gitnexus.mobile.agency-ai.dev/api/repos
|
||||
```
|
||||
|
||||
## Błędy
|
||||
|
||||
| Sytuacja | Akcja |
|
||||
|----------|-------|
|
||||
| MCP Error / timeout | Sprawdź health; użyj REST przez `gitnexus-search.py` |
|
||||
| Repo nie na liście | Operator: `docker exec -w /workspace one-gateway-gitnexus-server gitnexus analyze /workspace` |
|
||||
| Port 4747 zajęty lokalnie | Nie uruchamiaj drugiego `gitnexus serve` — użyj istniejącego kontenera |
|
||||
| Brak auth na zdalnym URL | NPMplus Access List / Basic Auth (patrz `reference.md`) |
|
||||
|
||||
## Powiązane skille
|
||||
|
||||
| Skill | Kiedy |
|
||||
|-------|-------|
|
||||
| [`gitnexus-graph`](../gitnexus-graph/SKILL.md) | Architektura, zależności, impact — użyj MCP po połączeniu |
|
||||
| [`gitnexus-search`](../gitnexus-search/SKILL.md) | Jawne wyszukiwanie `repo + prompt`; REST fallback |
|
||||
|
||||
## Referencja
|
||||
|
||||
- Szczegóły URL, porty, bezpieczeństwo: [`reference.md`](reference.md)
|
||||
- Extended docs (one-gateway): `coding-agent/33–36*.md`
|
||||
@@ -0,0 +1,112 @@
|
||||
# GitNexus — referencja połączeń
|
||||
|
||||
## Endpointy
|
||||
|
||||
| Zastosowanie | Zdalny (domyślny) | Lokalny (dev) |
|
||||
|--------------|-------------------|---------------|
|
||||
| REST API + MCP | `https://gitnexus.mobile.agency-ai.dev` | `http://127.0.0.1:4747` |
|
||||
| MCP HTTP | `…/api/mcp` | `http://127.0.0.1:4747/api/mcp` |
|
||||
| Health | `…/api/health` | `http://127.0.0.1:4747/api/health` |
|
||||
| Lista repo | `…/api/repos` | `http://127.0.0.1:4747/api/repos` |
|
||||
| UI (opcjonalnie) | osobna subdomena → port 4173 | `http://127.0.0.1:4173` |
|
||||
|
||||
## Scenariusz 1 — lokalny host (Docker one-gateway)
|
||||
|
||||
Kontener `one-gateway-gitnexus-server` nasłuchuje na `127.0.0.1:4747`.
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:4747/api/health
|
||||
curl -fsS http://127.0.0.1:4747/api/repos
|
||||
docker exec one-gateway-gitnexus-server gitnexus list
|
||||
```
|
||||
|
||||
**Ważne:** przy działającym kontenerze **nie uruchamiaj** dodatkowego `gitnexus serve` na hoście — konflikt na porcie 4747.
|
||||
|
||||
Cursor MCP lokalnie:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gitnexus": {
|
||||
"url": "http://127.0.0.1:4747/api/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Scenariusz 2 — zdalny agent (Cursor / Hermes na innym hoście)
|
||||
|
||||
NPMplus forward: `gitnexus.mobile.agency-ai.dev` → `127.0.0.1:4747` (websockets ON, SSL).
|
||||
|
||||
```bash
|
||||
curl -fsS https://gitnexus.mobile.agency-ai.dev/api/health
|
||||
curl -fsS https://gitnexus.mobile.agency-ai.dev/api/repos
|
||||
```
|
||||
|
||||
MCP:
|
||||
|
||||
```text
|
||||
https://gitnexus.mobile.agency-ai.dev/api/mcp
|
||||
```
|
||||
|
||||
Zdalny agent może:
|
||||
|
||||
- czytać listę repo
|
||||
- używać `query`, `context`, `impact`
|
||||
- korzystać z REST i MCP jako **read-only knowledge source**
|
||||
|
||||
Zdalny agent **nie** dodaje automatycznie swojego lokalnego repo do indeksu hosta mobile.
|
||||
|
||||
## Indeksowanie nowego repo
|
||||
|
||||
Repo musi być **na hoście GitNexus** (zamontowane lub sklonowane), potem:
|
||||
|
||||
```bash
|
||||
docker exec -w /workspace one-gateway-gitnexus-server gitnexus analyze /workspace
|
||||
```
|
||||
|
||||
lub dla konkretnej ścieżki:
|
||||
|
||||
```bash
|
||||
docker exec -w /data/gitnexus/repos/MOJE-REPO one-gateway-gitnexus-server \
|
||||
gitnexus analyze /data/gitnexus/repos/MOJE-REPO
|
||||
```
|
||||
|
||||
Jeśli repo nie ma w `GET /api/repos` — agent nie może go „podłączyć” zdalnie; operator musi zaindeksować na serwerze.
|
||||
|
||||
## Zmienne środowiskowe
|
||||
|
||||
| Zmienna | Domyślnie | Opis |
|
||||
|---------|-----------|------|
|
||||
| `GITNEXUS_SERVER_URL` | `https://gitnexus.mobile.agency-ai.dev` | Bazowy URL API (bez `/api/mcp`) |
|
||||
| `GITNEXUS_DEFAULT_REPO` | `one-gateway` | Repo sprawdzane przez `gitnexus-health.sh` |
|
||||
| `SKILLS_ROOT` | `$HOME/Pulpit/cursor/skills` | Katalog ze skillami (dla ścieżek w skryptach) |
|
||||
|
||||
## Bezpieczeństwo
|
||||
|
||||
GitNexus `serve` **nie ma własnego auth**. Przy wystawieniu `gitnexus.mobile.agency-ai.dev` zabezpiecz przez:
|
||||
|
||||
- Access List w NPMplus
|
||||
- Basic Auth
|
||||
- VPN / prywatny routing
|
||||
|
||||
Bez zabezpieczenia publicznie udostępniasz metadane repo, strukturę kodu i wyniki search/context/impact.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Rozwiązanie |
|
||||
|---------|-------------|
|
||||
| Timeout na zdalnym URL | Sprawdź NPMplus forward na 4747, websockets, SSL |
|
||||
| MCP Connected ale puste wyniki | `GET /api/repos` — czy `stats.files > 0`? |
|
||||
| Repo nie na liście | Operator: mount + `analyze` na hoście GitNexus |
|
||||
| Lokalny 4747 zajęty | `docker ps` — użyj kontenera, nie drugiego `serve` |
|
||||
| Hermes bez MCP | REST: `gitnexus-search/scripts/gitnexus-search.py` |
|
||||
|
||||
## Extended documentation (one-gateway)
|
||||
|
||||
- `coding-agent/31-gitnexus-deployment-report.md`
|
||||
- `coding-agent/33-gitnexus-m3gan-remote-client.md`
|
||||
- `coding-agent/34-gitnexus-npmplus-edge-setup.md`
|
||||
- `coding-agent/35-cursor-gitnexus-mcp-setup.md`
|
||||
- `coding-agent/36-gitnexus-repo-connection-guide.md`
|
||||
- `docs/hermes/GITNEXUS-CLIENT.md`
|
||||
Executable
+54
@@ -0,0 +1,54 @@
|
||||
#!/usr/bin/env bash
|
||||
# GitNexus health check — Cursor, Hermes, operator.
|
||||
set -euo pipefail
|
||||
|
||||
BASE="${GITNEXUS_SERVER_URL:-https://gitnexus.mobile.agency-ai.dev}"
|
||||
BASE="${BASE%/}"
|
||||
REPO="${GITNEXUS_DEFAULT_REPO:-one-gateway}"
|
||||
|
||||
echo "=== GitNexus health ==="
|
||||
echo "Server: $BASE"
|
||||
echo
|
||||
|
||||
echo "--- GET /api/health ---"
|
||||
HEALTH=$(curl -fsS "$BASE/api/health" 2>&1) || {
|
||||
echo "FAIL: cannot reach $BASE/api/health"
|
||||
echo "$HEALTH"
|
||||
exit 1
|
||||
}
|
||||
echo "$HEALTH"
|
||||
echo
|
||||
|
||||
echo "--- GET /api/repos ---"
|
||||
REPOS=$(curl -fsS "$BASE/api/repos" 2>&1) || {
|
||||
echo "FAIL: cannot reach $BASE/api/repos"
|
||||
echo "$REPOS"
|
||||
exit 1
|
||||
}
|
||||
echo "$REPOS"
|
||||
echo
|
||||
|
||||
if command -v python3 >/dev/null 2>&1; then
|
||||
if echo "$REPOS" | python3 -c "
|
||||
import json, sys
|
||||
repos = json.load(sys.stdin)
|
||||
names = [r.get('name', '') for r in repos]
|
||||
target = sys.argv[1]
|
||||
sys.exit(0 if target in names else 1)
|
||||
" "$REPO" 2>/dev/null; then
|
||||
echo "OK: repo '$REPO' is indexed"
|
||||
else
|
||||
echo "WARN: repo '$REPO' not found in index (check analyze on server)"
|
||||
exit 1
|
||||
fi
|
||||
else
|
||||
if echo "$REPOS" | grep -q "\"name\":\"$REPO\"" || echo "$REPOS" | grep -q "\"name\": \"$REPO\""; then
|
||||
echo "OK: repo '$REPO' appears in response"
|
||||
else
|
||||
echo "WARN: repo '$REPO' not found in response"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
echo
|
||||
echo "=== All checks passed ==="
|
||||
Reference in New Issue
Block a user