jsmcp

jsmcp existiert für Fälle, in denen ein Agent mehr als einen einzelnen MCP-Tool-Aufruf tätigen muss.

Die meisten MCP-Clients sind großartig für einen Tool-Aufruf nach dem anderen, aber umständlich, wenn die Arbeit Folgendes erfordert:

• mehrere zusammenhängende Tool-Aufrufe

• Verzweigungslogik basierend auf früheren Ergebnissen

• Schleifen, Wiederholungsversuche oder Ergebnisaggregation

• Transformation von Tool-Ausgaben vor dem nächsten Aufruf

jsmcp löst dies, indem es zugelassene MCP-Tools als JavaScript-Namespaces bereitstellt. Anstatt das Modell zu zwingen, viele separate Tool-Aufrufe zu jonglieren, kann es entdecken, was verfügbar ist, und dann eine kleine Menge JavaScript schreiben, um diese Tools programmatisch zu nutzen.

In der Praxis bedeutet das:

• der Agent lernt zuerst, welche Server und Tools verfügbar sind, während jsmcp den Zugriff auf die Server und Tools beschränkt, die Sie in einem Preset erlauben

• der Agent kann dann JavaScript für mehrstufige Arbeit schreiben

• Protokolle bleiben von Rückgabewerten getrennt, sodass der Code leichter nachvollziehbar bleibt

Die Konfiguration wird aus $XDG_CONFIG_HOME/jsmcp/ gelesen oder, falls XDG_CONFIG_HOME nicht gesetzt ist, aus ~/.config/jsmcp/. Genau eine der Dateien config.json, config.yaml oder config.yml muss dort existieren.

Warum

Verwenden Sie jsmcp, wenn Sie möchten, dass Agenten MCP-Tools eher wie eine kleine programmierbare API-Oberfläche behandeln als wie eine Abfolge isolierter Tastendrücke.

Dies ist besonders nützlich, wenn ein Agent:

• Ergebnisse von mehreren MCP-Tools kombinieren muss

• Arbeitsabläufe über einen oder mehrere MCP-Server hinweg skripten muss

• Entscheidungen im Code treffen muss, anstatt wiederholt zwischen Tool-Aufrufen neu zu planen

• den Tool-Zugriff auf ein geprüftes Preset beschränkt halten muss

Related MCP server: MCPMan

Installation

npm install -g @alesya_h/jsmcp

Oder führen Sie es aus, ohne es global zu installieren:

npx @alesya_h/jsmcp run

Ausführen

jsmcp run
jsmcp run work
jsmcp server work --port 3000 --bind 0.0.0.0
jsmcp client --profile work --host 127.0.0.1 --port 3000
jsmcp client --profile work --port 3000 --session-id my-agent-session
jsmcp auth
jsmcp auth firefox_devtools

Wenn Sie aus einem Quell-Checkout statt aus einem installierten Paket ausführen, ersetzen Sie jsmcp durch node src/index.js, zum Beispiel node src/index.js run.

run startet den Meta-MCP-Server direkt über stdio.

server startet einen langlebigen Daemon unter ws://<bind>:<port>/mcp, lädt das gewählte Preset einmal und hält die zugrunde liegenden MCP-Server-Verbindungen warm. Er bindet standardmäßig an 0.0.0.0 und akzeptiert --bind <host>, um eine andere Bind-Adresse zu wählen.

client stellt einen stdio-MCP-Server bereit, der rohe MCP/JSON-RPC-Nachrichten über WebSocket an server weiterleitet. Er akzeptiert --host <host> und --port <number>, um den Daemon zu wählen, mit dem eine Verbindung hergestellt werden soll, kann optional --profile <name> übergeben, um zu verlangen, dass der Daemon das erwartete Preset ausführt, und akzeptiert --session-id <id>, um dieselbe daemon-seitige Protokollsitzung über Client-Wiederverbindungen hinweg wiederzuverwenden.

run, server und client akzeptieren alle ein optionales Preset entweder als positionelles Argument oder als --profile <name>. Der Standard-Daemon-Port ist 41528. Wenn client --session-id weggelassen wird, generiert der Client eine zufällige Sitzungs-ID und verwendet sie für Wiederverbindungen während dieses Client-Prozesses wieder.

Beim ersten Start von server erstellt jsmcp einen API-Schlüssel unter $XDG_CONFIG_HOME/jsmcp/api-key.txt oder ~/.config/jsmcp/api-key.txt, falls XDG_CONFIG_HOME nicht gesetzt ist. Daemon-WebSocket- und HTTP-API-Anfragen müssen diesen im Header X-JSMCP-API-Key enthalten; nicht authentifizierte Anfragen erhalten 401.

Der Daemon stellt außerdem die fünf Meta-Tools über einen JSON-HTTP-Endpunkt bereit:

POST /api/call?tool=list_servers&profile=<name>
POST /api/call?tool=list_tools&profile=<name>
POST /api/call?tool=execute_code&sessionId=<id>&profile=<name>
POST /api/call?tool=fetch_logs&sessionId=<id>
POST /api/call?tool=clear_logs&sessionId=<id>

Der Anfragetext ist ein JSON-Objekt, das den ausgewählten MCP-Tool-Argumenten entspricht. HTTP-Aufrufer können sessionId in die Abfragezeichenfolge aufnehmen, um eine stabile daemon-seitige Protokollsitzung zu verwenden. Sie können profile aufnehmen, um zu verlangen, dass der Daemon das erwartete Preset ausführt; bei Nichtübereinstimmung wird 409 zurückgegeben.

Verwenden Sie jsmcp auth, um OAuth für Remote-Server zu verwalten. Ohne Argumente werden Remote-Server aufgelistet, für die OAuth aktiviert ist. Mit einem Servernamen wird der OAuth-Ablauf für diesen Server gestartet.

Wenn keine grafische Umgebung erkannt wird oder wenn Sie --no-browser übergeben, druckt jsmcp auth <server> die Autorisierungs-URL und wartet entweder auf den Localhost-Callback oder eine eingefügte Callback-URL/einen Code.

systemd Benutzerdienst

Dieses Repo enthält systemd/jsmcp.service, eine Benutzereinheit, die jsmcp server über die global installierte CLI startet.

Installieren Sie sie mit:

npm install -g .
mkdir -p ~/.config/systemd/user
ln -sfn "$PWD/systemd/jsmcp.service" ~/.config/systemd/user/jsmcp.service
systemctl --user daemon-reload
systemctl --user enable --now jsmcp.service

Nützliche Befehle:

systemctl --user status jsmcp.service
journalctl --user -u jsmcp.service -f
systemctl --user restart jsmcp.service

Die eingecheckte Einheit startet das Standard-Preset auf dem Standard-Daemon-Port und löst jsmcp über die tatsächliche Login-Shell des Benutzers aus getent passwd auf.

Konfiguration

Die Konfigurationsdatei kann JSON oder YAML sein und verwendet diese Schlüssel auf oberster Ebene:

• servers: Serverdefinitionen

• presets: optionale Überschreibungen dafür, welche Server und Tools dem Agenten ausgesetzt sind

Servernamen müssen gültige JavaScript-Bezeichner sein, da execute_code() sie direkt als Globals bereitstellt.

jsmcp akzeptiert sowohl den OpenCode-MCP-Konfigurationsstil als auch den überlappenden Claude-Code-MCP-Stil für die gemeinsamen Felder:

• lokale Server: type: "local" oder type: "stdio"

• Remote-Server: type: "remote", type: "http" oder type: "sse"

• Befehle: entweder command: ["cmd", "arg1"] oder command: "cmd" mit args: ["arg1"]

• Umgebungsvariablen: entweder environment oder env

Unterstützte servers.<name>-Felder:

• type: erforderlich; einer der Werte local, stdio, remote, http, sse

• description: optionale Zeichenfolge, die in list_servers() angezeigt wird

• enabled: optionaler boolescher Wert; standardmäßig true

• timeout: optionale Zahl in Millisekunden, die für die anfängliche Tool-Erkennung verwendet wird

Für lokale / stdio-Server:

• command: erforderlich; nicht leere Zeichenfolge oder nicht leeres Array

• args: optionales Array; wird an command angehängt, wenn command eine Zeichenfolge ist, und auch akzeptiert, wenn command ein Array ist

• env: optionales Objekt mit Umgebungsvariablen

• environment: optionales Objekt mit Umgebungsvariablen; wird mit env zusammengeführt und gewinnt bei doppelten Schlüsseln

• cwd: optionales Arbeitsverzeichnis

Für Remote- / HTTP- / SSE-Server:

• url: erforderliche Zeichenfolge

• headers: optionales Objekt mit Anfrage-Headern

• oauth: optionale OAuth-Konfiguration

Unterstützte oauth-Formen:

• weggelassen, null oder true: OAuth mit Standardverhalten aktivieren

• false: OAuth für diesen Server deaktivieren

• Objekt mit einem der folgenden Felder:

  • clientId

  • clientSecret

  • scope

Unterstützte Wertesubstitutionen in Zeichenfolgenfeldern:

• {env:NAME}: aus der aktuellen Umgebung erweitern

• ${NAME}: Umgebungserweiterung im Claude-Code-Stil

• ${NAME:-default}: Erweiterung im Claude-Code-Stil mit Fallback

• {file:path}: durch Dateiinhalt ersetzen

Für {file:path}:

• relative Pfade werden relativ zum Verzeichnis der Konfigurationsdatei aufgelöst

• ~/... wird vom Benutzer-Home-Verzeichnis aus aufgelöst

• absolute Pfade werden unverändert verwendet

Wenn presets weggelassen wird, enthält das Standard-Preset jeden Server mit enabled !== false und erlaubt alle Tools dieses Servers.

Wenn presets vorhanden ist, handelt es sich um ein Objekt von Preset-Namen. Jedes Preset ist ein Objekt von pro-Server-Überschreibungen, die über die Serverdefinitionen gelegt werden:

• presets.default: optionale Überschreibungen für das Standard-Preset

• jeder andere Preset-Name, wie presets.work: zusätzliche benannte Preset-Überschreibungen

Innerhalb eines Presets funktionieren Serverregeln wie folgt:

• weggelassene Serverregel: die Serverdefinition unverändert verwenden

• true: diesen Server einbeziehen und alle seine Tools erlauben

• false: diesen Server aus diesem Preset ausschließen

• "tool_name": nur dieses exakte Tool einbeziehen

• Array-Einträge können sein:

  • exakte Tool-Namenszeichenfolgen

  • { "regex": "..." } Selektoren

  • { "glob": "..." } Selektoren

Wenn ein Server enabled: false in servers hat, aktiviert das Hinzufügen zu einem Preset ihn für dieses Preset.

Beispiel:

{
 "servers": {
 "math": {
 "type": "stdio",
 "description": "Basic arithmetic tools",
 "command": "node",
 "args": ["/absolute/path/to/math-server.js"],
 "env": {
 "LOG_LEVEL": "debug"
 },
 "cwd": "${PWD}"
 },
 "docs": {
 "type": "http",
 "description": "Documentation search and retrieval",
 "url": "https://example.com/mcp",
 "headers": {
 "Authorization": "Bearer ${DOCS_TOKEN}"
 },
 "oauth": {
 "scope": "docs.read"
 }
 }
 },
 "presets": {
 "default": {
 "math": ["add", { "glob": "mul_*" }],
 "docs": [{ "regex": "(search|fetch)" }]
 },
 "work": {
 "docs": true
 }
 }
}

Kompatibilitätshinweise:

• Claude-Code-Stil env, type: "stdio", type: "http", type: "sse" und command plus args werden unterstützt

• OpenCode-Stil type: "local", type: "remote", Befehls-Arrays und environment werden ebenfalls unterstützt

• Claude-Code-spezifische Funktionen wie headersHelper und fortgeschrittene OAuth-Felder wie callbackPort oder authServerMetadataUrl werden noch nicht unterstützt

OAuth-Token und Registrierungsstatus werden unter $XDG_DATA_HOME/jsmcp/oauth.json oder ~/.local/share/jsmcp/oauth.json gespeichert.

Bereitgestellte Tools

• list_servers

• list_tools

• execute_code

• fetch_logs

• clear_logs

Verhalten

• Server im Standard-Preset werden gestartet, wenn jsmcp startet

• list_servers() ist der erforderliche erste Schritt, damit der Agent lernen kann, welche Fähigkeiten verfügbar sind

• Sie müssen list_tools(server) aufrufen, bevor Sie einen Server in execute_code() verwenden, damit Sie die exakten Tool-Namen, Aliase und Schemas kennen

• list_tools(server) gibt nur die Tools zurück, die für diesen Server im Preset erlaubt sind

• execute_code({ code, data?, timeoutMs? }) verwaltet nicht den Server-Lebenszyklus; es kann nur Server verwenden, die bereits gestartet sind

• bevorzugen Sie execute_code({ code, ... }), wann immer die Arbeit mehr als einen einzelnen Tool-Aufruf erfordern würde

• console.log, console.info, console.warn und console.error innerhalb von execute_code() werden für fetch_logs() gespeichert

• fetch_logs() leert den Protokollpuffer beim Lesen

execute_code

execute_code führt JavaScript als Körper einer asynchronen Funktion aus.

Gestartete Server werden als Globals injiziert. Jedes erlaubte MCP-Tool wird zu einer Funktion auf diesem Server-Objekt. Bevorzugen Sie Unterstrich-Aliase, wenn verfügbar.

Wenn Sie data übergeben, wird es dem Skript als globale Variable data bereitgestellt. Dies ist nützlich für Zeichenfolgen oder strukturierte Werte, die sonst innerhalb der Code-Zeichenfolge maskiert werden müssten.

Sie sollten list_tools(server) aufrufen, bevor Sie einen Server in execute_code() verwenden. Bevorzugen Sie für mehrstufige Arbeit das Schreiben von JavaScript, anstatt zu versuchen, mental mehrere Tool-Aufrufe zu verketten.

Beispiel:

return await math.add({ a: 2, b: 5 });

Mit Daten:

return data.message;

Wenn das MCP-Tool structuredContent zurückgibt, ist dies das, worauf der JavaScript-Aufruf aufgelöst wird. Das obige Beispiel kann also Folgendes zurückgeben:

{
 "sum": 7
}

Wenn ein Tool-Name kein gültiger JavaScript-Bezeichner ist, bevorzugen Sie seinen Unterstrich-Alias:

return await math.tool_name({ value: 1 });

Der ursprüngliche Tool-Name funktioniert weiterhin mit Klammerzugriff:

return await math["tool-name"]({ value: 1 });

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers