LightNow MCP Proxy

LightNow MCP Proxy

AI クライアントを MCP サーバーに接続し、すべてを安全に一元管理できます。

LightNow MCP Proxy は、LightNow プロファイルを動かすローカルランタイムです。 Codex、Claude Desktop、Cursor、VS Code、Antigravity を一度接続すれば、そのクライアントで利用できる MCP サーバーを、各ツールにサーバー設定やシークレットをコピーすることなく、LightNow で管理できます。

• 個人用および組織用プロファイルで MCP アクセスを整理できます。
• ローカルの stdio サーバーとリモートの Streamable HTTP サーバーを、1 つのエントリーから接続できます。
• MCP クライアントの設定に認証情報を埋め込まず、ユーザーのマシン上で解決できます。
• すべてのクライアント設定を再構築せずに、プロファイルやポリシーの変更を適用できます。
• クライアント、プロファイル、サーバーの健全性、ツールの使用状況を確認できます。ツールの引数はデフォルトで収集され、認証情報に似たフィールドはマスキングされます。収集は無効にできます。ツールの結果と解決済みのシークレットは収集されません。

インストール後もコマンドは lightnow-proxy のままです。ローカルで実行され、ID に紐付いた LightNow CLI セッションを使用して選択したプロファイルを解決し、そのプロファイルの MCP サーバーにツールやリソースのリクエストをルーティングします。

機能は LightNow プロファイルに応じて異なります

この Proxy には、デモ用ツールは意図的に含まれていません。MCP の機能は、アクティブな LightNow プロファイルで選択されているサーバーが公開する実際のツールとリソースです。そのため、チームやクライアントによって一覧は異なります。github__create_issue のような名前は、接続先のサーバーとそのツールの両方を示し、複数のサーバーで同じツール名が使われている場合の衝突を防ぎます。

この Proxy は、ステートレスなリクエストごとのプロトコルメタデータと server/discover を備えた、公式 MCP の 2026-07-28 リビジョンをサポートしています。また、2025-11-25 までのハンドシェイク方式のサーバーやクライアントとの自動互換性も維持します。

ツールの検出では、実際に設定されているアップストリームから、ページネーションを最後まで読み込みます。カーソルの繰り返し、同一名の重複、または30秒、100ページ、2,000個のツール、定義4 MiBの上限に達した場合は、明示的に失敗します。検出が完了していない状態と、検出が完了してツールが0件だった状態は区別されます。最新の HTTP 呼び出しでは、同じ完全な検出結果からパラメーターヘッダースキーマを準備します。管理対象のディスパッチ機能は、送信を1回行う前にその一覧を認可します。スキーマの不一致からの復旧や対話的な再試行は、必ずポリシーゲートを再度通過する必要があります。

Registry API がサニタイズ済みの任意のセットアッププレビューを要求した場合、Proxy はネイティブの管理対象コンテキストから、公開入力 ID、バインディングの真偽値、型付きプレースホルダー、明示的に許可された公開選択肢のインデックスのみを投影します。起動コマンドを解析したり、設定値、ファイル、エンドポイント、ツールのメタデータをプレビューにコピーしたりすることはありません。未対応または不一致の記述子がある場合は、非公開の検出が成功していても、利用不可のプレビューが返されます。共有は独立した明示的な API/UI 操作です。この Proxy はコントリビューションを作成または公開しません。ワークフロー全体の仕様は、Registry API #1340 を参照してください。 マネージド接続では、既存のデバイスハートビートで managed-connections.v1 を宣言し、任意のアクティビティ収集が無効になっている場合でも、 アクター所有のランタイムクライアント ID を取得します。 互換性のある同期プロキシは15秒ごとにポーリングし、キューに入った非公開の探索を 最大2件まで同時に実行します。正確な現在の割り当てを解決し、 アップストリームを開く前に、キュー内のプロファイル、ポリシー、認証情報のリビジョンを比較して、 If-Match を使用して元のリクエストに報告します。 シャットダウン時には未完了の探索処理をキャンセルします。失敗は、非公開の定義や 未加工のアップストリームエラーを含まない、制限されたコードで報告します。従来のプレゼンスのみのクライアントでは、120秒間隔が維持されます。 Registry は、正規の接続、割り当て、および制限されたブートストラップコンテキストを提供します。完全な非公開インベントリ報告では、 ディスパッチと同じバックエンド認可機構で許可された元の名前がそのまま返されます。 Proxy は探索結果をフィルタリングし、実際のアップストリームセッションで、その決定を業務呼び出しの前にもう一度確認します。想定されるマネージド拒否では、内容を含まない理由コードを記載した通常の MCP ツールエラーを返します。有効期限と単調時計に基づく期限の両方が適用され、報告によってリースが更新されることはありません。マネージドコンテキストでは、リソースメソッドは認可されません。同期されたプロファイルでは、永続的なツールキャッシュと古いフォールバックを使用しません。正規のエイリアスが優先されます。また、組織への参加が必須の場合、ローカルの静的および従来のランタイムオーバーライドはマネージドプロファイルから除外されます。 マネージドのワイヤ名には ln_<full assignment UUID hex>__<original tool name> を使用します。 説明とメタデータには、読みやすいエイリアスが保持されます。 そのため、アンダースコアを含むエイリアス、名前の変更、割り当ての置き換えによって、ツールの識別情報が引き継がれることはありません。 予約済みの UUID 名前空間では、割り当てが削除された後に静的または従来のルーティングへフォールバックすることはありません。通常の従来のツール名は、従来どおりの形式を維持します。

マネージド呼び出しでは、任意のアクティビティ収集とは別に、内容を含まない必須の証跡も保持されます。CLI セッションの隣にある非公開の SQLite ジャーナルが、各試行を起動前に、またディスパッチ前に引き渡しの意図を記録します。再試行するのは元のイベント UUID、サブジェクト、報告レシートのみであり、業務呼び出しは再試行しません。ネイティブ OS ロックによって、実行中の呼び出しと中断された呼び出しを区別します。失われた結果は不明のままです。Registry の明示的な RUNTIME_PROFILE_FORBIDDEN 応答では、元の報告レシートを使って拒否された呼び出しが記録されます。これはインフラストラクチャの障害ではありません。ストレージが利用できない場合や容量が枯渇した場合は、ディスパッチがブロックされます。ローカルの /status では、保留中および未解決の件数と、クローズ済みの配信コードが確認できます。制限付きジャーナルは、明示的な解決に備えて却下または期限切れの事実を保持します。 証跡の仕様を参照してください。

インストール

要件：

• Python 3.11 以降
• pipx
• LightNow アカウント
• LightNow CLI

pipx install lightnow-cli
lightnow login

Homebrew を使ってプロキシをインストールします：

brew tap lightnow-ai/tap
brew install lightnow-proxy

または、pipx を使ってインストールします：

pipx install lightnow-proxy

または、uv を使ってインストールします：

uv tool install lightnow-proxy

Python パッケージをインストールすると、MCP クライアントで使用する lightnow-proxy コマンドがインストールされます。

リポジトリ内で開発する場合：

uv tool install --from . lightnow-proxy

サポート対象の CLI および Proxy のインストールを、LightNow CLI から更新します：

lightnow update --check
lightnow update

Homebrew、pipx、uv は管理対象です。プロキシは、メタデータのみのハートビートで検出したバージョンと更新状態を報告するだけです。パッケージマネージャーを実行したり、リリースを確認するために MCP の起動を遅らせたりすることはありません。

クライアントの設定

LightNow CLI を使用します。クライアントの MCP エントリと、クライアントごとの Local Proxy 設定を書き込みます。

lightnow sync --client codex --local-proxy
lightnow sync --client claude-desktop --local-proxy
lightnow sync --client cursor --local-proxy
lightnow sync --client vscode --local-proxy
lightnow sync --client antigravity --local-proxy

同期後に MCP クライアントを再起動してください。

複数のアカウントと組織

同じ MCP クライアントに表示する各アカウント、組織、またはプロファイルには、それぞれ異なる --connection エイリアスを使用します。

lightnow login
lightnow sync --client codex --local-proxy \
  --connection lightnow-personal --profile default

# Sign in with the organization account before creating this connection.
lightnow login
lightnow sync --client codex --local-proxy \
  --connection lightnow-acme --tenant <tenant-id> --profile engineering

生成される各プロキシ設定には、安定した接続 ID が割り当てられ、~/.lightnow/sessions/ にある名前付き CLI セッションが参照されます。また、想定される発行者とサブジェクトも記録されます。これらの値が一致しない場合、プロキシは Registry リクエストを拒否するため、後から CLI にログインしても既存の接続が気付かないうちに切り替わることはありません。プロキシ YAML にアクセストークンやリフレッシュトークンが書き込まれることはありません。

ローカルのセットアップを確認します。

lightnow config-status --client codex

プロキシが選択したプロファイルを解決し、上流の MCP サーバーに接続できるかどうかを確認します。

lightnow-proxy --health
lightnow-proxy --health --json

デフォルトでは、Local Proxy モードにデフォルトプロファイルを同期したときに書き込まれる ~/.lightnow/lightnow-proxy/default.yaml が読み込まれます。クライアント固有の設定を使用する場合は、生成されたパスを明示的に指定します。

lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json

名前付き接続では、~/.lightnow/lightnow-proxy/codex-lightnow-acme.yaml などの個別のファイルが使用されます。JSON ヘルスレポートには、秘密情報ではない接続エイリアス、ID、アカウントラベル、スコープ、プロファイル、ID バインディングの状態が表示されます。cli_config_path を使用するレガシー設定も引き続き読み込めますが、設定された認証発行者に制限されます。

テレメトリが有効な場合、アクティブなヘルスチェックと実行時イベントが LightNow Control Plane に送信されます。ツール呼び出しの引数はデフォルトで記録されますが、Local Proxy の設定で個別に無効にできます。送信前に、認証情報に類するフィールドはマスキングされます。プロキシは起動時に直ちにデバイスのプレゼンス情報を送信し、その後は 2 分ごとに送信します。これにより Control Plane では、どのデバイス、クライアント、プロファイルがアクティブ、正常、劣化、または障害状態にあるかを、CLI／Proxy のバージョンや更新状態とあわせて確認できます。ツールの結果、解決済みの LightNow シークレット、マスキングされていない認証値、ネットワークアドレス、ハードウェア識別子、ローカルパスは保存されません。認証ヘッダーを含む、認証情報に類する引数フィールドは、送信前に [REDACTED] に置き換えられます。

実行時の解決用に設定された Vault プロバイダーは、Registry API が認証情報やシークレット値を含まないプロバイダー参照を返した後、このホスト上で解決されます。HashiCorp Vault Proxy の 127.0.0.1:8200 での自動認証がデフォルトです。プロバイダー固有のループバックリスナーは、生成された YAML の runtime_secrets.providers でマッピングできます。LightNow CLI は、以降の同期でもこれらの秘密情報を含まないマッピングを保持します。オプションの OS キーチェーン機能は lightnow-proxy[keyring] で利用できます。解決に失敗した場合はフェイルクローズとなり、平文の値がツールスキーマキャッシュに追加されることはありません。

管理対象の実行時ファイル

STDIO サーバーは、制限付きの秘密情報を含まない runtime_files を、Runtime Profile のクライアント設定に含めることができます。LightNow Proxy は上流プロセスの起動前に、各ファイルセットを ~/.lightnow/runtime-files 以下の不変なコンテンツアドレス指定ディレクトリに書き込みます。ファイルのモードは 0600、管理対象ディレクトリのモードは 0700 です。

引数、環境変数の値、または作業ディレクトリでは ${LIGHTNOW_RUNTIME_DIR} を使用して、解決されたディレクトリを参照します。

{
  "transport": "stdio",
  "command": "npx",
  "args": [
    "@bytebase/dbhub@latest",
    "--config",
    "${LIGHTNOW_RUNTIME_DIR}/dbhub.toml"
  ],
  "env": {
    "DBHUB_DSN": "${DBHUB_DSN}"
  },
  "runtime_files": [
    {
      "path": "dbhub.toml",
      "content": "[[sources]]\nid = \"analytics\"\ndsn = \"${DBHUB_DSN}\"\n"
    }
  ]
}

実行時ファイルは UTF-8 テキストで、上限は 16 ファイル、1 ファイルあたり 64 KiB、サーバー設定あたり 256 KiB です。パスは相対パスである必要があり、パストラバーサルセグメントやバックスラッシュを含めることはできません。シークレット値は LightNow の実行時シークレットバケットに保持する必要があります。ファイルから対応する環境変数名を参照することはできますが、平文の認証情報を埋め込んではいけません。無効なマテリアライズ、または変更されたマテリアライズは、上流プロセスの起動前にフェイルクローズとなります。

詳細なドキュメント

詳細なセットアップガイド、例、図、対応クライアントの接続方法、テレメトリの動作、トラブルシューティングについては、LightNow のドキュメントを参照してください。

• MCP クライアントを接続する
• CLI リファレンス
• リリースプロセス

ローカル開発

このリポジトリに貢献する方へ：

uv venv
uv pip install -e .[dev]
make test

Jenkins はランタイムイメージをビルドし、その中で make lint test の Ruff コマンドと pytest コマンドを実行した後、lightnow-proxy --help をチェックします。 チェックアウトは読み取り専用でマウントされ、テスト環境はコンテナ内に配置されます。 Jenkinsfile はネイティブの build-agent 機能プールを使用し、独自の検証イメージのみを削除します。タイムアウトにはエージェントの割り当て時間が含まれます。 GitHub Actions では引き続き Python バージョンマトリックスを実行します。Ops の依存関係を更新する前に、現在の PR ヘッドで Jenkins が最終的に成功することを必須にしてください。 このパイプラインは、イメージを公開したりアカウントを変更したりせずに変更を検証します。

サンプル設定でプロキシを実行します：

uv run lightnow-proxy --config config.example.yaml

stdio MCP サーバーとしてプロキシを実行します：

uv run lightnow-proxy --config config.example.yaml --transport stdio

サンプル設定に対してローカルでヘルスチェックを実行します：

uv run lightnow-proxy --config config.example.yaml --health