Serwer MCP - Aigmented

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. 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.

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

Konfiguracja dla Claude Desktop

Dodaj do claude_desktop_config.json:

{
  "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:

{
  "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”

describe_collection()               # potwierdź że graf jest zbudowany
list_clusters()                     # zobacz wszystkie tematy
get_cluster(cluster_id=<onboarding>)  # karty + encje w tym klastrze
retrieve_for_topic(topic="Onboarding nowych pracowników", description="...", top_k=30)
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?“

list_entities(entity_type="PERSON", top_k=100)
Dla każdej interesującej osoby: retrieve_for_topic(topic=<imię nazwisko>, top_k=10)
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”

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

6. “Przejrzyj wszystkie karty i wybierz to co istotne”

describe_collection()                              # zorientuj agenta
list_collection_cards(offset=0, limit=50)          # pierwsza strona lekkich streszczeń
list_collection_cards(offset=50, limit=50)         # kolejna
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:

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

Documentation Index

​Konfiguracja dla Claude Desktop

​Konfiguracja dla Cursor

​Zmienne środowiskowe

​Dostępne narzędzia

​Eksploracja i Q&A

​list_collections

​search_knowledge

​ask_question

​get_card_details

​Nawigacja po grafie wiedzy

​describe_collection

​list_clusters

​get_cluster

​list_entities

​get_gaps

​Retrieval do tworzenia treści

​retrieve_for_topic

​Przeglądanie kart

​list_collection_cards

​get_cards_batch

​get_related_cards

​Tworzenie treści z MCP — cookbook

​1. “Streść co wiemy o X”

​2. “Wygeneruj sekcję szkolenia o onboardingu”

​3. “Kto występuje w naszej bazie wiedzy?“

​4. “Gdzie mamy luki w wiedzy?“

​5. “Zbuduj quiz wokół konkretnej karty”

​6. “Przejrzyj wszystkie karty i wybierz to co istotne”

​Wskazówki

​Tryb HTTP (LibreChat)

​Błędy i degradacja

Konfiguracja dla Claude Desktop

Konfiguracja dla Cursor

Zmienne środowiskowe

Dostępne narzędzia

Eksploracja i Q&A

`list_collections`

`search_knowledge`

`ask_question`

`get_card_details`

Nawigacja po grafie wiedzy

`describe_collection`

`list_clusters`

`get_cluster`

`list_entities`

`get_gaps`

Retrieval do tworzenia treści

`retrieve_for_topic`

Przeglądanie kart

`list_collection_cards`

`get_cards_batch`

`get_related_cards`

Tworzenie treści z MCP — cookbook

1. “Streść co wiemy o X”

2. “Wygeneruj sekcję szkolenia o onboardingu”

3. “Kto występuje w naszej bazie wiedzy?“

4. “Gdzie mamy luki w wiedzy?“

5. “Zbuduj quiz wokół konkretnej karty”

6. “Przejrzyj wszystkie karty i wybierz to co istotne”

Wskazówki

Tryb HTTP (LibreChat)

Błędy i degradacja