jsmcp

jsmcpは、エージェントが単一のMCPツール呼び出し以上のことを行う必要がある場合のために存在します。

ほとんどのMCPクライアントは一度に1つのツール呼び出しを行うのには適していますが、以下のような作業が必要な場合には不向きです：

• 関連する複数のツール呼び出し

• 前の結果に基づいた分岐ロジック

• ループ、リトライ、または結果の集約

• 次の呼び出し前のツール出力の変換

jsmcpは、承認されたMCPツールをJavaScriptの名前空間として公開することでこれを解決します。モデルに多くの個別のツール呼び出しを強制する代わりに、何が利用可能かを発見し、それらのツールをプログラム的に使用するための少量のJavaScriptを書くことができます。

実際には、これは以下を意味します：

• エージェントはまずどのサーバーとツールが利用可能かを学習します。その際、jsmcpはプリセットで許可したサーバーとツールのみにアクセスを制限します。

• エージェントは、複数ステップの作業のためのJavaScriptを書くことができます。

• ログは戻り値とは別に保持されるため、コードの推論が容易になります。

設定は$XDG_CONFIG_HOME/jsmcp/から読み込まれます。XDG_CONFIG_HOMEが設定されていない場合は~/.config/jsmcp/から読み込まれます。そのディレクトリにはconfig.json、config.yaml、またはconfig.ymlのいずれか1つだけが存在する必要があります。

なぜ使うのか

エージェントにMCPツールを、孤立したボタン押下の連続としてではなく、小さなプログラム可能なAPIサーフェスとして扱わせたい場合にjsmcpを使用してください。

これは、エージェントが以下を行う必要がある場合に特に便利です：

• 複数のMCPツールの結果を組み合わせる

• 1つ以上のMCPサーバーにまたがるワークフローをスクリプト化する

• ツール呼び出しのたびに再計画を繰り返すのではなく、コード内で意思決定を行う

• ツールへのアクセスをレビュー済みのプリセットに制限し続ける

Related MCP server: MCPMan

インストール

npm install -g @alesya_h/jsmcp

または、グローバルにインストールせずに実行します：

npx @alesya_h/jsmcp run

実行

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

インストールされたパッケージではなくソースチェックアウトから実行している場合は、jsmcpをnode src/index.jsに置き換えてください（例: node src/index.js run）。

runは、stdio経由でメタMCPサーバーを直接起動します。

serverは、ws://<bind>:<port>/mcpで長時間稼働するデーモンを起動し、選択したプリセットを一度読み込んで、基盤となるMCPサーバー接続を維持します。デフォルトでは0.0.0.0にバインドされ、--bind <host>で別のバインドアドレスを選択できます。

clientは、生のMCP/JSON-RPCメッセージをWebSocket経由でserverにプロキシするstdio MCPサーバーを公開します。--host <host>と--port <number>で接続先のデーモンを選択でき、オプションで--profile <name>を渡してデーモンが期待されるプリセットを実行していることを要求したり、--session-id <id>を受け入れてクライアントの再接続間で同じデーモン側のログセッションを再利用したりできます。

run、server、clientはすべて、位置引数または--profile <name>としてオプションのプリセットを受け入れます。デフォルトのデーモンポートは41528です。client --session-idが省略された場合、クライアントはランダムなセッションIDを生成し、そのクライアントプロセス中の再接続でそれを再利用します。

最初のserver起動時に、jsmcpは$XDG_CONFIG_HOME/jsmcp/api-key.txt（XDG_CONFIG_HOMEが設定されていない場合は~/.config/jsmcp/api-key.txt）にAPIキーを作成します。デーモンのWebSocketおよびHTTP APIリクエストには、X-JSMCP-API-Keyヘッダーにこれを含める必要があります。認証されていないリクエストは401を受け取ります。

デーモンはまた、1つのJSON HTTPエンドポイントを通じて5つのメタツールを公開します：

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>

リクエストボディは、選択されたMCPツールの引数と一致するJSONオブジェクトです。HTTP呼び出し元は、クエリ文字列にsessionIdを含めて、安定したデーモン側のログセッションを使用できます。また、profileを含めて、デーモンが期待されるプリセットを実行していることを要求することもできます（不一致の場合は409が返されます）。

リモートサーバーのOAuthを管理するにはjsmcp authを使用します。引数なしの場合は、OAuthが有効なリモートサーバーを一覧表示します。サーバー名を指定すると、そのサーバーのOAuthフローを開始します。

グラフィカル環境が検出されない場合、または--no-browserを渡した場合、jsmcp auth <server>は認証URLを表示し、ローカルホストのコールバックまたは貼り付けられたコールバックURL/コードを待ちます。

systemdユーザーサービス

このリポジトリには、グローバルにインストールされたCLIからjsmcp serverを起動するユーザーユニットsystemd/jsmcp.serviceが含まれています。

インストール方法：

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

便利なコマンド：

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

チェックインされたユニットは、デフォルトのデーモンポートでデフォルトのプリセットを起動し、getent passwdからユーザーの実際のログインシェルを通じてjsmcpを解決します。

設定

設定ファイルはJSONまたはYAMLで、以下のトップレベルキーを使用します：

• servers: サーバー定義

• presets: エージェントに公開されるサーバーとツールに関するオプションのオーバーライド

execute_code()がそれらを直接グローバルとして公開するため、サーバー名は有効なJavaScript識別子である必要があります。

jsmcpは、共通フィールドに対してOpenCode MCP設定スタイルと、重複するClaude Code MCPスタイルの両方を受け入れます：

• ローカルサーバー: type: "local" または type: "stdio"

• リモートサーバー: type: "remote"、type: "http"、または type: "sse"

• コマンド: command: ["cmd", "arg1"] または command: "cmd" と args: ["arg1"]

• 環境変数: environment または env

サポートされているservers.<name>フィールド：

• type: 必須。local、stdio、remote、http、sseのいずれか

• description: list_servers()で表示されるオプションの文字列

• enabled: オプションのブール値。デフォルトはtrue

• timeout: 初回ツール検出に使用されるミリ秒単位のオプションの数値

ローカル/stdioサーバーの場合：

• command: 必須。空でない文字列または空でない配列

• args: オプションの配列。commandが文字列の場合にcommandに追加され、commandが配列の場合にも受け入れられます

• env: 環境変数のオプションのオブジェクト

• environment: 環境変数のオプションのオブジェクト。envとマージされ、重複するキーがある場合はこちらが優先されます

• cwd: オプションの作業ディレクトリ

リモート/HTTP/SSEサーバーの場合：

• url: 必須の文字列

• headers: リクエストヘッダーのオプションのオブジェクト

• oauth: オプションのOAuth設定

サポートされているoauth形式：

• 省略、null、またはtrue: デフォルトの動作でOAuthを有効にする

• false: そのサーバーのOAuthを無効にする

• 以下を含むオブジェクト：

  • clientId

  • clientSecret

  • scope

文字列フィールドでサポートされている値の置換：

• {env:NAME}: 現在の環境から展開

• ${NAME}: Claude Codeスタイルの環境展開

• ${NAME:-default}: フォールバック付きのClaude Codeスタイルの展開

• {file:path}: ファイルの内容で置換

{file:path}の場合：

• 相対パスは設定ファイルのディレクトリを基準に解決されます

• ~/...はユーザーのホームディレクトリから解決されます

• 絶対パスはそのまま使用されます

presetsが省略された場合、デフォルトのプリセットにはenabled !== falseであるすべてのサーバーが含まれ、そのサーバーのすべてのツールが許可されます。

presetsが存在する場合、それはプリセット名のオブジェクトです。各プリセットは、サーバー定義の上に重ねられるサーバーごとのオーバーライドのオブジェクトです：

• presets.default: デフォルトプリセットのオプションのオーバーライド

• その他のプリセット名（例: presets.work）: 追加の名前付きプリセットオーバーライド

プリセット内では、サーバーのルールは以下のように機能します：

• サーバールールが省略された場合: サーバー定義をそのまま使用

• true: そのサーバーを含め、すべてのツールを許可

• false: そのプリセットからそのサーバーを除外

• "tool_name": その正確なツールのみを含める

• 配列エントリは以下が可能：

  • 正確なツール名の文字列

  • { "regex": "..." } セレクター

  • { "glob": "..." } セレクター

サーバーがservers内でenabled: falseになっている場合、それをプリセットに追加するとそのプリセットに対して有効になります。

例：

{
  "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
    }
  }
}

互換性に関する注意：

• Claude Codeスタイルのenv、type: "stdio"、type: "http"、type: "sse"、およびcommandとargsがサポートされています

• OpenCodeスタイルのtype: "local"、type: "remote"、コマンド配列、およびenvironmentもサポートされています

• headersHelperや、callbackPortやauthServerMetadataUrlのような高度なOAuthフィールドなど、Claude Code固有の機能はまだサポートされていません

OAuthトークンと登録状態は$XDG_DATA_HOME/jsmcp/oauth.jsonまたは~/.local/share/jsmcp/oauth.jsonに保存されます。

公開ツール

• list_servers

• list_tools

• execute_code

• fetch_logs

• clear_logs

動作

• デフォルトプリセット内のサーバーはjsmcpの起動時に開始されます

• エージェントが利用可能な機能を学習できるように、list_servers()が必須の最初のステップとなります

• execute_code()でサーバーを使用する前に、正確なツール名、エイリアス、スキーマを知るためにlist_tools(server)を呼び出す必要があります

• list_tools(server)は、プリセットでそのサーバーに対して許可されたツールのみを返します

• execute_code({ code, data?, timeoutMs? })はサーバーのライフサイクルを管理しません。すでに開始されているサーバーのみを使用できます

• 作業が単一のツール呼び出し以上を必要とする場合は、execute_code({ code, ... })を優先してください

• execute_code()内のconsole.log、console.info、console.warn、console.errorはfetch_logs()のために保存されます

• fetch_logs()は読み取り時にログバッファを空にします

execute_code

execute_codeは、非同期関数の本体としてJavaScriptを実行します。

開始されたサーバーはグローバルとして注入されます。許可された各MCPツールは、そのサーバーオブジェクト上の関数になります。可能な場合はアンダースコアのエイリアスを優先してください。

dataを渡すと、それはグローバル変数dataとしてスクリプトに公開されます。これは、コード文字列内でエスケープが必要になる文字列や構造化された値に便利です。

execute_code()でサーバーを使用する前にlist_tools(server)を呼び出す必要があります。複数ステップの作業では、複数のツール呼び出しを頭の中でつなげようとするのではなく、JavaScriptを書くことを優先してください。

例：

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

データを使用する場合：

return data.message;

MCPツールがstructuredContentを返す場合、それがJavaScript呼び出しの解決結果となります。したがって、上記の例は以下を返すことができます：

{
  "sum": 7
}

ツール名が有効なJavaScript識別子ではない場合は、アンダースコアのエイリアスを優先してください：

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

元のツール名もブラケットアクセスで機能します：

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