vibe-prospecting

Vibe Prospecting CLI

CLI を使用します：npx @vibeprospecting/vpai@latest。すべてのツールの応答を JSON として扱ってください。

Cowork モードでは、必ずこのコネクターフローを使用してください。 Cowork モードで作業を始める前に、ツール一覧で Vibe Prospecting MCP コネクターのツールが利用可能か確認してください（mcp__*__fetch-entities のパターンに一致するツールを探してください）。

それらのツールがある場合は、コネクターを直接使用し、ツールの説明とスキーマに従ってください。ツールがない場合は、次の手順に従ってください。

1. キーワード ["vibe prospecting", "explorium"] を指定して mcp__mcp-registry__search_mcp_registry を呼び出します
2. UUID 1bdcb159-b6f0-4f13-bc08-fdb40b007828 とキーワード ["prospecting"] を指定して mcp__mcp-registry__suggest_connectors を呼び出します
3. カードの Connect をクリックするようユーザーに伝えます。認証が完了すると、ツールが自動的に使用可能になります
4. 接続されるまで確認を繰り返します。 以降の各ターンで、ツール一覧に mcp__*__fetch-entities があるか再確認してください。ツールが表示されるまで、プロスペクティング作業を始めないでください。Cowork モードでは、CLI、npm の vpai ツール、OAuth URL を使った代替手段に決して切り替えないでください。Cowork コネクターストアのみを使用してください。ユーザーが提案されたカードから接続できない場合は、connector store を開いて Vibe Prospecting をインストールし、その後もう一度確認するよう伝えてください。引き続きツールが表示されない場合は、ユーザーに接続を促して待機します。コネクターが使用可能になるまで繰り返してください。

Cowork モード以外で CLI が動作しない場合（例：npx を使用できない、環境がサンドボックス化されている、アクセスが拒否されたなど）、ユーザーのエージェント環境がコネクターに対応していれば、Vibe Prospecting コネクターを提案してください。このファイルの残りの部分は CLI 専用です。Cowork モードでは、上記のコネクターストアのフローを使用してください。

厳守事項

1. 必ず最初にサンプルを取得します。 本番実行の前に、エンティティをちょうど5件指定（--number-of-results 5）してワークフロー全体を実行します。この上限は品質確認のためだけのものです。同じフィルターでも、Explorium ではさらに多くの行が一致する場合があります。この5行をデータセット全体、「すべての結果」、または「データベースにあるもの」として決して説明しないでください。サンプルを表示し、これはプレビューであり、インデックスにはさらに多くのデータがあることを明確に伝えます。その後、明示的な承認を得てから、サンプルチェーンで使用したものと同じ CLI ツールを、本番規模のパラメーターで再実行します（同じ --args、セッション、フィルターを使用し、該当する場合は --number-of-results などの上限をユーザーが指定した実際の件数まで引き上げます）。すべての探索用 fetch-entities フィルター（およびサポートされるスコープフラグ）が統計にも有効な場合に限り、fetch-entities-statistics を実行します。ルール8を参照してください。エクスポートは自動で行わないでください。「100件を検索」する場合も、まず5件のサンプルを取得し、承認後に件数を増やします。
2. 実際の呼び出しごとに --tool-reasoning '<user wording>' を指定します。ユーザーの依頼文をそのまま使用します。ワークフロー全体を通じて同じ値を再利用します。--args を付けずに <tool> --all-parameters を実行する場合のみ省略します。
3. IDを貼り付けず、セッション DB でつなぎます。 各ステップでは session_id、db_path、table_name が出力されます。前の JSON 出力の session_id を --session-id に渡し、次のコマンドでも同じ SQLite セッションストアを使用します。--session-id を指定する場合、enrich-business、enrich-prospects、fetch-businesses-events、fetch-prospects-events では --table-name が必須です。前のステップの table_name をそのまま渡します。match-* の場合のみ、--table-name は任意です（省略すると、CLI は適切な ID 列を持つ最初のテーブルを選択できます）。先行する企業をスコープとして指定する fetch-entities の見込み顧客では、--businesses-table-name と --session-id を使用します。
4. --csv は最後のステップでのみ指定します。 中間ステップでは、チェーンで使う JSON を出力します。最後に一度だけ --csv を追加します。
5. 次の項目では、最初に autocomplete を実行します：naics_category、linkedin_category、company_tech_stack_tech、job_title、business_intent_topics、city_region。ユーザーの生の表現ではなく、返された標準化済みの値を使用します。
6. ツールのパラメーターを決して推測しないでください。 ワークフロー内で使用する各ツールについて、初めて --args を使って実行する前に、npx @vibeprospecting/vpai@latest <tool> --all-parameters を実行します（同じワークフロー内でそのスキーマをすでに表示している場合を除き、タスクごとにツールごとに1回）。このコマンドは、name、description、inputSchema（ツールの入力 JSON Schema）を含む1つの JSON オブジェクトを標準出力に表示します。予定している呼び出しが例と一致し、不明点がなくても、必ず実行してください。例の内容は古くなっている可能性があるため、表示されたスキーマを正とします。ツール、フィルター、またはデータ形状を大幅に変更する場合や、曖昧な点が残る場合は、再度 --all-parameters を実行します。例やリファレンスドキュメントは、実際のスキーマと整合することを確認した後に限り、手順を簡略化するために使用できます。--args は、--all-parameters の inputSchema で確認したフィールドとデータ形状（および、それと一致する例）のみを使って作成します。
7. --session-id は CLI フラグであり、--args の中には含めません。前の各ステップで MCP が返した session_id の値を使用します。チェーンの最初の呼び出しでのみ省略します。
8. 統計がフェッチ全体をサポートする場合に限り、fetch-entities-statistics を実行します。 予定している fetch-entities ペイロードを、fetch-entities-statistics --all-parameters から取得した入力スキーマと比較します。フィルターキー、値のデータ形状、entity_type、および依拠するスコープ（例：--session-id／--businesses-table-name）のすべてが、fetch-entities と同じ方法で統計ツールに受け付けられる場合に限り、統計を呼び出します。探索クエリの一部でも統計のスキーマに含まれていない場合、サポートされていない場合、または異なるデータ形状が必要な場合は、統計を省略します。一部だけを渡したり、推測した内容で呼び出したりしないでください。統計を呼び出す場合は、fetch-entities と同じ --args フィルターオブジェクト（およびサポートされるフラグ）を --tool-reasoning とともに再利用します。応答に利用可能な件数が含まれる場合に「合計[件数]件中5件」と伝えられるよう、可能であればサンプルを提示する前に統計を実行します。統計を実行しなかった場合（または利用可能な合計件数が得られなかった場合）は、「サンプルプレビュー（5行）」と提示し、同じフィルターに一致するデータが Explorium にさらに多くあることを伝えます。残りの件数を引用したり、統計が失敗した、または合計件数が得られなかったと言ったりせず、決して件数を捏造しないでください。フィルターまたはスコープを変更し、かつ本番実行のフィルター一式が統計で引き続きサポートされる場合は、本番規模のフェッチの前に統計を再度呼び出します。

認証

mcp__cowork__request_cowork_directory path=~/.config/vpai
API_KEY=$(python3 -c "import json;print(json.load(open('/sessions/<session-id>/mnt/vpai/config.json'))['api_key'])")
npx @vibeprospecting/vpai@latest config --api-key "$API_KEY"

マウントに失敗した場合、または config.json が見つからない場合は、login.md に従ってください。

サンプルのゲート

サンプルは、5件のエンティティに対するワークフロー全体であり、取得結果のプレビューではありません。

全体集合とサンプルの違い： 5行は、ユーザーがクォータを使う前にフィルターとエンリッチメントを検証できるようにするための、小規模で固定されたプレビューです。基になる一致集合は通常、はるかに大きく（多くの場合、数千件以上）なります。「5件を返した」ことを「存在するのは5件だけ」と同一視しないでください。件数を示す場合は、計画している fetch-entities のフィルターセット全体が統計の対象となる場合に限り、fetch-entities-statistics を使用してください（ルール8）。合計件数を推測してはいけません。

1. 取得フィルターセット全体が統計の対象となる場合は、続けて実行する fetch-entities と同じ検出用 entity_type、filters、およびサポートされている CLI フラグを使って fetch-entities-statistics を実行します（ルール8に従ってください）。それ以外の場合は統計をスキップし、それでも、同じフィルターに一致するデータが Explorium にはるかに多くあることをユーザーに伝えてください（数値の合計や統計の対象外であることには触れないでください）。
2. ちょうど5件取得します（--number-of-results 5）。
3. それ以降のすべてのステップ（match-*、enrich-*、fetch-*-events）をその5件に対して実行します。
4. エンリッチメント済みの最終行をすべて、有用な列をすべて含む Markdown テーブルで表示します。
5. ここで止めます。新しいメッセージで承認を待ちます。その後、全件規模で実行します。

取得後に止めて承認を求めてはいけません。まず5件についてワークフロー全体を完了してください。

例 — ユーザーが「イスラエルの企業を100社探し、CEOを30人取得して、連絡先情報を探して」と言った場合：

• 誤り：企業を5社取得 → テーブルを表示 →「続けますか？」と尋ねる
• 正しい：fetch-entities のフィルターセット全体が fetch-entities-statistics の対象となる場合は、先に統計を実行（同じ --args フィルターを使用）→ 企業を5社取得 → その5社の CEO を取得 → CEO の連絡先情報をエンリッチ → 最終テーブルを表示（統計で合計が得られた場合は 5 / [total] 件、そうでない場合は サンプルプレビュー（5行） と、このフィルターに一致するデータがはるかに多くあることを示す短い一文を添える—件数は示さず、統計についての謝罪もしない）→「全100件を実行しますか？」と尋ねる

サンプルの提示

テーブルは必ず全体ではなく、サンプルとして示してください。

• 統計で利用可能な合計件数が得られた場合（fetch-entities のフィルターがすべて fetch-entities-statistics の対象となる場合に限り、統計を呼び出しています）：サンプルプレビュー（[total]件中5件に一致） — [total] は fetch-entities-statistics から取得した値でなければなりません。5行を数えて求めてはいけません。
• 数値の合計件数を使用しなかった場合（統計を使わなかった場合、または利用可能な合計件数が得られなかった場合）：サンプルプレビュー（5行） と、これらのフィルターに一致するデータが Explorium にはるかに多くあることを示す簡潔な一文を記載します。さらに何件あるかは言わず、統計や合計件数がないことにも触れず、[total] を決して捏造しないでください。

Results Found: [X] [entity type] from [Y] [companies/sources] [qualifier]（補足情報として任意）

見出し： 統計に基づく [total] がある場合に限り、サンプルプレビュー（[total]件中5件に一致）： とします。それ以外の場合は、サンプルプレビュー（5行）： とし、同じフィルターに一致するレコードがはるかに多く存在することを示す一文を添えます（定性的な説明のみ）。

明確な次のステップを最後に示してください。例：確認いただいた後、同じツールを全件規模の上限（例：fetch-entities を使用した場合は --number-of-results [user's N]）で再実行して、実際のバッチを取得します。

プレビューがユーザーの依頼内容の一部にすぎない場合（全件規模では、さらに多くの行やフィールドが取得可能な場合）は、次のように追加してください。

• 統計に基づく [total] がある場合：利用可能なデータがさらにあります：プレビューには[total]件中[n]件が表示されています。全件をエクスポートする前に確認してください。
• 数値の [total] がない場合：プレビューが5行であること、同じフィルターに一致するデータが Explorium にはるかに多くあることを伝え、全件のエクスポートを実行するか確認してください。残りの件数を示したり、合計件数を表示しなかった理由に触れたりしてはいけません。

ユーザーが依頼した内容がすでにチャット内ですべて提示されている場合は、エクスポートに触れないでください。

全件をエクスポートする前に確認すること

• エクスポート件数（レコード数の上限）。
• フィルターの絞り込み：業種、規模、売上、地域、テクノロジー。
• 見込み顧客の場合：役職のバリエーション、企業単位で重複排除するか。
• 連絡先の場合：業務用メールアドレスのみか、個人用メールアドレスや電話番号も含めるか。

ワークフロー

0. Auth — see Auth section above (or login.md)
1. npx @vibeprospecting/vpai@latest --help                    Discover tools
2. Read references/<tool>.md for workflow + caveats
3. Before the first real `--args` for each tool: `npx @vibeprospecting/vpai@latest <tool> --all-parameters` (mandatory per tool, not only when uncertain). Prints the tool **input** schema as JSON. Run again if the planned call diverges from what you already validated.
4. Build `--args` only from fields confirmed by that printed input schema (examples count only when they match it). If a parameter is not confirmed there, do not use it.
5. When the **entire** planned **`fetch-entities`** filter set (and supported flags) matches **`fetch-entities-statistics`** input schema per **`--all-parameters`**: run **`fetch-entities-statistics`**, then sample (5 entities, full chain) — see Sample Gate
6. npx @vibeprospecting/vpai@latest <tool> --args '<json>' --tool-reasoning '<user request>'
7. Chain: --session-id <session_id> [--table-name <table_name>] [--businesses-table-name <name> for prospect fetch from businesses]
8. Final step only: add --csv

参考ドキュメント：

• autocomplete.md — 制御語彙の検索
• fetch.md — fetch-entities、fetch-*-events
• match.md — 既知のエンティティを ID に解決
• enrich.md — ID 取得後のエンリッチメント
• fetch-stats.md — 件数と市場規模の算出
• login.md — 認証のフォールバックフロー

フラグ

フラグ	説明
--help	ツールの一覧
--all-parameters	{ name, description, inputSchema } を標準出力に出力します（整形済み JSON）。ワークフロー内の各ツールで、最初の --args を実行する前に実行してください（ツールまたはペイロードが大きく変わった場合は再度実行してください）。不確かな場合だけでなく、通常の手順として実行してください。inputSchema フィールドが正式な仕様です。
--args '<json>'	ツールの引数
--session-id <id>	同じワークフローの場合、前のツールの JSON に含まれる session_id を渡します（db_path の共有 SQLite DB を開きます）。
--table-name <name>	enrich-business、enrich-prospects、fetch-businesses-events、fetch-prospects-events では --session-id と併せて必須です（前の手順の table_name）。match-* では省略可能です（テーブルが複数ある場合に絞り込みます）。
--businesses-table-name <name>	fetch-entities と entity_type: prospects の組み合わせで使用します。フィルターに使う business_id を行から取得するテーブルを指定します（--session-id と併用）。
--number-of-results <n>	fetch-entities の場合：ページをまたいだ合計行数（CLI がページネーションを行います）。生の 1 ページ分だけ取得する場合は省略します。
--file-path <path>	match-business / match-prospects の場合：照合する CSV ファイルへのパス。各行が候補になります。--schema が必要です。
--schema '<json>'	--file-path と併用する場合に必須です。CSV の列見出しを API フィールド名に対応付ける JSON 辞書です。Business のフィールド：name、domain。Prospect のフィールド：full_name、first_name、last_name、email、phone_number、linkedin、company_name、business_id。
--csv	フラット化した CSV も書き出します。最終ステップのみ。

フィルターパターン

{ "values": ["v1", "v2"], "negate": false }   // include or exclude
{ "gte": 6, "lte": 24 }                       // range
true | false | null                           // boolean (not wrapped)

制限

ツール	制限
match-business	1 回の呼び出しにつき 50 件
match-prospects	1 回の呼び出しにつき 40 件
enrich-business	1 回の呼び出しにつき ID 50 件
enrich-prospects	1 回の呼び出しにつき ID 50 件
fetch-businesses-events / fetch-prospects-events	MCP リクエスト 1 回につき ID は最大 20 件です（CLI が分割してマージします）。--args に event_types と timestamp_from を渡してください。business_ids / prospect_ids は --args に含めないでください。ID は --table-name からのみ取得されます。
fetch-entities	--number-of-results を使用してください。CLI がページネーションを行います。next_cursor や page_size を手動で渡さないでください。

よくあるワークフロー

SESSION_ID を前の手順の session_id に置き換えます。

NY の SaaS 企業における VP of Engineering

npx @vibeprospecting/vpai@latest autocomplete --args '{"field":"linkedin_category","query":"software"}' --tool-reasoning 'find VP Eng at SaaS in NY'
# When every fetch-entities filter (and flags) is valid for fetch-entities-statistics (--all-parameters):
npx @vibeprospecting/vpai@latest fetch-entities-statistics --args '{"entity_type":"prospects","filters":{"job_level":{"values":["vice president"]},"job_department":{"values":["engineering"]},"linkedin_category":{"values":["Software Development"]},"company_region_country_code":{"values":["US-NY"]},"has_email":true}}' --tool-reasoning 'find VP Eng at SaaS in NY'
npx @vibeprospecting/vpai@latest fetch-entities --args '{"entity_type":"prospects","filters":{"job_level":{"values":["vice president"]},"job_department":{"values":["engineering"]},"linkedin_category":{"values":["Software Development"]},"company_region_country_code":{"values":["US-NY"]},"has_email":true}}' --number-of-results 50 --tool-reasoning 'find VP Eng at SaaS in NY'
npx @vibeprospecting/vpai@latest enrich-prospects --args '{"enrichments":["contacts","profiles"]}' --session-id <session_id> --table-name <fetch_entities_table_from_prior_step> --csv --tool-reasoning 'find VP Eng at SaaS in NY'

資金調達済みで Salesforce を使用する企業

npx @vibeprospecting/vpai@latest autocomplete --args '{"field":"company_tech_stack_tech","query":"salesforce"}' --tool-reasoning 'companies that raised and use Salesforce'
# When every fetch-entities filter (and flags) is valid for fetch-entities-statistics (--all-parameters):
npx @vibeprospecting/vpai@latest fetch-entities-statistics --args '{"entity_type":"businesses","filters":{"company_tech_stack_tech":{"values":["Salesforce"]},"events":{"values":["new_funding_round"],"last_occurrence":60}}}' --tool-reasoning 'companies that raised and use Salesforce'
npx @vibeprospecting/vpai@latest fetch-entities --args '{"entity_type":"businesses","filters":{"company_tech_stack_tech":{"values":["Salesforce"]},"events":{"values":["new_funding_round"],"last_occurrence":60}}}' --number-of-results 50 --tool-reasoning 'companies that raised and use Salesforce'
npx @vibeprospecting/vpai@latest fetch-businesses-events --args '{"event_types":["new_funding_round"],"timestamp_from":"2024-10-01"}' --session-id <session_id> --table-name <fetch_entities_table_from_prior_step> --csv --tool-reasoning 'companies that raised and use Salesforce'

市場規模の算出

npx @vibeprospecting/vpai@latest fetch-entities-statistics --args '{"entity_type":"businesses","filters":{"linkedin_category":{"values":["Hospital & Health Care"]},"company_country_code":{"values":["US"]}}}' --tool-reasoning 'market sizing US healthcare'

トラブルシューティング

エラー	解決方法
CLI のインストールに失敗する（npx が使用できない、サンドボックス、アクセス拒否）	バンドルされた Vibe Prospecting MCP コネクターに切り替え、そのツールの説明に従ってください。それ以降のこのファイルの内容は適用されません。
認証／401（コネクター／Cowork）	上記の認証セクションを実行してください。マウントに失敗する場合は、login.md に従ってください。
認証／401（OpenClaw）	npx @vibeprospecting/vpai@latest login を実行し、続けて login --poll を実行してください。または、VP_API_KEY を設定してください。その後、ゲートウェイを再起動してください。上記の認証セクションを参照してください。
Not authenticated（OpenClaw）	~/.config/vpai/config.json も VP_API_KEY 環境変数も設定されていません。OpenClaw の認証セクションに従ってください。
OpenClaw でプラグインのツールが表示されない	openclaw plugins list を実行し、vpai が一覧にあることを確認してください。必要に応じて再インストールしてください：openclaw plugins install ./vpai-plugin。
OpenClaw のインストール後にツールが見つからない	ゲートウェイを再起動する必要があります：openclaw gateway restart。
JSON に session_id がない／CLI でチェーン処理できない	MCP は session_id を返す必要があります。本番環境の https://vibeprospecting.explorium.ai/mcp（npm CLI に埋め込まれています）を対象にしていることを確認してください。次のステップでは、完全に同じ文字列を --session-id に渡してください。
チェーン処理時に誤った行が使用される	前のステップの table_name に一致する --table-name を渡してください。
--session-id を指定した enrich-* または fetch-*-events に --table-name がない	--session-id を渡す場合、enrich-business、enrich-prospects、fetch-businesses-events、および fetch-prospects-events では --table-name が必須です。
結果が空	フィルター値を確認してください。制御語彙フィールドには autocomplete を実行し、関連する実行時の input スキーマを <tool> --all-parameters で再確認してください。
linkedin_category と naics_category の併用	相互に排他的です。どちらか一方を使用してください。
JSON の解析エラー	JSON を検証し、シェルの引用符を確認してください。
fetch-entities、enrich-*、fetch-*-events、または --file-path を指定した match-* のタイムアウト	同じ --session-id、--table-name、--args、および（match の場合は）--file-path／--schema を使って、まったく同じコマンドを再実行してください。CLI は最後のチェックポイントから再開します。完了済みの ID バッチはスキップされ、作業は繰り返されません。前回の実行ですでにジョブが完了している場合は、API 呼び出しなしで保存済みのマニフェストがすぐに返されます。
--session-id なしでのタイムアウト	チェックポイントを有効にするため、--session-id <any-stable-id> を追加してから再試行してください。セッション ID がないと、CLI は再開できません。