tomasz-syn-grzegorza/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add universal GitNexus skills for Cursor and Hermes.

Browse Source 
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:
Tomasz syn Grzegorza ©
2026-07-01 16:08:15 +02:00
parent fa48844fb3
commit 287c08ebfc
6 changed files with 428 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+75 -29
View File
@@ -1,29 +1,45 @@
# Workspace skills (`/home/test-user/cursor/skills`) # Workspace skills (`$HOME/Pulpit/cursor/skills`)
Wspólne skille dla **Cursor** i **Hermes** w ekosystemie agency-ai. Wspólne skille dla **Cursor** i **Hermes** w ekosystemie agency-ai.
## Skille Domyślna ścieżka:
| Skill | Wywołanie | Opis |
|-------|-----------|------|
| [gitnexus-search](gitnexus-search/SKILL.md) | `gitnexus-search <repo> <prompt...>` | Przeszukiwanie zdalnego GitNexus po nazwie repo |
## Cursor
Skills w tym katalogu nie są automatycznie widoczne w Cursor — utwórz symlink:
```bash ```bash
SKILLS_ROOT="${SKILLS_ROOT:-$HOME/Pulpit/cursor/skills}"
```
## Skille GitNexus
| Skill | Wywołanie / trigger | Opis |
|-------|---------------------|------|
| [gitnexus-connect](gitnexus-connect/SKILL.md) | setup MCP, health check, problemy z połączeniem | Bootstrap połączenia z `gitnexus.mobile.agency-ai.dev` |
| [gitnexus-graph](gitnexus-graph/SKILL.md) | architektura, zależności, impact, refaktoryzacja | Graph-first: `query` / `context` / `impact` przez MCP |
| [gitnexus-search](gitnexus-search/SKILL.md) | `gitnexus-search <repo> <prompt...>` | Jawne wyszukiwanie po nazwie repo + prompt |
## Endpointy
| Zastosowanie | Zdalny (domyślny) | Lokalny (dev na hoście GitNexus) |
|--------------|-------------------|-----------------------------------|
| MCP | `https://gitnexus.mobile.agency-ai.dev/api/mcp` | `http://127.0.0.1:4747/api/mcp` |
| REST API | `https://gitnexus.mobile.agency-ai.dev` | `http://127.0.0.1:4747` |
| UI (opcjonalnie) | osobna subdomena → 4173 | `http://127.0.0.1:4173` |
Szczegóły: [gitnexus-connect/reference.md](gitnexus-connect/reference.md).
## Cursor — instalacja
Symlinki do skilli (po sklonowaniu repo):
```bash
SKILLS_ROOT="$HOME/Pulpit/cursor/skills"
mkdir -p ~/.cursor/skills mkdir -p ~/.cursor/skills
ln -sfn /home/test-user/cursor/skills/gitnexus-search ~/.cursor/skills/gitnexus-search
ln -sfn "$SKILLS_ROOT/gitnexus-connect" ~/.cursor/skills/gitnexus-connect
ln -sfn "$SKILLS_ROOT/gitnexus-graph" ~/.cursor/skills/gitnexus-graph
ln -sfn "$SKILLS_ROOT/gitnexus-search" ~/.cursor/skills/gitnexus-search
``` ```
Opcjonalnie cały katalog: MCP w `~/.cursor/mcp.json`:
```bash
ln -sfn /home/test-user/cursor/skills ~/.cursor/skills-workspace
```
Wymagany MCP GitNexus w `~/.cursor/mcp.json`:
```json ```json
{ {
@@ -35,28 +51,58 @@ Wymagany MCP GitNexus w `~/.cursor/mcp.json`:
} }
``` ```
Lokalnie (ten sam host co Docker): zamień URL na `http://127.0.0.1:4747/api/mcp`.
Po symlinku: **Reload Window** + nowa sesja chatu. Po symlinku: **Reload Window** + nowa sesja chatu.
## Hermes (m3gan) Health check:
W promptcie systemowym lub `INSTALL-AGENT.md` podaj ścieżkę bezwzględną do skilla:
```text
/home/test-user/cursor/skills/gitnexus-search/SKILL.md
```
Hermes używa REST (skrypt), gdy MCP niedostępny:
```bash ```bash
python3 /home/test-user/cursor/skills/gitnexus-search/scripts/gitnexus-search.py \ bash "$SKILLS_ROOT/gitnexus-connect/scripts/gitnexus-health.sh"
```
## Hermes — instalacja
W promptcie systemowym lub `INSTALL-AGENT.md` podaj ścieżki do skilli:
```text
$SKILLS_ROOT/gitnexus-connect/SKILL.md
$SKILLS_ROOT/gitnexus-graph/SKILL.md
$SKILLS_ROOT/gitnexus-search/SKILL.md
```
Zmienne środowiskowe:
```bash
export GITNEXUS_SERVER_URL=https://gitnexus.mobile.agency-ai.dev
export GITNEXUS_DEFAULT_REPO=one-gateway
export SKILLS_ROOT="$HOME/Pulpit/cursor/skills"
```
Hermes używa MCP HTTP (ten sam URL co Cursor) lub REST fallback:
```bash
python3 "$SKILLS_ROOT/gitnexus-search/scripts/gitnexus-search.py" \
one-gateway "deploy_runner" one-gateway "deploy_runner"
``` ```
Więcej: [one-gateway/docs/hermes/GITNEXUS-CLIENT.md](../one-gateway/docs/hermes/GITNEXUS-CLIENT.md). Więcej: [one-gateway/docs/hermes/GITNEXUS-CLIENT.md](../one-gateway/docs/hermes/GITNEXUS-CLIENT.md).
## Przykład ## Przykłady
```text ```text
gitnexus-search ai-lawyer-srvr routes_paperless admin gitnexus-search ai-lawyer-srvr routes_paperless admin
gitnexus-search gateway gitnexus_workspace_dir gitnexus-search gateway gitnexus_workspace_dir
``` ```
## Extended documentation (one-gateway)
Szczegółowa dokumentacja deployu i operatora — w repo `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`
Canonical source skilli: **ten katalog** (`cursor/skills`). Kopia `one-gateway/.cursor/skills/gitnexus-graph-first` nie jest utrzymywana — używaj `gitnexus-graph` stąd.
gitnexus-connect/SKILL.md
+95
View File
@@ -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`
gitnexus-connect/reference.md
+112
View File
@@ -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`
gitnexus-connect/scripts/gitnexus-health.sh
Executable
+54
View File
@@ -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 ==="
gitnexus-graph/SKILL.md
+75
View File
@@ -0,0 +1,75 @@
---
name: gitnexus-graph
description: >-
Preferuj GitNexus przy zrozumieniu architektury, zależności, impact analysis,
łańcuchów wywołań, przepływu danych lub refaktoryzacji cross-file.
Użyj gdy MCP gitnexus jest dostępny i zadanie zależy od relacji w kodzie.
disable-model-invocation: true
---
# gitnexus-graph
Graph-first workflow dla **Cursor** (MCP) i **Hermes** (MCP lub REST fallback).
## Kiedy używać GitNexus
- MCP `gitnexus` jest Connected (lub REST działa — patrz `gitnexus-connect`)
- użytkownik pyta o architekturę
- zadanie zależy od zależności lub powiązanych plików
- potrzebujesz impact analysis przed refaktoryzacją
- śledzisz łańcuch wywołań lub przepływ danych
- potrzebujesz kontekstu na poziomie symboli w wielu plikach
## Kiedy NIE wymagać GitNexus
- poprawka literówki
- edycja jednego oczywistego pliku
- mechaniczny rename lub formatowanie
- proste „gdzie jest X?” gdy `rg` wystarczy
## Startup checklist
1. Jeśli brak połączenia — najpierw [`gitnexus-connect`](../gitnexus-connect/SKILL.md)
2. `list_repos` — potwierdź, że docelowe repo jest zaindeksowane (`stats.files > 0`)
3. Pytanie o symbol → `context` najpierw
4. Przed refaktoryzacją → `impact`
5. Eksploracja otwarta → `query`
## Narzędzia MCP
| Narzędzie | Zastosowanie |
|-----------|--------------|
| `list_repos` | Lista zaindeksowanych repo |
| `query` | Semantyczne wyszukiwanie w grafie |
| `context` | Kontekst wokół symbolu lub pliku |
| `impact` | Wpływ zmiany na resztę kodu |
Przy wielu repo podawaj `repo` explicite (nazwa lub ścieżka bezwzględna z indeksu).
## Default workflow
1. Oceń, czy zadanie jest relationship-heavy czy proste/lokalne.
2. Jeśli relationship-heavy i MCP dostępny — GitNexus najpierw.
3. Po wynikach grafu czytaj tylko najbardziej relevantne pliki lokalnie.
4. Fallback na `rg` / Read / SemanticSearch gdy GitNexus niedostępny lub niekompletny.
## Fallback
| MCP niedostępny | Akcja |
|-----------------|-------|
| Cursor | `gitnexus-connect` → napraw MCP; lub `gitnexus-search` (REST) |
| Hermes | REST: `gitnexus-search/scripts/gitnexus-search.py` |
| Ogólnie | `rg`, Read, SemanticSearch |
## Przykładowe prompty
- „Jak działa ten moduł?”
- „Które pliki są powiązane z `gitnexus_workspace_dir`?”
- „Co może się zepsuć, jeśli zmienię `deploy_runner.py`?”
- „Pokaż impact zmiany ścieżki instalatora.”
## Powiązane
- Setup: [`gitnexus-connect`](../gitnexus-connect/SKILL.md)
- Jawne wyszukiwanie: [`gitnexus-search`](../gitnexus-search/SKILL.md)
- Extended docs: `one-gateway/coding-agent/35-cursor-gitnexus-mcp-setup.md`
gitnexus-search/SKILL.md
+17 -6
View File
@@ -11,6 +11,15 @@ disable-model-invocation: true
Jawne wyszukiwanie w zdalnym GitNexus (`https://gitnexus.mobile.agency-ai.dev`). Działa w **Cursor** (MCP) i **Hermes** (REST). Jawne wyszukiwanie w zdalnym GitNexus (`https://gitnexus.mobile.agency-ai.dev`). Działa w **Cursor** (MCP) i **Hermes** (REST).
**Przed pierwszym użyciem:** jeśli brak połączenia lub MCP Error — przeczytaj [`gitnexus-connect`](../gitnexus-connect/SKILL.md).
## Ścieżki
```bash
SKILLS_ROOT="${SKILLS_ROOT:-$HOME/Pulpit/cursor/skills}"
SEARCH_SCRIPT="$SKILLS_ROOT/gitnexus-search/scripts/gitnexus-search.py"
```
## Format wejścia ## Format wejścia
```text ```text
@@ -53,11 +62,11 @@ Gdy MCP `gitnexus` jest Connected:
Gdy MCP niedostępny — **od razu** REST, bez pytania użytkownika: Gdy MCP niedostępny — **od razu** REST, bez pytania użytkownika:
```bash ```bash
python3 /home/test-user/cursor/skills/gitnexus-search/scripts/gitnexus-search.py \ python3 "$SKILLS_ROOT/gitnexus-search/scripts/gitnexus-search.py" \
<repo> "<prompt>" <repo> "<prompt>"
``` ```
Opcjonalnie: `--limit N`, `--json`. Opcjonalnie: `--limit N`, `--json`, `--server URL`.
## Format odpowiedzi ## Format odpowiedzi
@@ -71,12 +80,14 @@ Opcjonalnie: `--limit N`, `--json`.
| Sytuacja | Akcja | | Sytuacja | Akcja |
|----------|-------| |----------|-------|
| Repo nieznane | Lista z `/api/repos` | | Repo nieznane | Lista z `/api/repos` |
| Indeks pusty (`files: 0`) | Wskazówka: re-index (`gitnexus-index-remote.py` w projekcie) | | Indeks pusty (`files: 0`) | Operator: re-index na hoście GitNexus (`gitnexus-connect/reference.md`) |
| MCP Error / brak narzędzi | REST przez `gitnexus-search.py` | | MCP Error / brak narzędzi | REST przez `gitnexus-search.py` |
| HTTP / timeout | `curl -fsS $GITNEXUS_SERVER_URL/api/health` | | HTTP / timeout | `bash "$SKILLS_ROOT/gitnexus-connect/scripts/gitnexus-health.sh"` |
## Powiązane ## Powiązane
- Setup: [`gitnexus-connect`](../gitnexus-connect/SKILL.md)
- Graph workflow: [`gitnexus-graph`](../gitnexus-graph/SKILL.md)
- Skrypt: [`scripts/gitnexus-search.py`](scripts/gitnexus-search.py) - Skrypt: [`scripts/gitnexus-search.py`](scripts/gitnexus-search.py)
- Hermes: [`one-gateway/docs/hermes/GITNEXUS-CLIENT.md`](../../one-gateway/docs/hermes/GITNEXUS-CLIENT.md) - Hermes: `one-gateway/docs/hermes/GITNEXUS-CLIENT.md`
- Workspace skills: [`../README.md`](../README.md) - Indeks skilli: [`../README.md`](../README.md)