@cyclonedx/cdxgen 12.3.0 → 12.3.2

package/lib/helpers/mcp.js

@@ -0,0 +1,248 @@
+import { PackageURL } from "packageurl-js";
+
+const OFFICIAL_NPM_NAMESPACE = "@modelcontextprotocol";
+const OFFICIAL_PYPI_PACKAGES = new Set(["mcp"]);
+const OFFICIAL_MAVEN_GROUPS = new Set(["io.modelcontextprotocol.sdk"]);
+const OFFICIAL_NUGET_PREFIXES = ["modelcontextprotocol"];
+const OFFICIAL_GOLANG_PREFIX = "github.com/modelcontextprotocol/";
+const OFFICIAL_CARGO_PACKAGES = new Set(["rmcp", "rmcp-macros"]);
+const KNOWN_MCP_INTEGRATION_GROUPS = new Set(["org.springframework.ai"]);
+
+const MCP_ROLE_HINTS = [
+  ["server-sdk", /(?:^|[-/.])server(?:$|[-/.])/i],
+  ["client-sdk", /(?:^|[-/.])client(?:$|[-/.])/i],
+  [
+    "transport-sdk",
+    /(?:^|[-/.])(express|node|webflux|webmvc|aspnetcore)(?:$|[-/.])/i,
+  ],
+];
+
+function lower(value) {
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+
+function rootImportName(source) {
+  if (typeof source !== "string" || !source.length || source.startsWith(".")) {
+    return "";
+  }
+  if (source.startsWith("@")) {
+    return source.split("/").slice(0, 2).join("/");
+  }
+  return source.split("/")[0];
+}
+
+function normalizeReference(ref) {
+  if (typeof ref === "string") {
+    const importName = rootImportName(ref);
+    const importParts = importName.startsWith("@")
+      ? importName.split("/")
+      : ["", importName];
+    return {
+      ecosystem: "npm",
+      group: lower(importParts[0]),
+      name: lower(importParts[1]),
+      source: ref,
+    };
+  }
+  if (!ref || typeof ref !== "object") {
+    return { ecosystem: "", group: "", name: "", source: "" };
+  }
+  if (typeof ref.purl === "string" && ref.purl.length) {
+    try {
+      const purl = PackageURL.fromString(ref.purl);
+      return {
+        ecosystem: lower(purl.type),
+        group: lower(purl.namespace),
+        name: lower(purl.name),
+        source: ref.purl,
+      };
+    } catch {
+      // continue with object fallback
+    }
+  }
+  return {
+    ecosystem: lower(ref.ecosystem || ref.type),
+    group: lower(ref.group),
+    name: lower(ref.name),
+    source: lower(ref.source),
+  };
+}
+
+function inferRole(name, group) {
+  const combined = `${group}/${name}`;
+  for (const [role, pattern] of MCP_ROLE_HINTS) {
+    if (pattern.test(combined)) {
+      return role;
+    }
+  }
+  if (name.includes("sdk") || group.includes("modelcontextprotocol")) {
+    return "sdk";
+  }
+  if (name.includes("integration") || group.includes("springframework")) {
+    return "integration";
+  }
+  return "sdk";
+}
+
+/**
+ * Classify a package/component/import reference as MCP-related.
+ *
+ * @param {Object|string} ref Package/component reference or import source
+ * @returns {{
+ *   isMcp: boolean,
+ *   isOfficial: boolean,
+ *   isKnownIntegration: boolean,
+ *   role: string | undefined,
+ *   catalogSource: string | undefined,
+ *   packageName: string
+ * }}
+ */
+export function classifyMcpReference(ref) {
+  const normalized = normalizeReference(ref);
+  const ecosystem = normalized.ecosystem;
+  const group = normalized.group;
+  const name = normalized.name;
+  const packageName = [group, name].filter(Boolean).join("/") || name;
+  if (!name && !group) {
+    return {
+      isMcp: false,
+      isOfficial: false,
+      isKnownIntegration: false,
+      role: undefined,
+      catalogSource: undefined,
+      packageName,
+    };
+  }
+
+  let isMcp = false;
+  let isOfficial = false;
+  let isKnownIntegration = false;
+  let catalogSource;
+
+  if (ecosystem === "npm" && group === OFFICIAL_NPM_NAMESPACE) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (ecosystem === "pypi" && OFFICIAL_PYPI_PACKAGES.has(name)) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (ecosystem === "maven" && OFFICIAL_MAVEN_GROUPS.has(group)) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (
+    ecosystem === "nuget" &&
+    OFFICIAL_NUGET_PREFIXES.some((prefix) => name.startsWith(prefix))
+  ) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (
+    ecosystem === "golang" &&
+    `${group}/${name}`.startsWith(OFFICIAL_GOLANG_PREFIX)
+  ) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (ecosystem === "cargo" && OFFICIAL_CARGO_PACKAGES.has(name)) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (
+    ecosystem === "maven" &&
+    KNOWN_MCP_INTEGRATION_GROUPS.has(group) &&
+    name.includes("mcp")
+  ) {
+    isMcp = true;
+    isKnownIntegration = true;
+    catalogSource = "known-integration";
+  } else if (
+    packageName.includes("modelcontextprotocol") ||
+    packageName.includes("mcp")
+  ) {
+    isMcp = true;
+    catalogSource = "heuristic";
+  }
+
+  return {
+    isMcp,
+    isOfficial,
+    isKnownIntegration,
+    role: isMcp ? inferRole(name, group) : undefined,
+    catalogSource,
+    packageName,
+  };
+}
+
+function pushUniqueProperty(properties, name, value) {
+  if (value === undefined || value === null || value === "") {
+    return;
+  }
+  if (properties.some((prop) => prop.name === name && prop.value === value)) {
+    return;
+  }
+  properties.push({ name, value });
+}
+
+/**
+ * Add MCP catalog metadata to a CycloneDX component.
+ *
+ * @param {Object} component CycloneDX component
+ * @returns {Object} Same component reference
+ */
+export function enrichComponentWithMcpMetadata(component) {
+  if (!component || typeof component !== "object") {
+    return component;
+  }
+  const classification = classifyMcpReference(component);
+  if (!classification.isMcp) {
+    return component;
+  }
+  const tags = new Set(component.tags || []);
+  tags.add("mcp");
+  tags.add("mcp-sdk");
+  if (classification.role === "server-sdk") {
+    tags.add("mcp-server");
+  }
+  if (classification.role === "client-sdk") {
+    tags.add("mcp-client");
+  }
+  if (classification.isOfficial) {
+    tags.add("official-mcp-sdk");
+    tags.add("trusted-source");
+  }
+  if (classification.isKnownIntegration) {
+    tags.add("known-mcp-integration");
+  }
+  component.tags = Array.from(tags).sort();
+  component.properties = component.properties || [];
+  pushUniqueProperty(component.properties, "cdx:mcp:package", "true");
+  pushUniqueProperty(
+    component.properties,
+    "cdx:mcp:official",
+    classification.isOfficial ? "true" : "false",
+  );
+  if (classification.role) {
+    pushUniqueProperty(
+      component.properties,
+      "cdx:mcp:role",
+      classification.role,
+    );
+  }
+  if (classification.catalogSource) {
+    pushUniqueProperty(
+      component.properties,
+      "cdx:mcp:catalogSource",
+      classification.catalogSource,
+    );
+  }
+  if (classification.packageName) {
+    pushUniqueProperty(
+      component.properties,
+      "cdx:mcp:packageName",
+      classification.packageName,
+    );
+  }
+  return component;
+}

package/lib/helpers/mcp.poku.js

@@ -0,0 +1,101 @@
+import { assert, describe, it } from "poku";
+
+import { classifyMcpReference, enrichComponentWithMcpMetadata } from "./mcp.js";
+
+describe("classifyMcpReference()", () => {
+  it("detects official MCP SDK packages", () => {
+    const classification = classifyMcpReference({
+      purl: "pkg:npm/%40modelcontextprotocol/server@2.0.0-alpha.0",
+    });
+    assert.strictEqual(classification.isMcp, true);
+    assert.strictEqual(classification.isOfficial, true);
+    assert.strictEqual(classification.role, "server-sdk");
+  });
+
+  it("detects non-official MCP-like packages heuristically", () => {
+    const classification = classifyMcpReference({
+      purl: "pkg:npm/%40acme/mcp-server@1.0.0",
+    });
+    assert.strictEqual(classification.isMcp, true);
+    assert.strictEqual(classification.isOfficial, false);
+    assert.strictEqual(classification.catalogSource, "heuristic");
+  });
+
+  it("classifies official npm import strings using the package root", () => {
+    const classification = classifyMcpReference(
+      "@modelcontextprotocol/client/stdio",
+    );
+    assert.strictEqual(classification.isMcp, true);
+    assert.strictEqual(classification.isOfficial, true);
+    assert.strictEqual(classification.role, "client-sdk");
+    assert.strictEqual(
+      classification.packageName,
+      "@modelcontextprotocol/client",
+    );
+  });
+
+  it("detects known maven integrations separately from official SDKs", () => {
+    const classification = classifyMcpReference({
+      purl: "pkg:maven/org.springframework.ai/spring-ai-mcp@1.0.0",
+    });
+    assert.strictEqual(classification.isMcp, true);
+    assert.strictEqual(classification.isOfficial, false);
+    assert.strictEqual(classification.isKnownIntegration, true);
+    assert.strictEqual(classification.catalogSource, "known-integration");
+  });
+});
+
+describe("enrichComponentWithMcpMetadata()", () => {
+  it("adds MCP properties and tags to official SDK components", () => {
+    const component = enrichComponentWithMcpMetadata({
+      type: "library",
+      name: "server",
+      group: "@modelcontextprotocol",
+      purl: "pkg:npm/%40modelcontextprotocol/server@2.0.0-alpha.0",
+      version: "2.0.0-alpha.0",
+    });
+    assert.ok(component.tags.includes("mcp"));
+    assert.ok(component.tags.includes("official-mcp-sdk"));
+    assert.ok(
+      component.properties.some(
+        (prop) => prop.name === "cdx:mcp:official" && prop.value === "true",
+      ),
+    );
+  });
+
+  it("is idempotent when metadata enrichment is applied multiple times", () => {
+    const component = {
+      type: "library",
+      name: "client",
+      group: "@modelcontextprotocol",
+      purl: "pkg:npm/%40modelcontextprotocol/client@1.0.0",
+      properties: [],
+      tags: [],
+      version: "1.0.0",
+    };
+    enrichComponentWithMcpMetadata(component);
+    enrichComponentWithMcpMetadata(component);
+    assert.strictEqual(component.tags.filter((tag) => tag === "mcp").length, 1);
+    assert.strictEqual(
+      component.properties.filter((prop) => prop.name === "cdx:mcp:package")
+        .length,
+      1,
+    );
+  });
+
+  it("leaves non-MCP components unchanged", () => {
+    const component = {
+      name: "lodash",
+      purl: "pkg:npm/lodash@4.17.21",
+      properties: [{ name: "existing", value: "true" }],
+      tags: ["utility"],
+      type: "library",
+      version: "4.17.21",
+    };
+    const enriched = enrichComponentWithMcpMetadata(component);
+    assert.deepStrictEqual(enriched.properties, [
+      { name: "existing", value: "true" },
+    ]);
+    assert.deepStrictEqual(enriched.tags, ["utility"]);
+  });
+});