From 287c08ebfcd3a063015424a76b5abeb803a2df32 Mon Sep 17 00:00:00 2001 From: tomasz-syn-grzegorza Date: Wed, 1 Jul 2026 16:08:15 +0200 Subject: [PATCH] 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 --- README.md | 104 +++++++++++++----- gitnexus-connect/SKILL.md | 95 +++++++++++++++++ gitnexus-connect/reference.md | 112 ++++++++++++++++++++ gitnexus-connect/scripts/gitnexus-health.sh | 54 ++++++++++ gitnexus-graph/SKILL.md | 75 +++++++++++++ gitnexus-search/SKILL.md | 23 ++-- 6 files changed, 428 insertions(+), 35 deletions(-) create mode 100644 gitnexus-connect/SKILL.md create mode 100644 gitnexus-connect/reference.md create mode 100755 gitnexus-connect/scripts/gitnexus-health.sh create mode 100644 gitnexus-graph/SKILL.md diff --git a/README.md b/README.md index 86c537f..b584493 100644 --- a/README.md +++ b/README.md @@ -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. -## Skille - -| Skill | Wywołanie | Opis | -|-------|-----------|------| -| [gitnexus-search](gitnexus-search/SKILL.md) | `gitnexus-search ` | Przeszukiwanie zdalnego GitNexus po nazwie repo | - -## Cursor - -Skills w tym katalogu nie są automatycznie widoczne w Cursor — utwórz symlink: +Domyślna ścieżka: ```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 ` | 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 -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: - -```bash -ln -sfn /home/test-user/cursor/skills ~/.cursor/skills-workspace -``` - -Wymagany MCP GitNexus w `~/.cursor/mcp.json`: +MCP w `~/.cursor/mcp.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. -## Hermes (m3gan) - -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: +Health check: ```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" ``` Więcej: [one-gateway/docs/hermes/GITNEXUS-CLIENT.md](../one-gateway/docs/hermes/GITNEXUS-CLIENT.md). -## Przykład +## Przykłady ```text gitnexus-search ai-lawyer-srvr routes_paperless admin 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. diff --git a/gitnexus-connect/SKILL.md b/gitnexus-connect/SKILL.md new file mode 100644 index 0000000..e9f01f6 --- /dev/null +++ b/gitnexus-connect/SKILL.md @@ -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` diff --git a/gitnexus-connect/reference.md b/gitnexus-connect/reference.md new file mode 100644 index 0000000..83faa58 --- /dev/null +++ b/gitnexus-connect/reference.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` diff --git a/gitnexus-connect/scripts/gitnexus-health.sh b/gitnexus-connect/scripts/gitnexus-health.sh new file mode 100755 index 0000000..a93b24e --- /dev/null +++ b/gitnexus-connect/scripts/gitnexus-health.sh @@ -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 ===" diff --git a/gitnexus-graph/SKILL.md b/gitnexus-graph/SKILL.md new file mode 100644 index 0000000..8b88d2c --- /dev/null +++ b/gitnexus-graph/SKILL.md @@ -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` diff --git a/gitnexus-search/SKILL.md b/gitnexus-search/SKILL.md index b2eb87e..5d32f63 100644 --- a/gitnexus-search/SKILL.md +++ b/gitnexus-search/SKILL.md @@ -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). +**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 ```text @@ -53,11 +62,11 @@ Gdy MCP `gitnexus` jest Connected: Gdy MCP niedostępny — **od razu** REST, bez pytania użytkownika: ```bash -python3 /home/test-user/cursor/skills/gitnexus-search/scripts/gitnexus-search.py \ +python3 "$SKILLS_ROOT/gitnexus-search/scripts/gitnexus-search.py" \ "" ``` -Opcjonalnie: `--limit N`, `--json`. +Opcjonalnie: `--limit N`, `--json`, `--server URL`. ## Format odpowiedzi @@ -71,12 +80,14 @@ Opcjonalnie: `--limit N`, `--json`. | Sytuacja | Akcja | |----------|-------| | 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` | -| HTTP / timeout | `curl -fsS $GITNEXUS_SERVER_URL/api/health` | +| HTTP / timeout | `bash "$SKILLS_ROOT/gitnexus-connect/scripts/gitnexus-health.sh"` | ## 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) -- Hermes: [`one-gateway/docs/hermes/GITNEXUS-CLIENT.md`](../../one-gateway/docs/hermes/GITNEXUS-CLIENT.md) -- Workspace skills: [`../README.md`](../README.md) +- Hermes: `one-gateway/docs/hermes/GITNEXUS-CLIENT.md` +- Indeks skilli: [`../README.md`](../README.md)