@jskit-ai/connectors-catalog 0.1.1

package/src/server/salesforce.js

@@ -0,0 +1,84 @@
+import { createSchema } from "json-rest-schema";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { salesforceDefinition } from "../shared/salesforce.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const apiPath = "/services/data/v66.0";
+const origin = (settings) => new URL(settings.accountUrl).origin;
+const endpoint = (resource) => (settings) => `${origin(settings)}${apiPath}/${resource}`;
+const objectName = (value) => typeof value === "string" && /^[A-Za-z][A-Za-z0-9_]{0,254}$/u.test(value);
+const locator = (value) => typeof value === "string" && /^\/services\/data\/v66\.0\/query\/[A-Za-z0-9]{15,18}-[0-9]{1,10}$/u.test(value);
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const limits = (value) => record(value) && Number.isSafeInteger(value.DailyApiRequests?.Max) && value.DailyApiRequests.Max >= 0 &&
+  Number.isSafeInteger(value.DailyApiRequests.Remaining) && value.DailyApiRequests.Remaining >= 0;
+const queryResult = (value) => Number.isSafeInteger(value?.totalSize) && value.totalSize >= 0 && typeof value.done === "boolean" &&
+  Array.isArray(value.records) && value.records.length <= 2000 && value.records.every(record) && value.records.length <= value.totalSize &&
+  (value.done ? value.nextRecordsUrl == null : locator(value.nextRecordsUrl));
+const describeSchema = createSchema({ object: { type: "string", required: true, validator: (value) => objectName(value) || "Use a Salesforce object API name." } });
+const nextSchema = createSchema({ nextRecordsUrl: { type: "string", required: true, noTrim: true,
+  validator: (value) => locator(value) || "Use the nextRecordsUrl returned by this connection's v66.0 query." } });
+
+const salesforceProvider = Object.freeze({
+  ...salesforceDefinition,
+  oauth: (settings) => ({ issuer: origin(settings), authorization_endpoint: `${origin(settings)}/services/oauth2/authorize`, token_endpoint: `${origin(settings)}/services/oauth2/token` }),
+  apiOrigins: (settings) => [origin(settings)], checkOperation: "limits.read",
+  async normalizeTokenResponse(response, { settings }) {
+    if (!response.ok) return response;
+    let value;
+    try { value = await response.clone().json(); } catch { /* reported below */ }
+    if (!record(value) || ![origin(settings), origin(settings) + "/"].includes(value.instance_url) || typeof value.scope !== "string" || !value.scope.trim()) {
+      throw new ConnectorError("connector_response_invalid", "Salesforce returned an invalid grant or a different organisation.", { statusCode: 502 });
+    }
+    // Salesforce can omit expiry. Renew after five minutes of use as a local
+    // policy; this is not a claim about the org's actual session lifetime.
+    return value.expires_in === undefined ? Response.json({ ...value, expires_in: 300 }) : response;
+  },
+  operations: {
+    "limits.read": { ...jsonOperation(endpoint("limits"), {}, limits), scopes: ["api"] },
+    "objects.list": { ...jsonOperation(endpoint("sobjects"), {},
+      (value) => Array.isArray(value?.sobjects) && value.sobjects.every((object) => objectName(object?.name) && typeof object.label === "string" && typeof object.queryable === "boolean")), scopes: ["api"] },
+    "objects.describe": {
+      scopes: ["api"],
+      request(input, settings) {
+        const values = validateSchemaPayload({ schema: describeSchema, mode: "replace" }, input, { statusCode: 422 });
+        return { method: "GET", url: endpoint(`sobjects/${values.object}/describe`)(settings) };
+      },
+      validateResult: (value) => objectName(value?.name) && Array.isArray(value.fields) && value.fields.every((field) => objectName(field?.name) && typeof field.type === "string")
+    },
+    "query.read": {
+      ...jsonOperation(endpoint("query"), { q: { type: "string", required: true, minLength: 1, maxLength: 2000,
+        validator: (value) => /^SELECT\s/iu.test(value) && new TextEncoder().encode(value).length <= 3000 && !/\bFOR\s+(?:UPDATE|VIEW|REFERENCE)\b/iu.test(value) && !/[\p{Cc}]/u.test(value) || "Use a single-line SELECT query without FOR UPDATE, FOR VIEW or FOR REFERENCE." } }, queryResult), scopes: ["api"]
+    },
+    "query.next": {
+      scopes: ["api"],
+      request(input, settings) {
+        const values = validateSchemaPayload({ schema: nextSchema, mode: "replace" }, input, { statusCode: 422 });
+        return { method: "GET", url: origin(settings) + values.nextRecordsUrl };
+      },
+      validateResult: queryResult
+    }
+  },
+  async exchange(address, options, { fetchImpl }) {
+    const response = await fetchImpl(address, { ...options, credentials: "omit" });
+    let value;
+    try { value = await response.json(); } catch { /* checked after status */ }
+    const code = Array.isArray(value) ? value[0]?.errorCode : null;
+    if (!response.ok) {
+      if (code === "REQUEST_LIMIT_EXCEEDED") throw new ConnectorError("connector_rate_limited", "The Salesforce organisation's API request limit was reached.", { statusCode: 429 });
+      if (code === "INVALID_SESSION_ID") throw new ConnectorError("connector_reconnect_required", "Connect this Salesforce account again.", { statusCode: 401 });
+      if (code === "INVALID_QUERY_LOCATOR") throw new ConnectorError("connector_cursor_expired", "Start the Salesforce query again; its result cursor is no longer valid.", { statusCode: 410 });
+      if (response.status === 404) throw new ConnectorError("connector_resource_not_found", "This Salesforce resource is not available.", { statusCode: 404 });
+      if (response.status === 400) throw new ConnectorError("connector_query_invalid", "Salesforce rejected the query or object. Check its API names and the user's permissions.", { statusCode: 422 });
+      throw Object.assign(new Error("Salesforce request failed."), { status: response.status });
+    }
+    if (response.status !== 200 || !record(value)) throw new ConnectorError("connector_response_invalid", "Salesforce returned an unexpected response.", { statusCode: 502 });
+    const url = new URL(address);
+    if (url.pathname.endsWith("/describe") && value.name !== url.pathname.split("/").at(-2)) {
+      throw new ConnectorError("connector_response_invalid", "Salesforce described a different object.", { statusCode: 502 });
+    }
+    return value;
+  }
+});
+
+export { salesforceProvider };

package/src/server/sanity.js

@@ -0,0 +1,31 @@
+import { createSchema } from "json-rest-schema";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { mcpRegistrationFields, registerMcpClient } from "./mcpRegistration.js";
+import { sanityDefinition } from "../shared/mcp.js";
+import { mcpOperations, exchangeMcp } from "./mcpTransport.js";
+
+const oauth = Object.freeze({
+  issuer: "https://mcp.sanity.io", authorization_endpoint: "https://mcp.sanity.io/authorize",
+  token_endpoint: "https://mcp.sanity.io/token", registration_endpoint: "https://mcp.sanity.io/register",
+  response_types_supported: ["code"], code_challenge_methods_supported: ["S256"]
+});
+const registrationSchema = createSchema({ ...mcpRegistrationFields,
+  scopes: { type: "array", required: true, minLength: 1,
+    items: { type: "string", enum: ["global"] },
+    validator: (values) => values.length === 1 && values[0] === "global" || "Select Sanity MCP access." }
+});
+async function registerSanityClient(input, options) {
+  const values = validateSchemaPayload({ schema: registrationSchema, mode: "replace" }, input, { statusCode: 422 });
+  return registerMcpClient("Sanity", oauth, values, options);
+}
+
+const sanityProvider = Object.freeze({
+  ...sanityDefinition, oauth, oauthResource: "https://mcp.sanity.io",
+  apiOrigins: ["https://mcp.sanity.io"],
+  apiKey: { headers: (token) => ({ Authorization: `Bearer ${token}` }) },
+  checkOperation: "tools.list",
+  exchange: exchangeMcp,
+  operations: mcpOperations("https://mcp.sanity.io/")
+});
+
+export { sanityProvider, registerSanityClient };

package/src/server/semrush.js

@@ -0,0 +1,359 @@
+import { createSchema } from "json-rest-schema";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { semrushDefinition } from "../shared/semrush.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const projectsUrl = "https://api.semrush.com/apis/v4/projects/v1/projects";
+const projectSchema = createSchema({ projectId: { type: "integer", required: true, min: 1, max: Number.MAX_SAFE_INTEGER } });
+const projectName = { type: "string", required: true, minLength: 1,
+  pattern: /^[^~`!#%'\^&*=\[\]\\/{}|":<>?\p{Cc}]+$/u };
+const renameSchema = createSchema({
+  projectId: { type: "integer", required: true, min: 1, max: Number.MAX_SAFE_INTEGER },
+  project_name: projectName
+});
+
+const backlinkTarget = {
+  url: { type: "string", required: true, minLength: 1, maxLength: 2000 },
+  scope: { type: "string", required: true, enum: ["ROOT_DOMAIN", "SUBDOMAIN", "SUBFOLDER", "PAGE"] },
+  format: { type: "string", enum: ["json"], defaultTo: "json" }
+};
+const backlinkPage = {
+  ...backlinkTarget,
+  limit: { type: "integer", min: 1, max: 1000, defaultTo: 100 },
+  offset: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, defaultTo: 0 },
+  order_by: { type: "string", pattern: /^[a-z_]+$/u },
+  direction: { type: "string", enum: ["ASC", "DESC"], defaultTo: "DESC" },
+  filter: { type: "string", minLength: 1, maxLength: 4000 }
+};
+
+const domainColumns = ["Domain", "Rank", "Organic Keywords", "Organic Traffic", "Organic Cost", "Adwords Keywords", "Adwords Traffic", "Adwords Cost"];
+
+const keywordColumns = ["Keyword", "Position", "Search Volume", "CPC", "Competition", "Traffic (%)", "Number of Results"];
+
+function semrushKeywordReport(target, kind) {
+  const operation = jsonOperation("https://api.semrush.com/", {
+    [target]: { type: "string", required: true, minLength: 1, maxLength: target === "domain" ? 253 : 2000 },
+    database: { type: "string", required: true, pattern: /^[a-z]{2}$/u },
+    limit: { type: "integer", min: 1, max: 1000, defaultTo: 100 },
+    offset: { type: "integer", min: 0, max: 3_999_999, defaultTo: 0 },
+    display_sort: { type: "string", enum: ["po_asc", "po_desc", "tr_asc", "tr_desc", "nq_asc", "nq_desc"] },
+    display_filter: { type: "string", minLength: 1, maxLength: 4000 },
+    display_date: { type: "string", pattern: /^\d{4}(0[1-9]|1[0-2])15$/u }
+  });
+  return {
+    scopes: [],
+    request(input, settings) {
+      if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the separate Semrush V3 API key reference for keyword reports.");
+      const result = operation.request(input);
+      const url = new URL(result.url);
+      const limit = Number(url.searchParams.get("limit")), offset = Number(url.searchParams.get("offset"));
+      if (limit + offset > 4_000_000) throw new ConnectorError("connector_input_invalid", "The requested Semrush page exceeds the provider's result window.", { statusCode: 422 });
+      url.searchParams.delete("limit"); url.searchParams.delete("offset");
+      url.searchParams.set("display_limit", String(limit + offset));
+      url.searchParams.set("display_offset", String(offset));
+      url.searchParams.set("type", `${target}_${kind}`);
+      url.searchParams.set("export_columns", "Ph,Po,Nq,Cp,Co,Tr,Nr");
+      url.searchParams.set("export_escape", "1"); url.searchParams.set("export_decode", "1");
+      return { ...result, url: url.href };
+    }
+  };
+}
+
+function semrushTrackingReport(type, positions = false) {
+  const operation = jsonOperation("https://api.semrush.com/", {
+    campaignId: { type: "string", required: true, pattern: /^\d+(?:_\d+)?$/u, maxLength: 80 },
+    ...(positions ? {
+      url: { type: "string", minLength: 1, maxLength: 2000 },
+      date_begin: { type: "string", pattern: /^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$/u },
+      date_end: { type: "string", pattern: /^\d{4}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])$/u },
+      display_limit: { type: "integer", min: 1, max: 1000, defaultTo: 10 },
+      display_offset: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, defaultTo: 0 },
+      display_filter: { type: "string", minLength: 1, maxLength: 4000 }
+    } : {})
+  });
+  return { scopes: [], request(input, settings) {
+    if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the Semrush V3 key for position tracking.");
+    const result = operation.request(input);
+    const url = new URL(result.url);
+    url.pathname = `/reports/v1/projects/${url.searchParams.get("campaignId")}/tracking/`;
+    url.searchParams.delete("campaignId");
+    if (url.searchParams.has("date_begin") && url.searchParams.has("date_end") && url.searchParams.get("date_begin") > url.searchParams.get("date_end")) {
+      throw new ConnectorError("connector_input_invalid", "The tracking start date must not follow its end date.", { statusCode: 422 });
+    }
+    url.searchParams.set("action", "report"); url.searchParams.set("type", type);
+    return { ...result, url: url.href };
+  } };
+}
+
+function parseSemrushCsv(text) {
+  const rows = [];
+  let row = [], field = "", quoted = false, closed = false;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (quoted) {
+      if (char === '"' && text[i + 1] === '"') { field += '"'; i++; }
+      else if (char === '"') { quoted = false; closed = true; }
+      else field += char;
+    } else if (char === '"' && field === "" && !closed) quoted = true;
+    else if (char === ";" || char === "\n" || char === "\r") {
+      row.push(field); field = ""; closed = false;
+      if (char !== ";") { rows.push(row); row = []; if (char === "\r" && text[i + 1] === "\n") i++; }
+    } else {
+      if (closed || char === '"') throw new ConnectorError("connector_response_invalid", "Semrush returned malformed CSV.", { statusCode: 502 });
+      field += char;
+    }
+  }
+  if (quoted) throw new ConnectorError("connector_response_invalid", "Semrush returned incomplete CSV.", { statusCode: 502 });
+  if (field !== "" || closed || row.length) { row.push(field); rows.push(row); }
+  return rows;
+}
+
+function validProject(project) {
+  return Number.isSafeInteger(project?.project_id) && project.project_id > 0 &&
+    typeof project.project_name === "string" && project.project_name.length > 0 &&
+    typeof project.domain === "string" && project.domain.length > 0 &&
+    Number.isSafeInteger(project.owner_id) && project.owner_id > 0 &&
+    ["read", "edit", "delete", "share", "downgraded"].every((permission) => typeof project.permissions?.[permission] === "boolean") &&
+    Array.isArray(project.tools) && project.tools.every((tool) => typeof tool?.name === "string" && tool.name.length > 0);
+}
+
+const semrushProvider = Object.freeze({
+  ...semrushDefinition, apiOrigins: ["https://api.semrush.com"],
+  apiKey: { headers: (key) => {
+    if (/[\s\p{Cc}]/u.test(key)) {
+      throw new ConnectorError("connector_binding_missing", "Use the Semrush V4 API key without spaces or control characters.");
+    }
+    return { Authorization: `Apikey ${key}` };
+  } },
+  checkOperation: "projects.list",
+  operations: {
+    "tracking.campaigns": { scopes: [], request(input, settings) {
+      const { projectId } = validateSchemaPayload({ schema: projectSchema, mode: "replace" }, input, { statusCode: 422 });
+      if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the Semrush V3 key for campaign discovery.");
+      return { method: "GET", url: `https://api.semrush.com/management/v1/projects/${projectId}/tracking/campaigns` };
+    } },
+    "tracking.dates": semrushTrackingReport("tracking_campaign_dates"),
+    "tracking.organicPositions": semrushTrackingReport("tracking_position_organic", true),
+    "tracking.paidPositions": semrushTrackingReport("tracking_position_adwords", true),
+    "domains.organicKeywords": semrushKeywordReport("domain", "organic"),
+    "domains.paidKeywords": semrushKeywordReport("domain", "adwords"),
+    "urls.organicKeywords": semrushKeywordReport("url", "organic"),
+    "urls.paidKeywords": semrushKeywordReport("url", "adwords"),
+    "subfolders.organicKeywords": semrushKeywordReport("subfolder", "organic"),
+    "subfolders.paidKeywords": semrushKeywordReport("subfolder", "adwords"),
+    "domains.overview": {
+      scopes: [],
+      request(input, settings) {
+        if (!settings.v3ApiKeyRef) throw new ConnectorError("connector_binding_missing", "Configure the separate Semrush V3 API key reference for domain reports.");
+        const operation = jsonOperation("https://api.semrush.com/", {
+          domain: { type: "string", required: true, minLength: 1, maxLength: 253, pattern: /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/iu },
+          database: { type: "string", required: true, pattern: /^[a-z]{2}$/u }
+        });
+        const result = operation.request(input);
+        const url = new URL(result.url);
+        url.searchParams.set("type", "domain_rank");
+        url.searchParams.set("export_columns", "Dn,Rk,Or,Ot,Oc,Ad,At,Ac");
+        url.searchParams.set("export_escape", "1");
+        url.searchParams.set("export_decode", "1");
+        return { ...result, url: url.href };
+      }
+    },
+    "backlinks.overview": jsonOperation("https://api.semrush.com/apis/v4/backlinks/v1/overview", backlinkTarget),
+    "backlinks.list": jsonOperation("https://api.semrush.com/apis/v4/backlinks/v1/links", backlinkPage),
+    "backlinks.referringDomains": jsonOperation("https://api.semrush.com/apis/v4/backlinks/v1/ref-domains", backlinkPage),
+    "backlinks.anchors": jsonOperation("https://api.semrush.com/apis/v4/backlinks/v1/anchors", backlinkPage),
+    "keywords.metrics": {
+      scopes: [],
+      request(input) {
+        const operation = jsonOperation("https://api.semrush.com/apis/v4/keywords/v1/metrics", {
+          keyword: { type: "string", required: true, minLength: 1, maxLength: 255 },
+          country: { type: "string", required: true, pattern: /^[A-Z]{2}$/u },
+          month: { type: "string", pattern: /^\d{4}-(0[1-9]|1[0-2])$/u }
+        });
+        const result = operation.request(input);
+        const url = new URL(result.url);
+        const month = url.searchParams.get("month");
+        if (month && (month < "2012-01" || month > new Date().toISOString().slice(0, 7))) {
+          throw new ConnectorError("connector_input_invalid", "Choose a month from 2012-01 through the current month.", { statusCode: 422 });
+        }
+        url.searchParams.set("format", "json");
+        return { ...result, url: url.href };
+      }
+    },
+    "projects.create": jsonOperation(projectsUrl, {
+      domain: { type: "string", required: true, minLength: 1, maxLength: 253, pattern: /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/iu },
+      project_name: projectName
+    }, undefined, "POST"),
+    "projects.update": {
+      scopes: [],
+      request(input) {
+        const { projectId, project_name } = validateSchemaPayload({ schema: renameSchema, mode: "replace" }, input, { statusCode: 422 });
+        return { method: "PATCH", url: `${projectsUrl}/${projectId}`, body: { project_name } };
+      }
+    },
+    "projects.list": jsonOperation(projectsUrl, {
+      scope: { type: "string", enum: ["OWN", "ALL", "SHARED", "CORPORATE"], defaultTo: "OWN" },
+      limit: { type: "integer", min: 1, max: 1000, defaultTo: 100 },
+      offset: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER, defaultTo: 0 }
+    }),
+    "projects.delete": {
+      scopes: [],
+      request(input) {
+        const { projectId } = validateSchemaPayload({ schema: projectSchema, mode: "replace" }, input, { statusCode: 422 });
+        return { method: "DELETE", url: `${projectsUrl}/${projectId}` };
+      }
+    },
+    "projects.get": {
+      scopes: [],
+      request(input) {
+        const { projectId } = validateSchemaPayload({ schema: projectSchema, mode: "replace" }, input, { statusCode: 422 });
+        return { method: "GET", url: `${projectsUrl}/${projectId}` };
+      }
+    }
+  },
+  async exchange(address, options, { request, fetchImpl, settings, resolveReference }) {
+    const path = new URL(address).pathname;
+    if (path === "/" || path.startsWith("/management/v1/projects/") || path.startsWith("/reports/v1/projects/")) {
+      let key;
+      try { key = await resolveReference(settings.v3ApiKeyRef); } catch {
+        throw new ConnectorError("connector_binding_missing", "Provide the Semrush V3 API key through its private Env reference.");
+      }
+      if (typeof key !== "string" || !key || key === "MISSING" || /[\s\p{Cc}]/u.test(key)) {
+        throw new ConnectorError("connector_binding_missing", "Provide a valid Semrush V3 API key.");
+      }
+      const url = new URL(address);
+      url.searchParams.set("key", key);
+      let response, text;
+      try {
+        response = await fetchImpl(url.href, { method: "GET", headers: { Accept: "text/csv" },
+          credentials: "omit", redirect: "error", signal: options.signal });
+        if (!response.ok) throw new Error("Provider failure");
+        text = await response.text();
+      } catch {
+        options.signal.throwIfAborted();
+        const status = response?.status;
+        throw new ConnectorError(status === 429 ? "connector_rate_limited" : status === 403 ? "connector_permission_denied" : "connector_provider_failed",
+          "Semrush could not return the V3 report.", { statusCode: status === 429 ? 429 : status === 403 ? 403 : 502 });
+      }
+      if (text.length > 2_000_000) throw new ConnectorError("connector_response_invalid", "Semrush returned an oversized V3 report.", { statusCode: 502 });
+      if (path !== "/") {
+        let result;
+        try { result = JSON.parse(text); } catch {
+          throw new ConnectorError("connector_response_invalid", "Semrush returned invalid tracking JSON.", { statusCode: 502 });
+        }
+        let valid = result && typeof result === "object" && !Array.isArray(result) && result.error === undefined;
+        if (path.endsWith("/campaigns")) {
+          valid &&= String(result.project_id) === path.split("/")[4] && Array.isArray(result.campaigns) &&
+            result.campaigns.every((campaign) => typeof campaign?.id === "string" && /^\d+(?:_\d+)?$/u.test(campaign.id) &&
+              typeof campaign.url === "string" && typeof campaign.device === "string" && typeof campaign.isGathering === "boolean");
+        } else {
+          valid &&= result.data !== null && typeof result.data === "object" &&
+            /^(0|[1-9]\d*)$/u.test(String(result.total));
+          if (url.searchParams.get("type") === "tracking_campaign_dates") {
+            valid &&= Object.values(result.data).every((entry) => /^\d{8}$/u.test(String(entry?.Dt)));
+          } else {
+            valid &&= String(result.limit) === url.searchParams.get("display_limit") && String(result.offset) === url.searchParams.get("display_offset") &&
+              Object.values(result.data).length <= Number(url.searchParams.get("display_limit")) &&
+              Object.values(result.data).every((entry) => typeof entry?.Ph === "string" && typeof entry.Pi === "string" && entry.Dt !== null && typeof entry.Dt === "object");
+          }
+        }
+        if (!valid) throw new ConnectorError("connector_response_invalid", "Semrush returned unexpected tracking data.", { statusCode: 502 });
+        return result;
+      }
+      const columns = url.searchParams.get("type") === "domain_rank" ? domainColumns : keywordColumns;
+      const rowLimit = columns === domainColumns ? 1 : Number(url.searchParams.get("display_limit")) - Number(url.searchParams.get("display_offset"));
+      const error = /^ERROR\s+(\d+)/u.exec(text.trim());
+      if (error) {
+        if (error[1] === "50") return { columns, rows: [] };
+        const code = Number(error[1]);
+        if ([110, 120].includes(code)) throw new ConnectorError("connector_binding_missing", "Replace the separate Semrush V3 key in Env.");
+        if ([130, 133, 135].includes(code)) throw new ConnectorError("connector_permission_denied", "Check Semrush V3 API, database and report entitlement.", { statusCode: 403 });
+        if ([131, 132, 134].includes(code)) throw new ConnectorError("connector_quota_limited", "Check Semrush V3 API units and report limits.", { statusCode: 429 });
+        throw new ConnectorError("connector_provider_failed", "Semrush rejected the V3 report. Check its inputs and account access.", { statusCode: 502 });
+      }
+      const rows = parseSemrushCsv(text);
+      if (JSON.stringify(rows.shift()) !== JSON.stringify(columns) || rows.length > rowLimit ||
+        rows.some((row) => row.length !== columns.length)) {
+        throw new ConnectorError("connector_response_invalid", "Semrush returned unexpected V3 report columns or rows.", { statusCode: 502 });
+      }
+      return { columns, rows };
+    }
+    const result = await request(address, options);
+    if (result?.meta?.success === false) {
+      const code = result.error?.code;
+      if ([70, 120, 121, 122].includes(code)) {
+        throw new ConnectorError("connector_reconnect_required", "Replace the Semrush V4 key and connect again.", { statusCode: 401 });
+      }
+      if (code === 130) {
+        throw new ConnectorError("connector_permission_denied", "Semrush API access is disabled for this account.", { statusCode: 403 });
+      }
+      if ([131, 132, 134].includes(code)) {
+        throw new ConnectorError("connector_quota_limited", "Semrush API capacity is exhausted. Check the account's subscription and available units.", { statusCode: 429 });
+      }
+      if (code === 512) {
+        throw new ConnectorError("connector_resource_not_found", "The Semrush project was not found or is not accessible.", { statusCode: 404 });
+      }
+      throw new ConnectorError("connector_provider_failed", "Semrush could not complete this request.", { statusCode: 502 });
+    }
+    const url = new URL(address);
+    const meta = result?.meta;
+    const creating = options.method === "POST" && url.pathname === "/apis/v4/projects/v1/projects";
+    let valid = meta?.success === true && meta.status_code === (creating ? 201 : 200) &&
+      typeof meta.request_id === "string" && meta.request_id.length > 0 && result.error === undefined;
+    if (url.pathname === "/apis/v4/keywords/v1/metrics") {
+      const data = result?.data;
+      valid &&= meta.keyword === url.searchParams.get("keyword") && meta.country === url.searchParams.get("country") &&
+        typeof meta.month === "string" && /^\d{4}-(0[1-9]|1[0-2])$/u.test(meta.month) &&
+        (!url.searchParams.has("month") || meta.month === url.searchParams.get("month")) &&
+        data !== null && typeof data === "object" && !Array.isArray(data) &&
+        ["cpc", "number_of_results", "search_volume"].every((key) => typeof data[key] === "string" && /^\d+$/u.test(data[key])) &&
+        ["competitive_density", "keyword_difficulty"].every((key) => Number.isFinite(data[key])) &&
+        ["intents", "serp_features"].every((key) => Array.isArray(data[key]) && data[key].every((value) => typeof value === "string")) &&
+        Array.isArray(data.trends) && data.trends.every(Number.isFinite);
+    } else if (url.pathname.startsWith("/apis/v4/backlinks/v1/")) {
+      const report = url.pathname.split("/").at(-1);
+      const count = (value) => Number.isSafeInteger(value) && value >= 0;
+      if (report === "overview") {
+        valid &&= ["backlinks_count", "domains_count", "urls_count", "score"].every((field) => count(result.data?.[field]));
+      } else {
+        valid &&= Array.isArray(result.data) && result.data.length <= Number(url.searchParams.get("limit")) &&
+          result.data.every((row) => {
+            if (!row || typeof row !== "object" || Array.isArray(row)) return false;
+            if (report === "links") return typeof row.source_url === "string" && typeof row.target_url === "string" &&
+              typeof row.anchor === "string" && typeof row.is_nofollow === "boolean";
+            if (report === "ref-domains") return typeof row.domain === "string" && count(row.backlinks_count) && count(row.domain_score);
+            return typeof row.anchor === "string" && count(row.backlinks_count) && count(row.domains_count);
+          });
+        // Some report envelopes omit pagination metadata; validate it when supplied.
+        for (const field of ["limit", "offset"]) {
+          if (meta?.[field] !== undefined) valid &&= String(meta[field]) === url.searchParams.get(field);
+        }
+        if (meta?.total !== undefined) valid &&= count(meta.total);
+      }
+      if (meta?.scope !== undefined) valid &&= meta.scope === url.searchParams.get("scope");
+    } else if (creating) {
+      const submitted = options.body;
+      valid &&= validProject(result.data) && result.data.project_name === submitted.project_name &&
+        result.data.domain.toLowerCase() === submitted.domain.toLowerCase();
+    } else if (url.pathname === "/apis/v4/projects/v1/projects") {
+      const limit = Number(url.searchParams.get("limit"));
+      valid &&= meta.scope === url.searchParams.get("scope") && meta.limit === limit &&
+        meta.offset === Number(url.searchParams.get("offset")) &&
+        Number.isSafeInteger(meta.total_count) && meta.total_count >= 0 &&
+        Array.isArray(result.data) && result.data.length <= limit && result.data.length <= meta.total_count &&
+        result.data.every(validProject);
+    } else if (options.method === "DELETE") {
+      valid &&= Number.isSafeInteger(result.data?.project_id) &&
+        result.data.project_id === Number(url.pathname.split("/").at(-1));
+    } else {
+      valid &&= validProject(result.data) && result.data.project_id === Number(url.pathname.split("/").at(-1));
+      if (options.method === "PATCH") valid &&= result.data.project_name === options.body.project_name;
+    }
+    if (!valid) {
+      throw new ConnectorError("connector_response_invalid", "Semrush returned unexpected report or project data.", { statusCode: 502 });
+    }
+    return result;
+  }
+});
+export { semrushProvider };

package/src/server/sentry.js

@@ -0,0 +1,30 @@
+import { sentryDefinition } from "../shared/tokens.js";
+import { createSchema } from "json-rest-schema";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { mcpOperations, exchangeMcp } from "./mcpTransport.js";
+import { mcpRegistrationFields, registerMcpClient } from "./mcpRegistration.js";
+
+const oauth = Object.freeze({
+  issuer: "https://mcp.sentry.dev", authorization_endpoint: "https://mcp.sentry.dev/oauth/authorize",
+  token_endpoint: "https://mcp.sentry.dev/oauth/token", registration_endpoint: "https://mcp.sentry.dev/oauth/register",
+  response_types_supported: ["code"], code_challenge_methods_supported: ["S256"]
+});
+const registrationSchema = createSchema({ ...mcpRegistrationFields,
+  scopes: { type: "array", required: true, minLength: 1,
+    items: { type: "string", enum: sentryDefinition.scopes.map((scope) => scope.value) } }
+});
+async function registerSentryClient(input, options) {
+  const values = validateSchemaPayload({ schema: registrationSchema, mode: "replace" }, input, { statusCode: 422 });
+  return registerMcpClient("Sentry", oauth, values, options);
+}
+function sentryEndpoint(settings) {
+  const values = validateSchemaPayload({ schema: sentryDefinition.settingsSchema, mode: "replace" }, settings, { statusCode: 422 });
+  return `https://mcp.sentry.dev/mcp/${values.organizationSlug}${values.projectSlug ? `/${values.projectSlug}` : ""}`;
+}
+
+const sentryProvider = Object.freeze({
+  ...sentryDefinition, oauth, oauthResource: sentryEndpoint,
+  apiOrigins: ["https://mcp.sentry.dev"], checkOperation: "tools.list",
+  exchange: exchangeMcp, operations: mcpOperations(sentryEndpoint)
+});
+export { sentryProvider, registerSentryClient };

package/src/server/sevdesk.js

@@ -0,0 +1,20 @@
+import { sevdeskDefinition } from "../shared/tokens.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const sevdeskProvider = Object.freeze({
+  ...sevdeskDefinition,
+  apiOrigins: ["https://my.sevdesk.de"],
+  apiKey: { headers: (key) => ({ Authorization: key }) },
+  checkOperation: "contacts.list",
+  operations: {
+    "contacts.list": jsonOperation("https://my.sevdesk.de/api/v1/Contact", {
+      limit: { type: "integer", min: 1, max: 1000, defaultTo: 100 },
+      offset: { type: "integer", min: 0, max: 1000000, defaultTo: 0 },
+      countAll: { type: "boolean", defaultTo: false },
+      depth: { type: "integer", enum: [0, 1], defaultTo: 1 }
+    }, (result) => Array.isArray(result?.objects) &&
+      (result.total === undefined || Number.isInteger(result.total) && result.total >= 0 ||
+        typeof result.total === "string" && /^[0-9]+$/u.test(result.total)))
+  }
+});
+export { sevdeskProvider };

package/src/server/shopify.js

@@ -0,0 +1,99 @@
+import { createSchema } from "json-rest-schema";
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { shopifyDefinition } from "../shared/shopify.js";
+import { graphqlOperation } from "./graphqlOperation.js";
+
+const origin = (settings) => `https://${settings.shopDomain}`;
+const endpoint = (settings) => `${origin(settings)}/admin/api/2026-07/graphql.json`;
+const productId = (value) => typeof value === "string" && /^gid:\/\/shopify\/Product\/[1-9][0-9]*$/u.test(value);
+const idField = { type: "string", required: true, noTrim: true, maxLength: 100, validator: (value) => productId(value) || "Use a Shopify Product GID." };
+const productFields = {
+  title: { type: "string", minLength: 1, maxLength: 255, noTrim: true },
+  descriptionHtml: { type: "string", maxLength: 65536, noTrim: true },
+  vendor: { type: "string", maxLength: 255, noTrim: true },
+  productType: { type: "string", maxLength: 255, noTrim: true },
+  status: { type: "string", enum: ["ACTIVE", "ARCHIVED", "DRAFT"] },
+  tags: { type: "array", validator: (value) => value.length <= 250 || "Use at most 250 tags.",
+    items: { type: "string", minLength: 1, maxLength: 255, noTrim: true } }
+};
+const productSelection = "id title handle status";
+const validProduct = (product) => productId(product?.id) && typeof product.title === "string" && typeof product.handle === "string" &&
+  ["ACTIVE", "ARCHIVED", "DRAFT"].includes(product.status);
+const emptyUserErrors = (payload) => Array.isArray(payload?.userErrors) && payload.userErrors.length === 0;
+
+function productMutation(name, fields) {
+  const operation = graphqlOperation(endpoint,
+    `mutation ConnectorProduct${name}($product: Product${name}Input!) { product${name}(product: $product) { product { ${productSelection} } userErrors { field message } } }`,
+    { product: { type: "object", required: true, schema: createSchema(fields) } },
+    (data) => emptyUserErrors(data?.[`product${name}`]) && validProduct(data[`product${name}`].product));
+  return { ...operation, scopes: ["write_products"], request(input, settings) {
+    const request = operation.request(input, settings);
+    if (name === "Update" && Object.keys(request.body.variables.product).length === 1) {
+      throw new ConnectorError("connector_input_invalid", "Select at least one product detail to update.", { statusCode: 422 });
+    }
+    return request;
+  } };
+}
+
+const shopifyProvider = Object.freeze({
+  ...shopifyDefinition,
+  oauth: (settings) => ({ issuer: origin(settings), token_endpoint: `${origin(settings)}/admin/oauth/access_token` }),
+  scopeSeparator: ",", apiOrigins: (settings) => [origin(settings)],
+  apiKey: { headers: (token) => ({ "X-Shopify-Access-Token": token }) },
+  checkOperation: "products.list",
+  async normalizeTokenResponse(response) {
+    if (!response.ok) return response;
+    let token;
+    try { token = await response.clone().json(); } catch { /* reported below */ }
+    if (typeof token?.access_token !== "string" || !token.access_token.trim() ||
+      !Number.isSafeInteger(token.expires_in) || token.expires_in <= 0 ||
+      typeof token.scope !== "string" || !/^[a-z_]+(?:,[a-z_]+)*$/u.test(token.scope)) {
+      throw new ConnectorError("connector_response_invalid", "Shopify returned an invalid token grant.", { statusCode: 502 });
+    }
+    // Shopify's documented client-credentials response omits the standard token_type.
+    return Response.json({ ...token, token_type: token.token_type ?? "Bearer" });
+  },
+  operations: {
+    "products.list": { ...graphqlOperation(endpoint,
+      `query ConnectorProducts($first: Int!, $after: String, $query: String) { products(first: $first, after: $after, query: $query) { nodes { ${productSelection} } pageInfo { hasNextPage endCursor } } }`,
+      { first: { type: "integer", min: 1, max: 100, defaultTo: 20 },
+        after: { type: "string", minLength: 1, maxLength: 4096, noTrim: true },
+        query: { type: "string", minLength: 1, maxLength: 1024, noTrim: true } },
+      (data) => Array.isArray(data?.products?.nodes) && data.products.nodes.length <= 100 && data.products.nodes.every(validProduct) &&
+        typeof data.products.pageInfo?.hasNextPage === "boolean" &&
+        (data.products.pageInfo.endCursor === null || (typeof data.products.pageInfo.endCursor === "string" && data.products.pageInfo.endCursor.length > 0)) &&
+        (!data.products.pageInfo.hasNextPage || typeof data.products.pageInfo.endCursor === "string")),
+      scopes: ["read_products", "write_products"] },
+    "products.create": productMutation("Create", { ...productFields, title: { ...productFields.title, required: true }, status: { ...productFields.status, defaultTo: "DRAFT" } }),
+    "products.update": productMutation("Update", { id: idField, ...productFields }),
+    "products.delete": { ...graphqlOperation(endpoint,
+      "mutation ConnectorProductDelete($input: ProductDeleteInput!) { productDelete(input: $input, synchronous: true) { deletedProductId userErrors { field message } } }",
+      { input: { type: "object", required: true, schema: createSchema({ id: idField }) } },
+      (data) => emptyUserErrors(data?.productDelete) && productId(data.productDelete.deletedProductId)), scopes: ["write_products"] }
+  },
+  async exchange(address, options, { request }) {
+    const headers = { ...options.headers };
+    if (headers.Authorization) {
+      headers["X-Shopify-Access-Token"] = headers.Authorization.slice("Bearer ".length);
+      delete headers.Authorization;
+    }
+    const result = await request(address, { ...options, headers });
+    if (Array.isArray(result?.errors) && result.errors.length) {
+      const codes = result.errors.map((error) => error?.extensions?.code);
+      if (codes.includes("THROTTLED")) throw new ConnectorError("connector_rate_limited", "Shopify's request limit was reached.", { statusCode: 429 });
+      if (codes.includes("ACCESS_DENIED")) throw new ConnectorError("connector_permission_denied", "Shopify denied this operation.", { statusCode: 403 });
+    }
+    for (const name of ["productCreate", "productUpdate", "productDelete"]) {
+      const payload = result?.data?.[name];
+      if (Array.isArray(payload?.userErrors) && payload.userErrors.length) {
+        throw new ConnectorError("connector_operation_rejected", "Shopify rejected the product change. Check the product values and permissions before retrying.", { statusCode: 422 });
+      }
+    }
+    if (result?.data?.products?.nodes?.length > options.body.variables.first) {
+      throw new ConnectorError("connector_response_invalid", "Shopify returned more products than requested.", { statusCode: 502 });
+    }
+    return result;
+  }
+});
+
+export { shopifyProvider };