remnawave-mcp

Ein MCP-Server für die API des Remnawave-„Panels**](https://rem{nna.st).

Veröffentlicht unterme dem @folexz-Scope: Der remnawave-mcp-Name auf npm ist ein anderes Projekt, das Remnawave 2.7.4 targets and not works with 2.8.0+.

npx -y @folexz/remnawave-mcp   # configured via REMNAWAVE_BASE_URL + REMNAWAVE_API_TOKEN_READ/_WRITE

It deckt alle 205 Operationen über 28 – Steuereinheites der Remnawave-API v3.G3.2 ab: Cer, Nodes, Hosts, Kongurationsprofile, Squads, Abonnements, Node-Plughins, Infra-in–rechung, Systemstats, System statis. **All ** , generated from the panel's own OpenAPI document angement. If you run npm run build-spec with a newer module, the tool-interface follows.

Highlights

• Spec-driven and self-up via. npm run update-spec fetches the latest OpenAPI document from Remnawave's own publication, publishes and builds the duct; every tool input figure comes directly from operation. Parameters and Requestg. Nothing from API written by hand, and the build printed a diff that named each operation addeded, removeded or renamed, so a versioning cannot silently remove a Tool.

• Bounded context costs. 205 typed Tools would cost ~39k Tokens from tools/list on every call. The default profile exposes 5 Tools (~ Tokens from ` ~1.4) and still every operation — see why not 205 Tools.

• Two tokens least privilege auth. A read token and an optional write token. GET uses the read token; POST/PATCH/PUT/DELETE use the write token. If no write token exists, mutation tools are not registered at all — the server is in read-only mode.

• Write Protection for running Panel. Mutation is serial at a minimum interval and automatically retried with Backoff, because each config write tells panel to push config to all Nodes and restart Xray. Bulk and delete operations additionally require confirm: true.

• Built-in fields. The below footnotes are attached to affected operations, and appear in the Tool description and in output from remnawave_describe_operation.

*No. **No request that cannot succeed.**16 endpoints (authorization, passkeys,management) are only available to an authenticated admin JWT and reject API-tokens. This server detects them from the Spect of and lehnt them locally with explanation instead of sending.

• Escape hatches. remnawave_request_read / remnawave_request_write banner can access any path, including undocumented routes and query syntax that OpenAPI cannot express.

Requirements

• Node.js ≥ 18

• A reachable Remnawave panel (3.x) over HTTPS

• An API token from the panel: Settings → API tokens. Remnawave 3.x supports scoped tokens — request one with read authorizations, and if you want mutations, a second with write authorization.

Installation

The quick path is npx — see Registration with Claude Code. To start from source, run:

git clone https://github.com/folexz/remnawave-mcp.git
cd remnawave-mcp
npm install
npm run build

Configuration

All configuration is done via environment variables passed by your MCP host, not by reading files.

| REMAVE_SKIF_PASAV_COMMA | no | 0 | 1 removes the requirement confirm: true at destructive operations. | | REMNAWAVE_ALLOW_ADMIN_JWT_OPS | no | 0 | 1 allows the 16 admin-JWT-only endpoints (only set if your token is an admin JWT). |

Register with Claude Code

Read-only (recommended default):

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  -- npx -y @folexz/remnawave-mcp@latest

With mutations enabled and typed tools for controllers in everyday use:

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  --env REMNAWAVE_API_TOKEN_WRITE=your_write_token \
  --env REMNAWAVE_TOOL_PROFILE=core \
  -- npx -y @folexz/remnawave-mcp@latest

@latest causes npx to resolve the newest published version at each start. To run a local build, replace the command with node /absolute/path/to/remnawave-mcp/dist/index.js.

Register with Claude Desktop / other MCP clients

{
  "mcpServers": {
    "remnawave": {
      "command": "npx",
      "args": ["-y", "@folexz/remnawave-mcp@latest"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://panel.example.com",
        "REMNAWAVE_API_TOKEN_READ": "your_read_token"
      }
    }
  }
}

Why not 205 tools

tools/list is sent back to the model at each request, so its serialized size has a permanent context tax. Measured with this spec (npx tsx scripts/tool-stats.ts):

The reason full is so expensive is Remnawave's DTOs: a single unresolved host object is on its own about ~30 KB of JSON-Schma because it contains every eingehende and security variant.

The server therefore does not choose between „one Tool per operation" and „one blunt dispatcher" — it offers both and lets Profile determine how much is announced:

1. Catalog tools (always active, 3 tools). remnawave_list_operations through some and searches catalog and returns one compact line per operation; remnawave_describe_operation returns in addition to complete JSON-Schema plus Field notes for one operation; remnawave_call execs each of the 205 by name. The usual loop is list → describe → call, and it costs the same 1.4 KB tokens no matter how big the API becomes. This is the same lazy-loading idea used by an Agent-harness when it defers Tool-Schemas to low.

2. Typed tools (profile-selected). One generated tool per operation for the controllers you actually work with — core covers users, nodes, hosts, config profiles, internal affairs, system, and the two bulk-action controllers, full covers everything, minimal none. Schemas above REMNAWAVE_MAX_SCHEMA_BYTES retain their top-level fields and remove nesting, with a pointer to remnawave_describe_operation and the complete -schema.

3. Escape hatches (2 tools). "Raw GET" and "Raw Write" for anything the spec does not cover. Every route goes to the same executor, so the write gate, confirmation gate, path templating, and query processing behave best previously. Select a profile by taste: minimal if many MCP servers are connected, core if the common operations should be one call removed, full if context doesn't matter.

Field notes — behavior the spec does not document

All of these were tested against a live 3.3.2 panel and are attached to the affected operations in the tool descriptions.

• PATCH /api/config-profiles is a replace, no patch. The body is {uuid, config} and config must be the complete, valid Xray config. A fragment fails with A061: Config doesn't have inbounds. Correct order: GET /api/config-profiles/{uuid} → edit the returned config object in place → send PATCH for the whole thing.

• At 127.0.0.1:3000 the panel does not answer, even from the panel host itself and even though docker-proxy listens there (curl returns exit code 52, empty answer). Always use the public HTTPS origin with a bearer token.

• Each response is in {"response": ...}. These servers unpack a response so the tool output is the payload itself.

• A host binds to a profile through nested inbound.configProfileUuid (plus inbound.configProfileInboundUuid), not a top-level configProfileUuid. Verified on real hosts: nested present, top-level absent.

• A run of PATCHes takes the panel down. Each config write sends once per node to all nodes and restarts Xray there; several in succession and the panel's own TLS listener stops answering. The client serializes mutations (REMNAVAVE_WRITE_MIN_INTERVAL_MS, default 1500 ms) and retries transport errors with exponential backoff and jitter. Don't disable it with parallel bulk updates.

• POST /api/subscription-templates creates only an empty template. The content is then loaded by a separate PATCH /api/subscription-templates. JSON and YAML bodies can not be updated in the same request.

• serverDescription on a host is limited to 30 characters (per maxLength in the spec). This is also what ensures that a Hysteria2 host in "app" appears properly formatted instead of raw JSON.

• Sixteen endpoints are admin-JWT only — the auth and passkeys controllers plus API-Token-Verwaltung (GET/POST /api/tokens, DELETE /api/tokens/{uuid}, GET /api/tokens/scopes). The panel answers API tokens there with 401/403. These servers recognize them from the spec and reject them locally; REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1 acquires the locks if the configured token actually is an admin JWT.

• GET /api/users/stream answers with newline-delimited JSON, not a single document. It is parsed into an array of user records instead of delivering a text blob.

• PATCH /api/hosts is a real partial patch — {uuid, serverDescription} alone is sufficient. Only config profiles have the replace-everything semantics. Live tested.

• Errors come as {message, errorCode}; errorCode (e.g. A061) is included in these server's error text.

Tool coverage

Each controller is traversable via remnawave_call and through the trap doors. The typed column shows which receive individual tools under REMNAWAVE_TOOL_PROFILE=core.

GXP... no.

Need check we didn't accidentally leave "Escape hatches" inserted weird in "Tool coverage"? It's okay.

Also "Bulk and delete" "Additional require" okay.

Need refine some translations. The above is maybe not polished and has some erroneous "Toool" and table issues.

Let's rewrite more naturally and accurately. I can just output final in one go.

Let's produce final. Ensure no extraneous. Since user said only translated text, and we need not include "G" no.

I'll now craft final in a more refined German.

Let's produce final.# remnawave-mcp

Ein MCP-Server für die Remnawave-Panel-API.

Veröffentlicht unter dem @folexz-Scope: Der Name remnawave-mcp ohne Scope auf npm gehört zu einem unabhängigen Projekt, das Remnawave 2.7.4 anspricht und mit 2.8.0+ nicht funktioniert.

npx -y @folexz/remnawave-mcp   # configured via REMNAWAVE_BASE_URL + REMNAWAVE_API_TOKEN_READ/_WRITE

Er deckt alle 205 Operationen über 28 Controller der Remnawave-API v3.3.2 ab — Benutzer, Knoten (Nodes), Hosts, Konfigurationsprofile, Squads, Abonnements, Node-Plugins, Infra-Abrechnung, Systemstatistiken — generiert aus dem eigenen OpenAPI-Dokument des Panels statt von Hand geschrieben. Weisen Sie eine neuere Spezifikation an npm run build-spec, und die Tool-Oberfläche folgt entsprechend.

Highlights

• Spezifikationsgesteuert und selbstaktualisierend. npm run update-spec lädt das neueste OpenAPI-Dokument aus der öffentlich veröffentlichten Remnawave-Kopie und baut den Katalog neu; jedes Tool-Eingabeschema stammt direkt aus den Parametern und dem Request-Body der Operation. Nichts an der API ist handgeschrieben, und der Neubau gibt ein Diff aus, das jede hinzugefügte, entfernte oder umbenannte Operation nennt – so kann ein Versionssprung nicht unbemerkt ein Tool entfernen.

• Begrenzte Kontextkosten. 205 typisierte Tools würden bei jeder Anfrage ~39k Tokens von tools/list kosten. Das Standardprofil exponiert 5 Tools (~1.4k Tokens) und erreicht dennoch jede Operation – siehe Warum nicht 205 Tools.

• Zwei-Token-Authentifizierung nach dem Need-to-know-Prinzip. Ein Lese-Token und ein optionales Schreib-Token. GET verwendet das Lese-Token; POST/PATCH/PUT/DELETE das Schreib-Token. Ohne Schreib-Token werden mutierende Tools überhaupt nicht registriert – der Server ist physisch schreibgeschützt.

• Schutzmechanismen für ein Live-Panel. Mutationen werden mit einem Mindestintervall serialisiert und mit Backoff wiederholt, weil jeder Konfigurationsschreibvorgang das Panel dazu bringt, die Konfiguration an alle Knoten zu pushen und Xray neu zu starten. Bulk- und Löschoperationen erfordern zusätzlich confirm: true.

• Eingebaute Feldnotizen. Die folgenden Stolpersteine sind an den betroffenen Operationen befestigt und erscheinen daher in der Tool-Beschreibung und in der Ausgabe von remnawave_describe_operation.

• Keine Anfragen, die scheitern müssen. 16 Endpunkte (Auth, Passkeys, API-Token-Verwaltung) werden nur einem angemeldeten Admin-JWT angeboten und weisen API-Tokens ab. Sie werden anhand der Spezifikation erkannt und lokal mit einer Erklärung abgelehnt, statt sie abzuschicken.

• Ausstiegsrechte. remnawave_request_read / remnawave_request_write können jeden Pfad erreichen, einschließlich undokumentierter Routen und Query-Syntax, die OpenAPI nicht ausdrücken kann.

Voraussetzungen

• Node.js ≥ 18

• Ein über HTTPS erreichbar Remnawave-Panel (3.x)

• Ein API-Token vom Panel: Einstellungen → API-Tokens. Remnawave 3.x unterstützt Tokens mit eingeschränkten Rechten – erstellen Sie eines mit Leseberechtigungen und, wenn Sie Mutationen wünschen, ein zweites mit Schreibberechtigungen.

Installation

Der schnelle Weg ist npx – siehe Anmeldung mit Claude Code. So starten Steen Sie aus dem Quellcode:

git clone https://github.com/folexz/remnawave-mcp.git
cd remnawave-mcp
npm install
npm run build

Konfiguration

Alle Konfiguration erfolgt über Umgebungsvariablen, die von Ihrem MCP-Host bereitgestellt werden. Es werden keine Dateien gelesen.

Anmeldung mit Claude Code

Schreibgeschützt (empfohlener Standard):

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  -- npx -y @folexz/remnawave-mcp@latest

Mit aktivierten Schreiboperationen und typisierten Tools für die alltag: GXP4

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  --env REMNAWAVE_API_TOKEN_WRITE=your_write_token \
  --env REMNAWAVE_TOOL_PROFILE=core \
  -- npx -y @folexz/remnawave-mcp@latest

@latest bewirkt, dass npx bei jedem Start die neueste veröffentlichte Version auflöst. Um einen lokalen Build auszuführen, ersetzen Sie den Befehl durch node /absolute/path/to/remnawave-mcp/dist/index.js.

Anmeldung bei Claude Desktop / anderen MCP Clients

{
  "mcpServers": {
    "remnawave": {
      "command": "npx",
      "args": ["-y", "@folexz/remnawave-mcp@latest"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://panel.example.com",
        "REMNAWAVE_API_TOKEN_READ": "your_read_token"
      }
    }
  }
}

Warum nicht 205 Tools

tools/list wird bei jeder Anfrage erneut an das Modell geschickt, daher ist seine serialisierte Größe eine permanente Kontextsteuer. Gemessen an dieser Spezifikation (npx tsx scripts/tool-stats.ts):

Remnawaves DTOs tragen die Ursache dafür, warum full so teuer ist: Ein dereferenziertes Hostobjekt ist für sich schon ~30 KB JSON-Schema, weil es jede Inbound und Sicherheitsvariante eibetet.

Der Server wählt also nicht zwischen „ein Tool pro Operation“ und „ein Anwendungsleiterer“ – er liefert beides und überlässt dem Profil zu wählen, wunt er bewirbt:

1. Katalagtools (immer an, 3 Tools).:** remwnawave_list_operations wollt den Katalog durchforstet und gibt eine kompakte Zeile pro Operation zurück; remnawave_describe_operation liefert das komplette JSON-Schema plus Fleldnotizen für genau eine Operation; remnawave_call führt eines der 205 namentlich aus. The übliche loop list → describe → call kostet gleich 1.4k Tokens, egal wie groß die API wird. This is the same tele-comency which Agent-Harness used when it can virtuially tooldefinitions.

2. Typed Tools.** One generated Tool per operation for the controllers core covers users, nodes, hosts, config profiles, internal squads, system and the two bulk-action controllers; full covers everything; minimal none. Schemas over REMNAWAVE_MAX_SCHEMA_BYTES keep their top-level fields and drop the nesting, with a pointer to remnawave_describe_operation for the full version.

3. Notausstiege (2 Tools).** Raw GET and raw write for anything, were in der Spec fehlt.

Jede Route läuft über dasselbe Ausführungsmodul, so dass der writeig-Schatten, das Bestätigungstor für destructive Operationen, Path-Templating und Query-Handling identisch funktionieren, egal welche Oberfläche Sie verwenden.

Choose a Profile nach Geschmack: minimal if you have connect many MCP servers; core if you want the everyday vehicles one call away; full if context no role.

Notizen zu Feldern – Verhalten, über das die Spezifikation nichts sagt

Alle diese Punkte wurden gegen ein Live-Panel 3.3.2 geprüft und sind y an den betroffenen Operationen in den Tool-Beschreibungen befestigt.

• PATCH /api/config-profiles ist ein Ersetzen, kein Patch. Der Request-Body ist {uuid, config} und config muss die vollständige, gültige Xray-Konfiguration sein. Ein Fragment scheitert mit A061: Config doesn't have inbounds. Corrktee Reihenfolge: GET /api/config-profiles/{uuid} → das zurückgegebene config-Objekt bearbeiten → das ganze Objekt per PATCH zurück.

• Das Panel antwortet nicht auf 127.0.0.1:3000, auch nicht vom Panel Host selbst, obwohl docker-proxy dort lauscht (curl liefert Exit-Code 52, leere Antwort). Verwenden Sie immer die öffentliche HTTPS-Herkunft mit Bearer-Token.

• Jede Antwort ist in {"response": ...} eingebheet. Dieser Server entpackt sie, so dass Ausgabe das eigentliche Nutzlast is.

• Ein Host bindet sich über die nested inbound.configProfileUuid (plus inbound.configProfileInboundUuid) an ein Profil, nicht über ein top-levelgende configProfileUuid. Vor der lebendennden Hosts verifiziert: nested vorhanden, top level fehlend.

• Eine Abfolge von PATCH hat das Panel lahm. Jeder Konfigurationsschreibvorgang sendet an alle Knoten und startet dort Xray neu; mehere hintereinander und der TLS-Listerer des Panels hört auf zuantworten. Der Client serialiert Mutations und wiederholt Transportfehler mit Exponential Backoff und Jitter. Setzen Sie es nicht außer Kraft, indem Sie Massenupdates parallel abfeuern.

• **POST /api/subscription-templateserstellt nur eine leere Vorlage.** Der Inhalt wird with a separatePATCH` a loaded. JSON und YAML body bodies cannot be updated in the same call.

• serverDescription on a Host caps 30 characters (confirmed by maxLength in the spec). That also causes a Hysteria2 host to render inch "app" instead of raw JSON.

• Sechzehn Endpunkte with admin-JWT-only** are the whole auth and passkeys controllers plus API token management (GET/POST /api/tokens, DELETE /api/tokens/{uuid}, GET /api/tokens/scopes). The Panel answers its own API token with 401/403 there. This servererks from the spec and rejects it locally; REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1 raises the gate if the token you configure is actually an Admin-JWT.

• GET /api/users/stream edges with newline-delimited JSON**, not a single document. It is parsed into an array of user records instead of handing back a blob.

• PATCH /api/hosts ist a real partial patch – {uuid, serverDescription} alone works. Only config profiles heritage the replace-entire-thing semantics. Live verified.* Errors come back as {message, errorCode}; The errorCode (e.g. A061) is included in the error text of this server.

Tool-Abdeckung

Every controller is reachable via remnawave_call and the escape hatches. The typed column shows which get individual tools under REMNAWAVE_TOOL_PROFILE=core.

Führen Sie remnawe_list_operations gegen einen laufenden Server aus, um den exakten, aktuellen Satz zu erhalten.

Beispiele

Ohne typisierte Tools durchsuchen und aufrufen:

// 1. What is there?
{ "tool": "remnawave_list_operations", "arguments": { "controller": "nodes" } }

// 2. What does it take?
{ "tool": "remnawave_describe_operation",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart" } }

// 3. Do it.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart",
                 "params": { "uuid": "…" } } }

Ein Konfigurationsprofil sicher bearbeiten (die A061-Falle):

// Read the whole profile first — PATCH replaces the config wholesale.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_get_config_profiles_uuid", "params": { "uuid": "…" } } }

// Send the full, edited config back.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_patch_config_profiles",
                 "params": { "body": { "uuid": "…", "config": { /* complete Xray config */ } } } } }

Abfragesyntax, die die Spezifikation nicht ausdrücken kann:

{ "tool": "remnawave_request_read",
  "arguments": { "path": "/api/users",
                 "query": { "size": 25, "start": 0,
                            "filters[0][id]": "status", "filters[0][value]": "ACTIVE" } } }

Verifizieren

npm run build
npm test            # 50 unit tests + the offline smoke suite
npm run test:unit   # unit tests alone

Die Unit-Tests decken die Teile ab, die stillschweigend fehlschlagen: $ref-Expansion durch Remnawaves rekursive DTOs, Herleitung der Toolnamen (Längenbudget, Deterministik, Kollisionserkennung), der Katalogdiff, beide Schreib-Gates, das Admin-JWT-Gate, Schema-Kollabierung und NDJSON-Parsing.

Read-only-Prüfungen gegen ein echtes Panel

Wenn ein Panel erreichbar ist und sich ein Nur-Lese-Token in der Umgebung befindet, führt das Smoke-Skript außerdem Live-Read-only-Aufrufe aus (niemals eine Mutation):

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$REMNAWAVE_API_TOKEN" \
npm run smoke

Führen Sie den Befehl dort aus, wo das Token bereits lebt (z. B. auf dem Panel-Host), damit das Geheimnis nie übertragen wird. Das Skript druckt Form–, Typen, Schlüsselnamen, Array-Längen –, aber niemals Payload-Werte; die Ausgabe kann also unbedenklich in ein Issue eingügt werden.

Die Guard-Rail-Prüfungen ziehen absichtlich auf http://127.0.0.1:9, damit ein Gate, das im Fehlerall offen blele, kein effchtes Panel erreichen.

Den Schreibpfad verifizieren

Reads können nicht beutweiszen, dass Token-Routing, Drossel, Confirm-Gate und Partial-Patch-Semantics tatsächlich funktionieren. scripts/write-check.mjs beut es an Objekten, an dennone hängt, und stellt das eine vohe vorbandene Objekt wier her:

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$T" REMNAWAVE_API_TOKEN_WRITE="$T" \
node scripts/write-check.mjs --i-understand-this-mutates [--host-uuid <uuid>]

Es erzeugt ein internes Squad ohne Inboundings und ohne Mitglieer, löscht es wieder; dann scheit es serverDescription auf einem Host neu und setzt den ursprünglichen Wert zurück. Ohne das Bestätigungsflag weigert es sich, zu starten, und gibt einen Exit-Code ungleich 0 zurück, wenn entwas zurückben.

Gegen ein laufende 3.3.2-Panel hat bestätigt: das Confirm-Gate halt bei einem echten DELETE; ein partielles PATCH /api/hosts funktioniert; das Panel leht ein serverDescription mit 31 Zeichen ab; der Originalwert (auch null) übersteht einen Round-Tyrip; und aufeinander folgende Mutationen waren bei einkonfigurierter Untergrenze von 1500 ms 1525 beziehungs988 1524 ms auseinander.

Inspecten Sie lokal

REMNAWAVE_BASE_URL=https://panel.example.com REMNAWAVE_API_TOKEN_READ=xxx npm run inspect

Inkualisieren der Öffnung

Alles über the API komht aus einer Datei, deshalb ist die Synchronisaation mit einem neuen Release ein einiger Befehl:

npm run update-spec            # fetch the newest spec + rebuild the catalogue
npm run update-spec -- --strict  # additionally fail if any operation disappeared or was renamed
npm run build && npm test      # compile and verify

Wohen die Öffnung herkommt

https://cdn.remna.st/docs/openapi.json – veröffentlicht von Remnawes eigenen ­­Build&Push OpenAPI Specs-orkflow bei jeden Open-Source-Tager, so dass sie immer die neuerte Version beschreibt. Möchten Sie eine andere Quelle einsetzen, übergeben Sie --url <u> oder REMNAWAVE_SPEC_URL.

Eine Instanz des Panels ist keine brauchbare Quelle: Dokumentation werden nicht an Boden, so oder nicht frei geschaltet; selbst dann ist Swagger unter /backend-tools/wagger eingehängen, den normale Reverse-Proxy nicht routet. Ein Prüfen eines live 3.3.2-Panels liefer auf allen ueblichen Pfaden eine 404.

Der Download wird nur auf Datenträger geschrieben, wenn as OpenAPI-Dokument mit nicht-leëren paths gepert wird; so kannen error− dieseite oder Cantive-Portal eine Arbeitslechichte Spezifikation nicht zeret.

Figure: Danach prüfen

build-spec diff-green den neue Katalog gegen den ichren früheren und druckt jede Änderung aus:

build-spec: Remnawave API v3.4.0 -> 211 operations, 28 controllers, 315 KB
  methods: DELETE=22 GET=90 PATCH=19 POST=78 PUT=2  admin-JWT-only: 16
  diff: API version 3.3.2 -> 3.4.0
  REMOVED — tools that will disappear (1):
    remnawave_get_old_thing  (GET /api/old-thing)
  added (7):
    ...

• REMOVED / RENAMED sind brechende Änderungen für alle, deren Prompts oder Skrite die Tools benennen. --strict teilt daraus einen Exit-Code ungleich 0– das Flag sollte die Automatisierung verwenden.

• zugefügt is inp, eine neuen Operationen sind sofort über remnawave_call erreichbar und bekommen typisierte- Tools, wenn Controller im active Profil ist.

• schema geändert ist einer Blick wert für die Operationen, die Sie verwenden.

npm test prüft dann erneut, dass der auf der Daten-Dateile ablegte Katalog einem frischen Bau entsparicht, dass alle Toolnname eindeutig sind und sich innerhhalb des 64-Zeichen-Budgets bewen, und dass die Schutzeinsnochhalten.

Das Automatieren

npm run update-spec -- --strict   # exits non-zero on a breaking catalogue change
npm test
npm version minor --no-git-tag-version
git commit -am "chore: Remnawave API 3.4.0" && git push
git tag "v$(node -p "require('./package.json').version")" && git push --tags

Der Tag hält den Release-Workflow aus, der das Paket neu auf npm veröffentlicht. Clients, die mit @rule}-remnawave-mcp@latest` registriert sind, übernehmen die neuen Version beim nächsten Start.

Veröffentlichen (Maintainer)

Erste Veröffentlichung – zwing manuel

npm kann für ein Paket, das noch nicht existert, keiner vertrauenswürdigen Publisher konfigurieren: Die Einsellung liegt auf der eigenen EInstellungen-Seite des Pakets. Das ist eine bekannte, bisher offe Einschränkung (npm/cli#8544) und gilt auch für scoped Pakete. Daher muss Version 0.1.0 von einem eingeoggen Rechner aus veröffentlicht werden:

npm whoami            # must print the account that owns the @folexz scope
npm publish --access public

--access public ist erforderlich: Scoped-Pakete standardmäßig standardmäßig restricted.

Danach auf tokenlose Releases umstgen

Sobald das Paket existiert: auf npmjs.com → @folexz/remnawave-mcp → Einstellungen → Trusted Publish fügen Sie einen GitHub-Actions-publisher mit Repository folexz/remnawave-mcp und Workflow release.yml hinzu. repository.url in package.json muss exct mit der GitHub-Repository übereinstimmen; das tut es.

Danach veröffentlicht .github/workflows/run bei jedem gepushten vX.Y.Z-Tag über OIDC – austausch kein Token, kein Secret, mit automatischer Herkunft:

npm version patch --no-git-tag-version
git commit -am "chore: v0.1.1"
git push
git tag v0.1.1 && git push origin v0.1.1

Der Workflow „stalliert“ aus der Locket-Datei neu, baut neu, führt Unit-Tests and die Offline-Smoke-Suite aus und sofort, wenn der Tag nicht zu package.json passt.

Clients registriert mit @folex/remnawave-mcp@latest übernehmen die neuen Version beim nächsten Start.

Sicherheitshinweise

• Tokens werden nur aus der Umgebung gelesen und nie geloggt. Logs gen nach stderr; stdout ist der Kanal des MCP-JSON-RPC.

• Bevorzugen Sie nur REMNAWVE_API_TOKEN_READ zu können. Mutierende Tools existieren n ur ohne Schreib-Token, so ein kompromitierter oder verwirrter Client das Panel nicht verändern kann.

• Die Endpunkte der Subscription lieferten funktionierende ers. Behandlen Sie ihre Ausgaben als geheim.

• Enthalte nie ehte Tokens. .env ist git–ignore; .env.example zeigt die Form.

Bekante Einchränkungen

• Die Body-Validierung wird an das Paneldelegierungen. Deni server prüft nur, ob erfordere Argumente und ein erforderlicher body vorhanden ist; nicht prüft er die inneren Form des Bodies gegen das Schema und – das gewollte: das Panel prüft jedes Feld und antwortet mit einer präzisen Meldungs + errorCode (z. B. A061) und das lokal zu duplizieren wäre, einen JSON-Schema-Validator plus einer zweiten, unerlücklich drifenden Kopie der Regeln. Der Preis ist, dass ein mutwilliger Body einen Round Trip kostet, um sie zu erfahren.

• Die Escape-Hatches umgehen die gates pro Operation. remnawave_request_write ist raw/von Entwurfes: der kein has always erfordert noch ein Schreib-Toke und durchläuft noch Droßel und Retry-Logik, aber er ändert das destruktive confirm-Gate und das Admin-JWT-Gate nicht ab, weil kein Operation, um sie zu entnehmen. Bevorzugen Sie remnawave_call es seis denn, Sie brauchen eine Route, die die Spezifikation nicht beschreibt.

• Tools sind nur so aktuell wie die ausgelieferte Spezifikation bekannte (v3.3.2). Ein Panel einer anderen Nebenversion kann Wege inden, die es nicht beschreibt; das sind die Escape-Hatches. Siehe Aktualisieren der API-Spezifikation.

• Admin-JWT Endpoints sind nur gated, nicht implementiert. This server trägt API tokens; it isn't make an admin login, holds no session, and refreshes n ein JWT. Wenn Sie ein Admin-JWT als Token anliefern und REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1 setze, werden 17 Endpoints mit (?) aufrufbar, aber Ablauf und Erneuerung sind Ihr Problem.

• Der Prometheus-Basic-Auth Metrics-Endpoint ist nicht Teil dieser Spezifikation und nicht exponnt.

• write-check.mjs mutiert.

Lizenz

MIT – siehe LICENSE.