Skip to main content
Glama
AgentPickLink

AgentPickLink

README.md
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="media/readme-header-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="media/readme-header-light.png">
  <img alt="AgentPickLink for M365" src="media/readme-header-dark.png" width="100%">
</picture>

# AgentPickLink for M365

[日本語](release-docs/README.md) | [English](README.en.md)

**v0.2.17 Beta** — VS Code から、利用を承認した Microsoft 365 エージェントへ質問するためのローカル MCP ブリッジです。

Microsoft 365 にサインインしてエージェントを選び、ワークスペース単位で利用を承認すると、MCP 対応の AI クライアントから質問できるようになります。回答テキストや引用に加え、エージェントが生成したファイルを保存できます。

AgentPickLink は **MIT ライセンスのオープンソースソフトウェア(OSS)** です。利用している第三者ソフトウェアには、それぞれのライセンスが適用されます。

本ソフトウェアは Microsoft の公式製品ではありません。ベータ版のため、Microsoft 365 の画面変更やテナントの設定によって接続・取得に失敗する場合があります。

## v0.2.17 の主な変更

**ベータ版を含む自動更新は、初期値で有効です。** 既定の `beta` チャネルでは、新しいベータ版も取得・検証して自動インストールします。インストール後は VS Code を再読み込みしてください。

- 添付ファイルの確認中に変化した回答を再確認し、会話作成のキャンセル時にページを閉じます。
- セットアップで編集した別名を保存し、MCP の一覧に反映します。
- CLI とポータブル版で VS Code Insiders のユーザー設定に対応しました。
- サイドバーで更新チャネルとローカル MCP の接続状態を確認できます。
- ポータブル版の同梱 Node.js を 24.22.2 に更新しました。

詳細と更新時の注意点は [リリースノート](release-docs/CHANGELOG.md) を参照してください。

## 利用環境

- ローカルの VS Code 1.101 以降と、単一フォルダのワークスペース。
- Windows 11 と Microsoft Edge を主な対象としています。macOS は開発・検証向けで、Edge または Google Chrome を使用します。
- 対象エージェントを利用できる Microsoft 365 の職場または学校アカウント。必要なライセンス・利用権限は別途用意してください。
- MCP に対応した AI クライアント。

Node.js を別途インストールすると実行環境を明示できます。npm・ソースビルドの要件は、22系では22.22.2以降、24系では24.15.0以降、または26以降と npm です。未導入の場合、拡張機能は VS Code 内蔵ランタイムの利用を試みます。古い内蔵ランタイムでビルド証明を検証できない場合は、手動更新を案内します。

WSL、Remote SSH、Dev Containers、Codespaces、複数ルートのワークスペース、リモート MCP サーバー、無人実行は対象外です。すべての Microsoft 365 エージェントや画面構成への対応を保証するものではありません。

Windows・macOS・Ubuntu の自動テストを公開 CI で実行します。Ubuntu は開発・CI 専用の検証対象で、通常利用の対象外です。実際の Microsoft 365 テナントと VS Code 画面での確認は CI に含まれません。詳しくは [対応環境と検証範囲](release-docs/RELEASE-CHECKLIST.md) を参照してください。

## インストール

1. GitHub の **Releases → v0.2.17 (Beta)** で `agent-pick-link-0.2.17.vsix` をダウンロードします。
2. VS Code のコマンドパレットから **Extensions: Install from VSIX… / 拡張機能: VSIX からのインストール…** を実行し、ダウンロードしたファイルを選びます。
3. 再読み込みを求められた場合は、VS Code を再読み込みします。

ターミナルからもインストールできます。

```sh
code --install-extension agent-pick-link-0.2.17.vsix
```

VSIX には拡張機能、CLI、ローカル接続プロセス、MCP サーバーを同梱しています。npm パッケージや Marketplace からのインストールは、このベータ版の配布手順には含みません。

### 以前の版からの更新

同じ手順で v0.2.17 の VSIX をインストールし、VS Code を再読み込みしてください。既存の設定・ワークスペース承認・専用ブラウザープロファイルはそのまま利用できます。パネルで接続状態を確認し、必要に応じて **接続して更新 / Connect and refresh** を実行してください。外部 AI クライアントの MCP 接続も再起動して、新しいバージョンを読み込みます。v0.1.x で有効にした Codex / Claude Code / VS Code の連携設定は、起動時に新しい形式へ更新し、その旨を 1 回通知します。

v0.2.12 以降で自動更新を有効にしている場合は、更新のインストール後に VS Code を再読み込みしてください。v0.2.11 以前からの更新や、自動更新を無効にしている場合は、v0.2.17 の VSIX を手動でインストールしてください。自動更新を希望しない場合は、更新後にサイドバーの **拡張機能の自動更新** をオフにしてください。以前から `agentpicklink.checkForUpdates` を無効にしていた場合は、その設定を保持します。

## 拡張機能なしでインストールする

**v0.2.0 から利用できます。** VS Code 拡張機能のインストールが許可されていない環境向けに、ポータブルアーカイブから直接インストールできます。

1. GitHub の Releases から、お使いの OS 用のアーカイブ(`AgentPickLink-<版>-win-x64.zip` など)をダウンロードし、任意の場所に展開します。
2. 展開したフォルダで cmd・PowerShell・ターミナルのいずれかを開きます。
3. ワークスペース(VS Code で開くフォルダ)のフルパスを指定して、次のコマンドを 1 回実行します。

   ```
   .\apl-setup C:\path\to\workspace          (Windows)
   ./apl-setup /path/to/workspace            (macOS)
   ```

Linux アーカイブは開発・CI 専用です。通常の `serve` は `PLATFORM_UNSUPPORTED` で停止します。`M365_AGENT_ALLOW_UNSUPPORTED_OS=1` は開発者向けの例外で、一般利用の導入手順ではありません。Remote SSH・WSL・コンテナー等はこの指定でも利用できません。

Node.js は同梱されているため、別途インストールする必要はありません。アップグレードは、新しいアーカイブを展開して同じコマンドを再実行するだけです(`apl-setup <ワークスペース>`)。以前の版に戻す場合は `apl self use <version>` を実行します。

この説明の `apl` は、セットアップ結果に表示されるインストール済みランチャーの絶対パスに置き換えて実行してください。PATH への自動追加は行いません。既定の場所は Windows が `%LOCALAPPDATA%\AgentPickLink\bin\apl.cmd`、macOS が `~/.local/share/AgentPickLink/bin/apl` です。PowerShell では `& "<ランチャーの絶対パス>" self status` のように呼び出せます。

画面をブラウザーに表示する場合は `--browser` を追加します。`--no-open` を併用すると
一度だけ使えるURLを端末に表示します。操作は15分以内に完了してください。承認操作には対話端末が必要です。
`--dry-run` は設定を初期化・移行せず計画のみを表示します。`apl self prune` は旧版削除前に確認し、
`--yes` でこの削除確認を省略できます。拡張パネルの「機械インストールを更新」は自動実行されません。

管理者向けの詳細(書き込まれるファイル、実行制御ポリシー、許可リストの設定など)は [管理者向けノート](release-docs/MANAGED-ENVIRONMENTS.md) を参照してください。

## 拡張機能の自動更新

VS Code の `agentpicklink.updateChannel` 設定で `stable`(安定版のみ)と `beta`(ベータ版を含む)を選べます。既定は `beta` です。チャネルは自動インストールと手動更新の通知の両方に適用します。

自動更新は初期値で有効です。VS Code 起動時と6時間ごとに GitHub の選択したチャネルの公開リリースを確認し、VSIX の SHA-256 とビルド証明を検証してから自動インストールします。証明を取得・検証できない場合や、公式リポジトリの対象タグとビルド元が一致しない場合はインストールせず、次の確認で再試行します。証明のない過去のリリースも自動インストールされません。検証には GitHub と Sigstore への接続、および Node.js 22.22.2 以降の22系、24.15.0 以降の24系、または26以降が必要です。対応しない Node.js では拡張機能は起動しますが自動インストールを見送ります。更新後は通知の **再読み込み** を押して反映してください。

サイドバーの **拡張機能の更新 → 拡張機能の自動更新** で切り替えられます。変更はすぐに保存され、オフの場合は同じバージョンの通知を一度だけ表示します。確認と通知も止める場合は、VS Code の設定で `agentpicklink.checkForUpdates` を無効にします。オフライン時は通常の起動を続け、次の確認時に再試行します。質問やワークスペースの内容を送信することはありません。機械インストールの更新は引き続き手動です。

## 最初のセットアップ

1. 利用するフォルダを VS Code で開き、内容を確認したうえでワークスペースを信頼します。
2. アクティビティバーの **AgentPickLink** を開き、**環境をセットアップする / Set up environment** を選びます。
3. サインイン画面が開いたら、職場または学校アカウントでサインインします。追加認証が必要な場合も、この専用ブラウザーで操作してください。
4. 一覧から、このワークスペースで利用するエージェントを選びます。
5. **クライアント・ファイル設定 / Client and file settings** で、必要なクライアント連携とファイル保存設定を選びます。
6. **承認して保存 / Approve and save** を押し、確認画面で利用対象を承認します。

VS Code の MCP 定義は拡張機能から提供されます。追加で有効にした連携は、対応するクライアント設定に反映されます。外部クライアントが変更を認識しない場合は、そのクライアントを再起動してください。

設定済みのワークスペースを再度開くと、保存したエージェントと接続状態を復元します。新しいエージェントを取得したい場合は **接続して更新 / Connect and refresh** を選びます。

## AI クライアントからの利用

クライアントで `m365-agents` の MCP ツールを有効にし、例えば「利用可能な Microsoft 365 エージェントを確認し、選んだエージェントにこの質問を送って」と依頼します。実際の呼び出し可否は、クライアント側のツール設定と承認にも従います。

| ツール               | 用途                                             |
| -------------------- | ------------------------------------------------ |
| `m365_agent_list`    | 利用対象と準備状態を確認する                     |
| `m365_agent_ask`     | 承認したエージェントに質問する                   |
| `m365_agent_session` | 会話の作成・一覧・終了・質問を送らない確認を行う |

質問と新しい会話の作成では、エージェントの別名、または一意に一致する承認済みの表示名を指定できます。会話を1件返す `m365_agent_session` の応答では、最上位の `conversationHandle` を次の質問や読み取りに使えます。従来の `conversation.conversationHandle` も保持します。

単発の質問では、回答取得後に会話を自動的に閉じます。送信結果が不明、または回答が完了しなかったエラーに `conversationHandle` がある場合は、その会話を残します。`m365_agent_session` の `action: "read"` で質問を送り直さずに確認でき、完了した回答を回収すると閉じます。詳しくは [トラブルシューティング](release-docs/TROUBLESHOOTING.md) を参照してください。複数ターンの会話では、作成したセッションを指定して質問を続け、終了時に閉じます。回答やファイル生成には数分かかることがあります。送信結果が不明な場合は自動再送しません。

## 生成ファイル

ファイル保存は初期設定で有効です。許可されたダウンロード先は、標準では `*.sharepoint.com` と `onedrive.live.com` です。保存先は、開いているワークスペースの `APL_downloads/<workspace-key>/<request-id>/` です。

回答に含まれるファイルの共有リンクやダウンロード操作から取得します。SharePoint / OneDrive のリンクを開ける権限とサインイン状態が必要です。通常のページへのリンクがすべて保存対象になるわけではありません。

初期上限は 1 回の回答につき 10 ファイル、1 ファイル 25 MiB、合計 100 MiB です。保存したファイルを自動実行・変換することはありません。ファイルの正確さや安全性は、利用前に確認してください。保存先に機密情報が含まれる可能性があるため、Git への追加や外部同期に注意してください。

## データと承認

質問は選択した Microsoft 365 エージェントへ送信され、取得した回答は呼び出し元の AI クライアントへ返されます。組織の規程に従い、必要最小限の情報だけを送ってください。ワークスペースの設定ファイルだけでは利用許可にならず、この端末での明示的な承認が必要です。

サインインには専用ブラウザープロファイルを使用します。通常のブラウザープロファイルを指定しないでください。プロファイルや承認情報はローカルに保存されます。詳細は [セキュリティとデータの扱い](release-docs/SECURITY.md) を参照してください。

## 利用規約と商標

AgentPickLink は、Microsoft 365 Copilot の Web 画面を、利用者自身のサインイン済みセッションで、専用ブラウザープロファイルから自動操作します。Microsoft のサービス規約・製品条件、および所属組織の方針(テナント管理者の設定を含む)に従って利用してください。自動操作が許可されるかどうかは契約や組織の方針によって異なるため、導入前に管理者や担当部門へ確認することを推奨します。規約の順守と送信するデータについての責任は利用者にあります([MIT ライセンス](LICENSE) の無保証条項を参照)。

本ツールは Microsoft と提携・承認・後援の関係にない独立したソフトウェアです。Microsoft、Microsoft 365、Microsoft Edge、Copilot、Visual Studio Code は Microsoft グループ企業の商標です。名称中の「for M365」は対応する製品を示すためのもので、Microsoft の商標やロゴは使用していません。その他の製品名・会社名は各社の商標です。

## ドキュメント・ソース

- [設定ガイド](release-docs/CONFIGURATION.md)
- [トラブルシューティング](release-docs/TROUBLESHOOTING.md)
- [開発者向けビルド・テスト手順](release-docs/DEVELOPMENT.md)
- [リリースノート](release-docs/CHANGELOG.md)
- [ライセンス: MIT](LICENSE)
- [利用 OSS・第三者ソフトウェア一覧](release-docs/OSS-LICENSES.md)
- [第三者ソフトウェアの著作権・ライセンス全文](release-docs/THIRD-PARTY-NOTICES.txt)

開発者向けには `agent-pick-link-0.2.17-source.zip` を配布します。依存関係は `package-lock.json` に固定しており、展開したソースのみでインストール・テスト・ビルドできます。

## CLI の出力・削除時の確認

`--json` のコマンド結果は stdout の単一 JSON オブジェクトです。進捗・確認は stderr に出ます(`serve` は MCP 通信専用、ヘルプ・版表示は対象外)。`doctor` は正常 0、問題あり 1、診断実行失敗 2。`install` は完了・dry-run 0、拒否・引数不正・導入失敗 1、クライアント未反映 2、一部導入・選択したクライアントの書き込み失敗・検証失敗 3 です(書き込めなかったクライアントは `clientErrors` に出ます)。`integrations write` / `remove` は、要求したクライアントをすべて反映できた場合 0、書き込み・削除できなかったクライアントがある場合 1 です。理由は `errors` に出ます。`skipped` は対応不要の項目だけです。

`doctor --auth` は認証状態、`doctor --agent <エイリアス>` は指定したエージェントの利用可否も確認します。認証が必要、アクセス拒否、無効、未確認の結果は `findings` に表示され、終了コードは 1 になります。これらのオプションを指定しない場合、検査していないことを失敗とは扱いません。診断は質問を送信せず、実際の回答やファイル取得を保証しません。

`self prune` は保持版・ランチャー・版記録・削除対象を照合します。不明なファイルやディレクトリー、不完全なパッケージ、リンク、不整合がある場合は何も削除せず停止します。`--yes` でも検証は省略しません。対象フォルダーを確認し、必要なファイルを別の場所に保管してから、壊れた情報を同じ場所への再インストールで修復してください。現行パッケージを配置しないソース参照インストールでは旧版整理を実行できません。

`doctor` は接続・認証・エージェント検査でエラーが起きても、該当項目に理由を含む診断結果を返して終了します(`ok: false`、終了コード 1)。診断結果自体を作れない場合は終了コード 2 です。解析できない連携設定は `invalid` として報告し、空のファイルは設定なしとして扱います。

`integrations remove` は解析できない設定を変更せず、`errors` の `invalid-configuration` と終了コード 1 で報告します。`--force` でも解析エラーは回避できません。`integrations status` は該当クライアントを `invalid` と表示します。`self uninstall` は削除できない連携設定を理由付きの `skippedIntegrations` に残し、アンインストールを続行します。残った設定は構文を修正してから手動で削除してください。

`self uninstall` は正規のインストール情報と実体を検証し、対象ブローカーの終了を確認してから削除します。`--yes` は確認の省略だけです。`--purge-data` は共有データを削除するため、別インストールのブローカーが稼働中なら拒否します。削除後も起動競合を防ぐ空の `broker/startup.lock` は残します。壊れたインストールは同じ場所に再インストールして修復してから削除してください。