google-contacts

Google Contacts

Google Contacts 用の、エージェントから呼び出せるツールです。Google People API をラップしています。ユーザーの連絡先を作成、読み取り、更新、削除したり、名前、メールアドレス、電話番号で連絡先を検索したり、連絡先の写真を設定または削除したり、連絡先グループ（ラベル）とそのメンバーを作成・管理したり、自動保存された「その他の連絡先」を参照したりできます。すべてのツールは単一の OAuth 接続を使用し、機能の利用可否は付与されたスコープによって決まります。

Google Contacts 用の独立した非公式コネクターです。Google Contacts との提携、Google Contacts による承認、または Google Contacts からの後援を受けていません。「Google Contacts」は、その所有者の商標であり、このコネクターが連携するサービスを識別する目的でのみ使用しています。

使用する場面

• ユーザーの Google Contacts で連絡先を保存、検索、更新、削除するとき（「Jane を連絡先に追加して」「Bob のメールアドレスは？」「この連絡先を削除して」）。
• 連絡先をグループ／ラベルに整理したり、メンバーを追加または削除したりするとき。
• 連絡先の写真を設定または削除するとき。
• ユーザーがやり取りした（例：メールを送った）ものの、明示的には保存していない相手を見つけるとき（「その他の連絡先」）。また、その相手を保存済みの連絡先に登録するとき。

セットアップ

これは agentskills.io のスキルです。

コネクターがまだスキルとしてインストールされていない場合は、まず npx skills add zapier/connectors --skill google-contacts（またはお使いのハーネス独自のスキルインストール方法）でインストールしてから、ここに戻ってください。スキルのインストールでコピーされるのはこれらのファイルであり、依存関係ではありません。CLI、ローカル MCP サーバー、または zapier-sdk の認証コマンドを実行する前に、ここで一度 npm install --omit=dev を実行してください。公開パッケージを依存関係として独自のプロジェクトにインポートする場合は、npm install によってすでにすべての依存関係が解決されています。詳細は references/use-as-sdk.md を参照してください。

リポジトリのソースそのものを確認する場合（references/ の閲覧、このコネクターのテスト実行、またはコードの変更など）は、対象を絞った git clone について README.md を参照してください。

このコネクターの実行には Node.js 22.18+ が必要です。実行方法に合ったリファレンスを選び、ほかの作業を始める前に読み込んでください。

利用できるもの...	読み込むリファレンス
MCP 対応クライアント（ツールがすでに読み込まれている場合があります（例：mcp__google-contacts__<tool>）。または、独自にローカルサーバーを登録できます（ユーザーに案内する方法もあります））	references/use-as-mcp.md
ターミナル／サブプロセスへのアクセス（node を実行できます）	references/use-as-cli.md
このパッケージを依存関係としてインポートする、独自のコードのみ	references/use-as-sdk.md
ツールやターミナルにアクセスできず、このパッケージをインポートすることもできない場合（コード実行サンドボックスなどで、Google Contacts API を直接呼び出す独自コードを作成します）	references/use-as-recipe.md

スクリプト

すべてのスクリプトは、単一の google-contacts 接続を使用します。

スクリプト	スクリプト名	接続先	説明
scripts/createContact.ts	createContact	google-contacts	構造化された名前、メールアドレス、電話番号、住所、組織の各フィールドから連絡先を作成します。
scripts/getContact.ts	getContact	google-contacts	リソース名で単一の連絡先を取得し、すべてのフィールドの詳細を含めます。
scripts/updateContact.ts	updateContact	google-contacts	連絡先を更新します。送信した配列は該当フィールド全体を置き換え、省略したフィールドには変更を加えません。
scripts/deleteContact.ts	deleteContact	google-contacts	アカウントから連絡先を削除します。
scripts/listContacts.ts	listContacts	google-contacts	アカウントの連絡先をページネーション付きで一覧表示します。主な resourceName 解決手段です。
scripts/searchContacts.ts	searchContacts	google-contacts	名前、ニックネーム、メールアドレス、電話番号、組織で連絡先を検索します（前方一致）。
scripts/updateContactPhoto.ts	updateContactPhoto	google-contacts	Base64 エンコードされた画像から連絡先の写真を設定または置き換えます。
scripts/deleteContactPhoto.ts	deleteContactPhoto	google-contacts	連絡先の写真を削除し、デフォルトのアバターに戻します。
scripts/listContactGroups.ts	listContactGroups	google-contacts	ユーザーグループとシステムグループの連絡先グループ（ラベル）を一覧表示します。contactGroupResourceName の解決手段です。
scripts/getContactGroup.ts	getContactGroup	google-contacts	単一の連絡先グループを取得します。必要に応じて、メンバーの連絡先リソース名も含められます。
scripts/createContactGroup.ts	createContactGroup	google-contacts	新しいユーザー連絡先グループ（ラベル）を作成します。
scripts/updateContactGroup.ts	updateContactGroup	google-contacts	ユーザー連絡先グループの名前を変更します（システムグループの名前は変更できません）。
scripts/deleteContactGroup.ts	deleteContactGroup	google-contacts	ユーザー連絡先グループ（ラベル）を削除します。必要に応じて、メンバーの連絡先も削除できます。
scripts/modifyContactGroupMembers.ts	modifyContactGroupMembers	google-contacts	他のグループ所属に影響を与えず、グループ内の連絡先を追加または削除します。
scripts/listOtherContacts.ts	listOtherContacts	google-contacts	自動保存された「その他の連絡先」（やり取りはしたものの、保存していない人）を一覧表示します。
scripts/searchOtherContacts.ts	searchOtherContacts	google-contacts	名前、メールアドレス、電話番号で「その他の連絡先」を検索します（前方一致）。
scripts/copyOtherContact.ts	copyOtherContact	google-contacts	「その他の連絡先」を保存済みの連絡先に追加し、編集可能な連絡先として返します。

識別と拒否

• 実行前に名前を特定します。 名前で特定された連絡先に対して updateContact／deleteContact／modifyContactGroupMembers を実行する前に、searchContacts（または listContacts）を呼び出し、大文字と小文字を区別せずに名前が完全一致する件数を確認します。一致が1件なら、その連絡先に対して実行します。過剰に確認を求めないでください。一致件数が2件以上で同数の場合は、処理を中止し、メールアドレスまたは電話番号などの識別情報とともに候補を列挙して、どれを選ぶか尋ねます。黙って選んではいけません。同じルールは listContactGroups を使ったグループの特定にも適用されます。
• リストフィールドを編集すると、値が置き換わります。 updateContact は、送信した各配列（例：emailAddresses）全体を置き換えます。他の値を残したまま値を_追加_するには、先に getContact を呼び出して既存の配列に追加してから、配列全体を送信します。グループのメンバーシップには、updateContact よりも要素単位で操作できる modifyContactGroupMembers を優先してください。
• 対象範囲外の場合は、代替手段を使わずに拒否します。 このコネクターは、連絡先の一括作成・一括更新・一括削除、Google Workspace のディレクトリ検索、連絡先の統合／重複排除には対応していません。これらを依頼された場合は、対応していないと伝えて処理を中止してください。別のツールを呼び出して、完了したと報告してはいけません。
• 一括操作には対応していません。ループで偽装してはいけません。 バッチエンドポイントはありません。多数またはすべての連絡先のフィールドを一度に変更・追加・削除するよう依頼された場合（例：「全員の会社を Acme に設定して」）、対応していないと説明して断ってください。一括操作を装うために、複数の連絡先に対して updateContact／deleteContact／modifyContactGroupMembers をループで実行してはいけません。明示的に特定された単一の連絡先への操作には対応できますが、アドレス帳全体に処理を展開することはできません。

認証

すべてのシェイプでは、認証情報そのものではなく、1つの接続セレクター（[<resolver>:]<value> 形式の文字列）を使用します。すべてのコネクターで zapier:<connection-id> を使用できます（Zapier 管理の認証で、Zapier の認証、再試行、ガバナンスレイヤーを経由します）。一部のコネクターでは、直接トークン用のリゾルバーも1つ以上使用できます（名前や数はコネクターによって異なります）。推測せず、このコネクター独自のリゾルバーを確認してください。<resolver>: プレフィックスは省略可能です。プレフィックスのない値は、最初にその値を受け付けるリゾルバーに渡されます。UUID 形式のプレフィックスのない値は、必ず zapier: で受け付けられます。各スクリプトでは、必要な接続と、それぞれが受け付けるリゾルバーを宣言します。接続を渡す正確な構文と、このコネクターのリゾルバー一覧の確認方法は、シェイプによって異なります。上記で読み込んだリファレンスを参照してください。

すでに設定されているものを確認しますか？確認のために環境変数の値を出力しないでください。env や env | grep <name> は名前とともに値も出力するため、値が設定されている場合、使用中の認証情報がトランスクリプトに漏えいします。名前だけを確認するには（env | cut -d= -f1 | grep -i <name>）、または既知の名前を直接テストします（[ -n "$VAR_NAME" ]）。

まだ接続がありませんか？どちらかを選び、接続を取得するにはリファレンスに記載された手順に従ってください。接続 ID やトークンをユーザーがすでに覚えているものとして、ただ尋ねてはいけません。

	読み込む
認証情報を直接渡す	references/use-without-zapier.md
Zapier 接続経由で認証情報を渡す	references/use-with-zapier.md

出力形式

各スクリプトは { data, meta } エンベロープを返します。

• data — スクリプトの結果（outputSchema が宣言する形式です。スクリプト固有の正確なスキーマを確認する方法については、上で読み込んだリファレンスを参照してください）。
• meta.outputDataValidation — data の検証結果です。
  • { skipped: false, droppedPaths: null } — 検証済みで、削除されたものはありません。
  • { skipped: false, droppedPaths: [...], instruction } — 検証済みですが、該当するパスが data から除去されました。これらは、スクリプトが API から返したフィールドのうち outputSchema で宣言されていないものです。必要な場合は、出力検証をスキップして再実行してください。
  • { skipped: true } — 検証が回避され、data は未検証のスクリプト出力そのものです。

除去されたフィールドの確認／skipOutputDataValidation。 未検証の生の結果を受け取るには、出力検証を無効にします（正確な構文はシェイプによって異なります。詳細は上で読み込んだリファレンスを参照してください）。入力検証はスキップされません。

結果の絞り込み／filterOutputData。 大きな結果を必要なフィールドだけに絞るには、data に後処理を適用する jq 式を渡します（正確な構文はシェイプによって異なります）。jq が処理するのは { data, meta } エンベロープではなく data のみなので、data を起点に記述してください（出力スキーマを確認するには、スクリプトの --help を実行するか、シェイプに相当する方法を使用してください）。変換後の値が data に置き換わり、meta は保持されます。また、結果は出力スキーマに対して再検証されません。

リファレンス

該当する領域で作業する前に、対応するリファレンスファイルを読み込んでください。

リファレンス	内容	読み込むタイミング
references/google-contacts-api-gotchas.md	エラーコード、更新時の置換セマンティクス、etag による並行処理、検索の前方一致とウォームアップ、書き込みの反映遅延、リソース名の形式、連絡先グループの種類、メンバーシップの上限、その他の連絡先のフィールド制限、ページネーション。	ツールを呼び出す前。