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>
2026-07-01 16:08:15 +02:00
parent fa48844fb3
commit 287c08ebfc
6 changed files with 428 additions and 35 deletions
@@ -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`