chore(release): v0.5.0

Author: github-actions[bot]

.gitleaks.toml

@@ -7,8 +7,8 @@ useDefault = true
 description = "Obvious SDK documentation and test placeholders"
 regexTarget = "match"
 regexes = [
-  '''bsk_live_(\.\.\.|[a-z0-9_]*(example|secret|do_not_log|123456)[a-z0-9_]*)''',
-  '''bsp_live_(\.\.\.|[a-z0-9_]*(example|secret|123456)[a-z0-9_]*)''',
+  '''bsb_key_live_(\.\.\.|[a-z0-9_]*(example|secret|do_not_log|123456)[a-z0-9_]*)''',
+  '''bsb_pat_live_(\.\.\.|[a-z0-9_]*(example|secret|123456)[a-z0-9_]*)''',
   '''mig_(\.\.\.|secret)''',
   '''Bearer reflected-secret''',
   '''US/Texas/Austin''',

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.5.0 - 2026-07-29
+
+- Breaking: require public ID v3 prefixes and `bsb_key_*` or `bsb_pat_live_` credentials.
+  Public ID v2 values and legacy `bsk_*` or `bsp_*` credentials are no longer accepted.
+
 ## 0.4.0 - 2026-07-29
 
 - Breaking: use the same 84 unprefixed `snake_case` tool names as `/api/mcp`; clients must remove

README.md

@@ -37,7 +37,7 @@ The SDK is consumed from the npm registry:
 ## Environment
 
 ```sh
-export BISIBILITY_API_KEY="bsp_live_..."
+export BISIBILITY_API_KEY="bsb_pat_live_..."
 export BISIBILITY_BASE_URL="https://bisibility.com/api/v1"
 export BISIBILITY_PROJECT_ID="prj_..."
 export BISIBILITY_MCP_READ_ONLY="1"
@@ -46,18 +46,18 @@ export BISIBILITY_MCP_TOOLSETS="projects,keywords,checks,rank-history"
 
 `BISIBILITY_BASE_URL` is optional and defaults to `https://bisibility.com/api/v1`. For self-hosted
 installs, set it to your API v1 root, for example `https://rank.example/api/v1`.
-`BISIBILITY_API_KEY` accepts a project key (`bsk_live_...`) or personal access
-token (`bsp_live_...`). Set optional `BISIBILITY_PROJECT_ID` as the default
+`BISIBILITY_API_KEY` accepts a project key (`bsb_key_live_...`) or personal access
+token (`bsb_pat_live_...`). Set optional `BISIBILITY_PROJECT_ID` as the default
 `X-Bisibility-Project` selector for project-implicit PAT tools; a tool's
 optional `project_id` argument overrides it for that call. Every resource ID
 accepted by the MCP server, including `BISIBILITY_PROJECT_ID`, must use public
-ID v2: a canonical lowercase prefix plus `_` and a 24-character lowercase
+ID v3: a canonical lowercase prefix plus `_` and a 24-character lowercase
 CUID2 suffix, for example `prj_a1b2c3d4e5f6g7h8j9k0m2n3`. Raw database IDs,
 legacy IDs, mixed-case IDs, and wrong resource prefixes are rejected. Location
 selection uses the returned `location_key`, never a location ID.
 
-The SDK dependency and lockfile use the published registry package. Do not use
-a local SDK link.
+The server consumes the public ID v3 contract from the published
+`@bisibility/sdk` package. Do not replace it with a local SDK link.
 
 `BISIBILITY_MCP_READ_ONLY` accepts `1`, `true`, `yes`, or `on`, ignoring case. When enabled,
 write tools are not registered and do not appear in `tools/list`.
@@ -73,7 +73,7 @@ control, not a way to improve tool selection.
 
 ```sh
 npm run build
-BISIBILITY_API_KEY="bsk_live_..." node dist/stdio.js
+BISIBILITY_API_KEY="bsb_key_live_..." node dist/stdio.js
 ```
 
 When installed as a package, the bin is:
@@ -93,7 +93,7 @@ Example MCP client configuration using the built local package:
       "command": "node",
       "args": ["/path/to/bisibility-mcp/dist/stdio.js"],
       "env": {
-        "BISIBILITY_API_KEY": "bsk_live_...",
+        "BISIBILITY_API_KEY": "bsb_key_live_...",
         "BISIBILITY_BASE_URL": "https://bisibility.com/api/v1"
       }
     }
@@ -109,7 +109,7 @@ Example using the package bin:
     "bisibility": {
       "command": "bisibility-mcp",
       "env": {
-        "BISIBILITY_API_KEY": "bsk_live_...",
+        "BISIBILITY_API_KEY": "bsb_key_live_...",
         "BISIBILITY_BASE_URL": "https://bisibility.com/api/v1"
       }
     }
@@ -230,9 +230,9 @@ registered tool surface.
 ## Security
 
 The credential's scope is the primary authorization control, and the server accepts two kinds.
-A project key (`bsk_live_...`) belongs to exactly one project, which bounds the damage from a
+A project key (`bsb_key_live_...`) belongs to exactly one project, which bounds the damage from a
 leak and makes it a good fit for a single-project or machine setup. A personal access token
-(`bsp_live_...`) covers the projects you are a member of, so one token serves them all; its
+(`bsb_pat_live_...`) covers the projects you are a member of, so one token serves them all; its
 effective access in each project is the lower of the token's scope and your role there, meaning
 a token never grants more than the person behind it. Use `BISIBILITY_PROJECT_ID` to set the
 default project for a token that spans several, as described under Environment above.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@bisibility/mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Model Context Protocol server for the Bisibility REST API.",
   "type": "module",
   "license": "Apache-2.0",
@@ -65,7 +65,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bisibility/sdk": "^0.5.0",
+    "@bisibility/sdk": "^0.6.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "^4.4.3"
   },

package.json

@@ -47,6 +47,21 @@ export interface BisibilityMcpConfig {
   projectId?: PublicIdForPrefix<"prj">;
 }
 
+const API_CREDENTIAL_PREFIXES = ["bsb_key_live_", "bsb_key_test_", "bsb_pat_live_"] as const;
+
+function readApiCredential(value: string | undefined) {
+  const credential = cleanEnvValue(value);
+  if (!credential) {
+    throw new Error("BISIBILITY_API_KEY is required to run the Bisibility MCP server.");
+  }
+  if (!API_CREDENTIAL_PREFIXES.some((prefix) => credential.startsWith(prefix))) {
+    throw new Error(
+      "BISIBILITY_API_KEY must use bsb_key_live_, bsb_key_test_, or bsb_pat_live_. Legacy bsp_ and bsk_ credentials are not accepted.",
+    );
+  }
+  return credential;
+}
+
 function cleanEnvValue(value: string | undefined) {
   const cleaned = value?.trim();
   if (!cleaned) {
@@ -93,10 +108,7 @@ export function readBisibilityMcpToolConfig(
 }
 
 export function readBisibilityMcpConfig(env: BisibilityMcpEnv = process.env): BisibilityMcpConfig {
-  const apiKey = cleanEnvValue(env.BISIBILITY_API_KEY);
-  if (!apiKey) {
-    throw new Error("BISIBILITY_API_KEY is required to run the Bisibility MCP server.");
-  }
+  const apiKey = readApiCredential(env.BISIBILITY_API_KEY);
 
   const baseUrl = cleanEnvValue(env.BISIBILITY_BASE_URL ?? DEFAULT_BISIBILITY_BASE_URL);
   if (!baseUrl) {
@@ -107,7 +119,7 @@ export function readBisibilityMcpConfig(env: BisibilityMcpEnv = process.env): Bi
   if (projectId) {
     const parsedProjectId = projectIdInput.safeParse(projectId);
     if (!parsedProjectId.success) {
-      throw new Error("BISIBILITY_PROJECT_ID must be a prj_ public ID v2.");
+      throw new Error("BISIBILITY_PROJECT_ID must be a prj_ public ID v3.");
     }
     return { apiKey, baseUrl, projectId: parsedProjectId.data };
   }

src/config.ts

@@ -1,29 +1,29 @@
 import * as z from "zod/v4";
 
 export const publicIdPrefixes = [
-  "alert",
+  "al",
+  "alr",
   "audit",
   "check",
-  "comp",
+  "cmp",
   "conn",
-  "hook",
-  "invite",
-  "job",
+  "dwh",
+  "ferry",
+  "imp",
+  "inv",
   "key",
   "kw",
-  "member",
-  "mtok",
-  "notif",
+  "mbr",
+  "ntf",
   "pat",
   "prj",
-  "rule",
-  "ses",
+  "sid",
   "sig",
-  "skw",
+  "svkw",
   "tag",
   "usr",
-  "view",
-  "webhook",
+  "viw",
+  "we",
 ] as const;
 
 export type PublicIdPrefix = (typeof publicIdPrefixes)[number];
@@ -54,7 +54,7 @@ export function assertPublicId<Prefix extends PublicIdPrefix>(
   prefix: Prefix,
 ): asserts value is PublicIdForPrefix<Prefix> {
   if (!matchesPublicId(value, prefix)) {
-    throw new Error(`Expected a ${prefix}_ public ID v2.`);
+    throw new Error(`Expected a ${prefix}_ public ID v3.`);
   }
 }
 
@@ -71,31 +71,31 @@ export const publicIdInput = <Prefix extends PublicIdPrefix>(prefix: Prefix) =>
     .string()
     .trim()
     .regex(publicIdPattern(prefix), {
-      message: `Expected a ${prefix}_ public ID v2.`,
+      message: `Expected a ${prefix}_ public ID v3.`,
     })
     .transform((value) => parsePublicId(value, prefix));
 
-const alertIdInput = publicIdInput("alert").describe(
+const alertIdInput = publicIdInput("al").describe(
   "Identifier of the triggered alert to operate on.",
 );
 const checkIdInput = publicIdInput("check").describe("Identifier of the rank check to retrieve.");
-const competitorIdInput = publicIdInput("comp").describe(
+const competitorIdInput = publicIdInput("cmp").describe(
   "Identifier of the competitor to operate on.",
 );
 const connectionIdInput = publicIdInput("conn").describe(
   "Identifier of the provider connection to operate on.",
 );
-const inviteIdInput = publicIdInput("invite").describe(
+const inviteIdInput = publicIdInput("inv").describe(
   "Identifier of the team invitation to operate on.",
 );
 const keyIdInput = publicIdInput("key").describe("Identifier of the API key to operate on.");
 const keywordIdInput = publicIdInput("kw").describe(
   "Identifier of the tracked keyword to operate on.",
 );
-const memberIdInput = publicIdInput("member").describe(
+const memberIdInput = publicIdInput("mbr").describe(
   "Identifier of the project member to operate on.",
 );
-const migrationTokenIdInput = publicIdInput("mtok").describe(
+const migrationTokenIdInput = publicIdInput("ferry").describe(
   "Identifier of the migration token to operate on.",
 );
 const personalAccessTokenIdInput = publicIdInput("pat").describe(
@@ -104,9 +104,9 @@ const personalAccessTokenIdInput = publicIdInput("pat").describe(
 export const projectIdInput = publicIdInput("prj").describe(
   "Identifier of the Bisibility project to operate on; list_projects returns valid project ids.",
 );
-const ruleIdInput = publicIdInput("rule").describe("Identifier of the alert rule to operate on.");
-const viewIdInput = publicIdInput("view").describe("Identifier of the saved view to operate on.");
-const webhookIdInput = publicIdInput("webhook").describe(
+const ruleIdInput = publicIdInput("alr").describe("Identifier of the alert rule to operate on.");
+const viewIdInput = publicIdInput("viw").describe("Identifier of the saved view to operate on.");
+const webhookIdInput = publicIdInput("we").describe(
   "Identifier of the webhook endpoint to operate on.",
 );
 export const deviceInput = z
@@ -979,7 +979,7 @@ function validateAlertTargets(
     if (!matchesPublicId(targetId, expectedPrefix)) {
       ctx.addIssue({
         code: "custom",
-        message: `Expected a ${expectedPrefix}_ public ID v2.`,
+        message: `Expected a ${expectedPrefix}_ public ID v3.`,
         path: ["target_ids", index],
       });
     }