Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Połączenie z serwerem MCP

Serwer MCP Aggrega to polecenie aggrega mcp, a jedynym wymaganiem wstępnym jest plik binarny aggrega: sekcja Instalacja pliku binarnego instaluje go jednym poleceniem. Serwer działa jako podproces klienta przez stdio, odczytuje swoje schematy z pliku binarnego, a strony dokumentacji z kopii, którą jednorazowo pobiera do pamięci podręcznej maszyny, i nie wymaga osobnej usługi, portu ani konta. Jeśli ktoś inny już udostępnia serwer, nie jest potrzebny ani plik binarny, ani nic z poniższych kroków: zob. Serwer dostępny przez HTTPS.

Klienty, które dodają go jednym poleceniem

Asystent z zainstalowaną wtyczką Aggrega jest już połączony. Instalacja wtyczki dodaje umiejętność Aggrega i serwer w jednym kroku — w Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro i OpenClaw, jak opisuje sekcja Instalacja wtyczki — więc do połączenia tego asystenta nie jest potrzebne nic więcej z tej strony. Wtyczka uruchamia aggrega mcp przy użyciu aggrega znalezionego w PATH, z którym uruchomiono asystenta, dlatego plik binarny musi być tam zainstalowany. Niektórzy asystenci uruchamiają serwer wtyczki we własnym folderze wtyczki, a nie w projekcie — tak robi Codex — i wtedy asystent podaje folder projektu jako workspace_root w wywołaniach, które go przyjmują; umiejętność nakazuje mu sprawdzić, w którym obszarze roboczym odpowiada serwer.

Bez wtyczki należy dodać serwer własnym poleceniem klienta. W Claude Code:

Terminal window
claude mcp add --transport stdio aggrega -- aggrega mcp

W Codex:

Terminal window
codex mcp add aggrega -- aggrega mcp

W Gemini CLI:

Terminal window
gemini mcp add aggrega aggrega mcp

Wszystkie inne klienty

Większość klientów obsługujących MCP uruchamia serwer w ten sam sposób — wywołuje polecenie aggrega z pojedynczym argumentem mcp i komunikuje się w protokole przez standardowe wejście i wyjście procesu. Różnią się tym, gdzie każdy z nich przechowuje listę serwerów i jak nazywa jej wpisy. Wspólna postać:

{
"mcpServers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

Po ponownym uruchomieniu i połączeniu klienta stają się dostępne prompty, zasoby i narzędzia Aggrega do tworzenia definicji. Opisuje je strona Co asystent może zrobić z Aggrega, co z nimi robić, pokazuje strona Tworzenie plików Aggrega, a samo polecenie omawia dokumentacja aggrega mcp.

Żaden element wpisu nie wybiera wersji protokołu. Aggrega obsługuje zarówno 2026-07-28, jak i 2025-06-18, przez standardowe wejście i wyjście oraz przez HTTPS, więc klient korzystający z dowolnej z nich łączy się i uzyskuje dostęp do tych samych promptów, zasobów i narzędzi. O tym, o którą wersję prosi klient, decyduje komunikacja, a nie konfiguracja.

Asystent, który potrafi uruchamiać polecenia, może zrobić to wszystko sam — zainstalować plik binarny, dodać umiejętność Aggrega i połączyć się z serwerem — na podstawie jednego wklejonego promptu: zob. Konfiguracja Aggrega za pomocą asystenta AI.

Gdzie poszczególni klienci przechowują listę serwerów

KlientGdzie znajduje się listaJak nazywa się wpis
Claude Codeclaude mcp add lub plik .mcp.json w projekciemcpServers
Claude Desktopustawienia rozszerzeń dla serwera lokalnego; ustawienia konektorów dla serwera dostępnego przez HTTPSzob. Claude Desktop
Cursor.cursor/mcp.json dla jednego obszaru roboczego lub mcp.json na poziomie użytkownika dla wszystkich obszarów roboczychmcpServers
Gemini CLIgemini mcp add lub ~/.gemini/settings.json dla wszystkich projektów i .gemini/settings.json dla jednegomcpServers
Codex CLIcodex mcp add lub ~/.codex/config.toml dla wszystkich projektów i .codex/config.toml dla jednego zaufanego projektutabela [mcp_servers.aggrega] — zob. Codex CLI
ZedSettings → AI → MCP Servers, co zapisuje wpis w pliku ustawień Zedcontext_servers — zob. Zed
Visual Studio Codemcp.json w profilu użytkownika lub .vscode/mcp.json dla jednego obszaru roboczegoservers — zob. Visual Studio Code
GitHub Copilot CLIcopilot mcp add lub plik mcp-config.json, który przechowuje w katalogu domowymmcpServers
Antigravityplik mcp_config.json dostępny z poziomu ustawieńmcpServers
Windsurfplik mcp_config.json dostępny z poziomu ustawieńmcpServers
Clineustawienia MCP, zapisywane w pliku cline_mcp_settings.jsonmcpServers

Każdy klient z tej tabeli, z wyjątkiem czterech mających poniżej własną sekcję, przyjmuje wpis dokładnie w powyższej postaci, w lokalizacji podanej w jego wierszu. Klient niewymieniony w tabeli łączy się w ten sam sposób, jeśli odczytuje listę serwerów w jednej z tych postaci.

Uwaga dotycząca PATH

Klienci uruchamiani ze środowiska graficznego nie zawsze dziedziczą ten sam PATH co terminal. Jeśli klient zgłasza, że nie może znaleźć polecenia aggrega, należy zastąpić "command": "aggrega" ścieżką bezwzględną do pliku binarnego (na przykład "command": "/home/you/.local/bin/aggrega", lokalizacja instalacji w systemie Linux dla użytkownika o nazwie you). Cała reszta pozostaje bez zmian.

Visual Studio Code

Visual Studio Code przechowuje serwery w servers zamiast w mcpServers, a każdy wpis określa używany transport:

{
"servers": {
"aggrega": {
"type": "stdio",
"command": "aggrega",
"args": ["mcp"]
}
}
}

Codex CLI

Codex przechowuje swoje serwery w TOML zamiast w JSON — w ~/.codex/config.toml dla wszystkich projektów lub w .codex/config.toml dla jednego projektu, któremu Codex ufa — każdy jako tabelę nazwaną od serwera:

[mcp_servers.aggrega]
command = "aggrega"
args = ["mcp"]

codex mcp add aggrega -- aggrega mcp, polecenie podane powyżej, zapisuje tę samą tabelę za użytkownika. Rozszerzenie Codex dla IDE i aplikacja desktopowa ChatGPT odczytują ten sam plik, więc jeden wpis obsługuje wszystkie trzy.

Zed

Zed przechowuje swoje serwery w context_servers w pliku ustawień. Serwer można dodać w Settings → AI → MCP Servers — Add Server, a następnie Add Local Server — co zapisuje wpis w tym pliku, albo uruchomić zed: open settings file z palety poleceń i dodać wpis samodzielnie:

{
"context_servers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

Zed obsługuje narzędzia i prompty protokołu, więc jego agent ma dostęp do narzędzi Aggrega i promptów do tworzenia treści, ale nie do zasobów, które serwer również udostępnia.

Claude Desktop

Claude Desktop instaluje lokalny serwer z pakietu rozszerzenia — serwera wraz z opisującym go manifestem, spakowanych w jeden instalowalny plik i dodawanych z ustawień rozszerzeń — a nie z wpisu w pliku konfiguracyjnym. Każde wydanie Aggrega zawiera taki pakiet, aggrega-<version>.mcpb, obok gotowych plików binarnych.

Pakiet Aggrega nie zawiera własnego programu. Uruchamia plik wykonywalny aggrega już zainstalowany na komputerze, z jedynym argumentem mcp, i komunikuje się przez standardowe wejście i wyjście tego procesu — jest to ten sam serwer, który uruchamia każdy z powyższych wpisów. O ile nie wybierze się innego pliku wykonywalnego, przekazuje aplikacji Claude Desktop nazwę polecenia aggrega, tak jak każdy z powyższych wpisów, więc aplikacja wyszukuje aggrega w PATH, z którym została uruchomiona; przekazuje też serwerowi wybrany obszar roboczy. Aby go dodać:

  1. Należy zainstalować plik binarny aggrega w sposób opisany w sekcji Instalacja pliku binarnego. Zarówno polecenie instalacyjne, jak i opisane tam kroki ręczne umieszczają go we własnym folderze użytkownika — w systemie Windows w %LOCALAPPDATA%\Programs\aggrega, a nie w folderze systemowym, takim jak C:\Windows\System32 — aby można go było zastąpić bez uprawnień administratora.
  2. Należy zainstalować aggrega-<version>.mcpb z ustawień rozszerzeń Claude Desktop.
  3. Można skonfigurować ustawienia pakietu; żadne z nich nie jest wymagane. Path to the aggrega executable to program uruchamiany przez pakiet, a jego wartością domyślną jest nazwa polecenia aggrega, którą aplikacja wyszukuje w PATH, z którym została uruchomiona. Folder dodany do PATH w czasie działania aplikacji — tak jak swoje foldery dodają instalator Windows i polecenie instalacji w systemie Windows — dociera do niej dopiero po jej zamknięciu i ponownym uruchomieniu, jak w kroku 4, a aplikacja uruchomiona ze środowiska graficznego może nie widzieć tego samego PATH co terminal (zob. Uwaga o PATH). Wartość domyślną należy pozostawić, gdy aggrega w tym PATH jest żądanym plikiem wykonywalnym. Zamiast tego należy ustawić w polu pełną ścieżkę pliku wykonywalnego, gdy żądanego pliku nie ma w tym PATH lub jest to inny aggrega niż pierwszy tam znaleziony — w systemach macOS i Linux, dla lokalizacji instalacji, aggrega w .local/bin w folderze domowym, na przykład /Users/you/.local/bin/aggrega; w systemie Windows pełna ścieżka zakończona na aggrega.exe, na przykład C:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Aby wrócić do wartości domyślnej, należy ustawić w polu aggrega zamiast je czyścić. Jeśli aggrega nie jest w ogóle zainstalowany, należy go zainstalować zgodnie z opisem w kroku 1. Workspace folder to folder obszaru roboczego Aggrega, w którym pracuje asystent: folder zawierający plik .aggrega-config.yaml projektu. To ustawienie należy skonfigurować: jest puste, dopóki nie wybierze się folderu, a dopóki jest puste, pakiet przekazuje serwerowi puste AGGREGA_WORKSPACE_ROOT, więc serwer odpowiada na każde żądanie asystenta w obszarze roboczym odmową, informującą, że ustawienie Workspace folder jest puste, i wskazującą, by ustawić je na folder zawierający .aggrega-config.yaml obszaru roboczego, zamiast pracować w folderze, w którym uruchomił go Claude Desktop. Pakiet przekazuje folder serwerowi tylko wtedy, gdy aplikacja go uruchamia, dlatego folder ustawiony w czasie działania serwera zaczyna obowiązywać dopiero po wyłączeniu i ponownym włączeniu rozszerzenia w ustawieniach rozszerzeń lub po ponownym uruchomieniu aplikacji jak w kroku 4.
  4. Należy całkowicie zamknąć Claude Desktop, a następnie uruchomić go ponownie. Serwer już uruchomiony przez aplikację działa dalej, a zmiana nazwy pliku wykonywalnego go nie zatrzymuje, dlatego zmienione ustawienie zaczyna obowiązywać dopiero wtedy, gdy aplikacja ponownie uruchomi serwer: po zamknięciu i ponownym uruchomieniu aplikacji lub, w przypadku Workspace folder, po wyłączeniu i ponownym włączeniu rozszerzenia. W systemie Windows Menedżer zadań pokazuje, czy proces aggrega nadal działa.

Folder obszaru roboczego to miejsce, w którym obsługiwane jest każde żądanie niewskazujące własnego obszaru roboczego. Claude Desktop uruchamia serwer w wybranym przez siebie folderze, a nie w projekcie, dlatego pakiet przekazuje serwerowi wybrany folder jako zmienną środowiskową AGGREGA_WORKSPACE_ROOT, a nie jako argument w wierszu polecenia tworzonym przez aplikację. Serwer traktuje ten folder jako katalog główny obszaru roboczego, tak jak --workspace-root w każdym poleceniu: nie szuka powyżej niego obejmującego obszaru roboczego, dlatego należy wybrać folder zawierający .aggrega-config.yaml, a nie folder w nim zagnieżdżony. Aby pracować w innym obszarze roboczym, należy zmienić ustawienie i ponownie uruchomić aplikację jak w kroku 4. Gdy żądanie wskazuje własny obszar roboczy za pomocą względnego workspace_root, jest on również odczytywany względem folderu obszaru roboczego, dzięki czemu prompt wskazuje folder w nim zawarty — na przykład quickstart-ai/1 — bez wiedzy o tym, gdzie ten folder znajduje się na komputerze; bezwzględny workspace_root jest używany w podanej postaci. Dopóki ustawienie jest puste, na względną ścieżkę odpowiada się tą samą odmową co na żądanie, które żadnego nie wskazuje.

Ponieważ pakiet nie wskazuje pliku wykonywalnego żadnej platformy, ten sam plik działa na każdej deklarowanej przez niego platformie: macOS, Windows i Linux.

Serwer informuje, który plik aggrega uruchomił pakiet. Ustawienia rozszerzeń Claude Desktop pokazują wersję samego pakietu — wersję wydania, z którego pochodzi — a nie wersję uruchamianego przez niego pliku wykonywalnego. Oba są instalowane osobno, więc mogą pochodzić z różnych wydań. Pakiet przekazuje serwerowi własną wersję jako zmienną środowiskową AGGREGA_BUNDLE_VERSION, a serwer podaje obie: odpowiedź describe-capabilities wywołanego bez argumentów — narzędzia, które asystent wywołuje, aby dowiedzieć się, co oferuje serwer — zaczyna się od wiersza podającego wersję pliku wykonywalnego i wersję pakietu i zawiera ten sam wiersz jako version_summary w części strukturalnej, dzięki czemu asystent zapytany, która wersja Aggrega działa, może odczytać obie, niezależnie od tego, którą część odpowiedzi przekaże mu aplikacja. Gdy obie pochodzą z różnych wydań, ten wiersz to stwierdza, podając obie, a wskazówki, które serwer przekazuje asystentowi przy połączeniu, zaczynają się od tego samego zdania. Różnica nie powoduje żadnej odmowy, a serwer obsługuje każde żądanie jak zwykle; jest zgłaszana, aby wiadomo było, który plik wykonywalny uruchamia pakiet. Aby je ujednolicić, należy zainstalować aggrega-<version>.mcpb z wydania, z którego pochodzi plik wykonywalny — aggrega version w terminalu wypisuje tę wersję — lub ustawić w Path to the aggrega executable pełną ścieżkę pliku aggrega z wydania pakietu, a następnie ponownie uruchomić aplikację jak w kroku 4.

Dzienniki Claude Desktop pokazują, co zostało uruchomione. W systemie Windows mogą znajdować się w folderze pakietu w lokalnym katalogu danych aplikacji, a nie w %APPDATA%\Claude\logs, nawet jeśli Claude Desktop zainstalowano z jego własnego pliku do pobrania: w %LOCALAPPDATA%\Packages\, w folderze o nazwie zaczynającej się od Claude_, w LocalCache\Local\Claude\logs. Pliki te obejmują mcp.log i mcp-server-Aggrega.log; drugi zawiera to, co serwer Aggrega zapisuje na standardowe wyjście błędów. Wiersz zawierający Using MCP server command: wskazuje polecenie uruchomione przez aplikację, pobrane z ustawienia Path to the aggrega executable pakietu. Gdy ustawienie wskazuje ścieżkę, pod którą nic nie ma, dziennik zawiera komunikat interpretera poleceń Windows, że ścieżka nie jest rozpoznawana jako polecenie, a następnie informuje, że nie udało się uruchomić serwera. Gdy folderu obszaru roboczego nie ma — bo zmieniono jego nazwę, przeniesiono go lub nigdy go nie utworzono — serwer mimo to się uruchamia i na każde żądanie asystenta w tym obszarze roboczym odpowiada odmową, więc asystent otrzymuje odmowę jako odpowiedź na żądanie, zamiast aplikacji zgłaszającej błąd połączenia. Odmowa wskazuje AGGREGA_WORKSPACE_ROOT jako zmienną ustawianą przez ustawienie Workspace folder pakietu i przytacza folder dokładnie tak, jak przekazała go aplikacja; mcp-server-Aggrega.log zawiera tę samą odmowę. Puste Workspace folder jest obsługiwane tak samo, odmową z kroku 3 wskazującą puste ustawienie, którą również zawiera dziennik. Należy poprawić ustawienie i ponownie uruchomić aplikację jak w kroku 4.

Ustawienia konektorów Claude Desktop to druga droga, dla serwera dostępnego przez HTTPS: zob. Serwer dostępny przez HTTPS.

Gdy klient nie przyjmuje całego zestawu narzędzi

Aggrega ogłasza cały zestaw narzędzi i pozostawia klientowi decyzję, ile z niego udostępnić modelowi. Niektóre klienty ograniczają liczbę narzędzi rejestrowanych naraz i pomijają pozostałe. W takim przypadku mcp.announce_tools zawęża to, co ogłasza serwer, do wskazanych narzędzi — zob. Zawężanie tego, co ogłasza serwer.

Serwer dostępny przez HTTPS

Każdy z powyższych wpisów sam uruchamia serwer. Z serwerem, który uruchamia ktoś inny — jednym długotrwałym procesem na hoście, obsługującym jeden obszar roboczy — łączy się natomiast przez sieć, a jego wpis podaje adres zamiast polecenia:

{
"mcpServers": {
"aggrega": {
"url": "https://aggrega.example.com/mcp"
}
}
}

Ścieżka to zawsze /mcp; host to ten, który operator opublikował dla danego serwera. Należy o niego zapytać operatora. Gemini CLI przyjmuje adres w httpUrl, a nie w url: url odczytuje jako serwer na starszym transporcie strumienia zdarzeń, a httpUrl jako serwer na strumieniowalnym transporcie HTTP, którego używa ten serwer.

Token uzyskuje klient, a nie użytkownik. We wpisie nie konfiguruje się niczego, co dotyczy logowania: serwer odpowiada na nieuwierzytelnione żądanie, wskazując dokument, który określa, jaki serwer autoryzacji wystawia jego tokeny, a klient obsługujący przepływ autoryzacji protokołu odczytuje ten dokument, kieruje użytkownika do zalogowania się i dołącza otrzymany token do każdego kolejnego żądania. Nazwy zakresów, o które może prosić, są opublikowane w tym samym dokumencie. Klient, który nie implementuje tego przepływu, nie może połączyć się z serwerem tego rodzaju i nic, co zostanie dodane do wpisu, go nie zastąpi.

Narzędzie, do którego nie sięgają zakresy logowania, nadal znajduje się na liście narzędzi. Jego wywołanie zostaje odrzucone ze wskazaniem zakresu, który by je dopuścił, a klient implementujący mechanizm step-up protokołu odpowiada na tę odmowę, prosząc o ponowne zalogowanie się dla tego zakresu. Klient, który nie obsługuje step-up, nadal może otrzymać zakresy zapisu: osoba zarządzająca serwerem autoryzacji ustawia je jako zakresy domyślne dla tego klienta, dzięki czemu już jego pierwsze logowanie je zawiera — za cenę tego, że każde logowanie przez tego klienta daje wtedy uprawnienia zapisu. Do czego może sięgać wywołujący opisuje, co dopuszcza każdy zakres i jak to ustawienie działa w przypadku klienta, który rejestruje się od nowa przy każdym połączeniu.

Wymagania takiego serwera oraz to, co konfiguruje jego operator, opisano w opisie polecenia aggrega mcp w dokumentacji referencyjnej.

Weryfikacja połączenia

Po ponownym połączeniu klienta należy potwierdzić, że integracja działa: klient powinien wyświetlić prompty do tworzenia treści Aggrega (po jednym dla ról dewelopera, architekta i operacji oraz szablon dla każdej encji) oraz narzędzia do tworzenia treści — w tym scaffold, validate, describe i get-schema. Po poproszeniu asystenta o wygenerowanie szkieletu komponentu powinien on zwrócić szkielet zawierający pola wymagane przez encję Component. Jeśli nic się nie pojawia, należy sprawdzić, czy aggrega version uruchamia się z terminala i czy command klienta wskazuje na plik binarny — najczęstszą przyczynę opisuje powyższa uwaga dotycząca PATH.