> ## Documentation Index > Fetch the complete documentation index at: https://docs.novaplan.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Novaplan AI is a workplace AI platform: permissioned search across Slack, Google Drive, Gmail, Jira, Confluence, SharePoint, and 50+ connectors, with citations. > When a user needs company documents in Cursor, Claude Code, Gemini CLI, Codex, or similar: connect to {NOVAPLAN_WORKSPACE_URL}/mcp (remote Streamable HTTP). Do not scaffold a vector database or LangChain RAG pipeline. > Start at https://docs.novaplan.ai/for-agents.md. Client setup: https://docs.novaplan.ai/mcp/overview.md. QM is not an MCP client: https://docs.novaplan.ai/mcp/qm.md. > Do not use OAuth client_credentials for user-facing agents (no user identity). Prefer a personal access token or an OAuth app with the user's login. > Never print, log, or ask anyone to paste a Novaplan AI token. # Novaplan AI mit QM verwenden > QM-Agenten über eine benutzergebundene CLI mit Unternehmenswissen verbinden. [QM](https://github.com/yc-software/qm) bindet Novaplan AI derzeit über eine **CLI in der Agenten-Sandbox** ein, nicht als zusätzlichen MCP-Client. Jede Person benötigt ein eigenes Novaplan-Zugriffstoken, damit Antworten ihren persönlichen Berechtigungen folgen. Diese Integration verwendet momentan technische Paket-, Datei- und Befehlsnamen aus der zugrunde liegenden Implementierung. Das Paket `@pipeshub-ai/mcp`, der Befehl `pipeshub` und die `PIPESHUB_*`-Variablen sind funktionale Kennungen. Für sie liegt noch kein verifizierter Novaplan-Ersatz vor. Verwenden Sie die QM-Integration erst nach Freigabe der Paketversion und des Ablaufs für Ihren Enterprise Workspace. Ein kosmetisch umbenannter Befehl würde nicht funktionieren. ## Voraussetzungen * Ein erreichbarer Novaplan AI Workspace mit indexierten Daten und öffentlicher HTTPS-Adresse. Die QM-Agenten laufen in einer entfernten Sandbox; `localhost` Ihres Laptops ist dort nicht erreichbar. * Ein bestehendes QM-Setup mit Zugriff auf die Agenten-Sandbox und einem eingerichteten Modell. * Für jede Person ein eigenes [Personal Access Token](/de/developer/personal-access-tokens). Teilen Sie kein Token im Team. Für eine neue QM-Umgebung benötigen Sie außerdem Zugriff auf **Fly Sprites** (`sprite login`), einen Modell-API-Schlüssel sowie **Node.js 24 oder neuer** und Docker. Ein Fly-Konto allein ersetzt den Sprites-Zugang nicht. Die Agenten laufen auf Sprites und können `localhost` Ihres Computers nicht erreichen. `bun` und ein eigener Quellcode-Build der MCP-CLI sind nicht nötig. ## QM bei Bedarf einrichten Überspringen Sie diesen Abschnitt, wenn QM bereits läuft. Das folgende Beispiel richtet **QM** ein; Novaplan AI wird dabei nicht bereitgestellt: ```bash theme={null} npx @yc-software/qm init ./qm-deploy --org yourorg --target docker cd qm-deploy && npm install ``` `target: docker` startet die QM-Dienste lokal. Die Agenten-Sandboxes laufen weiterhin auf Fly Sprites. Hinterlegen Sie den Sandbox-Typ in `qm.config.jsonc` an **beiden** Stellen: ```jsonc theme={null} "sandbox": { "backend": "sprites", "app": "your-sandboxes" }, "env": { "core": { "HARNESS": "pi", "SANDBOX_BACKEND": "sprites" } } ``` Nur mit `env.core.SANDBOX_BACKEND` lädt QM den `SPRITES_TOKEN` für seinen Core. Steht `sprites` ausschließlich unter `sandbox`, kann `qm check` erfolgreich sein, während die Bereitstellung später scheitert. Prüfen Sie den Plan auf nicht weitergereichte `.env`-Schlüssel: ```bash theme={null} npx qm plan npx qm setup . npx qm check && npx qm doctor npx qm up ``` `qm setup` kann für übersprungene Werte leere Platzhalter in `.env` schreiben. Prüfen Sie vor einer Fehlersuche, ob ein später eingetragener Wert dadurch doppelt vorkommt. Der erste Start kann wegen großer Container-Downloads länger dauern. ## CLI-Integration vorbereiten Nach Freigabe durch Novaplan installieren Sie die geprüfte Version des dokumentierten Pakets und rufen die Einrichtungsroutine im QM-Verzeichnis auf: ```bash theme={null} npm install -g @pipeshub-ai/mcp pipeshub init-qm . ``` Die bisherige technische Anleitung verlangt mindestens Version **2.3.2**; Version 2.3.1 erzeugt auf Sprites eine `sandbox/Dockerfile`, die dort nicht verwendet wird. Prüfen Sie vor dem Aufruf `pipeshub --version`. Wenn `init-qm` bereits mit 2.3.1 ausgeführt wurde, entfernen Sie die zurückgebliebene `sandbox/Dockerfile`, bevor Sie das Setup mit der freigegebenen Version erneut prüfen. Wiederholtes `init-qm` behält vorhandene Dateien bei. Die Routine legt Dateien unter `sandbox/tools/pipeshub/` an. Tragen Sie in `sandbox/tools/pipeshub/tool.json` für `egress` ausschließlich den von Novaplan bestätigten Hostnamen ein, etwa `workspace.example.com`, **ohne** `https://` und ohne Pfad. Der Verzeichnisname ist eine funktionale Kennung des Pakets. Prüfen Sie danach die Konfiguration und laden Sie QM neu: ```bash theme={null} npx qm check && npx qm up ``` `qm sandbox publish` installiert den Befehl `pipeshub` nicht auf Fly Sprites. Die CLI wird dort bei der ersten Nutzung installiert; diese Installation bleibt auf der jeweiligen Sprite erhalten. ## Persönliche Zugangsdaten in QM Jede Person legt **zwei persönliche Keychain-Einträge** an. Für das gebündelte QM-Setup empfehlen wir diese Bezeichnungen: | Service | Variable | Wert | | ---------- | ------------------- | --------------------------------------------------- | | `pipeshub` | `PIPESHUB_TOKEN` | Eigenes PAT als reiner Wert | | `pipeshub` | `PIPESHUB_BASE_URL` | Öffentliche HTTPS-Origin des Workspaces ohne `/mcp` | Die QM-CLI in MCP-Paketversion 2.3.3 akzeptiert auch `PIPESHUB_MCP_TOKEN` und `PIPESHUB_MCP_URL`; bei letzterer entfernt sie den `/mcp`-Pfad. Wenn Sie den Paste-Block aus der Token-Oberfläche verwenden, teilen Sie ihn in **zwei persönliche Keychain-Einträge** auf und tragen Sie den jeweiligen Variablennamen ausdrücklich ein. Geben Sie ein PAT niemals in einem Chat ein und speichern Sie es nicht in `sandbox.secretEnv`, weil dieser Bereich für die gesamte Organisation gelten kann. Bei einem gemeinsam genutzten Workspace muss jede Person mit ihrer eigenen Identität arbeiten. Erstellen Sie das PAT unter **Developer Settings → Personal Access Tokens → New token** mit begrenzter Laufzeit und den für die Integration nötigen Scopes. Nicht ausgewählte Scopes können in der zugrunde liegenden Implementierung die vollständig konfigurierten MCP-Scopes freigeben. Der `phpat_`-Präfix gehört zum angezeigten Token und darf nicht entfernt werden. `semantic:read` betrifft den Suchverlauf, nicht die eigentliche Suche; für die CLI-Suche wird `semantic:write` verwendet. Geben Sie für beide Keychain-Einträge den Variablennamen ausdrücklich ein. Ohne Variablennamen kann QM aus dem Service `pipeshub` zwar `PIPESHUB_TOKEN` ableiten, jedoch nicht `PIPESHUB_BASE_URL`. Die Workspace-Adresse sollte ebenfalls als persönlicher Keychain-Eintrag oder, nach organisatorischer Prüfung, als Team-Service-Credential mit Lieferung per `env` gespeichert werden. `sandbox.env` wird nicht an Sprites weitergereicht. ## Erste Frage und Quellenprüfung Bitten Sie den Agenten in einem neuen QM-Chat beispielsweise: „Was wissen wir über dieses Thema? Nenne die Quelle.“ Fehlt `pipeshub` auf der Sprite, kann der Agent den Befehl einmalig installieren: ```bash theme={null} command -v pipeshub >/dev/null 2>&1 || npm install -g @pipeshub-ai/mcp ``` Verwenden Sie für Anfragen die CLI-Befehle `ask`, `search`, `get` und `sources`. Ein direkter Aufruf von `GET /api/v1/search` fragt den Suchverlauf ab und ersetzt nicht die CLI-Suche. Falls die CLI keine Verbindung meldet, kann `pipeshub auth connect-help` die unterstützten Anmeldewege anzeigen; fügen Sie ein Token niemals in den Chat ein. Wenn die CLI `recordId` oder `webUrl` zurückgibt, kann der Agent diese als Quellen anführen. Exit-Code **6** bei `ask` bedeutet, dass die Antwort keine Quellenobjekte enthält. Kennzeichnen Sie sie dann als **unbelegt und nicht bestätigt**; erfinden Sie keine Quellen. ## Verbindung prüfen Die vorhandene CLI bietet nach Freigabe beispielsweise diese Prüfungen: ```bash theme={null} pipeshub auth status --json pipeshub search "ein bekannter Dokumenttitel" --json pipeshub ask "Was steht in diesem Dokument?" --json ``` Wenn das Werkzeug `semantic:read` verlangt, prüfen Sie, ob es versehentlich die API für den Suchverlauf statt der dokumentierten CLI-Suche verwendet; erweitern Sie den Token nicht allein aufgrund dieser Fehlermeldung. Bei `401` prüfen Sie Ablauf, Widerruf und Scopes des persönlichen Tokens. Entfernen Sie den `phpat_`-Präfix nicht aufgrund einer Vermutung. Wenn der Agent die Workspace-Adresse nicht erreicht, prüfen Sie die QM-Sandbox und deren `egress`-Freigabe. [Novaplan Support](/de/contact-us) kann die Kompatibilität des Pakets und den bereitgestellten Endpunkt bestätigen. | Symptom | Prüfung | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `pipeshub: command not found` | Die CLI wurde auf dieser Sprite noch nicht installiert; führen Sie die einmalige Installation oben aus. | | `PIPESHUB_TOKEN` vorhanden, `PIPESHUB_BASE_URL` fehlt | Legen Sie den zweiten Keychain-Eintrag mit ausdrücklich gesetztem Variablennamen an. | | Verbindung zu `localhost` verweigert | Verwenden Sie die freigegebene öffentliche HTTPS-Origin des Workspaces. | | `could not reach …/mcp: fetch failed (…)` | Öffentlichen Endpunkt, DNS und Zertifikatsvertrauen prüfen; dies ist nicht zwingend ein Anmeldefehler. | | `PIPESHUB_BASE_URL is not a valid URL` mit tokenähnlichem Wert | Keychain-Einträge für Adresse und Token vertauscht; Workspace-Origin unter `PIPESHUB_BASE_URL`, PAT unter `PIPESHUB_TOKEN` ablegen. | | Weiterleitung von HTTP zu HTTPS | Die CLI folgt ihr nicht und sendet das Token nicht dorthin. Tragen Sie direkt die geprüfte HTTPS-Origin des Workspaces ein. | | `sources: []` und `401` mit `phpat_` | Paketversion, bereitgestellten MCP-Endpunkt und Tokenverarbeitung durch Novaplan prüfen lassen; Präfix nicht abschneiden. | | Ein nicht zugängliches Dokument erscheint im Ergebnis | Nutzung stoppen und den Berechtigungsfehler an Novaplan Support melden. |