bisibility

@bisibility/mcp

属于 bisibility 的一部分——一个用于关键词研究、反向链接分析和 Google 排名跟踪的开源 SEO 平台。本仓库包含 MCP 服务，可向 AI Agent 提供 bisibility 工具。

文档 · 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 参数会覆盖该值，仅对当次调用生效。MCP 服务接受的每个资源 ID （包括 BISIBILITY_PROJECT_ID）都必须使用当前的类型化公开 ID 格式：规范的小写前缀，加上 _ 和 24 个小写字符的后缀，例如 prj_a1b2c3d4e5f6g7h8j9k0m2n3。 格式错误的 ID、大小写混用的 ID 以及资源前缀错误的 ID 都会被拒绝。 位置选择使用返回的 location_key，而不是位置 ID。键的末尾可以加上 @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 端点共享的工具使用相同名称。两种传输方式 的工具清单不同；切换前请检查 tools/list。

Domain Overview 工具始终要求设置非负的整数美分 max_cost_cents 上限。安全的先估算步骤应同时使用 estimate_only: true 和 max_cost_cents: 0；提供方估算值和返回的费用仍可能包含小数美分。

对于排名结果，请结合执行状态和 observation_completeness 查看 position。当覆盖情况未知或属于旧版时，位置为 null 并不能证明结果不在 Top N 内。只有覆盖完整时才能得出该结论；即使覆盖被截断，正的位置仍然有效。 latest_successful_check 指最近一次已完成的观测，该观测本身的覆盖情况也可能未知。

反向链接历史记录为可选项。history_unavailable 表示历史记录获取失败，但费用已确认；摘要和链接仍可用。如果费用未知，请求仍会失败（isError），并且可能会将已完成的摘要作为当前响应证据返回： cost_cents 为 null，且不会请求行数据。此证据不是缓存快照或已结算总额，不能通过 load_more_backlink_rows 扩展，也不会在重新加载后保留。

区域	示例
发现	健康状态、功能、提供方费率和费用估算
排名跟踪	项目、关键词、检查、排名历史和站点地图
分析	流量快照、查询统计、信号、反向链接和 Domain Overview
Agent 分析	项目上下文、已保存的报告、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 | 读取一项保留的执行记录，不会启动或重试检查。 |

• 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）断言，因此会与已注册的工具保持同步。

安全

凭证的作用范围是主要的授权控制，服务接受两种凭证。项目密钥（bsb_key_live_...）仅属于一个项目，可限制泄露造成的损失，因此很适合单项目或机器环境。个人访问令牌（bsb_pat_live_...）涵盖你所属的所有项目，因此一个令牌即可用于所有这些项目；它在每个项目中的实际访问权限取决于令牌作用范围和你在该项目中的角色，两者取较低者，也就是说，令牌授予的权限不会超过令牌持有者本人的权限。对于覆盖多个项目的令牌，请按上文“环境”部分所述，使用 BISIBILITY_PROJECT_ID 设置默认项目。

无论使用哪种凭证，只要可能，就应为助手创建带有 read 作用范围的凭证；除非助手需要执行管理 API 操作，否则不要授予 admin 权限。服务端过滤会缩小呈现给模型的工具范围，但不会扩大或取代已配置凭证的权限。

如果 Agent 获得带有写入权限或管理员权限的凭证，就可以创建和更改项目数据。由提供商支持的 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 返回的内容是不可信输入，且会传递给模型。项目名称、关键词短语、提醒文本和类似的跟踪数据可能包含恶意指令，意图操纵同时拥有写入工具的 Agent。请根据工作流所需，将凭证和已注册的工具集范围限制在最小程度；如果 MCP 客户端支持，请启用工具调用的客户端确认。

HTTP 传输

此软件包仅提供 stdio 传输。代码经过拆分，HTTP 传输可以复用相同的服务工厂：

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

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

HTTP 入口可使用官方 SDK 的 HTTP 传输（例如 StreamableHTTPServerTransport），在 Node、Worker 或托管适配器中封装该服务。

开发

npm run lint
npm run typecheck
npm test
npm run build

许可证

根据 Apache License 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。预览会审核全部五个上下文字段、选定的竞争对手、模型和市场，不会触发付费服务商操作。生成需要完整且未过期的冻结预览、明确的付费同意以及稳定的 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。

保留数据的本地读取

这五个只读工具 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 范围、空值／未知质量、精确的字符串 CID 和保留的源元数据。历史记录的 as_of/from/to 使用规范的 UTC 毫秒时间和 occurrence_created_at；使用签名游标保留 完整选择（1..8000 个字符）。导出工具仅返回现有的 Local point-report-v1 JSON。读取操作 不会启动服务商操作或计划任务。这些源代码变更尚未发布；打包版本的支持将在 SDK 发布后提供。

已审核的默认设置

使用 preview_project_defaults 读取当前草案和影响；它不会写入设置或执行任何提供方操作，但服务器仍要求具有设置权限。调用方明确批准该草案后，调用 update_project_defaults，并传入相同的设置，以及包含返回的 expected_source_hash、字符串类型的 expected_revision、preview_token、稳定的 idempotency_key 和 confirmed: true 的 review。缺少确认时返回 428；审核已过期或与当前状态不符时返回 409。如果响应丢失，请重用完全相同的请求正文和命令键。这些工具绝不会自动确认。

发送预览或经审核的更新 PATCH 请求前，SDK 要求服务器具备 features.reviewed_project_defaults: "v1" 能力。为避免将写入误当作预览，SDK 会拒绝使用较旧的服务器。此标记不会授予设置权限。