Intégration MCP CodeCleared

Connectez un client MCP à CodeCleared en stdio ou HTTP hébergé, avec scopes minimaux et outils de sécurité orientés dépôt.

Connecter votre client MCP

Utilisez le package @codecleared/mcp-server pour un serveur stdio local, ou l’endpoint HTTP hébergé {API_URL}/mcp. Utilisez un service token au moindre privilège et conservez-le dans le coffre de secrets du client.

Dans l’app, copiez les snippets prêts à l’emploi sous Paramètres → Jetons de service → MCP (/settings/service-tokens?tab=mcp). Créez les jetons sur l’onglet Jetons de la même page.

Configuration stdio locale

Installez le package dans l’environnement qui exécute votre client MCP, puis configurez l’URL API et le token :

{
  "mcpServers": {
    "codecleared": {
      "command": "npx",
      "args": ["-y", "@codecleared/mcp-server", "stdio"],
      "env": {
        "CODECLEARED_API_URL": "https://api.example",
        "CODECLEARED_TOKEN": "cc_..."
      }
    }
  }
}

Configuration HTTP hébergée

Connectez le client à {API_URL}/mcp et envoyez Authorization: Bearer cc_.... En HTTP hébergé, la liste d’outils est filtrée par les scopes du token. scan:read suffit pour lire les résultats ; scan:all est requis pour lancer des analyses ou générer des SBOM. La recherche et l’évaluation de paquets demandent aussi package-finder:read. Les outils policy-bundle demandent policy:read (et policy:write / policy:admin pour importer). Les outils de triage des constats demandent finding:read ou finding:write — non inclus dans scan:all.

Contexte de dépôt facultatif

Un fichier .codecleared.json peut définir le dépôt par défaut :

{ "repositoryId": "repository-uuid", "fullName": "owner/repository" }

Préférez un identifiant stable. Si les deux champs sont présents, vérifiez qu’ils désignent le même dépôt dans l’organisation voulue.

Outils disponibles

Tous les noms d’outils sont préfixés par codecleared_.

Découverte : codecleared_list_repositories, codecleared_resolve_repository, codecleared_list_project_units
Exécution : codecleared_trigger_scan, codecleared_generate_sbom, codecleared_get_scan_status, codecleared_wait_for_scan
Résultats : codecleared_get_vulnerabilities, codecleared_get_sbom, codecleared_get_licenses, codecleared_get_secrets, codecleared_get_sast_findings, codecleared_get_scores, codecleared_get_security_reference
Triage des constats : codecleared_list_ignored_findings (finding:read ou finding:write), codecleared_ignore_finding / codecleared_unignore_finding (finding:write). Préférez scope=occurrence ; scope=rule ou scope=cve est plus large et survit au rescan — à utiliser délibérément.
Gouvernance licence : codecleared_list_license_allowances, codecleared_create_license_allowance, codecleared_delete_license_allowance, codecleared_list_license_overrides, codecleared_create_license_override, codecleared_delete_license_override, codecleared_append_license_policy_licenses (policy:read / policy:write / policy:admin — pas dans scan:all). La sauvegarde d’une allowance ne lance pas de scan.
Paquets : codecleared_search_packages, codecleared_evaluate_package
Policy bundles (portes de qualité, etc.) : codecleared_list_policy_bundle_schemas, codecleared_export_policy_bundle, codecleared_validate_policy_bundle, codecleared_import_policy_bundle — schémas par défaut codecleared.io/policy/1.1.0 (expressions Quality Gates supportées)
Tickets support : codecleared_list_support_tickets, codecleared_get_support_ticket, codecleared_reply_support_ticket, codecleared_update_support_ticket_status

Exemples de demandes à un LLM

« Évalue le package express sur npm pour notre organisation. » → codecleared_evaluate_package
« Exporte notre bundle de portes de qualité. » → codecleared_export_policy_bundle avec kind=quality
« Valide ce bundle quality, puis dry-run import. » → codecleared_validate_policy_bundle puis codecleared_import_policy_bundle avec dryRun=true
« Interdis les packages avec des vulnérabilités OSV connues. » → exporter le bundle quality, poser conditions.maxVulns: 0, valider, importer

Résultats fréquents

Un 402 signifie que le type d’analyse demandé n’a pas de crédits/droit éligible, ou que l’org n’a plus de licence MAU pour le propriétaire du token ce mois-ci (seat_license_required). Si un dépôt manque, vérifiez l’organisation et l’accès du token plutôt que d’utiliser le token d’une autre organisation. codecleared_wait_for_scan peut expirer alors que l’analyse continue : gardez l’ID puis demandez le statut au lieu de créer un doublon.

Quand un scan se termine en status: failed, inspectez chaque projectUnits[].errorCode (et le message error). Codes stables : pat_required, lockfile_not_found, insufficient_credits, workflow_timeout, system_error, etc. Voir Échecs de scan.