@cognium-ai/mcp-server

An MCP server exposing Cognium's security scanning and spec-conformance tools over stdio. Backed by the circle-ir-ai engine.

Tools Overview

| Tool | Category | Description | |------|----------|-------------| | find_credential_exposure | Pillar I | Detect hardcoded secrets (AWS, GitHub, OpenAI, etc.) | | check_license_compliance | Pillar I | Flag copyleft licenses in dependencies | | find_stale_dependencies | Pillar I | Check npm registry for outdated packages | | find_install_script_risk | Pillar I | Detect malicious install script patterns | | find_typosquats | Pillar I | Detect typosquat package names | | find_excessive_permissions | Pillar I | Audit MCP config permissions | | verify_spec_conformance | Spec | Analyze code-to-spec alignment | | find_spec_drift | Spec | Report spec/code drift | | find_pattern | Utility | Regex search over code |

Install & run

npm install -g @cognium-ai/mcp-server
cognium-mcp          # speaks MCP JSON-RPC over stdin/stdout

Or wire it into an MCP client config:

{
  "mcpServers": {
    "cognium": {
      "command": "npx",
      "args": ["-y", "@cognium-ai/mcp-server"]
    }
  }
}

Inspect it interactively:

npx @modelcontextprotocol/inspector cognium-mcp

Pillar I Security Tools

All Pillar I tools return a common envelope:

{
  "findings": [{ "kind": "...", "severity": "...", "location": {...}, "evidence": {...}, "suggested_action": "..." }],
  "summary": { "total": N, "by_severity": {...}, "truncated": false }
}

• location.span is 1-indexed line numbers [start_line, end_line]
• All tools accept severity_floor to filter results

find_credential_exposure

Detect hardcoded secrets using SAST pattern matching.

| Input | Type | Description | |-------|------|-------------| | code_root | string | Absolute path to scan | | include_git_history | boolean | Scan git history (default: false) | | severity_floor | enum | Minimum severity: info/low/medium/high/critical |

Evidence: rule_id, match_snippet (redacted), confidence

check_license_compliance

Flag copyleft licenses in npm/Cargo dependencies.

| Input | Type | Description | |-------|------|-------------| | code_root | string | Absolute path to scan | | include_dev_deps | boolean | Include devDependencies (default: false) | | severity_floor | enum | Minimum severity |

Severity: AGPL/SSPL=critical, GPL=high, LGPL/MPL=medium, EUPL/CPAL=low

find_stale_dependencies

Check npm dependencies for staleness and known vulnerabilities.

| Input | Type | Description | |-------|------|-------------| | code_root | string | Absolute path to scan | | include_dev_deps | boolean | Include devDependencies (default: false) | | severity_floor | enum | Minimum severity | | check_vulnerabilities | boolean | Query OSV for CVEs (default: true) |

Staleness severity: >3 years=high, >2 years=medium, >1 year=low

Vulnerability severity: CVSS ≥9.0=critical, ≥7.0=high, ≥4.0=medium, <4.0=low

Evidence:

• Staleness: dependency, current_version, latest_version, days_since_publish, last_publish_date
• Vulnerability: dependency, current_version, vuln_id, cve, cvss, summary

find_install_script_risk

Detect malicious patterns in npm lifecycle scripts (preinstall, postinstall, etc.).

| Input | Type | Description | |-------|------|-------------| | code_root | string | Absolute path to scan | | severity_floor | enum | Minimum severity |

Rules: piped downloads (critical), eval/exec (critical), base64 decode (high), env exfiltration (high), network downloads (medium), hidden file writes (medium)

find_typosquats

Detect typosquat package names using Levenshtein distance and homoglyph detection.

| Input | Type | Description | |-------|------|-------------| | code_root | string | Absolute path to scan | | include_dev_deps | boolean | Include devDependencies (default: false) | | severity_floor | enum | Minimum severity | | check_homoglyphs | boolean | Detect visual deception attacks (default: true) | | check_popularity | boolean | Query npm for download counts (default: false) |

Detection methods:

• Levenshtein: distance=1 is high, distance=2 is medium
• Homoglyph: detects visual deception (rn→m, 1→l, 0→o, etc.) - always high severity

Evidence: dependency, similar_to, detection_method, distance, homoglyph, target_downloads

find_excessive_permissions

Audit MCP server configurations for overly broad permissions.

| Input | Type | Description | |-------|------|-------------| | code_root | string | Absolute path to scan | | severity_floor | enum | Minimum severity | | deep_analysis | boolean | Run CircleIR to detect undisclosed capabilities (default: true) |

Config formats: skill bundle (mcp.json), Claude Desktop, Cursor

Static rules: broad filesystem paths, secret env vars, unrestricted network, dangerous commands

Deep analysis: Cross-references declared permissions against actual code behavior. Detects undisclosed network, filesystem, or process execution capabilities.

Spec Tools

verify_spec_conformance

Analyze how well code conforms to its Specifica spec.

Input

| field | type | description | |-------------|--------|-----------------------------------------------| | spec_dir | string | Path to the .specifica/ directory (spec.md) | | code_root | string | Path to the code root to analyze |

Output

{
  "alignment_score": 100,           // 0–100
  "requirements": [
    { "id": "REQ-001", "status": "covered",   "evidence": { "function": "calculateTotal" } },
    { "id": "REQ-002", "status": "partial",   "evidence": { "function": "applyDiscount" } },
    { "id": "REQ-003", "status": "uncovered", "evidence": {} }
  ],
  "summary": "2/3 requirements covered (67%); 0 undocumented behaviors"
}

status is derived from the engine's match confidence:

• covered — confidence ≥ 0.7
• partial — matched but confidence < 0.7
• uncovered — no matching code behavior

The engine has no native "partial" state; it is a boundary heuristic at confidence 0.7 over the engine's already-filtered match set (min confidence 0.3).

Empty spec: if no requirements parse from spec_dir (missing, empty, or malformed spec.md), alignment_score is reported as 0 with an explanatory summary — never a misleading 100 — so a >= N gate fails safely instead of passing on a spec that was never read.

find_spec_drift

Report drift in both directions.

Input: same as above (spec_dir, code_root).

Output

{
  "drifts": [
    { "kind": "code_without_spec", "location": "deleteUser",  "suggested_action": "Document deleteUser: ..." },
    { "kind": "spec_without_code", "location": "REQ-004",     "suggested_action": "Implement REQ-004: ..." }
  ]
}

• code_without_spec — an undocumented public behavior (engine undocumentedBehaviors).
• spec_without_code — a requirement with no matching code (engine uncoveredRequirements).

find_pattern

Search file contents under a code root with a JavaScript regular expression.

Input

| field | type | description | |-------------|--------|---------------------------------------------------| | pattern | string | JS RegExp source (applied with the global flag) | | code_root | string | Path to the code root to search |

Output

{
  "matches": [
    { "file": "src/cart.ts", "span": [7, 7], "snippet": "return unitPrice * quantity;" }
  ]
}

span is line-based [startLine, endLine] (1-based), not character offsets. Files larger than 1 MiB, files detected as binary (NUL byte in the leading window), and common build/vendor directories are skipped; results are capped at 1000 matches.

The pattern is validated once up front (an invalid regex errors even over an empty tree). A 2 s wall-clock budget bounds total scanning between matches; it does not interrupt a single exec, so the 1 MiB per-file cap is the real bound against a catastrophic-backtracking pattern.

Field mapping (engine → MCP boundary)

The engine emits camelCase; this server renames to snake_case at the boundary.

| MCP field | engine source (SpecGapResult) | |----------------------------|---------------------------------------------------------| | alignment_score | specAlignmentScore | | requirements[].id | coveredRequirements[].requirement.id / uncoveredRequirements[].requirement.id | | requirements[].status | derived from coveredRequirements[].confidence (≥0.7) | | requirements[].evidence.function | coveredRequirements[].matchedFunction | | drifts (code_without_spec) | undocumentedBehaviors[] → {functionName, suggestion} | | drifts (spec_without_code) | uncoveredRequirements[] → {requirement.id, reason} |

Schema stability

Tool input/output field names are draft-stable through 2026-08-31. Additive fields are non-breaking; renames or removals are breaking changes (major bump).

Runtime support

Works under Node (≥18) and Bun. circle-ir's WASM is resolved via createRequire(import.meta.url) from node_modules/circle-ir, so no symlink is required under either runtime. Both are exercised by the CI stdio smoke matrix.

Development

npm install        # installs deps and builds (prepare → tsc)
npm run typecheck
npm test           # vitest: mapper unit tests
npm run smoke      # spawn dist/index.js over stdio against the demo fixture

License

PolyForm Noncommercial License 1.0.0 — see LICENSE.