agent-connector

agent-connector

1 つの MCP を、あらゆるエージェントホストにデプロイします。

配布ではなく、実装に集中しましょう。

defineConnector() でサーバーとフックを一度記述すれば、検出されたすべてのエージェントホスト（ターミナル CLI、IDE 拡張機能、デスクトップアプリを含む。Claude Code、Codex、Cursor、Copilot、Gemini、OpenCode、Warp、Zed など）に、ネイティブ設定へ install するか、実際のプラグインとして package できます。

エージェント向けドキュメント：llms.txt（ルートマップ）・ llms-full.txt（ホストごとのリファレンス）・ SKILL.md（エージェントスキル）・ ガイド：ユーザーがあらゆるエージェントホストにインストールできるよう、MCP サーバーを公開する。

数字で見る。 すべての数値はアダプターレジストリから取得するか、実行のたびにテストで測定しています。README とソースに不一致があると、差分テストが失敗します。

アダプターを備えたエージェントホスト	42 — ターミナル CLI、IDE 拡張機能、デスクトップアプリ（対応状況一覧）
ホストごとにレンダリングされるサーフェス	8 — MCP サーバー（41 ホスト）、メモリ（41）、スキル（36）、フック（32）、コマンド（19）、サブエージェント（16）、アクション（9）、ステータス行（4）
正規化されるフックイベント	13。3 種類のパラダイムでディスパッチされます（json-stdio 24 ホスト · mcp-only 10 · ts-plugin 8）
生成されるパッケージ形式	ホストプラグイン形式 9 種類 + MCP 標準アーティファクト 2 種類（mcp-server-json、mcpb）
シークレットのバックエンド	4 — macOS Keychain、Linux Secret Service、Windows Credential Manager、オプトインのファイルストア。stdio サーバーの env にある ${secret:NAME} はホスト設定に渡りません
OAuth プロバイダープリセット	5 — google、microsoft、github、bing-webmaster、posthog（+ 汎用）
実際のホストバイナリで検証済みのホスト	42 中 29（うち 22 はモデルツール呼び出しを通じたエンドツーエンド検証）。残りの 13 は、隔離された HOME でレジストリのインストールハーネスを使って検証
測定されたフットプリント	135 行の defineConnector() 1 つ → ユーザースコープで 42 ホスト中 41 にわたり、6 種類のファイル拡張子で 66 個のホストネイティブファイル（プロジェクトスコープでは 63 個） — npm run measure:footprint
テストスイート	テストファイル 174 個

対象ユーザー。 agent-connector は MCP 配布における公開者側です。MCP サーバーを作成済み（または作成中）で、フック、スキル、プラグインバンドルとともに、自分のパッケージから npx <your-package> install でユーザーのエージェントホストにインストールしたい方を対象としています。add-mcp や agent-install などのツールはエンドユーザー側で、1 台のマシン上にあるエージェントへ既存のサーバーを追加します。この 2 つは組み合わせて使えます。agent-connector は、サーバーの作者が公開するものです。 2 つの対象者： コネクター開発者はクイックスタートから始めてください。 すでにエージェントホストを運用していて、トークンの合計数だけを確認したい場合は、 usageに直接進んでください。

• クイックスタート — SDK を依存関係に追加し、コネクターを宣言してインストールします
• リリース — 直接インストールまたはマーケットプレイスプラグイン
• 一度だけ定義する内容 — サーバー、フック、その他の連携方法
• 仕組み — 単一のホームバイナリ、プロジェクトごとのデータ、フックの方式
• CLI — すべてのコマンドの概要
• トークンテレメトリーと使用状況 — ツールごとのテレメトリーと、コネクター不要のusage
• MCP エコシステムに公開する — MCP 公式標準のアーティファクトを生成します
• 検証 — プラットフォーム対応契約の証明方法

_{一度定義 → 独自ブランドの CLI としてリリース → ユーザーが各ホストのネイティブなマーケットプレイスからインストール → 1 つのコマンドですべての CLI を操作します。 このデモを再生成します。}

クイックスタート

agent-connector は、コネクター開発者が依存関係として追加する SDKです。コネクターを保持する パッケージに追加し、コネクターを一度宣言してから、npx @acme/acme-db-mcp installのような 独自ブランドの MCP パッケージ／バイナリをリリースします。これにより、検出された各エージェントホストの ネイティブ設定にデプロイされます。@ken-jo/agent-connectorをグローバルにインストールするのは、 独自ブランドの MCP ライフサイクルの方法ではありません。グローバル CLI の説明は、コネクター不要の トークン使用状況レポート用に限られます。フレームワークのアーティファクトツールは開発者向けであり、 通常はnpx @ken-jo/agent-connector ... --connectorを使って実行します。手順は次のとおりです。 サーバーを用意する → 宣言する → 独自ブランドのパッケージからインストールする。

0. まず MCP サーバーファイルが必要です。 以下の設定は ./my-mcp-server.mjsを参照しているため、インストール前にそのファイルが存在している必要があります。 まだ MCP サーバーがない場合は、 examples/acme-db/acme-db-mcp-server.mjs （自己完結型の約 35 行のスタブ）を./my-mcp-server.mjsとしてコピーするか、 公式 MCP SDK クイックスタートに従ってください。

# 1. add agent-connector as a DEPENDENCY of your connector package
npm install @ken-jo/agent-connector

// 2. package.json — this is the user-facing package identity
{
  "name": "@acme/acme-db-mcp",
  "mcpName": "io.github.acme/acme-db",
  "bin": { "acme-db": "./bin.mjs" },
  "dependencies": { "@ken-jo/agent-connector": "^0.8.0" }
}

// 3. agent-connector.config.mjs — declare your server + hooks once
import { fileURLToPath } from "node:url";
import { defineConnector } from "@ken-jo/agent-connector/sdk";

const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

export default defineConnector({
  // package.json / npm metadata is the source of truth. The host alias/runtime
  // id and connector version are derived from name/mcpName/bin/version unless
  // you need a legacy or multi-instance alias. Host-native ids are generated
  // during install, so do not copy them back into defineConnector({ id }).
  server: {
    transport: "stdio",
    command: "node",
    args: [serverPath],
  },
  // hooks, telemetry, and more surfaces — see "What you define once" below
});

連携の契約は次のとおりです。

1. package.jsonで公開する製品の識別情報（name、mcpName、bin、 version）を定義します。
2. bin.mjsでcreateConnectorCli({ packageJson, connector })を呼び出し、すべての install／doctor／upgrade／uninstall コマンドを開発者のブランドで実行します。
3. agent-connector.config.*でdefineConnector({ server, ...surfaces })を使い、 実際の MCP 起動形式またはリモートエンドポイントを記述します。
4. installは、その宣言を検出された各ホストのネイティブな MCP 設定に反映します。stdio プロセスの場合、ホストは安定した agent-connector ホームバイナリを参照します。このバイナリが 実際のコマンドを起動し、ツールごとのトラフィックを計測できます。リモート HTTP サーバーの場合、 対応しているホストには URL が設定されます。ラップする stdio プロセスはありません。

コマンド境界

2 つのコマンドレイヤーを分けてください。

レイヤー	実行する人	例	目的
ブランド化された MCP ライフサイクル	MCP パッケージのユーザー	npx @acme/acme-db-mcp install、acme-db doctor --probe、acme-db upgrade、acme-db uninstall、acme-db telemetry report --by tool	お使いの MCP をインストール、検証、更新、削除し、テレメトリを調べます。
フレームワークのツール	MCP パッケージの開発者	npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs	コネクター設定から、ホストのプラグインバンドルと MCP 配布用アーティファクトを生成します。
コネクター不要のユーザーテレメトリ	MCP パッケージを使用しない Agent-CLI ユーザー	npx @ken-jo/agent-connector usage report --by platform	会話全体のトークン合計を確認するため、ホストの CLI ログを読み取り専用で読み込みます。

作成後の MCP を操作するコマンドには、ブランド化されたパッケージまたは実行ファイルを使用してください。 フレームワークの配布用アーティファクトをビルドするコマンドには、フレームワーク CLI を使用してください。

MCP サーバーの起動例

構築する MCP に合った server の形式を選んでください。ラッパーパッケージの識別情報は引き続き package.json から取得されます。これらの例では、実際の MCP サーバーを起動または接続する方法のみを説明します。

形式	用途	最小限の起動方法
パッケージランナー型 MCP	MCP がパッケージとして公開されている場合。	npx -y @acme/acme-db-mcp
ローカルサーバープロセス型 MCP	MCP サーバーがパッケージ内に含まれている場合。	node ./my-mcp-server.mjs
Python MCP	MCP サーバーが Python 製で、起動時にランタイム依存関係を解決する場合。	uv run --with mcp ./my_mcp_server.py
CLI ベースの MCP	既存の実行ファイルが MCP サービングモードを提供している場合。	local-tools mcp serve
リモートサーバー型 MCP	MCP が HTTP エンドポイントの背後でホストされている場合。	https://mcp.example.com/mcp

以下の各スニペットは defineConnector({ ... }) の server フィールドです。インラインで示す serverPath ヘルパーが必要なのは、ローカルサーバープロセスの例だけです。

パッケージランナー型 MCP — npx で起動する公開済みパッケージ：

server: {
  transport: "stdio",
  command: "npx",
  args: ["-y", "@acme/acme-db-mcp"],
}

ローカルサーバープロセス型 MCP — バンドルされたサーバーファイルまたはバイナリ：

import { fileURLToPath } from "node:url";

const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

server: {
  transport: "stdio",
  command: "node",
  args: [serverPath],
}

Python MCP — 通常は uv 経由で実行し、サーバーとともに依存関係を解決します：

server: {
  transport: "stdio",
  command: "uv",
  args: ["run", "--with", "mcp", "./my_mcp_server.py"],
}

ランタイム環境がパッケージまたはデプロイラッパーによってすでに管理されている場合に限り、python ./my_mcp_server.py を直接使用してください。

CLI ベースの MCP — 既存の実行ファイルが MCP モードを提供している場合：

server: {
  transport: "stdio",
  command: "local-tools",
  args: ["mcp", "serve"],
}

リモートサーバー型 MCP — ホストされた MCP エンドポイント：

server: {
  transport: "http",
  url: "https://mcp.example.com/mcp",
}

# 4. deploy under your branded MCP package/bin
npx @acme/acme-db-mcp detect            # which platforms are installed here?
npx @acme/acme-db-mcp audit             # catch package/bin/connector identity drift
npx @acme/acme-db-mcp install --dry-run # preview every change first
npx @acme/acme-db-mcp install           # write native config in each host

install が対象にするのは、このマシンで実際に検出されたホスト（または明示的に指定した --targets / connector.targets のリスト）のうち、/coverage に表示されている現在のアダプターレジストリにも含まれるものだけです。「すべてのホストに無条件でインストールする」方法はありません。 @ken-jo/agent-connector は基盤となるフレームワーク依存関係です。フレームワークのパッケージ化やデバッグ、またはコネクター不要のトークンテレメトリには直接使用してください。ユーザー向けのインストールブランドとして前面に出すものではありません。

配布する：直接インストールまたはマーケットプレイスプラグイン

定義は同じで、配布方法を選べます。

直接インストール — ブランド化されたコマンド（acme-db install、npx @acme/acme-db-mcp install）は、プラットフォームごとのマーケットプレイスへの申請や審査なしで、各ホストのネイティブな MCP、フック、コンテンツサーフェスの設定をその場で書き込みます。上記のクイックスタートで説明した方法です。

配布物の取り込みをテストする場合は、フレームワークのフォールバックを使ってコネクターソースを直接インストールすることもできます。ソースには github:owner/repo、npm:@scope/package@version、または archive: / 直接指定の .tgz / .zip を使用できます。取得したソースはすべて ~/.agent-connector/sources/ にキャッシュされ、agent-connector.config.* を含んでいる必要があります。 マーケットプレイスプラグイン — フレームワークの package コマンドを使うと、1つの定義からコネクターを実際のプラグイン／拡張機能バンドル（マニフェストと、バンドルされたコマンド、エージェント、スキル、フック、MCP）に変換できます。これはフレームワークのツールなので、npx @ken-jo/agent-connector package --connector ... で実行してください。フレームワークの CLI をすでにグローバルにインストールしている場合は、agent-connector package --connector ... と短く記述できます。フックと MCP はテレメトリー用のサーブラッパーを維持するため、マーケットプレイスからインストールしたコネクターでも、stdio サーバーのツールごとのトークン数が報告されます。--format all は9種類のホスト形式を出力します。ポータブルでベンダーに依存しない Agent Plugins 1.0.0 パッケージ（デフォルト）と、仕様に対応していないホスト向けの8種類のホストネイティブバンドルです。

形式	ホスト
agent-plugin	Agent Plugins 1.0.0（デフォルト — 1つのバンドルが唯一の信頼できる情報源）：Codex · GitHub Copilot CLI · VS Code / JetBrains Copilot · Kiro · Hermes · Cursor · OpenClaw · …
claude-plugin	Claude Code · OpenClaw · OMP
factory-plugin	Droid
gemini-extension	Gemini CLI
qwen-extension	Qwen Code
agy-plugin	Antigravity（CLI + IDE）
cursor-plugin	Cursor
kimi-plugin	Kimi CLI
npm-plugin	OpenCode · Kilo CLI · Pi

agent-plugin は、仕様に対応するすべてのホストで唯一の信頼できる情報源です。 オープンな Agent Plugins 仕様（Vercel が主導し、AWS、Cursor、GitHub、Microsoft、OpenAI が共同で保守）に準拠しています。ルートの plugin.json、mcp.json（stdio と リモートの streamable-http／sse サーバー）、および準拠するあらゆるクライアントがインストールできる skills/ を備えています。フック、スラッシュコマンド、サブエージェントはポータブルな v1 コンポーネントではないため、1つのバンドル内でクライアント拡張名前空間ごとに提供します。具体的には com.github.copilot/（Copilot CLI、VS Code、JetBrains）と com.openai/（マニフェストの extensions ブロック経由で Codex に接続）です。クライアントは自身が所有しない名前空間を無視します。Codex と GitHub Copilot CLI の install --method marketplace ドライバーは、このバンドルをそのままステージングします（codex 0.149 + Copilot CLI 1.0.80 で実機検証済み）。VS Code は CLI がインストールしたものを自動検出します。この仕様ではコマンドの絶対パスが禁止されているため、バンドルには実行時にランタイムを解決する小さな bin/agent-connector.mjs ランチャーが含まれます（ホームのバイナリ → PATH → npx）。テレメトリーを引き継ぐためにグローバルインストールは不要です。廃止された codex-plugin／copilot-plugin の名前も引き続き解析され、このバンドルを出力します。

公式のMCP 標準アーティファクト2種類は、オプトインで利用できます（publish ブロックが必要なため、--format all の対象外です）。mcp-server-json（MCP Registry の server.json）と mcpb（ワンクリックでインストールできる MCPB バンドル）です。詳しくはMCP エコシステムへの公開を参照してください。

# emit every host format (mcp-server-json + mcpb are opt-in by name)
npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin
npx @ken-jo/agent-connector package --connector ./agent-connector.config.mjs --format gemini-extension --out ./ext   # or just one

# if you already keep the framework CLI globally installed, the same command is:
agent-connector package --connector ./agent-connector.config.mjs --format all --out ./dist-plugin

# e.g. Claude Code:  /plugin marketplace add ./dist-plugin/claude-plugin
#                    /plugin install <connector-id>@agent-connector
# e.g. Gemini CLI:   gemini extensions install ./dist-plugin/gemini-extension/<id>

埋め込みパスに関する注意点。 ほとんどのホストバンドルには、package を実行したマシンのホームディレクトリーにあるバイナリーへの絶対パスがランチャーとして埋め込まれるため、同じマシン／ホームディレクトリーへのローカルインストールで有効です。共有配布には agent-plugin、npm-plugin、または MCP 標準アーティファクトを使用するか、マシンごとに package を再実行してください。

install --method marketplace を使うと、ブランド化された MCP パッケージから、ホスト独自のインストールフローを実行できます。

acme-db install --method marketplace

# framework fallback for local framework development/debugging only
npx @ken-jo/agent-connector install --method marketplace --connector ./agent-connector.config.mjs

• 動作内容 — バンドルをステージングし、ホストがローカルマーケットプレイスに対応している場合はそれを登録してから、ホストのプラグインインストールコマンドを実行します（npm プラグインホストでは、ローカルの file:// エントリを書き込みます）。ヘッドレスで冪等です。その他のマーケットプレイス形式のホストでは、正確な手動コマンドを出力します。
• ホスト対応状況 — Linux、Windows、macOS で、Claude Code、Codex、OpenCode、Kilo（CLI + ext）、Antigravity（CLI + IDE）を実機で検証済みです。Droid と Qwen Code はドライバーを同梱済みですが、実機のホストでの検証待ちです。Gemini CLI はレガシー扱いです（Antigravity への移行に伴い終了予定ですが、既存のインストール向けにドライバーを保持しています）。
• 安全性 + 元に戻す方法 — 同じコネクターを両方の方法でインストールしようとするとガード機能が拒否します。uninstall --method auto はインストール済みの方法に応じて元に戻し、doctor は登録のずれを確認します。

ブランド付き CLI を提供する

コネクター開発者は、ユーザーに agent-connector と入力させる代わりに、独自の bin を提供できます。createConnectorCli({ packageJson, connector })（@ken-jo/agent-connector/cli エクスポートから）は、package.json から bin 名とバージョンを取得し、すべてのサブコマンドを独自ブランドで公開します。コネクターのスコープが自動設定され、委譲されるため、ユーザーはブランド付き MCP のインストール、doctor、アンインストールにフレームワークのグローバルインストールや --connector を指定する必要がありません。実行可能なパッケージ全体については、examples/branded-cli を参照してください。

#!/usr/bin/env node
// bin.mjs — every agent-connector subcommand, branded as `acme-db`
import { createConnectorCli } from "@ken-jo/agent-connector/cli";

// run() resolves to the exit code and never calls process.exit
process.exitCode = await createConnectorCli({
  // packageJson supplies public identity: name, mcpName, bin, version.
  packageJson: new URL("./package.json", import.meta.url),
  // connector supplies behavior: server, hooks, skills, telemetry.
  // These are two layers, not duplicate id/display-name inputs.
  connector: new URL("./agent-connector.config.mjs", import.meta.url),
}).run();

利用者があなたのパッケージをインストールすると、acme-db bin が PATH に追加され、すべてのコマンドがあなたのコネクターのスコープで実行されます（acme-db install ≈ agent-connector install --connector ./agent-connector.config.mjs）。スコープの自動設定は、同じ単一のホームバイナリに引数を追加するだけの仕組みです。serve と hook は引き続き、すべてのホスト設定が参照する単一の ~/.agent-connector ホームバイナリを経由します。明示的な --connector / --connector-id は、常に追加されたデフォルト値より優先されます。

一度だけ定義する内容

単一の defineConnector({...}) で、MCP サーバーとライフサイクルフックを宣言し、必要に応じて追加の機能面であるコマンド、スキル、サブエージェント、メモリ、ステータスライン、アクション、およびホスト固有の拡張機能も宣言します。agent-connector は各機能面を検出されたすべてのホストのネイティブ形式に変換します。ホストがサポートできない場合は、黙って破棄することなく、スキップした旨を警告します。

import { fileURLToPath } from "node:url";
import { defineConnector } from "@ken-jo/agent-connector/sdk";

// Resolve your server to an absolute path — host CLIs spawn it from their own CWD.
const serverPath = fileURLToPath(new URL("./my-mcp-server.mjs", import.meta.url));

export default defineConnector({
  server: {
    transport: "stdio",
    command: "node",           // or "npx", "python", etc. — whatever starts your server
    args: [serverPath],        // replace with your real server entrypoint
    env: { ACME_DB_DSN: "${env:ACME_DB_DSN}" },
  },
  hooks: {
    PreToolUse: {
      matcher: "acme_write",
      async handler(evt) {
        return evt.toolName === "acme_write"
          ? { decision: "ask", reason: "Confirm write" }
          : { decision: "allow" };
      },
    },
  },
  // telemetry is on by default
});

npx @acme/acme-db-mcp install を実行すると、たとえば次のように設定されます。

ホスト	書き込まれる内容
Claude Code	~/.claude.json → mcpServers.acme-db（+ ~/.claude/settings.json のフック）
Codex CLI	~/.codex/config.toml → [mcp_servers.acme-db]（+ ~/.codex/hooks.json）
Cursor	~/.cursor/mcp.json → mcpServers.acme-db（+ ~/.cursor/hooks.json）

…フックはそれぞれ単一の安定したホームバイナリを参照するため、更新はすべての場所に反映されます。

シークレットの環境変数参照（${env:VAR}）。 command / args / env / url / headers のどこにでも "${env:VAR}"（または "${env:VAR:-default}"）と記述すると、環境変数を参照できます。

ネイティブ補間と、インストール時のリテラル解決

ネイティブ補間に対応するホスト（Claude Code、Cursor、VS Code Copilot、 amp、codebuff）では、トークンがホスト設定にそのまま書き込まれ、実行時に解決されます。 その他のホストはネイティブ補間に対応していないため、値はインストール時にリテラルとして解決されます。デフォルト値のない未設定の変数は空文字列に解決され、install はリテラル解決型のホストに対して警告を出力します。

**OS キーストアのシークレット（`${secret:NAME}`）。** stdio サーバーの `env`（基本設定の `server.env` または `platforms[].server.env` のオーバーライド）に値として `"${secret:NAME}"` を指定すると、ユーザーが `secrets set NAME` で一度保存したシークレットを参照できます。値がホストの設定に渡ることはありません。ホストに見えるのは `serve` ラッパーの `--secret-env NAME={secret:NAME}` プレースホルダーだけです（ホストが展開する形式ではありません）。起動時にラッパーが OS のキーストアから値を読み取り、サーバー自身の環境に注入します。参照先の名前が設定されていない場合（または読み取った値が空の場合）、空の値でサーバーを起動するのではなく、`secrets set` を案内して起動を中止します。参照の周囲にあるテキスト中の `${env:VAR}` は起動時にラッパーによって展開されますが、シークレットの値は展開されません。`install` は未設定の名前ごとに警告し、`doctor` は `: secrets` チェックを報告します。`${secret:…}` はそれ以外の場所（`command`／`args`／`url`／`headers`、リモートサーバー）では拒否されます。名前は `[A-Za-z0-9][A-Za-z0-9._-]{0,63}` に一致し、値は 8192 文字以下の空でない文字列である必要があります。また、`:-default` 形式はありません。

バックエンド	OS	値の保存場所	備考
keychain	macOS	/usr/bin/security 経由のログインキーチェーン：サービス agent-connector/<connector-id>、アカウント <NAME>	キーチェーンがロックされている場合は、GUI セッション（Keychain Access またはデスクトップへのログイン）が必要です。agent-connector が unlock-keychain を実行することはありません。
secret-service	Linux	secret-tool 経由の freedesktop Secret Service（GNOME Keyring および互換デーモン）	D-Bus と実行中のデーモンが必要です。いずれかが利用できない場合、secrets check がその旨を示し、--backend file を案内します。
credential-manager	Windows	PowerShell 経由の Credential Manager：ターゲット agent-connector/<connector-id>/<NAME>	OS の BLOB 制限により、値は 2560 バイト（1280 UTF-16 文字）までです。
file	すべて	~/.agent-connector/secrets/file-store.json（ディレクトリは 0700、ファイルは 0600）	オプトインの平文保存であり、暗号化されません（--backend file または AGENT_CONNECTOR_SECRETS_BACKEND=file）。キーストアのない CI 環境やヘッドレスホスト向けです。

secrets set は、--backend または AGENT_CONNECTOR_SECRETS_BACKEND（keychain|secret-service|credential-manager|file|auto）で別の指定がない限り、OS ネイティブのバックエンドに書き込みます。各名前を保持するバックエンドは ~/.agent-connector/secrets/<connector-id>.index.json に記録され（名前のみで、値は記録されません）、読み取り時にはその記録に従います。値は非表示のプロンプトまたは --stdin から受け取ります（--value フラグはないため、シェルの履歴やプロセス一覧に値が残ることはありません）。値を出力するコマンドはありません。 OAuth ログイン（oauth.<key>）。 OAuth 2.0 API と通信するサーバーは、プロバイダーを oauth.<key> の下で宣言します — oauth: { google: { provider: "google", clientId: "1234-abcd.apps.googleusercontent.com", clientSecret: "${secret:google-client-secret}", scopes: ["https://www.googleapis.com/auth/webmasters.readonly"] } } — そしてユーザーは auth login <key> で一度だけ認証します。ブラウザーのループバックフロー（PKCE S256、127.0.0.1 で 1 件のリクエストを受け付けるリスナー）を使うか、ブラウザーを開けない場合は、プリセットが対応していればデバイスコードのプロンプトを使います。リフレッシュトークンは、OS のキーストア内にあるコネクターの名前空間に oauth.<key>.refresh-token として保存されます（secrets set が書き込むのと同じストアです）。サーバーは SDK から getAccessToken({ connectorId, key }) を呼び出してアクセストークンを発行します。トークンを更新し、有効期限の 60 秒前までプロセスメモリにキャッシュし、ローテーションされたリフレッシュトークンを保存します。遅延ログインの場合、保存済みのログイン情報がない状態で呼び出すと、ブラウザーを開けるときはログインを実行し、開けないときは正確な auth login コマンドを示して安全側に失敗します。そのため、ホストプラグインとして（install を使わずに）インストールされたコネクターも、最初のツール呼び出し時にログインできます。アクセストークンが存在するのはプロセスメモリ内と auth token <key> の標準出力だけです。それ以外でトークン、認可コード、クライアントシークレットが出力されることはありません。また、ホスト設定、パッケージマニフェスト、非機密のメタデータファイル ~/.agent-connector/oauth/<connector-id>.json にトークンが含まれることもありません。install はログインが不足している項目ごとに警告し、doctor は <id>: logins チェックを報告します（どちらもネットワーク通信は行いません）。プリセットが提供するのはエンドポイント、パラメーター、固有の動作のみです。agent-connector はクライアント ID を提供しません。作成者が各プロバイダーにアプリを登録するか、各ユーザーが自分で登録します。開発者が用意する方法：シークレットを伴わないリテラルの clientId（パブリッククライアント）、google に限ったリテラルの clientSecret（Google はインストール済みアプリのクライアントシークレットを機密情報ではないと説明しています）、または tokenExchangeUrl — クライアントシークレットを保持し、すべてのトークンリクエストをプロバイダーに転送する、開発者独自の https トークン交換サービス（コネクターが送信するのは client_id であり、シークレットは送信されません。ワイヤーコントラクトは llms-full.txt §2.2 に記載されています）。それ以外のすべてのプリセットでは、clientSecret は ${secret:NAME} 参照にします。ユーザーが登録する方法：clientId: "${secret:NAME}" と clientSecret: "${secret:NAME}" — 各ユーザーが自分のアプリを登録し、secrets set で両方を保存します。また、install、doctor、auth login は、まだ実行が必要な secrets set コマンドを示します。${env:VAR} のクライアント ID は、ログイン時とトークン更新時にプロセス環境から展開されます。ホストから起動されたサーバーはプロセス環境を参照できず、シェルのエクスポートを継承しないためです。examples/seo-connector は、Google Search Console、Bing Webmaster Tools、PostHog の 3 つのログインを備えた実行可能なサーバーで、3 つすべての方法を示し、トークン交換サービスのサンプルも提供します。プロバイダーごとの登録表は運用ガイドにあります。

プリセット	プロバイダー	フロー	備考
google	Google APIs (OAuth 2.0 / OpenID Connect)	loopback	リフレッシュトークンが返されるように、access_type=offline と prompt=consent を追加します。flow: "auto" ではデバイスグラントにフォールバックしません（Google の入力制限付きグラントでは、Search Console などの API スコープが対象外です）。明示的に flow: "device" を指定すると実行されます。リテラルの clientSecret も受け付けます（Google は機密情報ではないと説明しています）。
microsoft	Microsoft identity platform (Entra ID and personal accounts)	loopback, device	options.tenant でテナントを選択します（既定値は common）。offline_access スコープを要求しないと、リフレッシュトークンは返されません。パブリッククライアントのため、必要なのは clientId のみです。
github	GitHub Apps and OAuth Apps	loopback, device	リフレッシュトークンを取得するには、有効期限付きユーザートークン（アプリ設定）または offline_access スコープが必要です。どちらもない場合、ログイン時にトークンが返されなかったことが報告されます。ブラウザーフローにはシークレットが必要です：${secret:…}（ユーザー登録済み）または tokenExchangeUrl。デバイスフローには必要ありません。
bing-webmaster	Bing Webmaster Tools	loopback	リダイレクト URI はポートを含めて完全一致で登録されるため、redirectPort に固定ポートを設定してください。また、Bing の登録フォームでは、ドットの後に英字がないリダイレクト URI は拒否されます（127.0.0.1 と localhost はどちらもチェックに失敗します）。そのため、redirectPath には /callback.html など、ドットを含むパスを設定してください。PKCE はなく、ドキュメントに記載されているレスポンスには state が含まれません（ログインは固定リダイレクト URI のみで紐付けられるため、redirectPort が必要です）。シークレットが必要です：${secret:…}（ユーザー登録済み）または tokenExchangeUrl。
posthog	PostHog	loopback	clientId はアプリの Client ID Metadata Document の URL です。このドキュメントにはリダイレクト URI としてポートなしの http://127.0.0.1/callback が記載されています。クライアントシークレットなしの PKCE を使用します。options.region で us または eu を指定できます。省略した場合は、リージョン非依存の issuer が適切なクラウドにルーティングします。必要なのは clientId のみです。
generic	任意の RFC 8414 / OpenID Connect プロバイダー	loopback, device	検出には issuer を使用するか、authorizationEndpoint と tokenEndpoint を明示的に指定します。デバイスフローには deviceAuthorizationEndpoint が必要です（明示的に指定するか、検出される必要があります）。シークレットはプロバイダーの要件に応じて指定します：不要、${secret:…}（ユーザー登録済み）、または tokenExchangeUrl。

ネイティブフックによる拡張。 正規化された hooks API はクロスプラットフォームイベント 13 種に対応しています。ホスト専用イベント（Claude Code 単体で 30 種を提供）には、platforms: { "claude-code": { nativeHooks: { TaskCompleted: { handler } } } } を宣言します。

未加工ペイロードのセマンティクスと約 14 のパススルー対応ホスト

ハンドラーはホストの未加工ペイロードを受け取り、返した値がそのまま 逐語的な JSON 応答になります（終了コード 0 のみ — 終了コード 2 によるブロックはモデル化されていません）。ホストネイティブのパススルーに対応するホスト：amp、claude-code、continue、 copilot-cli、cursor、gemini-cli、hermes、jetbrains-copilot、kimi、 nemoclaw、omp、openclaw、opencode、qwen-code。その他のホストは警告を出してスキップします。

ホスト設定キーのパッチ。 他の手段では設定できないホスト固有の設定キーには、platforms: { "claude-code": { configPatch: [{ key, value, reason }] } } を宣言します（現時点では Claude Code のみ対応。他のホストでは警告を出してスキップし、手動で行うべき編集内容をそのまま表示します）。

未設定の場合のみ設定 + 参照カウント + 拒否リストのセマンティクス

セマンティクスは固定です：未設定の場合のみ設定し、競合があれば警告を出してスキップします — 上書きも、ディープマージも行いません。所有権は永続化された台帳で参照カウント管理されます。セキュリティに関わるキー、およびエージェントコネクターのモデルがファーストクラスのサーフェスとして扱うキーは、明示的に拒否されます。

### メモリ、ステータスライン、アクション、SDK

• memory（AGENTS.md 標準に準拠）— 各ホストが実際に読み込むメモリ／ルールファイルに、継続的なガイダンスを反映します。 AGENTS.md を採用しているホストには標準ファイルを使用します。Claude Code → CLAUDE.md、Gemini CLI → GEMINI.md のようなホスト固有の例外は、それぞれの公式ドキュメントに従って設定されています。書き込みは、マーカーで囲まれた管理ブロックに対してのみ行われ、ハッシュが付与されます — 複数のコネクターが共存でき、マーカー外のバイト列には一切触れず、アンインストール時には自身のブロックだけを正確に削除します。
• statusline（defineStatusline）— ステータスが更新されるたびにホストから呼び出される、ライブ HUD のレンダリング関数です。SDK はトップレベルおよびホストごとの render(ctx) ハンドラーと、refreshInterval、 respectUserColors、hideContextIndicator、フレームワークによって適用される maxLines などの options をサポートします。現在、Claude Code、 Qwen Code、Antigravity CLI 向けにコマンド駆動のステータスラインを登録します（未設定の場合のみ設定し、参照カウントに対応し、元に戻せます）。 コネクター所有のコマンドではなく、組み込みプリセットのみをステータスラインとして使うホストは、引き続き警告を出してスキップします。ランタイムはフェイルセーフです。エラーが発生すると、HUD によってホストが停止しないよう、終了コード 0 と空の標準出力で終了します。
• actions（defineAction）— agent-connector action <platform> <id> --connector <id> という共通コマンドで実行される、名前付きのユーザー呼び出し可能な操作です。 アクションでは、label、icon、placement、confirm と、ユーザー向けメタデータまたは run(ctx) のホストごとのオーバーライドを宣言できます。install は droid、hermes、kiro、nemoclaw、omp、openclaw、pi、 warp、zed にホスト側の実行手段を追加します。アダプターの機能情報から、その実行手段が exec コマンド、exec-file、手動フックパネル、貼り付けワークフロー、プラグインコマンド、タスクのいずれかを確認できます。他のホストは警告を出してスキップします。エラーはユーザー起動時に処理されます（不明な ID または例外の発生時は終了コード 1）。
• Connector SDK（@ken-jo/agent-connector/sdk、/sdk/test）— 統合された作成者向けインターフェイスです。defineConnector、define* ファミリー全体（defineHook、defineCommand、defineSkill、defineSubagent、 defineMemory、defineStatusline、defineAction、defineConfigPatch、 defineNativeHook）、イントロスペクションヘルパー（hostsSupporting、 capabilitiesOf、surfaceSupport）、およびオフラインハーネス （simulate、explain、explainHooks）を再エクスポートします。オフラインハーネスは、実際のアダプターの parse→handler→format チェーンを実行するため、実際のホストに触れる前に*「自分のハンドラーはホスト X で本当に動作するか？」*を確認できます。エージェント向けガイダンスは、小さなルータースキルと、skills/agent-connector/references にある用途別のリファレンスに意図的に分けています。詳しくは docs/ARCHITECTURE.md を参照してください。

仕組み

• ホームディレクトリにインストールする単一バイナリ。 ランタイムは ~/.agent-connector に一度だけインストールされます （AGENT_CONNECTOR_DATA_DIR で変更できます）。書き込むホスト設定はすべて、 この単一バイナリを参照する薄いポインターです。更新は 明示的に管理され（agent-connector upgrade）、サイレントな自動更新は行われません。
• プロジェクトごとのデータを保持。 テレメトリ／状態は安定したプロジェクト ID（git リモートまたは正規化されたパス）にひも付き、プロジェクトごとに 分割されてホームのデータルートに保存されます。そのため、git clean を実行しても 保持され、同じプロジェクトを開く複数のホスト間で共有されます。
• ネイティブ設定はそのまま。 ホスト独自の設定ファイルの場所は変更せず、 フレームワークが所有する状態のみをデータルートに保存します。
• Windows を優先した正確性。 シンボリックリンクは使わず、POSIX 固有の 前提に依存しません。

3 つのフック方式はすべて、登録済みプラットフォーム全体でインストールを 検証済みです（/coverage および docs/ARCHITECTURE.md を参照）。

方式	プラットフォーム
json-stdio（完全なフックディスパッチ）	CodeBuddy · Claude Code · Codex CLI · Cursor · VS Code Copilot · JetBrains Copilot · GitHub Copilot CLI · Gemini CLI · Qwen CLI · Kiro · Kimi CLI · Crush · Goose · Hermes · Droid (Factory) · OpenHands · Antigravity · Antigravity CLI · Continue · Amazon Q · Grok Build · Grok CLI · Devin CLI · Open Interpreter
mcp-only（MCP 登録のみ）	Warp · Cline · Trae · Zed · Freebuff · Xum · Pi · Windsurf · Junie · Mistral Vibe
ts-plugin（生成されたブリッジモジュール）	OpenCode · MiMoCode · Kilo CLI · Kilo · OMP · NemoClaw · OpenClaw · Amp

プラットフォームの追加は、レジストリエントリー 1 つとアダプター 1 つで行えます。

CLI

コマンド	目的
detect	インストール済みのプラットフォーム、スコープ、機能、フックの方式を一覧表示します。
install [<source>] [--scope …] [--targets …] [--method …] [--dry-run] [--force]	MCP、フック、コンテンツの各サーフェスを生成して書き込みます。<source> には、ローカル、GitHub/git、npm:<package>[@version]、または .tgz/.zip/archive: を指定できます。
uninstall [--targets …] [--purge] [--method …]	完全に元に戻します。書き込んだものをすべて削除し、--purge を指定するとフレームワークの状態も消去します。
upgrade [--channel …]	ホスト設定を再生成し、古いポインターを修復して、ホームのバイナリを更新します（エイリアス：update、sync）。doctor のすべてのバージョン警告を解消します。サイレントな自動更新は行いません。
doctor [--probe] [--heal] [--explain] [--json] [--dry-run]	プラットフォームごとのヘルスチェックと修正に加え、バージョンチェックを行います。ホームのバイナリの対象インストールと、各コネクターのレンダリングフレームワークのバージョンを、実行中の CLI と比較します（不一致の場合は警告し、upgrade を案内します）。--probe は MCP のハンドシェイクをライブで実行し、--heal は修正可能なすべての検出結果を再同期し、--explain は (host, event) ごとのフック適用状況マトリクスを表示します。
status	インストール状態を簡易表示します。どのホストにどのコネクターが存在するかを示します（常に終了コード 0 で終了します）。
secrets set|delete|list|check [<name>] [--backend keychain|secret-service|credential-manager|file] [--stdin] [--json]	コネクターが ${secret:NAME} として参照するシークレットを、OS のキーストアに保存します。macOS Keychain（keychain）、Linux Secret Service（secret-service）、Windows Credential Manager（credential-manager）、またはオプトイン方式の平文 file ストアを利用できます。set は非表示のプロンプトまたは --stdin から値を読み込みます（--value フラグはありません）。list は名前／バックエンド／有無を表示し、check は読み書きのセルフテストを実行します。値が表示されることはありません。
auth login|status|logout|token [<key>] [--device|--loopback] [--port <n>] [--json]	コネクターが oauth.<key> で宣言する OAuth 2.0 プロバイダーにログインします（プリセット：google、microsoft、github、bing-webmaster、posthog、generic）。login はブラウザーのループバックまたはデバイスコードのフローを実行し、更新トークンを OS のキーストアに保存します。status はキー／プロバイダー／有無を表示します（ログインがなくても失敗しません）。logout は可能な場合にプロバイダー側でトークンを失効させ、トークンを削除します。token は新しいアクセストークンを標準出力に表示します。トークンを表示するのはこのコマンドだけです。
package [--format <fmt>|all]	ホストプラグインバンドル、または公式標準アーティファクトを出力します：mcp-server-json（レジストリ）· mcpb（ワンクリックバンドル）。
audit [--strict]	インストール前にパッケージの識別情報を検査します。パッケージ名／バージョン／バイナリ、ランタイム依存関係、コネクター ID／バージョンの不一致、公開時の files の網羅性を確認します。
action <platform> <id> [--connector <id>]	宣言済みのアクションをシェルから実行します。
telemetry report [--by …] [--since …] [--connector <id>]	ラップしたサーバーのうち、自分のコネクターが所有するものについて、ツールごとのトークン使用量を表示します。stdio サーバーのみ対応します。
telemetry export [--format …] [--connector <id>]	ラップしたサーバーの未加工の集計レコードを出力します。
usage report|export|leaderboard [--by …]	**コネクターは不要です。**各エージェント CLI 独自のログから読み取り専用で解析した、ホストネイティブの会話全体のトークン合計です。個別の MCP やツールごとの内訳は表示されません。
leaderboard [--since …] [--connector <id>] [--scope …]	起源をラベル付けした 3 種類のボードを表示します。それぞれ必要条件が異なります（🔌 MCP／プラグイン · 🛰️ ホストネイティブのターン · 🖥️ ホスト／ユーザー）。これらの間で件数を合算することはありません。

hook と serve も存在します。作成されるホスト設定が参照する内部エントリーポイントであり、手動で実行することはありません。フラグの詳細なリファレンスについては、ドキュメントサイトの /docs/dev/cli · llms-full.txt §3（正準仕様。テストで差異を検出します）をご覧ください。

何か問題がありますか？ドキュメントサイトの /docs/dev/troubleshooting のページでは、doctor の出力と終了コードの読み方、よくある ConnectorConfigError メッセージ、MCP 専用ホストで「hooks unavailable here」と表示される場合、 telemetry report に何も表示されない理由について説明しています。

トークンのテレメトリーと使用状況

トークンコストを示す、互いに独立した 2 つのビューです。合算はされません。

• 自分のサーバーのツールごとのテレメトリー（MCP 開発者向けの方法）。ホストから MCP サーバーにツールごとの使用状況が報告されることはないため、agent-connector はサーバー自体のバイト数（入力された引数、出力された結果、ツールスキーマ）を計測し、ローカルでトークン化します。集計数のみをローカルに保存し、デフォルトでは外部に一切送信しません。 ツールごとのテレメトリーは stdio サーバーでは自動的に有効になります。リモート（http／sse／ws）サーバーは登録されますが、ラップされません（プロキシはリモートトランスポートをインターセプトできません）。agent-connector telemetry report --by tool で確認できます。

• コネクター不要の使用状況（agent-connector usage）。Claude Code／ Codex／Cursor をすでに実行していて、合計だけを知りたい場合は、usage でローカルのエージェント CLI セッションログを読み取り専用で参照します。ホスト設定への書き込みはなく、コネクターもインストールも不要です。

  npx @ken-jo/agent-connector usage report --by platform        # CLI/model/project/session/day
  npx @ken-jo/agent-connector usage leaderboard --by platform   # or --by model
  npx @ken-jo/agent-connector usage export --format csv --out usage.csv
  

  エージェントホスト／モデル／プロジェクト／セッション／日ごとの会話全体の合計を報告します。個々の MCP サーバーやツールごとのコスト内訳は表示しません。エージェントホストはツールごとの内訳を記録しないためです。

プライバシーとトークナイザー。 デフォルトのトークナイザーは gpt-tokenizer（純粋な JavaScript 製で、ネイティブビルド不要）です。OpenAI／Codex 系では o200k_base を、Anthropic ではドキュメントに記載された近似値を使用します。読み込みに失敗した場合は、chars/4 のヒューリスティックにフォールバックします。すべてのレコードには信頼度タグが付与されます。生のツール引数や結果が保存・送信されることはありません。無効にするには、AGENT_CONNECTOR_TELEMETRY=0 または telemetry: { enabled: false } を設定します。

MCP エコシステムへの公開

MCP 標準ですでにサーバーの機能がカバーされている場合、agent-connector は標準に厳密に準拠した形式で出力するため、すでに標準に準拠している成果物を移植できます。

• package --format mcp-server-json → MCP Registry 公式の server.json（スキーマ 2025-12-11）。レジストリのインストーラーが実行する、テレメトリーラッパーではない実際のアップストリームサーバーを記述します。公式の mcp-publisher CLI で公開します。
• package --format mcpb → 公式の MCPB（.mcpb、旧称 DXT） バンドルの manifest.json（manifest_version 0.3）。シークレットはホストのキーチェーン経由（user_config）で扱われ、Claude Desktop や MCPB ホストでワンクリックのローカルインストールが可能です。

どちらも、コネクターの publish ブロック（所有する名前空間、公開するパッケージ、作成者）を読み取ります。

defineConnector({
  server: { transport: "stdio", command: "npx", args: ["-y", "@acme/acme-db-mcp"] },
  publish: {
    registryNamespace: "io.github.acme", // a namespace YOU proved ownership of
    packageName: "@acme/acme-db-mcp",     // your REAL published package
    author: { name: "Acme Inc" },
  },
});

書き込む設定は標準形式です。 install は各ホストのネイティブな MCP 設定を、事実上の標準である mcpServers 形式で書き込みます。stdio では { command, args, env }、リモートでは { url, headers } です。ストリーム可能な HTTP の仕様上のトランスポートスラッグは streamable-http（レジストリの server.json）ですが、ホスト設定では標準的に http を使います。WebSocket（ws）は MCP 仕様のトランスポートではないため、標準形式の成果物では拒否されます。

トランスポートによる前方互換性。 serve プロキシはバイト透過です。すべての JSON-RPC メッセージをそのまま転送し、tools/call の往復を計測するためにコピーを複製するだけです。そのため、新しい MCP 機能も変更されずに通過します。公式の io.modelcontextprotocol/ui 拡張である MCP Apps や、initialize でネゴシエートされるあらゆるリバース DNS 拡張も同様です。サーバーがこれらに対応しているコネクターは、すべてのホストにデプロイでき、現時点でもテレメトリーを維持できます。agent-connector の変更は不要です。

検証

単一 API の契約全体は、コミット済みのレジストリ駆動型インストール往復テストハーネスによって、現在のプラットフォームレジストリ全体でインストール検証されています。このハーネスはすべてのアダプターについて、実際のインストールからアンインストールまでを隔離された HOME 内で実行し、ディスク上の配置と残存物がないことを検証します。これとは別に、コミット済みの scripts/verify-host.mjs ドライバーが検証マトリックスに記載された実際のホスト CLI をインストールし、インストール → 配置 → クリーンなアンインストールを確認します。ヘッドレスで実行できるホストでは、実際のモデルまたはコミット済みのローカルモックモデルプロバイダー（scripts/README.md）を使って、フックのライブディスパッチとテレメトリーをエンドツーエンドで検証します。ヘッドレス CLI を持たない IDE 拡張機能や GUI エディターは、インストール往復テストハーネスで引き続きカバーされます。

実測フットプリント。 実行可能なサンプル（examples/acme-db は、MCP サーバー、PreToolUse + SessionStart フック、ステータス行、アクションを宣言する 135 行の defineConnector()）を、専用の bin から隔離された HOME に、登録済みホストごとに 1 回インストールし、そのディスク上に作成されたファイルを数えます。その数値は上記の数字で見るに記載されています。すべてのホストで、サンプルはユーザースコープまたはプロジェクトスコープにインストールされます。tests/docs/readme-footprint.test.ts は実行のたびに測定し、README に異なる数値が記載されている場合は失敗します。npm run measure:footprint を実行すると、同じ JSON が出力されます。

開発

npm install
npm run typecheck
npm run build
npm run dev -- detect     # run the CLI from source via tsx

# Tests: scope + single-fork (useful on low-RAM machines).
npm run test:single -- tests/adapters/<host>.test.ts

コントリビューション

PR を歓迎します。特に、新しいホストアダプターや、ホストの一次情報に照らして検証された修正を歓迎します。開発ワークフロー、単一フォークのテスト規律、アダプターの先に検証するルール、新しいホスト向けチェックリストについては、CONTRIBUTING.md をご覧ください。新しいエージェントホストへの対応を希望しますか？ホストアダプターのリクエストを作成してください。

セキュリティに関する報告については、SECURITY.mdをご覧ください。

ライセンス

Apache-2.0 © 2026 KenJo