> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aigmented.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Serwer MCP

> Połącz Aigmented z Claude Desktop, Cursor i innymi klientami MCP

Serwer MCP Aigmented pozwala przeszukiwać, nawigować i pobierać treści z bazy wiedzy bezpośrednio w Claude Desktop, Cursor, LibreChat lub dowolnym kliencie kompatybilnym z [MCP](https://modelcontextprotocol.io).

W tej wersji serwer MCP udostępnia te same prymitywy danych, których wewnętrznie używa auto-wiki Aigmented do budowy treści — więc Twój zewnętrzny agent (Claude, Cursor itp.) może eksplorować graf wiedzy, wyciągać zbiory kart pod zadany temat i sam syntezować dokumenty, raporty czy materiały szkoleniowe.

<Note>
  Pakiet `@aigmented/mcp` nie jest jeszcze opublikowany na npm. Na razie używaj buildu ze źródeł z repozytorium.
</Note>

## Konfiguracja dla Claude Desktop

Dodaj do `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "aigmented": {
      "command": "npx",
      "args": ["@aigmented/mcp"],
      "env": {
        "AIGMENTED_API_KEY": "sk-TWOJ_KLUCZ_API",
        "AIGMENTED_COLLECTION_ID": "49"
      }
    }
  }
}
```

## Konfiguracja dla Cursor

Dodaj do ustawień MCP w Cursor:

```json theme={null}
{
  "aigmented": {
    "command": "npx",
    "args": ["@aigmented/mcp"],
    "env": {
      "AIGMENTED_API_KEY": "sk-TWOJ_KLUCZ_API",
      "AIGMENTED_COLLECTION_ID": "49"
    }
  }
}
```

## Zmienne środowiskowe

| Zmienna                   | Wymagana | Domyślnie              | Opis                                                                       |
| ------------------------- | -------- | ---------------------- | -------------------------------------------------------------------------- |
| `AIGMENTED_API_KEY`       | Tak      | —                      | Twój klucz API (`sk-...`)                                                  |
| `AIGMENTED_API_URL`       | Nie      | `https://aigmented.io` | Bazowy URL API                                                             |
| `AIGMENTED_COLLECTION_ID` | Nie      | —                      | Domyślne ID kolekcji (jeśli pominięte, trzeba podać przy każdym wywołaniu) |

## Dostępne narzędzia

Serwer MCP udostępnia **13 narzędzi** podzielonych na cztery grupy.

### Eksploracja i Q\&A

#### `list_collections`

Wylistuj wszystkie dostępne kolekcje wiedzy. Brak parametrów.

#### `search_knowledge`

Semantyczne wyszukiwanie w bazie wiedzy.

| Parametr        | Wymagany | Opis                                           |
| --------------- | -------- | ---------------------------------------------- |
| `query`         | Tak      | Zapytanie wyszukiwania                         |
| `collection_id` | Nie      | ID kolekcji (używa domyślnego jeśli pominięte) |
| `top_k`         | Nie      | Maks. wyników (domyślnie 5)                    |

#### `ask_question`

Zadaj pytanie i otrzymaj odpowiedź AI wraz z cytowaniem źródeł.

| Parametr        | Wymagany | Opis                                           |
| --------------- | -------- | ---------------------------------------------- |
| `question`      | Tak      | Twoje pytanie                                  |
| `collection_id` | Nie      | ID kolekcji (używa domyślnego jeśli pominięte) |

#### `get_card_details`

Pobierz pełne szczegóły karty z **kompletną proweniencją źródeł**. Używaj gdy chcesz zacytować skąd pochodzi informacja.

| Parametr  | Wymagany | Opis                                            |
| --------- | -------- | ----------------------------------------------- |
| `card_id` | Tak      | ID karty (z wyników wyszukiwania lub retrieval) |

Response zawiera:

* `card_id`, `title`, `statement`, `knowledge_type`, `importance_score`
* **`source_documents`** — tablica `{id, name}` dla każdego dokumentu z którego karta powstała
* **`page_numbers`** — płaska tablica wszystkich numerów stron źródłowych (po wszystkich dokumentach; schema nie trzyma mapowania strona-dokument)
* **`section_context`** — ścieżka sekcji w dokumencie źródłowym (np. `"Rozdział 3 / Urlopy"`)
* **`related_header`** — najbliższy nagłówek w dokumencie źródłowym
* **`verbatim_content`** — dosłowny cytat ze źródła, gdy applicable (formularze, szablony, tekst prawny)
* **`source_card_ids`** — pośrednie karty Phase 2 (głębsza traceability)
* `related_card_ids` — do 5 sąsiadów z grafu (pusta jeśli graf nie zbudowany)
* `created_at`, `updated_at`

Dla zachowania kompatybilności wstecznej zwracane jest też `source_document` (pierwszy wpis z `source_documents` + `page_range` typu `"12-14"`).

### Nawigacja po grafie wiedzy

Te narzędzia wymagają aby kolekcja miała zbudowany graf wiedzy. Kolekcje bez grafu zwrócą błąd `409` z czytelnym komunikatem — użyj wtedy `retrieve_for_topic` albo `search_knowledge`.

#### `describe_collection`

Zwraca statystyki kolekcji, flagę czy graf jest zbudowany i podgląd top klastrów. **Wywołaj jako pierwsze**, żeby zrozumieć co jest dostępne zanim odpalisz droższe narzędzia.

| Parametr        | Wymagany | Opis                                           |
| --------------- | -------- | ---------------------------------------------- |
| `collection_id` | Nie      | ID kolekcji (używa domyślnego jeśli pominięte) |

Zwraca: `{ total_cards, has_graph, total_clusters, total_entities, top_clusters }`.

#### `list_clusters`

Wylistuj wszystkie klastry grafu wiedzy (tematy / społeczności) w kolekcji.

Każdy klaster zawiera: `id`, `llm_name`, `llm_description`, `card_count` i do 5 `top_entities`. Użyj, żeby zobaczyć strukturę tematyczną kolekcji.

#### `get_cluster`

Pełny widok jednego klastra: karty (z 200-znakowymi podglądami), encje i powiązane klastry.

| Parametr        | Wymagany | Opis                                           |
| --------------- | -------- | ---------------------------------------------- |
| `cluster_id`    | Tak      | ID klastra (z `list_clusters`)                 |
| `collection_id` | Nie      | ID kolekcji (używa domyślnego jeśli pominięte) |

#### `list_entities`

Top encje (osoby, organizacje, pojęcia) w kolekcji z liczbą kart.

| Parametr        | Wymagany | Opis                                            |
| --------------- | -------- | ----------------------------------------------- |
| `top_k`         | Nie      | Maks. wyników (domyślnie 50, maks. 200)         |
| `entity_type`   | Nie      | Filtr po typie (np. `PERSON`, `ORG`, `CONCEPT`) |
| `collection_id` | Nie      | ID kolekcji (używa domyślnego jeśli pominięte)  |

#### `get_gaps`

Luki w wiedzy: izolowane encje (występujące tylko w jednej karcie z małą liczbą relacji) i małe klastry. Przydatne do identyfikacji problemów z pokryciem zanim zaczniesz generować treści.

### Retrieval do tworzenia treści

#### `retrieve_for_topic`

**Kluczowe narzędzie do generowania treści.** Uruchamia ten sam pipeline retrievalu co wewnętrzne auto-wiki Aigmented: wyszukiwanie wektorowe → filtr ważności → deduplikacja → rerank Cohere. Zwraca najtrafniejsze karty dla danego tematu, gotowe do wrzucenia w syntezę Twojego agenta.

| Parametr         | Wymagany | Opis                                                         |
| ---------------- | -------- | ------------------------------------------------------------ |
| `topic`          | Tak      | Temat lub tytuł sekcji                                       |
| `description`    | Nie      | Dłuższy opis tego czego szukasz (poprawia retrieval)         |
| `top_k`          | Nie      | Maks. kart do zwrócenia (domyślnie 25, maks. 50)             |
| `rerank`         | Nie      | Uruchom rerank Cohere (domyślnie `true`)                     |
| `min_importance` | Nie      | Odfiltruj karty poniżej tej oceny ważności (domyślnie `0.4`) |
| `collection_id`  | Nie      | ID kolekcji (używa domyślnego jeśli pominięte)               |

Zwraca karty jako `{ card_id, title, statement, importance_score, knowledge_type }`.

### Przeglądanie kart

Używaj tych narzędzi gdy chcesz wylistować, bulk-pobrać albo eksplorować semantyczne sąsiedztwa pojedynczych kart — bez pełnego pipeline'u retrievalu.

#### `list_collection_cards`

Płaski paginowany browse wszystkich kart w kolekcji. Bez zapytania. Przydatne do przeglądu "co jest w tej kolekcji".

| Parametr         | Wymagany | Opis                                                 |
| ---------------- | -------- | ---------------------------------------------------- |
| `offset`         | Nie      | Offset paginacji (domyślnie 0)                       |
| `limit`          | Nie      | Maks. kart na stronę (domyślnie 20, maks. 100)       |
| `knowledge_type` | Nie      | Filtr po typie (np. `fact`, `procedure`, `decision`) |
| `cluster_id`     | Nie      | Filtr po klastrze grafu (wymaga zbudowanego grafu)   |
| `collection_id`  | Nie      | ID kolekcji (używa domyślnego jeśli pominięte)       |

Zwraca: `{ cards: [{card_id, title, statement, knowledge_type, importance_score}], total_count, offset, limit, has_more }`. Statement obcięty do 200 znaków — użyj `get_card_details` dla pełnej treści.

#### `get_cards_batch`

Pobierz pełne szczegóły wielu kart w jednym wywołaniu (do 25 ID). Używaj po `search_knowledge` / `retrieve_for_topic` gdy potrzebujesz pełnej treści kilku kart — unikasz N round-tripów.

| Parametr        | Wymagany | Opis                                           |
| --------------- | -------- | ---------------------------------------------- |
| `card_ids`      | Tak      | Tablica ID kart, długość 1-25                  |
| `collection_id` | Nie      | ID kolekcji (używa domyślnego jeśli pominięte) |

Zwraca: `{ cards: [...], not_found: [ids] }`.

#### `get_related_cards`

Znajdź karty semantycznie podobne do podanej karty. Użyj do budowy klastrów tematycznych wokół pojedynczej karty (np. do generowania quizów: "5 kart najbardziej powiązanych z kartą X").

| Parametr        | Wymagany | Opis                                           |
| --------------- | -------- | ---------------------------------------------- |
| `card_id`       | Tak      | ID karty źródłowej                             |
| `limit`         | Nie      | Maks. powiązanych kart (domyślnie 5, maks. 20) |
| `collection_id` | Nie      | ID kolekcji (używa domyślnego jeśli pominięte) |

Zwraca: `{ source_card_id, related: [{card_id, title, statement, similarity_score}] }`. Nie wymaga grafu.

## Tworzenie treści z MCP — cookbook

Nowe narzędzia pozwalają Twojemu agentowi zreplikować to co auto-wiki Aigmented robi wewnętrznie — nawigację po grafie i pobieranie źródeł pod temat — przy czym synteza pozostaje po stronie Twojego agenta. Typowe wzorce:

### 1. "Streść co wiemy o X"

```
1. retrieve_for_topic(topic="X", top_k=20)
2. Agent czyta karty i pisze streszczenie.
```

Nie wymaga grafu. Działa na każdej kolekcji z włączonym wyszukiwaniem.

### 2. "Wygeneruj sekcję szkolenia o onboardingu"

```
1. describe_collection()               # potwierdź że graf jest zbudowany
2. list_clusters()                     # zobacz wszystkie tematy
3. get_cluster(cluster_id=<onboarding>)  # karty + encje w tym klastrze
4. retrieve_for_topic(topic="Onboarding nowych pracowników", description="...", top_k=30)
5. Agent składa sekcję używając kart z kroków 3 i 4 jako źródeł.
```

### 3. "Kto występuje w naszej bazie wiedzy?"

```
1. list_entities(entity_type="PERSON", top_k=100)
2. Dla każdej interesującej osoby: retrieve_for_topic(topic=<imię nazwisko>, top_k=10)
3. Agent buduje profil per osoba.
```

### 4. "Gdzie mamy luki w wiedzy?"

```
1. get_gaps()
2. Agent raportuje izolowane encje i małe tematy — wraca do reviewera lub pokazuje co doingestować.
```

### 5. "Zbuduj quiz wokół konkretnej karty"

```
1. get_related_cards(card_id=<seed card>, limit=10)
2. get_cards_batch(card_ids=[...powiązane ID...])
3. Agent generuje 5 pytań + odpowiedzi cytując karty źródłowe.
```

### 6. "Przejrzyj wszystkie karty i wybierz to co istotne"

```
1. describe_collection()                              # zorientuj agenta
2. list_collection_cards(offset=0, limit=50)          # pierwsza strona lekkich streszczeń
3. list_collection_cards(offset=50, limit=50)         # kolejna
4. Agent wybiera interesujące ID → get_cards_batch([...])
```

To flow dla **admina budującego program szkoleniowy** — zobacz co jest, wybierz źródła, złóż treść.

### Wskazówki

* **Zawsze zaczynaj od `describe_collection`** na nowej kolekcji. Powie Twojemu agentowi czy graph tools są dostępne i da zgrubny widok tematów.
* **Wybieraj `retrieve_for_topic` nad `search_knowledge` do generowania treści** — uruchamia pełniejszy pipeline (filtr ważności + dedup + rerank) dający czystsze źródła.
* **`get_card_details` jest tanie** — gdy agent ma już card\_id z dowolnego narzędzia, pobranie pełnej karty jest lekkie.
* **Uwaga o kosztach:** `retrieve_for_topic` używa Cohere embedding + rerank (płatne). Domyślne `top_k=25` to dobry balans. `rerank=false` pomija rerank jeśli zależy Ci na koszcie.

## Tryb HTTP (LibreChat)

Dla LibreChat lub innych klientów MCP opartych na HTTP, uruchom serwer HTTP:

```bash theme={null}
AIGMENTED_API_KEY=sk-TWOJ_KLUCZ npx @aigmented/mcp --http
```

Uruchamia serwer HTTP na porcie 3002 (konfigurowalne przez `MCP_PORT`) z transportem MCP Streamable HTTP pod `/mcp`.

## Błędy i degradacja

| Scenariusz                                     | Co się dzieje            | Co zrobić                                                                            |
| ---------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ |
| Kolekcja bez zbudowanego grafu                 | Graph tools zwracają 409 | Użyj `retrieve_for_topic` / `search_knowledge`, lub odpal `build-graphs` na kolekcji |
| `top_k > 50` w `retrieve_for_topic`            | Błąd walidacji 400       | Zmniejsz `top_k`                                                                     |
| `limit > 100` w `list_collection_cards`        | 400                      | Zmniejsz `limit`                                                                     |
| `card_ids > 25` w `get_cards_batch`            | 400                      | Podziel na kilka batchy                                                              |
| `get_related_cards` z nieistniejącym `card_id` | 404                      | Sprawdź czy ID istnieje w kolekcji                                                   |
| Niepoprawne / cudze `collection_id`            | 404                      | Sprawdź ID i czy klucz API należy do właściwego teamu                                |
| Przekroczony limit tokenów                     | 429                      | Poczekaj na reset limitu lub poproś o wyższy                                         |