jev-decision-mcp

Jev Decision MCP

任意の SDK 互換の意思決定 API エンドポイントを通じて型付きの判断を行う、単一のツール jev_decide を公開するローカル stdio MCP サーバーです。BASE_URL と MODEL を使ってエンドポイントを指定してください。プロバイダーのプリセット、ホストの許可リスト、モデルの許可リストはありません。公式 MCP SDK と、型付き判断 SDK の @typesafe-ai/sdk を使用して TypeScript で記述されています。

独立したコミュニティプロジェクトであり、SDK ベンダーとは提携していません。MIT ライセンスで提供されています。

質問	用途	結果
choice	ラベルまたは候補を選択する	選択、確率、信頼度
score	2～10 段階の順序尺度で単一の次元を評価する	0 始まりのスコア、確率、凡例、信頼度
noul	条件が成り立つかどうかを判定する	0～1 の「はい」の確率

同じコンテキストに関する独立した質問を、1 回の呼び出しでまとめて処理できます。回答には質問 ID が保持されます。MCP は判断とトークン使用量を返します。しきい値の設定、エスカレーション、アクションの実行は呼び出し側が担当します。

要件

• Node.js 22 以降。PATH から npm を利用できること。
• ローカル stdio サーバーに対応する MCP クライアント。
• 設定した判断エンドポイント用の API キー（API_KEY）。API キーは判断の呼び出しにのみ必要です。キーがなくてもツールを検出できます。

ここでいう「SDK 互換」の意味。 @typesafe-ai/sdk の型付き判断コントラクトに準拠していることを指します。エンドポイントは、確率分布と使用量を返す型付きの choice／score／noul 回答を含む SystemOne リクエスト（POST {BASE_URL}/v1/systemone）を実装している必要があります。

npm からインストール

npm パッケージには、ビルド済みのサーバーが含まれています。npx は初回の使用時にパッケージをダウンロードし、クローンやビルドを行わずに実行します。

npx -y [email protected]

エンドポイントの値に合わせてプレースホルダーを置き換え、以下の設定を MCP クライアントに追加してください。mcpServers JSON を使用するクライアントの場合：

{
  "mcpServers": {
    "jev": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "YOUR_API_KEY",
        "BASE_URL": "https://api.example.com/decisions",
        "MODEL": "your-model-name"
      }
    }
  }
}

または、クライアントを起動する環境で API_KEY、BASE_URL、MODEL を設定し、クライアントがそれらの変数を引き継ぐ場合は env を省略してください。設定を保存した後、クライアントの MCP サーバーを再起動または再読み込みしてください。ツールは jev_decide として表示されます。

ホストが npx を解決できない場合は、そのホストのドキュメントに記載されているプラットフォーム固有のランチャーまたは絶対パスを使用してください。GUI アプリケーションでは、ターミナルとは異なる PATH が設定されている場合があります。

サーバーは stdio で通信します。ターミナルで起動すると、Web ページを開くのではなく、MCP クライアントからの接続を待機します。npm からのインストールでは、呼び出し元の作業ディレクトリにある .env は読み込まれません。

実行ファイルをグローバルにインストールする場合：

npm install -g [email protected]

その後、MCP クライアントで引数なしの "command": "jev-decision-mcp" を使用し、同じ API_KEY、BASE_URL、MODEL の値を指定してください。

Glama 経由でインストール

Jev Decision MCP の Glama ページを開くと、README、ツールスキーマ、ソースを確認できます。ローカルにインストールするには、上記の npm 設定を使用するか、掲載ページの GitHub Repository リンクに従ってソースをダウンロードまたはクローンし、以下の手順でビルドしてください。Glama ではローカル stdio サーバーとして掲載されています。掲載ページの URL は MCP 接続エンドポイントではありません。

エンドポイントの設定

BASE_URL と MODEL は起動時に必須で、プロセスの実行中は固定されます。ツール呼び出しで上書きできるのはモデル名のみです。実行時にプリセットを選択する機能はありません。サーバーは呼び出しごとにエンドポイントや認証情報を切り替えず、URL 検証以外のホストまたはモデルの許可リストも適用しません。BASE_URL はプレフィックスです。SDK が末尾に /v1/systemone を追加するため、カスタムパスプレフィックスを含む HTTP(S) URL に対応しています。

エンドポイントの参考例（例示のみで、特定のプロバイダーを示唆または推奨するものではありません）。 SDK 互換であることが確認されているエンドポイントです。独自の API_KEY とともに BASE_URL／MODEL に設定して使用できます。

例	BASE_URL	MODEL
TypeSafe	https://api.typesafe.ai	jev-latest
Liquid	https://api.liquid.ai/decisions	d1-ultra

エンドポイントを比較するための 2 つのインスタンス。 エンドポイントごとにインスタンスを 1 つ設定し、それぞれのインスタンスの jev_decide に同じリクエストを送信してください。

{
  "mcpServers": {
    "jev-a": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "YOUR_FIRST_API_KEY",
        "BASE_URL": "https://api.typesafe.ai",
        "MODEL": "jev-latest"
      }
    },
    "jev-b": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "YOUR_SECOND_API_KEY",
        "BASE_URL": "https://api.liquid.ai/decisions",
        "MODEL": "d1-ultra"
      }
    }
  }
}

各インスタンスはそれぞれの固定エンドポイントを使用するため、比較では常に呼び出しごとにエンドポイントが 1 つだけ使用されます。

Codex に接続する

npm パッケージを使用する場合は、次の設定を Codex の config.toml に統合してください。

[mcp_servers.jev]
command = "npx"
args = ["-y", "[email protected]"]
env_vars = ["API_KEY", "BASE_URL", "MODEL"]
tool_timeout_sec = 45

Codex の起動時に使われる環境で API_KEY、BASE_URL、MODEL を設定してください。env_vars は、それらの既存の値をサーバーに渡します。ホスト側のツールタイムアウトは JEV_TIMEOUT_MS / 1000 より大きく設定してください。Codex の公式 MCP 設定を参照してください。

ソースからビルドする

リポジトリをクローンし、依存関係をインストールして、サーバーをコンパイルします。

git clone https://github.com/amidabuddha/jev-decision-mcp.git
cd jev-decision-mcp
npm ci
npm run build

GitHub の Code → Download ZIP からリポジトリをダウンロードし、展開したディレクトリで npm ci と npm run build を実行することもできます。

そのディレクトリ内で .env.example を .env にコピーし、API_KEY、BASE_URL、MODEL を設定するか、MCP クライアントの環境から設定してください。ソースビルドでは、作業ディレクトリに関係なくこの .env が読み込まれます。既存の環境変数が優先されます。変更後はサーバーを再起動してください。.env は Git の対象外です。

ビルドしたエントリーポイントを実行するよう、MCP クライアントを設定してください。

{
  "mcpServers": {
    "jev": {
      "command": "node",
      "args": ["/absolute/path/to/jev-decision-mcp/dist/index.js"]
    }
  }
}

プレースホルダーは、チェックアウト先の絶対パスに置き換えてください。Windows のパスにはスラッシュを使用できます。例：C:/projects/jev-decision-mcp/dist/index.js。node がクライアントの PATH にない場合は、Node 実行ファイルの絶対パスを指定してください。

Codex の場合は、上記の TOML の例と同じ command と args を使用してください。.env ではなく Codex の環境を通じて設定を渡す場合に限り、env_vars を残してください。

ビルドを確認するには、npm run check を実行します（型チェックと、API レスポンスをモックしたテストを実行します。ネットワーク呼び出しはありません）。ローカル開発には npm run dev を使用してください。ソースを変更した後、MCP クライアントを再起動する前に npm run build で再ビルドしてください。

設定

これらの変数は、MCP クライアントのサーバー環境、またはソースビルドの場合は .env に設定します。読み取られるのは次の 4 つだけです。

変数	デフォルト	用途
API_KEY	なし	設定済みエンドポイントのベアラー認証情報です。判断の呼び出しには必須ですが、ツールの検出時は起動時に省略できます
BASE_URL	なし	絶対 http(s) API ルートのプレフィックスです（SDK が /v1/systemone を追加します）。起動時に必須です
MODEL	なし	判断の呼び出しに使用するデフォルトのモデル名です。起動時に必須です
JEV_TIMEOUT_MS	30000	SDK の再試行を含む、呼び出しごとの合計タイムアウトです。1～120000 ms の範囲で指定します

必須と任意。 BASE_URL と MODEL は起動時に明示的に設定する必要があります。設定されていない場合、サーバーは設定エラーで終了し、SDK やベンダーのデフォルト値にはフォールバックしません。API_KEY は起動時に任意のため、クライアントはキーなしで jev_decide を検出できます。キーなしで判断を呼び出すと、MISSING_API_KEY が返されます。空白文字のみの値は未設定として扱われます。

モデルの優先順位（高い順）：呼び出しごとの model 引数、次に MODEL です。呼び出しごとの model が空、または空白文字のみの場合は INVALID_INPUT で拒否され、空の値や非表示のデフォルト値にフォールバックすることはありません。呼び出しごとのモデル指定で変更されるのはリクエストのモデル名だけです。認証情報と送信先は固定されています。

エンドポイントはツールではなく、オペレーターが固定します。 プロセスはすべてのリクエストを設定済みの BASE_URL に送信します。ツールの入力で送信先を変更することはできず、プロバイダーのホストやモデルの許可リストもありません。BASE_URL には任意のホストとパスのプレフィックスを指定できます（セルフホスト用の localhost を含みます）。BASE_URL は、認証情報、クエリ、フラグメントを含まない絶対 http:／https: URL である必要があります。? または # を含む値は起動時に拒否されるため、空のクエリやフラグメントの区切り文字が追加されることはありません。状態と質問は設定済みのエンドポイントに送信され、API 使用料が発生する場合があります。サーバーは入力や判断を永続化せず、上流のエラー本文も公開しません。

タイムアウト。 JEV_TIMEOUT_MS は、自動 SDK 再試行を含む、1 回の判断呼び出しに対する合計タイムアウトです（個々の試行の上限は 10 秒です）。クライアントのツールのタイムアウトは、JEV_TIMEOUT_MS / 1000 秒より長く設定してください。

0.1.3 からの移行。 バージョン 0.1.3 では TYPESAFE_API_KEY と TYPESAFE_DEFAULT_MODEL（デフォルトは jev-latest）が読み取られ、リクエストは常に https://api.typesafe.ai に送信されていました。TYPESAFE_API_KEY を API_KEY に、TYPESAFE_DEFAULT_MODEL を MODEL に変更してください。以前のデフォルトモデルを使用していた場合は、MODEL=jev-latest を明示的に設定してください。0.1.3 で使用していたエンドポイントを維持するには、BASE_URL=https://api.typesafe.ai を追加します。最後に、ピン留めしているパッケージ設定を [email protected] に更新し、ホストを再起動または再読み込みして、新しいプロセスに変更後の変数を反映してください。

ツールを呼び出す

examples/decision.json の JSON を使って jev_decide を呼び出します。チームの選択、返金の可否判定、緊急度スコアを組み合わせています。簡単な例：

{
  "state": { "request": "Please refund the duplicate charge." },
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which team should handle `request`?",
      "criteria": {
        "billing": "Charges, invoices, refunds",
        "technical": "Broken software or integrations",
        "other": "Neither billing nor technical"
      }
    }
  }
}

レスポンスには model、answers、usage が含まれ、MCP の構造化コンテンツと JSON テキストの両方で返されます。Jev は確率を小数点以下 2 桁に丸めることがあるため、その合計は 1 からわずかにずれる場合があります。サーバーは対応する丸め誤差（選択肢ごとに最大 0.005）を許容し、返された値を修正することはありません。すべて API が送信したとおりに渡され、確率の再正規化やトークン数の捏造は行われません。usage のカウントが null のレスポンスは互換性がないため、捏造したゼロを報告するのではなく、INVALID_RESPONSE として拒否されます。選択肢では、名前付きの選択肢を 1～255 個指定できます。

受け付ける入力形式は変更されていません。指示と説明には、文字列、JSON オブジェクト、配列を指定できます。選択肢の説明には null を指定できます。noul では、任意の criteria.true と criteria.false の説明を受け付け、null も指定できます。リクエストの送信時にサーバーが行う正規化は 1 つだけです。noul の基準の説明が null の場合、送信リクエストから省略され、説明が残っていない criteria オブジェクトは全体が省略されます。これは、未設定の任意の説明をプロバイダーに依存せず正規化して省略する処理です。一部のエンドポイントでは、noul の説明に null を指定して送信すると HTTP 422 で拒否されますが、省略すれば説明なしとして扱われます（Liquid のリファレンスエンドポイントで確認され、省略によって解決しました）。それ以外はすべて指定どおりに送信されます。null を含む構造化オブジェクトや配列を含め、null 以外の noul の説明、および null の選択肢の説明を含むすべての choice と score の値が対象です。

関連する事実、ソーステキスト、ポリシーは明示的に指定してください。Jev から呼び出し元の会話やローカルファイルを参照することはできません。完全な判断内容を instructions に記述してください。ID はレスポンスのキーにすぎません。適切な場合は該当なしの選択肢を含めてください。同じバッチ内の質問は、互いの回答を参照できません。noul が 0.5 近辺の場合は、yes/no に関する不確実性を示しており、中程度の強さを示すものではありません。信頼度は、行動を許可したり正確性を保証したりするものではありません。代表的なデータでしきい値を評価してください。

トラブルシューティング

更新後にツールが表示されない場合は、サーバーを再起動し、新しいクライアントセッションを開始してください。設定されたサーバー名は jev、そのツール名は jev_decide です。2 インスタンス比較の設定では、両方のサーバーが jev_decide を公開します。サーバー名（jev-a、jev-b）で各インスタンスを区別できます。

サービスまたは設定の失敗は MCP ツールエラー（isError: true）であり、判断が捏造されることはありません。エラーコードには MISSING_API_KEY、INVALID_INPUT、INVALID_RESPONSE、API_ERROR、CONNECTION_ERROR、TIMEOUT、CANCELLED があります。無効な引数は MCP SDK によって直接拒否される場合もあります。BASE_URL または MODEL がない、または形式が正しくない場合、起動時に設定エラーが発生します。エラーには変数名が示されますが、値が出力されることはありません。

参考資料

• TypeSafe JavaScript SDK — このサーバーが使用する @typesafe-ai/sdk
• TypeSafe HTTP API — このサーバーが実行する typed-decision（SystemOne）リクエスト
• 判断プリミティブと質問の設計
• 関数呼び出しのクックブック