# 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` |

## LocalAI (HTTP embeddings + chat LLM)

Opcjonalna integracja z LocalAI OpenAI-compatible API (np. `http://192.168.100.5:8070`):

| Zmienna | Opis |
|---------|------|
| `GITNEXUS_EMBEDDING_URL` | `http://<host>:8070/v1` — semantic search |
| `GITNEXUS_EMBEDDING_MODEL` | model z `/v1/models` (embeddings) |
| `GITNEXUS_EMBEDDING_DIMS` | wymiar wektora (musi zgadzać się z modelem) |
| `GITNEXUS_EMBEDDING_API_KEY` | Bearer token LocalAI |
| `GITNEXUS_LLM_BASE_URL` | `http://127.0.0.1:18070/v1` przez lokalny proxy (SSRF) |
| `GITNEXUS_API_KEY` / `GITNEXUS_MODEL` | chat / wiki LLM |

Setup: `one-gateway/coding-agent/37-gitnexus-localai-integration.md`

## 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`