bisibility

@bisibility/mcp

bisibility の一部です。キーワード調査、被リンク分析、Google の検索順位追跡に対応するオープンソースの SEO プラットフォームです。このリポジトリには、bisibility のツールを AI エージェントに公開する MCP サーバーが含まれています。

ドキュメント · API リファレンス · ロードマップ

ステータス： 開発者向けプレビュー。

配布

配布状況とリリースチャネル

bisibility REST API 用の Model Context Protocol サーバーです。公開済みの @bisibility/sdk パッケージを利用する stdio ツールを公開します。

要件

• Node.js 18 以降
• bisibility API キー
• bisibility API v1 のベース URL

インストール

グローバルインストールせずに、公開済みの stdio サーバーを実行します。

npx -y @bisibility/mcp

ローカル開発では、このパッケージのディレクトリからインストールしてビルドします。

このパッケージのディレクトリから：

npm install
npm run build

SDK は npm レジストリから利用します。

"@bisibility/sdk": "^0.17.1"

MCPB バンドル

MCPB に対応したディレクトリやクライアントでは、ワンクリックでインストールできるローカルバンドルとして bisibility を配布できます。 バンドルには stdio サーバーとすべての本番環境用依存関係が含まれますが、bisibility の認証情報は含まれません。インストール時にクライアントが設定情報を収集します。

アップロード用の成果物をビルドするには、次を実行します。

npm ci
npm run build
npm run build:mcpb

バージョン付きファイルは artifacts/ に出力されます。

環境

export BISIBILITY_API_KEY="bsb_pat_live_..."
export BISIBILITY_BASE_URL="https://eu.bisibility.com/api/v1"
export BISIBILITY_PROJECT_ID="prj_..."
export BISIBILITY_MCP_READ_ONLY="1"
export BISIBILITY_MCP_TOOLSETS="projects,keywords,checks,rank-history"

BISIBILITY_BASE_URL は省略可能で、省略時は https://eu.bisibility.com/api/v1 が使用されます。セルフホスト環境では、API v1 のルートを設定します。たとえば https://rank.example.com/api/v1 です。 BISIBILITY_API_KEY には、プロジェクトキー（bsb_key_live_...）または個人アクセストークン（bsb_pat_live_...）を指定できます。省略可能な BISIBILITY_PROJECT_ID を設定すると、プロジェクトを暗黙的に指定する PAT ツールで、デフォルトの X-Bisibility-Project セレクターとして使用されます。ツールに省略可能な project_id 引数がある場合、その呼び出しでは引数の値が優先されます。BISIBILITY_PROJECT_ID を含め、MCP サーバーが受け付けるすべてのリソース ID は、現在の型付き公開 ID 形式（正規の小文字プレフィックス、_、24 文字の小文字サフィックス）を使用する必要があります。例：prj_a1b2c3d4e5f6g7h8j9k0m2n3。 形式が不正な ID、大文字と小文字が混在した ID、リソースのプレフィックスが正しくない ID は拒否されます。 ロケーションの選択には、ロケーション ID ではなく、返された location_key を使用します。キーの末尾に @language を付けると、そのロケーションのデフォルト以外の言語を選択できます。たとえば ES/Andalusia/Malaga@en です。言語指定のないキーでは、その国のデフォルト言語が使用されます。

サーバーは、公開済みの @bisibility/sdk パッケージが提供する公開 ID の仕様を使用します。ローカル SDK リンクに置き換えないでください。

BISIBILITY_MCP_READ_ONLY には 1、true、yes、on を指定でき、大文字と小文字は区別されません。有効にすると、書き込みツールは登録されず、tools/list にも表示されません。

BISIBILITY_MCP_TOOLSETS は省略可能な、カンマ区切りの許可リストです。有効なツールセットは account、agent-reports、ai-visibility、 alerts、analytics、backlinks、checks、competitors、domain-overview、keywords、 notifications、project-context、projects、prompt-explorer、providers、rank-history、saved-keywords、saved-views、signals、site-audits、sitemaps、 system、team、tokens、webhooks です。不明な値が指定されると、サーバーは起動しません。 この環境変数が設定されていない場合は、すべてのツールセットが登録されます。ツールセットのフィルターと読み取り専用モードは併用できます。許可リストは対象範囲を制御するものであり、ツールの選択精度を高めるためのものではありません。

実行

npm run build
BISIBILITY_API_KEY="bsb_key_live_..." node dist/stdio.js

パッケージとしてインストールした場合の実行ファイルは次のとおりです。

bisibility-mcp

接続

リポジトリをビルドした後、Codex をローカルの stdio サーバーに接続します。

codex mcp add bisibility \
  --env BISIBILITY_API_KEY="bsb_key_live_..." \
  --env BISIBILITY_BASE_URL="https://bisibility.com/api/v1" \
  -- node /absolute/path/to/bisibility-mcp/dist/stdio.js

上記の codex mcp add の構文は Codex CLI で検証済みです。実行する前に、 絶対パスと認証情報を置き換えてください。

その他の MCP クライアントでは、一般的に次のような JSON 設定を使用します。

{
  "mcpServers": {
    "bisibility": {
      "command": "npx",
      "args": ["-y", "@bisibility/mcp"],
      "env": {
        "BISIBILITY_API_KEY": "bsb_key_live_...",
        "BISIBILITY_BASE_URL": "https://eu.bisibility.com/api/v1"
      }
    }
  }
}

bisibility-mcp がクライアントの PATH にインストールされている場合は、パッケージの実行ファイルを使用します。

{
  "mcpServers": {
    "bisibility": {
      "command": "bisibility-mcp",
      "env": {
        "BISIBILITY_API_KEY": "bsb_key_live_...",
        "BISIBILITY_BASE_URL": "https://eu.bisibility.com/api/v1"
      }
    }
  }
}

ツール

ツール名には接頭辞のない snake_case が使われ、BISIBILITY_MCP_TOOLSETS でフィルタリングできます。組み込みの /api/mcp エンドポイントと共有するツールには、同じ名前が使われます。2 つのトランスポートではツールの一覧が異なるため、切り替える前に tools/list を確認してください。

Domain Overview ツールでは、0 以上の整数のセント単位で max_cost_cents 上限を指定する必要があります。安全のため、まず estimate_only: true と max_cost_cents: 0 を指定して見積もりを行ってください。プロバイダーの見積もりや返却される料金には、小数のセントが含まれる場合があります。

順位の結果を確認するときは、実行ステータスと observation_completeness を position とあわせて確認してください。カバレッジが不明またはレガシーの場合、position が null であっても Top N 内に存在しないことの根拠にはなりません。その結論を裏付けるのはカバレッジが完全な場合のみです。カバレッジが不完全でも、正の position は有効です。latest_successful_check は直近で完了した観測を意味しますが、そのカバレッジ自体が不明な場合もあります。

被リンクの履歴は任意です。history_unavailable は、サマリーとリンクは引き続き利用できるものの、確認済みのコストを伴う履歴取得の失敗を示します。会計情報が不明な場合、リクエストは失敗（isError）のままとなり、現在のレスポンスの証拠として、完了済みのサマリーを含むことがあります。この場合、cost_cents は null で、行はリクエストされません。この証拠はキャッシュされたスナップショットでも確定済みの合計でもなく、load_more_backlink_rows で追加取得することも、再読み込み後に保持することもできません。

領域	例
検出	ヘルス、機能、プロバイダーの料金、コスト見積もり
順位追跡	プロジェクト、キーワード、チェック、順位履歴、サイトマップ
分析	トラフィックのスナップショット、クエリ統計、シグナル、被リンク、Domain Overview
エージェント分析	プロジェクトのコンテキスト、保存済みレポート、AI の可視性、合成プロンプトの比較、範囲を限定したサイト監査
コラボレーション	アラート、チームメンバー、招待、通知
管理	プロバイダー、API キー、個人用トークン、Webhook、移行トークン

このソースチェックアウトに含まれるツール名を表示

この一覧は、ソースチェックアウトと未リリースの変更内容を示しています。現在公開されているパッケージとディレクトリのバージョンについては、 配布状況を参照してください。 ホストされたエンドポイントには独自のツール一覧があります。

• get_session_profile

• get_health

• get_capabilities

• get_cloud_import_compatibility

• get_provider_rates

• get_cost_estimate

• get_me

• update_me

• list_projects

• create_project

• get_project

• search_locations

• update_project

• delete_project

• get_project_defaults

• preview_project_defaults

• update_project_defaults

• list_keywords

• list_ranked_keyword_suggestions

• research_keywords

• estimate_keyword_research_cost

• analyze_backlinks

• estimate_backlinks_cost

• load_more_backlink_rows

• analyze_domain_overview

• estimate_domain_overview_cost

• load_domain_overview_history

• load_domain_overview_keywords

• load_domain_overview_pages

• get_keyword_metrics

• add_keywords

• get_keyword

• update_keyword

• set_keyword_target_url

• delete_keyword

• bulk_update_keywords

• run_rank_check

• get_rank_history

• export_rank_history | list_rank_check_runs | 保持された実行結果と継続カーソルを読み取ります。チェックを実行せずに終了した、ブロック済みおよびキャンセル済みの実行も含まれます。 | | get_rank_check_run | チェックを開始または再試行せずに、保持された実行を1件読み取ります。 |

• list_local_monitor_runs

• get_local_monitor_run_results

• list_local_monitor_point_listings

• list_local_monitor_point_history

• export_local_monitor_run

• list_sitemap_monitors

• enable_sitemap_monitor

• disable_sitemap_monitor

• get_rank_check_result

• create_signal

• list_signals

• list_traffic_snapshots

• list_search_performance_query_stats

• sync_project_traffic

• list_api_keys

• create_api_key

• revoke_api_key

• list_project_api_keys

• create_project_api_key

• list_personal_tokens

• create_personal_token

• revoke_personal_token

• list_webhooks

• create_webhook

• update_webhook

• delete_webhook

• list_alert_rules

• create_alert_rule

• update_alert_rule

• delete_alert_rule

• list_triggered_alerts

• mute_triggered_alert

• mark_project_alerts_read

• list_team_members

• list_team_invites

• create_team_invite

• revoke_team_invite

• resend_team_invite

• update_team_member_role

• remove_team_member

• list_providers

• connect_provider (primary: true は優先度 0 のレガシーエイリアスです）

• test_provider_connection

• update_provider_settings

• set_provider_enabled

• set_provider_priority

• set_primary_provider（レガシー：true は優先度 0 に昇格し、false は何もしません）

• disconnect_provider

• list_saved_keywords

• create_saved_keywords

• delete_saved_keyword

• list_saved_views

• create_saved_view

• delete_saved_view

• list_competitors

• add_competitor

• remove_competitor

• get_notification_preferences

• update_notification_preferences

• list_migration_tokens

• mint_migration_token

• revoke_migration_token

• get_project_context

• update_project_context

• list_agent_reports

• create_agent_report

• get_agent_report

• analyze_ai_visibility

• get_ai_research_catalog

• compare_ai_prompts

• run_site_audit

• list_site_audits

• get_site_audit

• list_ai_tracking_topics

• create_ai_tracking_topic

• update_ai_tracking_topic

• archive_ai_tracking_topic

• list_ai_tracking_prompts

• create_ai_tracking_prompt

• update_ai_tracking_prompt

• archive_ai_tracking_prompt

• list_ai_tracking_schedules

• create_ai_tracking_schedule

• update_ai_tracking_schedule

• archive_ai_tracking_schedule

• preview_ai_tracking_run

• create_ai_tracking_run

• list_ai_tracking_runs

• get_ai_tracking_run

• list_ai_tracking_samples

• cancel_ai_tracking_run

• retry_ai_tracking_run

• get_ai_tracking_history

• get_ai_tracking_trends

• export_ai_tracking_evidence

• suggest_ai_tracking_prompts

• accept_ai_tracking_suggestions

• ai_tracking_suggestions_preview

• ai_tracking_suggestions_generate

すべての保護されたツールは、設定済みの `BISIBILITY_API_KEY` を使用します。`idempotency_key` を受け付けるツールは、これを API の `Idempotency-Key` リクエストオプションとして渡します。このキーは `create_ai_tracking_run`、`retry_ai_tracking_run`、および `ai_tracking_suggestions_generate` で必須です。生成には UUID が必要です。その他のツールでは、スキーマでサポートされている場合にオプションのキーを公開します。

上記の一覧はテスト（test/tools.test.ts）で検証されているため、登録済みツールの一覧と常に一致します。

セキュリティ

認証情報のスコープが主要な認可制御であり、サーバーは2種類の認証情報を受け付けます。プロジェクトキー（bsb_key_live_...）は1つのプロジェクトにのみ属するため、漏えい時の被害を抑えられ、単一プロジェクト環境やマシンでの利用に適しています。パーソナルアクセストークン（bsb_pat_live_...）は、メンバーになっているプロジェクトを対象とするため、1つのトークンですべてのプロジェクトに対応できます。各プロジェクトで有効となるアクセス権は、トークンのスコープとそのプロジェクトでのあなたのロールのうち、より制限の厳しい方です。そのため、トークンが本人の権限を超えることはありません。複数のプロジェクトにまたがるトークンのデフォルトプロジェクトを設定するには、上記の環境設定で説明した BISIBILITY_PROJECT_ID を使用してください。

どちらの種類を使用する場合でも、可能な限りアシスタント用には read スコープで作成し、アシスタントが管理 API 操作を必要としない限り、admin を付与しないでください。サーバー側のフィルタリングによってモデルに提示されるツールは絞り込まれますが、設定済みの認証情報の権限が拡大したり、置き換わったりすることはありません。

書き込みスコープまたは管理者権限の認証情報を受け取ったエージェントは、プロジェクトデータを作成・変更できます。プロバイダーを利用する Domain Overview ツールは、キャッシュミス時にプロジェクト固有のプロバイダー予算を消費する場合もあります。すべての Domain Overview 呼び出しでは、負でない整数の max_cost_cents を明示的に指定する必要があります。安全な事前見積もりには、analyze_domain_overview を estimate_only: true および max_cost_cents: 0 で呼び出してください。キャッシュのみを試す場合も、同じゼロ上限を使用してください。正の値を指定すると、許可されるプロバイダー料金の上限になります。

AI の可視性機能が読み取るのは、プロバイダーが観測した限定的なデータセットです。Prompt Explorer は合成プロンプトを実行するものであり、すべてのユーザーとの会話や観測された AI の可視性を測定するものではありません。観測された可視性を取得するには、セント単位の整数で max_cost_cents の上限を明示する必要があります。プロンプト比較では、この上限をデフォルトのハード上限モードで使用します。明示的なプロバイダー実費モードでは、保証されないことを確認したうえでの見積もりと、参考上限を使用します。まず estimate_only: true とゼロ上限で開始してください。サイト監査では、ページ数と期限を制限してプロジェクトのドメインのみをクロールします。Lighthouse の実行や有料プロバイダー処理は行いません。保存済みレポートとプロジェクトコンテキストには、プロジェクトに既存の認可ルールが適用されます。

破壊的な操作には、delete_project、delete_keyword、操作が delete の場合の bulk_update_keywords、delete_webhook、delete_alert_rule、delete_saved_keyword、delete_saved_view、remove_team_member、remove_competitor、disconnect_provider、revoke_api_key、revoke_personal_token、revoke_team_invite、および revoke_migration_token が含まれます。サーバーが使用している認証情報を失効させると、サーバーが即座にアクセスできなくなる場合があります。

多層防御として、読み取り専用モードと、許可するツールを絞ったリストを使用してください。

export BISIBILITY_MCP_READ_ONLY="1"
export BISIBILITY_MCP_TOOLSETS="projects,keywords,checks,rank-history,alerts"

API から返されるコンテンツは、モデルに届く信頼できない入力です。プロジェクト名、キーワードのフレーズ、アラートのテキストなどの追跡データには、書き込みツールも持つエージェントを誘導しようとする悪意ある指示が含まれている可能性があります。ワークフローで許容できる範囲で認証情報と登録済みツールセットを絞り、MCP クライアントが対応している場合は、ツール呼び出しに対するクライアント側の確認を有効にしてください。

HTTP トランスポート

このパッケージには stdio トランスポートのみが含まれています。コードは分割されているため、HTTP トランスポートから同じサーバーファクトリーを再利用できます。

import { createBisibilityClientFromEnv, createBisibilityMcpServer } from "@bisibility/mcp";

const client = createBisibilityClientFromEnv();
const server = createBisibilityMcpServer({ client });

HTTP エントリーポイントでは、Node、Worker、またはホスト型アダプターで、StreamableHTTPServerTransport などの公式 SDK HTTP トランスポートを使用して、そのサーバーをラップできます。

開発

npm run lint
npm run typecheck
npm test
npm run build

ライセンス

Apache License, Version 2.0 に基づいてライセンスされています。LICENSE と NOTICE を参照してください。

AI トラッキング

ai-tracking ツールセットは、トピック、不変のプロンプト改訂、無効化されたスケジュール、費用のかからないプレビュー、同意済みの実行、サンプル、履歴、トレンド、エクスポート、明示的に承認されたプロンプト候補に関する、プロジェクト単位のツールを26個提供します。読み取り専用セッションでは、プレビューとエビデンスの読み取りを引き続き利用できます。起動と再試行には、確認済みの認証情報／予算／同意の改訂、明示的な有料利用への同意、および安定したidempotency_keyが必要です。このキーはSDKを通じてIdempotency-Keyとして転送されます。どの操作も、有料のベースラインを自動的に開始することはありません。

get_ai_research_catalogは、無料で利用できるモデルと言語／地域の機能を読み取ります。compare_ai_promptsは、カタログのモデルID、任意のウェブ検索と言語／地域のヒント、および実費に関する明示的なポリシーを受け付けます。実費への同意は、見積もり額が保証された上限ではないことを了承するものです。

モデルのプロンプト生成では、ai_tracking_suggestions_previewに続いてai_tracking_suggestions_generateを使用します。プレビューでは、有料のプロバイダー処理を行わずに、5つのコンテキストフィールド、選択した競合他社、モデル、市場を確認できます。生成には、有効期限内の完全な固定済みプレビュー、明示的な有料利用への同意、および安定したUUID形式のidempotency_keyが必要です。予測値に保証された上限はありません。生成された下書きには、測定済みの人気度は付与されません。承認された編集では信頼済みのgeneration_referenceが保持され、プロバイダーのデータセットでは検証済みのprovider_dataset_referenceが使用されます。

レスポンスエビデンスの互換性

順位チェックでは省略可能なobservation_completenessが公開され、キーワードでは省略可能なlatest_checkとlatest_successful_checkが公開されます。古いレスポンスでは、これらのフィールドが省略されることがあります。要求された深さまで網羅的に確認できた場合に限り、結果がないことを根拠として扱えます。順位が確認できた場合は、網羅性が不明または途中までであっても有効です。新しいチェックが失敗した場合も、以前の成功結果は保持されます。

サイトの被リンク履歴は通常、12か月分です。一部のみを含むスナップショットが成功した場合、history: []およびhistory_unavailable: trueが返されます。その要約、行データ、確認済みの費用は保持してください。ページ単位のスコープでは履歴を要求しません。利用可能性のメタデータがない場合は、従来のデフォルト値が使用されます。要約の取得に失敗した場合は、HTTPエラーとなり、現在のレスポンスのエビデンスが問題のdetailsに含まれます。cost_cents: nullは合計が不明であることを示し、known_summary_cost_centsは確認済みの金額を示します。

バージョン管理された保持履歴のエクスポート（未リリース）

バージョン2をオプトインすると、レポートの品質、メトリックのバージョン、固定された選択内容、および署名付き継続カーソルが保持されます。各ページで、ストリーム、基準、開始／終了日時、キーワードの選択を変更しないでください。デフォルトでは、従来のv1形式の行が引き続き使用されます。観測には、上限が設定された正規化済みアイテムが含まれます。CIDを表す不透明な文字列は、元の桁をすべて保持します。記録時刻を基準とする試行ストリームには、チェックを伴わない実際の実行／アイテムのバリエーションも含まれ、キャンセル済み、延期、ブロックの各結果が対象となります。プロジェクト全体のエクスポートでは、プロジェクトのみを対象とする実行も明示的に保持されます。選択したエクスポートでは、メンバーシップを解決できないために除外された項目が報告されます。CSVには、上限が設定された完全なレポートマニフェストが含まれ、カーソルは受け付けません。サイズ超過のソースは413エラーとなり、署名付きスナップショットが変更されている場合は409エラーとなります。

順位履歴の仕様を参照してください。

提供されるMCPツールはJSONを返します。完全なCSVのダウンロードにはREST APIまたはSDKを使用してください。

保持されたLocalデータの読み取り

読み取り専用の5つのツール、list_local_monitor_runs、get_local_monitor_run_results、list_local_monitor_point_listings、list_local_monitor_point_history、export_local_monitor_runは、SDKの実際のLocal APIメソッドを呼び出します。元のlmn／lmr／lmtスコープ、null／不明な品質、正確な文字列形式のCID、保持されたソースメタデータをそのまま維持します。履歴のas_of／from／toには、正規のUTCミリ秒とoccurrence_created_atを使用します。署名付きカーソルを使って、選択内容全体を保持してください（1～8000文字）。エクスポートツールが返すのは、既存のLocal point-report-v1 JSONのみです。これらの読み取りによって、プロバイダー処理やスケジュールが開始されることはありません。これらのソース変更は未リリースであり、パッケージでの対応はSDKのリリース後に提供されます。

レビュー済みのデフォルト設定

preview_project_defaults を使って現在のドラフトと影響を読み取ります。このツールは設定を書き込まず、プロバイダーにも処理を依頼しませんが、サーバーには引き続き設定権限が必要です。呼び出し元がドラフトを明示的に承認した後、同じ設定と、返された expected_source_hash、文字列の expected_revision、preview_token、安定した idempotency_key、および confirmed: true を含む review を指定して update_project_defaults を呼び出します。確認がない場合は 428 が返され、レビューが古いか期限切れの場合は 409 が返されます。応答を受け取れなかった場合は、同一のボディとコマンドキーを再利用します。ツールが自動的に確認を行うことはありません。

SDK は、プレビューまたはレビュー済み更新の PATCH を送信する前に、サーバーが features.reviewed_project_defaults: "v1" 機能に対応していることを必要とします。プレビューを装った書き込みを誤って行うリスクを避けるため、古いサーバーにはリクエストを送信しません。このマーカーによって設定権限が付与されることはありません。