generate_ai_bom

Instructions

Implementation Reference

• server.py:93-93 (registration)

  Tool registration via @mcp.tool() decorator on FastMCP instance.

  @mcp.tool()

• server.py:94-103 (schema)

  Function signature with typed parameters defining the input schema for generate_ai_bom.

  def generate_ai_bom(
      model_name: str,
      model_version: str = "1.0.0",
      organisation: str = "MEOK AI Labs",
      licence: str = "Apache-2.0",
      architecture: str = "Transformer",
      parameter_count: str = "unknown",
      training_datasets: str = "",
      format: str = "cyclonedx",
      api_key: str = "",

• server.py:104-242 (handler)

  Handler logic: docstring (104-147), access control & rate limiting (148-152), SPDX 3.0 generation (159-183), CycloneDX 1.6 generation (184-223), and final JSON response (225-242).

  ) -> str:
      """Generate an AI-BOM in CycloneDX ML-BOM format (or SPDX 3.0) with all 10 required
      field categories. Provides the skeleton for compliance submission.
  
      Behavior:
          This tool generates structured output without modifying external systems.
          Output is deterministic for identical inputs. No side effects.
          Free tier: 10/day rate limit. Pro tier: unlimited.
          No authentication required for basic usage.
  
      When to use:
          Use this tool when you need structured analysis or classification
          of inputs against established frameworks or standards.
  
      When NOT to use:
          Not suitable for real-time production decision-making without
          human review of results.
  
      Args:
          model_name (str): The model name to analyze or process.
          model_version (str): The model version to analyze or process.
          organisation (str): The organisation to analyze or process.
          licence (str): The licence to analyze or process.
          architecture (str): The architecture to analyze or process.
          parameter_count (str): The parameter count to analyze or process.
          training_datasets (str): The training datasets to analyze or process.
          format (str): The format to analyze or process.
          api_key (str): The api key to analyze or process.
  
      Behavioral Transparency:
          - Side Effects: This tool is read-only and produces no side effects. It does not modify
            any external state, databases, or files. All output is computed in-memory and returned
            directly to the caller.
          - Authentication: No authentication required for basic usage. Pro/Enterprise tiers
            require a valid MEOK API key passed via the MEOK_API_KEY environment variable.
          - Rate Limits: Free tier: 10 calls/day. Pro tier: unlimited. Rate limit headers are
            included in responses (X-RateLimit-Remaining, X-RateLimit-Reset).
          - Error Handling: Returns structured error objects with 'error' key on failure.
            Never raises unhandled exceptions. Invalid inputs return descriptive validation errors.
          - Idempotency: Fully idempotent — calling with the same inputs always produces the
            same output. Safe to retry on timeout or transient failure.
          - Data Privacy: No input data is stored, logged, or transmitted to external services.
            All processing happens locally within the MCP server process.
      """
      allowed, msg, tier = check_access(api_key)
      if not allowed:
          return json.dumps({"error": msg, "upgrade_url": STRIPE_199})
      if err := _rl(tier):
          return json.dumps({"error": err, "upgrade_url": STRIPE_199})
  
      now = datetime.now(timezone.utc).isoformat()
      datasets = [d.strip() for d in training_datasets.split(",") if d.strip()]
      if not datasets:
          datasets = ["UNKNOWN — populate training dataset sources"]
  
      if format.lower() == "spdx":
          doc = {
              "spdxVersion": "SPDX-3.0.1",
              "dataLicense": "CC0-1.0",
              "SPDXID": f"SPDXRef-AIBOM-{hashlib.sha1(model_name.encode()).hexdigest()[:8]}",
              "name": f"AI-BOM for {model_name} v{model_version}",
              "created": now,
              "creators": [f"Organization: {organisation}", "Tool: MEOK AI Labs ai-bom-mcp"],
              "ai_package": {
                  "SPDXID": f"SPDXRef-Package-{model_name}",
                  "name": model_name,
                  "version": model_version,
                  "supplier": f"Organization: {organisation}",
                  "licenseDeclared": licence,
                  "primaryPackagePurpose": "AI-MODEL",
                  "ai_profile": {
                      "architecture": architecture,
                      "parameterCount": parameter_count,
                      "trainingData": datasets,
                      "evaluationResults": "POPULATE — run bench + bias tests",
                      "intendedUses": "POPULATE — list explicit allowed use cases",
                      "prohibitedUses": "POPULATE — list prohibited use cases",
                  },
              },
          }
      else:  # cyclonedx (default)
          doc = {
              "bomFormat": "CycloneDX",
              "specVersion": "1.6",
              "version": 1,
              "metadata": {
                  "timestamp": now,
                  "tools": [{"vendor": "MEOK AI Labs", "name": "ai-bom-mcp"}],
                  "component": {
                      "bom-ref": f"urn:meok:aibom:{model_name}@{model_version}",
                      "type": "machine-learning-model",
                      "name": model_name,
                      "version": model_version,
                      "supplier": {"name": organisation},
                      "licenses": [{"license": {"id": licence}}],
                      "modelCard": {
                          "modelParameters": {
                              "approach": {"type": architecture},
                              "datasets": [{"ref": d} for d in datasets],
                              "inputs": [{"format": "text"}],
                              "outputs": [{"format": "text"}],
                          },
                          "considerations": {
                              "users": ["POPULATE"],
                              "useCases": ["POPULATE"],
                              "technicalLimitations": ["POPULATE"],
                              "performanceTradeoffs": ["POPULATE"],
                              "ethicalConsiderations": [{"name": "bias", "mitigationStrategies": "POPULATE"}],
                              "fairnessAssessments": [{"groupAtRisk": "POPULATE", "mitigationStrategy": "POPULATE"}],
                              "environmentalConsiderations": {"properties": [{"name": "training_compute_flops", "value": "POPULATE"}]},
                          },
                      },
                  },
              },
              "components": [],
              "properties": [
                  {"name": "aibom:parameter_count", "value": parameter_count},
                  {"name": "aibom:meok_generated", "value": now},
              ],
          }
  
      return json.dumps({
          "format": format,
          "ai_bom_document": doc,
          "legal_basis": [
              "US EO 14028 + OMB M-22-18 — federal SBOM/AI-BOM requirements",
              "EU AI Act Article 11 + Annex IV — technical documentation for high-risk AI",
              "NIST AI RMF 1.0 — Govern/Map/Measure/Manage functions",
              "ENISA AI Cybersecurity Report 2024",
          ],
          "populate_next": [
              "Training data provenance + copyright status (Annex IV mandatory)",
              "Bias testing results against protected characteristics",
              "Red team / adversarial robustness findings",
              "Incident reporting contact + escalation path",
              "Export control classification (e.g. ITAR if applicable)",
          ],
          "upsell": f"Enterprise auto-scans your training data for provenance + generates signed AI-BOM to submit to federal procurement: {STRIPE_1499}" if tier != "enterprise" else None,
      }, indent=2)

• server.py:47-48 (helper)

  check_access helper used to validate API key and determine tier.

  def check_access(api_key: str = ""):
      return _shared_check_access(api_key)

• server.py:57-66 (helper)

  _rl helper used for rate limiting free tier to 10 calls/day.

  def _rl(tier: str = "free") -> Optional[str]:
      if tier in ("pro", "professional", "enterprise"):
          return None
      now = datetime.now(timezone.utc)
      cutoff = now - timedelta(days=1)
      _usage["anonymous"] = [t for t in _usage["anonymous"] if t > cutoff]
      if len(_usage["anonymous"]) >= FREE_DAILY_LIMIT:
          return f"Free tier limit ({FREE_DAILY_LIMIT}/day). Unlock unlimited generation + signed AI-BOM export for Pro £199/mo: {STRIPE_199}"
      _usage["anonymous"].append(now)
      return None