Jev agent tools

jev-agent-tools

pi、omp、すべての MCP クライアントで使える、Jev API 形式に対応した、エビデンス重視の 6 つのツールです。これらを使って、未知のコードを調べたり、リポジトリ内のエビデンスについて型付きの質問をしたり、完了した変更をレビューしたり、既存のテストを選択したりできます。これらのツールは、コードの読み込み、検索、実行を補完するものであり、それらに取って代わるものではありません。

紹介動画を見る（74 秒、MP4）。

初めての方は、スタートガイドから始めてください。ドキュメント索引では、対象読者ごとに関連ドキュメントを案内しています。

インストール

ホストのパッケージマネージャーからインストールするか、MCP クライアントに MCP サーバーを登録してください。npm パッケージ名は jev-agent-tools です。pi と omp は TypeScript ソースを直接読み込みます。MCP サーバーはビルド済みのものを提供します。

pi

pi install npm:[email protected]
# Project-local installation:
pi install -l npm:[email protected]

omp

omp plugin install [email protected]

すべての MCP クライアント

バージョン 0.2.0 以降、このパッケージには jev-agent-tools-mcp も含まれています。これは、同じ 6 つのツールをあらゆる MCP クライアントに提供する stdio MCP サーバーです。対応クライアントには Claude Code、Claude Desktop、Kiro、Cursor、VS Code、Codex CLI などがあります。一般的な mcpServers の設定例：

{
  "mcpServers": {
    "jev": {
      "command": "npx",
      "args": ["-y", "-p", "jev-agent-tools", "jev-agent-tools-mcp", "--root", "/path/to/repository"],
      "env": {
        "JEV_TOOLS_URL": "${JEV_TOOLS_URL}",
        "JEV_TOOLS_API_KEY": "${JEV_TOOLS_API_KEY}"
      }
    }
  }
}

Windows では、ほとんどのクライアントがシェルを介さずにコマンドを起動するため、args の先頭に "/c", "npx" を指定し、"command": "cmd" を使用してください。MCP セットアップガイドでは、クライアントごとの設定ファイル、CLI コマンド、変数の補間、検証、トラブルシューティングについて説明しています。リリースは、公式 MCP Registry に io.github.NomenAK/jev-agent-tools としても掲載されています。エージェントがツールを正しく使い、その内容を読み取れるよう、エージェント向けの指示を CLAUDE.md、AGENTS.md、または Kiro のステアリングファイルに追加してください。

サーバーは、pi と omp と同じ環境変数、および /jev-setup で保存された設定を読み込みます。サーバープロセス 1 つにつき、セッションは 1 つです。MCP には実行終了時にドキュメントを自動で読み込むフックがありませんが、それを手動で代替する呼び出しを行う必要はありません。コマンドが有効な場合、jev_ask は読み取り専用ではないものとしてマークされます。JEV_TOOLS_ALLOW_COMMAND=0 を設定すると、スキーマから command が削除されます。

要件と互換性

Node.js 24 以降が必要です。サポート対象ホストの最低バージョンは、pi 0.87.1 と omp 18.4.10 です。これらはサポート対象の最低バージョンであり、それ以降のすべてのバージョンを個別に検証済みであることを示すものではありません。omp は Bun ランタイムを使用します。Node.js ベースのプロジェクトチェックにも Node.js が必要です。Git と、任意のコマンドエビデンスを利用する場合は Bash が必要です。Windows では、コマンドエビデンスに Git for Windows の bash を使用します（PATH 上の git の隣、または Program Files 内から検出します）。WSL の bash.exe ランチャーは使用しません。別の bash を使う場合は、完全なパスを JEV_TOOLS_BASH に設定してください。一部のプラットフォームでは、オプションのネイティブパーサーやファイル検索の高速化機能を利用できない場合があります。その場合、該当するツールが制限事項を報告します。

公開済みの [email protected] パッケージは、Linux 上で Node.js 24.15.0 を使用し、pi 1.0.0 でも検証済みです。npm によるインストール、ホストの型定義に対する TypeScript のチェック、実際の CLI での 6 つのツールすべての実行、読み取りガイドの注入が成功しました。CLI のスモークテストでは、シミュレートされた会話プロバイダーと Jev エンドポイントを使用しました。これはホストとの統合を検証するものであり、実際のモデルの精度や、すべてのツールシナリオを検証するものではありません。

**pi 1.0.0 のパッケージングに関する警告：**このパッケージは @sinclair/typebox を dependencies に指定していますが、pi はホストから提供される拡張モジュールを、"*" の範囲を指定した peerDependencies に含めることを想定しています。別途インストールされたコピーによって、実行時モジュールが重複する可能性があると pi は警告します。この警告がスモークテストの完了を妨げることはありませんでしたが、パッケージング上の問題として残っています。警告のない互換性を示すものではありません。

設定

対話型セットアップ

pi または omp のメイン対話型ターミナルで、設定されていない状態で初回起動すると、Configure now / Later が表示されます。エンドポイント、モデル、キーを変更するには、いつでも /jev-setup を実行してください。キーはマスクされたフィールドに入力し、コマンドライン引数として渡されることはありません。This session only（何も書き込みません）または Save for future sessions を選択してください。どの手順でもキャンセルすれば、何も変更されません。

フラグ	効果
--jev-skip-setup	この実行では初回起動時の案内を表示しません。/jev-setup は引き続き使用できます。
--jev-url <url>	この実行で使用するエンドポイントです。
--jev-model <name>	会話モデルではなく、この実行で使用する Jev モデルです。

印刷、JSON、RPC モード、またはサブエージェントではダイアログは表示されません。これらは以下の環境変数で設定してください。変更はホストを再起動せずに直ちに反映されます。

対話型セットアップは、送信またはキャンセルされるまで待機し、認証情報の入力にタイムアウトはありません。初回起動時の案内は、エンドポイントやキーを探している間、ホストの起動イベントハンドラーを開いたままにしません。

フィールドごとの優先順位： 環境変数、起動フラグ、このセッションのセットアップ、保存済み設定、デフォルトモデル openjev の順です。環境変数またはフラグで設定されたフィールドは、管理対象として表示され、保存されることはありません。

保存済み設定はリポジトリの外部にある $XDG_CONFIG_HOME/jev-agent-tools/config.json（デフォルトは ~/.config/jev-agent-tools/config.json）に、プライベートディレクトリ（0700）とプライベートファイル（0600）として保存されます。モードビットが存在しない Windows では、プライバシーはフォルダーのアクセスリストで保護されます。保存時にアクセスは自分、SYSTEM、Administrators に制限され、ほかのアカウントがアクセスできる場合、読み込みは拒否されます。キーは暗号化されず、平文で保存されます。 ストレージがシンボリックリンクである場合、ほかのユーザーがアクセス可能な場合、自分が所有していない場合、または形式が不正な場合は、上書きせずに拒否されます。MCP サーバーもこのファイルを環境変数の後に読み込みます。

環境変数

ホストの起動前に、ご自身のエンドポイントと認証情報を使って設定してください。

export JEV_TOOLS_URL="${YOUR_JEV_ENDPOINT}"
export JEV_TOOLS_API_KEY="${YOUR_JEV_API_KEY}"
# Optional; already the default:
export JEV_TOOLS_MODEL="openjev"

YOUR_* プレースホルダーは入力値であり、追加の製品設定ではありません。環境変数は拡張機能の読み込み時に読み取られ、ほかのすべての設定より優先されます。

変数	意味
JEV_TOOLS_URL	必須の完全なエンドポイント URL です。Jev API 形式に対応している必要があります。https: が必須です。平文の http: は 127.0.0.1、::1、または localhost に限り使用できます。
JEV_TOOLS_API_KEY	必須の Bearer 認証情報です。設定値はツール出力に表示されず、コマンドの子プロセスにも渡されません。
JEV_TOOLS_MODEL	要求するモデル文字列です。デフォルトは openjev です。これは随時変更されるエイリアスであり、実際に提供されるモデルの識別を保証するものではありません。
JEV_TOOLS_MAX_CALLS	セッション全体に適用される、0 以上の安全な整数による呼び出し上限です。未設定または空の場合、上限はありません。無効な値ではリクエストが拒否されます。
JEV_TOOLS_MAX_USD	セッション全体に適用される、端数を含む有限の 0 以上の費用上限です。未設定または空の場合、上限はありません。無効な値ではリクエストが拒否されます。
JEV_TOOLS_ALLOW_COMMAND	0 を指定すると、jev_ask の command が無効になります。それ以外の場合、コマンドは追加のサンドボックスなしで通常のシェル権限を使って実行されます。
JEV_TOOLS_AUTO_DOCS	0 を指定すると、実行終了時の自動ドキュメントチェックが無効になります。
JEV_TOOLS_BASH	Windows で jev_ask コマンドに使用する bash のフルパスを任意で指定します。
JEV_TOOLS_ROOT	MCP サーバーのみ：--root が指定されていない場合のリポジトリディレクトリです。

エンドポイントまたはキーが設定されていなくても、ツールは登録されたまま、不足している設定を説明します。自動ドキュメントチェックは無効になります。チャットモデルへのフォールバックはありません。ツールごとの max_calls はセッション上限とは別に設定されます。応答で返されるモデル名を見ても、実際に提供されたモデルを特定することはできません。

ツールを選ぶ

ツール	選択する状況
jev_ask	メモ、ファイル、以前のバージョン、またはコマンド出力を組み合わせて、1つの判断を行う場合。
jev_ask_files	同じ質問を各候補ファイルに個別に適用する場合。
jev_find_files	動作上の目標から調査を始めたいものの、ファイル名がわからない場合。omp で有効な場合は、ネイティブの find を使用してください。
jev_locate_in_file	19 KB 以上のファイル内で、関連する範囲を特定する場合。
jev_check_diff	完了した変更について、リスク、既存のドキュメント、または仕様をレビューする場合。
jev_select_tests	影響を受ける既存のテストを実行または収集せずに、そのテスト用のコマンドが必要な場合。

正確なソーステキスト、既知のシンボル、ファイル名、行番号、件数、算術計算には、ネイティブの読み取り／検索ツールまたはコードを使用してください。コマンドの出力全体が必要な場合は、自分でコマンドを実行してください。ツールのリファレンスにある例では架空のリポジトリパスを使用しており、実行記録ではなく、呼び出し例を示しています。

エビデンスのルート

6つのツールすべてで、任意の root: string を指定できます。指定しない場合、ホストの現在のディレクトリまたは設定済みの MCP サーバーディレクトリにおける既存の動作が維持されます。オーバーライドには、初期リポジトリの Git トップレベル、または同じ正規 Git 共通ディレクトリを持つ登録済みの稼働中ワークツリーを正確に指定する必要があります。相対パスのオーバーライドは初期ディレクトリを基準に解決されます。絶対パスはこのパラメーターでのみ使用できます。サブディレクトリ、別のクローン／リポジトリ、親ディレクトリへの移動、シンボリックリンクを含むパスは、エビデンスの収集、コマンドの実行、キャッシュへのアクセス、判断を行う前に拒否されます。別のチェックアウトへのフォールバックはありません。

許可されたルートは、その呼び出しに限り、ファイル、ベース／差分、インベントリ、仕様のパス、ランナーの計画、コマンドの cwd を決定します。別の呼び出しや自動ドキュメントフックには影響しません。ファイル引数は引き続きリポジトリ相対であり、許可された範囲内に限定されます。コマンドには通常のシェル権限があり、サンドボックスではありません。結果を使用する前に、報告された権限、要求されたルート／実効ルート、解決されたベースを確認してください。

結果を読む

各結果は、実行状態（complete、partial、not_judged、refused）で始まります。これは処理状況を示すものであり、正確性、安全性、網羅性を示すものではありません。項目では、Jev による新規またはキャッシュ済みの判定、静的な処理、未判定の作業を区別します。静的な選択と保守的なフォールバックでは、確率を創作しません。不確実性のマークが付いていない判定済みの行は判定です。提示された証拠で確認すべき手掛かりであり、それを超える証明ではありません。

マーク	意味と次のアクション
unsure	回答が曖昧であるか、制御に失敗しています。示された箇所を読み取るか、決着に必要な具体的な証拠を追加してください。質問を言い換えるだけでは解決しません。
abstain	必要な情報が不足しています。指定された証拠を入手するか、結論を保留してください。証拠が変わり、役立つ場合は、Jev を再度呼び出してもかまいません。
no (not shown) / not addressed	提示された証拠では、その記述を確認できません。だからといって、誤りだとは限りません。
uncalibrated	この問いには確立されたエラー率の較正が適用されません。確率が高くても、手掛かりとして扱ってください。
診断と次のアクション	原因の種類、発生元、影響範囲、重要度、復旧手順を示し、不確実な判定と未判定の作業を区別します。

通常のブール判定のしきい値は、0.20 以下または 0.80 以上です。カテゴリ／レベル判定では、適用される制御の後、最有力候補の確率が少なくとも 0.85 であることが必要です。固定チェックとナビゲーションツールにはそれぞれ独自のしきい値があり、リファレンスと設計に記載されています。

記録では、HTTP 試行数、送信した質問数、要求された結果（新規／キャッシュ／静的／未判定）、キャッシュの照会数、補助的な制御と箇所の選択、現在報告されている USD コスト、経過時間を分けて扱います。これらの数値は相互に置き換えられません。キャッシュ済みの判定では HTTP 試行数が 0 の場合があります。試行数が 0 でも、静的な処理または判定なしを意味する場合があります。不明なコストは未報告であり、無料という意味ではありません。コンテキスト値では、既知、不明、未収集、該当なしを区別します。

pi と omp は、バージョン管理されたレポートを details.result として公開します。2025-06-18 以降の MCP バージョンでは、同じレポートを、公開された出力スキーマとともに structuredContent.result で公開します。それ以前のバージョンでは、同じレポートから自己完結型のテキストが返されます。テキストには、重要な制限、証拠の出所、有用な読み取り／実行コマンドが保持されます。

現在の結論、決定的な証拠とその出所および適用範囲、重要な留保事項を報告してください。同じコンテキストについて、ネイティブな読み取りまたは実行によって以前の unsure や abstain が解消された場合、現在の結論は Jev ではなく、そのネイティブな証拠に帰属させてください。Jev が返した不確実性が依然として重要な場合は、Jev が結論を確認していないこと、必要な証拠、およびその影響を明示してください。独立した制限、古い証拠、相反するコンテキストも引き続き明らかにしてください。報告されたチェックは実行を観測したことを意味しません。網羅的な履歴ブロックや、新たな永続レジスターは必要ありません。

pi と omp の使用ガイダンス

この拡張機能は、両方のホストで共通の読み取りガイドを提供します。omp は通常の起動時に有効な npm プラグインのルールを検出しますが、pi はパッケージの rules/ ディレクトリを自動的には検出しません。pi では、同じ判断ポリシーが jev_ask ツールのガイドラインに含まれているため、jev_ask が有効なときは常に利用できます。強制的な不透明プロンプトの上書きによって、この統合が回避される場合があります。無効化されたツールや無効化された omp のルールは対象外です。この README の記述は推奨される使用ガイダンスであり、それ自体がインストール済みの指示ではありません。

未解決の判断を変えたり、調査対象を絞り込んだりできる場合は、範囲を限定した意味上の判断に Jev を使用してください。決定的なネイティブの読み取り、検索、または許可された実行は直接行ってください。Jev の呼び出しは、結論、レビュー、または完了の前提条件ではありません。呼び出しを選ぶ際は、比較する両方の側面と、各説明を見分ける根拠を提示してください。変化した証拠、コンテキスト、または有用な新しい質問がある場合にのみ再検討してください。変化のない証拠を繰り返すことは、復旧の手段にはなりません。

MCP クライアントはガイドをサーバーの instructions として受け取りますが、一部のクライアントはこれを無視します。エージェント向け指示を、プロジェクトの CLAUDE.md、AGENTS.md、または Kiro のステアリングファイルに追加してください。

データとコマンドの安全性

リポジトリの証拠、メモ、任意のコマンド出力は、設定済みのエンドポイントに送信されます。機密性の高いリポジトリで使用する前に、そのデータ取り扱いポリシーを確認してください。設定済み API キーの値は、送信前にすべてのペイロード文字列から秘匿され、コマンドは JEV_TOOLS_API_KEY なしで実行されます。セキュリティガイダンスを参照してください。

ファイルの収集対象はリポジトリ内に限定されます。絶対パス、親ディレクトリへの移動、リポジトリ外に出るシンボリックリンク、Git メタデータ、内部 URL はファイル入力として扱われません。秘密情報のような名前のファイル（.env、.env.*（.env.example／.env.sample／.env.templateを除く）、*.pem、id_rsa*、*.p12、credentials*、secrets*。深さや大文字・小文字は問いません）は、読み取り前に拒否され、原因 secret_pattern が示されます。ビルド出力、バイナリ、ロックファイル、大きすぎるファイルは、表示される上限に従ってスキップまたは拒否されます。証拠が判定に使われる形で黙って切り詰められることはありません。この制限は、コマンドをサンドボックス化するものではありません。jev_ask コマンドは、ホストのシェル権限で読み取り、書き込み、またはネットワークへのアクセスを行えます。コマンドは JEV_TOOLS_API_KEY なしで実行され、設定済みのキーは出力内で [redacted] に置き換えられます。omp ではコマンドの実行に承認が必要です。pi ではツールごとの追加のコマンド承認は行われません。MCP クライアントは独自のツール承認を適用し、サーバーは jev_ask を読み取り専用ではないものとして示します。JEV_TOOLS_ALLOW_COMMAND=0 を設定すると、コマンドを無効化できます。

ドキュメントの自動チェック

ツリーに変更がある場合、この拡張機能は実行終了時に、HEAD からの変更を対象として既存の Markdown ドキュメントを一度チェックできます。Git の無視対象ではなく、秘密情報のような名前でもない、追跡対象外のファイルも含まれます。これらは明示的なツール呼び出しなしでエンドポイントに送信され、Jev の呼び出しは最大 8 回です。問題が指摘された既存の文については、追加のターンを一度だけ要求し、その文を調査して更新するか、根拠を示して正しいままである理由を説明できます。問題の指摘だけで誤りが立証されるわけではなく、2 回目の呼び出しが必須になるわけでもありません。単に確信が持てないセクションだけでは、追加のターンは発生しません。JEV_TOOLS_AUTO_DOCS=0、設定の不足、無効または使い切ったセッション予算、あるいはクリーンなツリーの場合、チェックはスキップされます。エラーやタイムアウトによってホストがブロックされることはありません。このオプトアウト可能なホスト機能は、ドキュメントの完全性を保証するものではありません。MCP にはフックがないため、手動で代替する手順も不要です。

既知の制限

静的な証拠や確率は、実行、安全性、完全性を証明するものではありません。インポートの閉包ですべての関係を検出できるわけではなく、動的コード、未対応の構文、任意のパーサーの失敗によって、明示的な抜けが生じます。問題が見つからなくても、見つかっていない呼び出し元やドキュメントが正しいことの証明にはなりません。テストの選定では、検出済みの既存シナリオが考慮されますが、新しいシナリオを追加すべきかどうかは判断されません。セッションのキャッシュでは、変化するモデルエイリアスの同一性や安定性を確認できません。

開発とコントリビューション

CONTRIBUTING.md、CHANGELOG.md、設計、アーキテクチャ決定を参照してください。ドキュメントの目次から始めてください。コントリビューターはアーキテクチャとツールの仕組みを追加します。開発時のチェックは、判定エンドポイントに接続せずにローカルで実行できます。

npm ci --include=optional
npm run typecheck
npm run check:imports
npm run lint
npm test

内部のソースモジュールは実装の詳細であり、安定したライブラリーインターフェースではありません。

ライセンス

MIT。