AI-assistent (MCP)

Inleiding

Ekos bevat een ingebouwde Model Context Protocol (MCP)-server. MCP is een open standaard waarmee AI-assistenten en -agents hulpmiddelen kunnen ontdekken en aanroepen die door een toepassing wordt aangeboden. Wanneer de MCP-server is ingeschakeld, kan een AI-assistent uw apparatuur observeren — zoals de verbindingsstatus, de positie van de opstelling en de laatst gemaakte opname — en, indien u dit toestaat, de opstelling en focusser bedienen, objecten uit catalogi opzoeken, en meer.

Elke MCP-geschikte client kan de server direct gebruiken: deze communiceert via standaard JSON-RPC 2.0 over HTTP, met de gebruikelijke methoden initialize, tools/list en tools/call. Er is geen KStars-specifieke clientcode nodig.

De server inschakelen

De server wordt geconfigureerd in het instellingenvenster van Ekos, op het tabblad MCP.

• Activeer MCP-server inschakelen aan om deze te starten. De server start automatisch samen met Ekos wanneer deze optie is geactiveerd.

• Poort selecteert de TCP-poort waarop wordt geluisterd. De standaardwaarde is 8765; elke poort tussen 1024 en 65535 kan worden gebruikt.

• De status-led naast de poort geeft aan of de server momenteel luistert.

Notitie

De server luistert alleen op de lokale machine (127.0.0.1). Hij is niet bereikbaar via het netwerk. Om hem vanaf een andere machine te gebruiken, moet u een eigen tunnel opzetten (bijvoorbeeld via SSH-poortdoorsturing) en op de hoogte zijn van de beveiligingsimplicaties daarvan.

Authenticatie en tokens

Elk verzoek moet een bearer-token bevatten. Er worden twee tokens beheerd in het tabblad MCP, elk voorzien van knoppen voor weergeven, kopiëren en Opnieuw genereren:

• Het veld Token bevat het token voor volledige toegang. Clients die dit token aanbieden, kunnen elk ingeschakeld hulpmiddel aanroepen.

• Het veld Alleen-lezen token bevat een apart token dat beperkt is tot hulpmiddelen met alleen-lezenrechten. Geef dit token aan assistenten die de opstelling moeten kunnen observeren, maar nooit hardware mogen verplaatsen.

Tokens worden opgeslagen in de sleutelhanger van uw systeem (onder de servicenaam kstars), nooit in configuratiebestanden in leesbare tekst. Het opnieuw genereren van een token maakt het vorige token onmiddellijk ongeldig.

Om een ​​client te verbinden, laat u deze verwijzen naar http://127.0.0.1:8765/mcp en geeft u het token door als standaard HTTP-bearer-credential. Verzoeken zijn JSON-RPC 2.0-berichten die via POST worden verstuurd. Bijvoorbeeld het aanroepen van het hulpmiddel ekos_status met curl:

curl -s http://127.0.0.1:8765/mcp \
  -H "Authorization: Bearer <your token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
       "params": {"name": "ekos_status", "arguments": {}}}'

Het antwoord is een JSON-RPC-envelope waarvan het veld result de uitvoer van het hulpmiddel bevat — in dit geval de status van de INDI-verbinding, het actieve profiel en de verbonden apparaten.

Er is een Server-Sent Events-stream beschikbaar op /mcp/stream. Per verbinding geldt een limiet van 60 verzoeken.

Controles op besturing

Waarschuwing

Met een token dat volledige toegang biedt, kan een AI-agent uw opstelling en focusser aansturen. Behandel zo’n token bij een actieve opstelling als een wachtwoord: geef de voorkeur aan een ‘alleen-lezen’-token wanneer waarnemen volstaat, en controleer welke functies zijn ingeschakeld voordat u de besturing aan een agent overdraagt.

Drie mechanismen beperken wat een verbonden client kan doen:

• Alleen-lezen-modus (weigert hulpmiddelen voor rig-besturing). Indien geactiveerd, weigert de server alle hulpmiddelen die wijzigingen aanbrengen voor alle clients, ongeacht welk token ze aanbieden.

• Het alleen-lezen-token. Clients die zich hiermee authenticeren, kunnen alleen hulpmiddelen aanroepen die als alleen-lezen zijn gemarkeerd, zelfs wanneer de alleen-lezen-modus is uitgeschakeld.

• De boomstructuur Beschikbare hulpmiddelen. Hier staan ​​alle tools vermeld die de server aanbiedt, gegroepeerd per familie, met een selectievakje voor elke hulpmiddel en elke familie. Hulpmiddelen die niet zijn geselecteerd, zijn volledig verborgen voor clients: ze verdwijnen uit hulpmiddelen/lijst en aanroepen ervan worden geweigerd.

In de boomstructuur markeert een hangslotpictogram alleen-lezen-hulpmiddelen en een tandwielpictogram hulpmiddelen die de status van de rig wijzigen. Tekstballonnen geven ook aan welke hulpmiddelen een effect hebben dat moeilijk ongedaan te maken is (zoals mount_sync), in overeenstemming met de annotatierichtlijnen van de MCP-specificatie.

Verwijzing naar hulpmiddelen

De onderstaande tabellen vermelden de hulpmiddelen die momenteel bij KStars worden meegeleverd. De kolom Toegang geeft lezen aan voor hulpmiddelen die de apparatuur alleen observeren, en besturen voor hulpmiddelen die de status ervan wijzigen.

Ekos-status

Hulpmiddel	Doel	Toegang
ekos_status	Huidige INDI/Ekos-verbindingsstatus, actief profiel en namen van verbonden apparaten.	gelezen

Catalogus

Hulpmiddel	Doel	Toegang
catalog_search	Doorzoek de KStars-catalogi op naam. Dit levert overeenkomende objecten op, inclusief hun officiële namen, typen, J2000-coördinaten en magnitudes. Er wordt ondersteuning geboden voor zoeken op deelreeksen of exacte overeenkomsten, evenals voor een typefilter en een magnitude-limiet. Gebruik deze functie om een ​​naam zoals “M42” om te zetten naar de officiële naam “M 42” voordat de telescoop naar het object wordt gericht.	gelezen

Opstelling

Hulpmiddel	Doel	Toegang
mount_coords	Huidige RK/Dec, Alt/Az, uurhoek, pier-kant en volgstatus.	gelezen
mount_get_slew_rates	Vermeld de door het stuurprogramma ondersteunde draaisnelheden en de momenteel geselecteerde draaisnelheid.	gelezen
mount_goto	Draai naar equatoriale coördinaten (RK in uren, Dec in graden).	besturing
mount_goto_target	Naar een benoemd object draaien, opgelost door KStars (canonieke naam, bijv. “M 42”).	besturing
mount_sync	Synchroniseer het positioneringsmodel van de opstelling met de opgegeven coördinaten. Dit is lastig terug te draaien: een foutieve synchronisatie verstoort het positioneringsmodel.	besturing
mount_park / mount_unpark	Zet de opstelling in de parkeerstand of haal hem uit de parkeerstand voor gebruik.	besturing
mount_abort	Stop onmiddellijk alle beweging van de opstelling.	besturing
mount_set_tracking	Schakel siderisch volgen in of uit.	besturing
mount_set_track_mode	Selecteer de volgsnelheid: siderisch, maan-, zon- of aangepast.	besturing
mount_set_slew_rate	Selecteer een draaisnelheid op basis van de index in de lijst van het stuurprogramma.	besturing
mount_set_meridian_flip	Schakel de automatische meridiaanwissel in of uit en stel de uurhoek-offset in.	besturing

Focuser

Hulpmiddel	Doel	Toegang
focuser_status	Naam van de focuser, huidige en maximale positie, en vlaggen voor mogelijkheden. Een optionele parameter name selecteert een apparaat bij opstellingen met meerdere focusers; alle focuser-hulpmiddelen ondersteunen deze parameter.	gelezen
focuser_move_absolute	Verplaats naar een absolute stap-positie, gevalideerd aan de hand van het maximum van het stuurprogramma. Mag niet worden aangeroepen terwijl de Ekos-autofocus actief is.	besturing
focuser_move_relative	Verplaats over een bepaald aantal stappen (positief naar buiten, negatief naar binnen; de richting hangt af van de aansturing). Mag niet worden aangeroepen terwijl de autofocus van Ekos actief is.	besturing
focuser_abort_move	Stop elke beweging van de focuser tijdens het werken.	besturing

Toegang tot afbeelding

Deze hulpmiddelen werken met beelden van elke fabrikant: de opnamewachtrij, Focus, Align, pooluitlijning en ad-hocopnames. Bij een opstelling met meerdere camera’s kan een optionele parameter camera worden gebruikt om een ​​apparaat te selecteren; standaard wordt het meest recente beeld van alle camera’s geretourneerd.

Hulpmiddel	Doel	Toegang
image_last_info	Metagegevens van het laatst vastgelegde frame: bestandspad, camera, belichting, filter, doelobject, tijdstempel, sensortemperatuur, HFR, aantal sterren en afmetingen.	gelezen
image_last_thumbnail	Een base64-gecodeerde JPEG-voorvertoning van het meest recente frame, met een formaat dat geschikt is voor modellen met beeldherkenning (standaard 512 pixels aan de langste zijde, maximaal 1024).	gelezen