@raviraj87/armorcode-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravi Raj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# ArmorCode MCP
+
+Local MCP server for **ArmorCode** — finding triage, scans, exceptions, risk scores, and release gate checks.
+
+---
+
+## Quick start
+
+```json
+{
+  "mcpServers": {
+    "armorcode": {
+      "command": "npx",
+      "args": ["-y", "@raviraj87/armorcode-mcp"],
+      "env": {
+        "ARMORCODE_URL": "https://your-tenant.armorcode.com",
+        "ARMORCODE_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+`ARMORCODE_WRITE_ENABLED` is **optional** — omit it for safe defaults (write tools preview only).
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ARMORCODE_URL` | Yes | Tenant base URL |
+| `ARMORCODE_API_TOKEN` | Yes | API token from Manage → Integrations → API |
+| `ARMORCODE_WRITE_ENABLED` | No | Set `true` to apply writes with `dryRun: false` |
+
+---
+
+## Tools (v1.0)
+
+### Findings
+| Tool | Purpose |
+|------|---------|
+| `armorcode_search_findings` | Search/filter findings |
+| `armorcode_get_finding` | Full finding detail |
+| `armorcode_get_finding_events` | Audit trail |
+| `armorcode_get_findings_stats` | Counts by severity/status |
+| `armorcode_get_severity_stats` | Severity breakdown |
+
+### Status & comments (write, dry-run default)
+| Tool | Purpose |
+|------|---------|
+| `armorcode_confirm_finding` | OPEN → CONFIRMED |
+| `armorcode_control_finding` | → CONTROLLED |
+| `armorcode_block_finding` | Block via accept-risk |
+| `armorcode_accept_risk` | Accept risk |
+| `armorcode_mark_false_positive` | False positive |
+| `armorcode_reopen_finding` | Reopen |
+| `armorcode_triage_finding` | → TRIAGE |
+| `armorcode_mitigate_finding` | → MITIGATED |
+| `armorcode_suppress_finding` | Suppress |
+| `armorcode_add_comment` | Add note |
+| `armorcode_add_exploitability_comment` | Structured exploitability |
+| `armorcode_update_finding_severity` | Change severity |
+
+### Products & risk
+| Tool | Purpose |
+|------|---------|
+| `armorcode_list_products` | List products/groups |
+| `armorcode_list_subproducts` | List subproducts |
+| `armorcode_get_product_risk_score` | Product risk |
+| `armorcode_get_subproduct_risk_score` | Subproduct risk |
+| `armorcode_get_all_product_risk_scores` | All products |
+
+### Scans & exceptions
+| Tool | Purpose |
+|------|---------|
+| `armorcode_list_scans` | List scans |
+| `armorcode_get_scan` | Scan details |
+| `armorcode_execute_scan` | Trigger scan |
+| `armorcode_trigger_scan_pull` | PULL tool scheduler (Black Duck, etc.) |
+| `armorcode_list_scan_schedulers` | List schedulers |
+| `armorcode_delete_scan_scheduler` | Clean up scheduler |
+| `armorcode_list_exceptions` | Open exceptions |
+| `armorcode_get_exception` | Exception detail |
+| `armorcode_create_exception` | Create risk register entry |
+| `armorcode_release_gate_status` | Jenkins release gate check |
+
+### Escape hatch
+| Tool | Purpose |
+|------|---------|
+| `armorcode_health` | Connectivity check |
+| `armorcode_api` | Any GET/POST/PUT/DELETE path |
+
+---
+
+## Dev
+
+```bash
+cd armorcode-mcp
+npm install
+npm run build
+ARMORCODE_URL=... ARMORCODE_API_TOKEN=... npm run test:readonly
+```
+
+## License
+
+MIT — Copyright © 2026 Ravi Raj

package/dist/client.js

@@ -0,0 +1,449 @@
+import fetch from "node-fetch";
+import { computeStats, matchesFindingFilters, normalizeStatusList, productExploitabilityTag, } from "./findingFilters.js";
+export class ArmorCodeClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    get writeEnabled() {
+        return this.config.writeEnabled;
+    }
+    async get(path, query) {
+        const url = new URL(this.path(path), this.config.url);
+        this.applyQuery(url, query);
+        return this.request("GET", url.toString());
+    }
+    async post(path, body, query) {
+        const url = new URL(this.path(path), this.config.url);
+        this.applyQuery(url, query);
+        return this.request("POST", url.toString(), body);
+    }
+    async put(path, body) {
+        return this.request("PUT", `${this.config.url}${this.path(path)}`, body);
+    }
+    async delete(path) {
+        return this.request("DELETE", `${this.config.url}${this.path(path)}`);
+    }
+    // --- Findings ---
+    async searchFindings(opts = {}) {
+        const filters = {};
+        if (opts.productIds?.length)
+            filters.product = opts.productIds;
+        if (opts.subproductIds?.length)
+            filters.subProduct = opts.subproductIds;
+        // Severity server-side filter is unreliable on many tenants — applied client-side below.
+        if (opts.status?.length)
+            filters.status = normalizeStatusList(opts.status);
+        if (opts.sourceTools?.length)
+            filters.toolSource = opts.sourceTools;
+        if (opts.cves?.length)
+            filters.cveId = opts.cves;
+        if (opts.tags?.length)
+            filters.tags = opts.tags;
+        const url = new URL("/api/findings", this.config.url);
+        url.searchParams.set("size", String(opts.size ?? 50));
+        if (opts.afterKey != null)
+            url.searchParams.set("afterKey", String(opts.afterKey));
+        const raw = await this.request("POST", url.toString(), { filters });
+        const clientFilter = opts.severity?.length || opts.excludeTagPrefix || opts.findingAgeDays != null
+            ? {
+                severity: opts.severity,
+                excludeTagPrefix: opts.excludeTagPrefix,
+                findingAgeDays: opts.findingAgeDays,
+            }
+            : undefined;
+        if (!clientFilter)
+            return raw;
+        const data = raw?.data;
+        const findings = Array.isArray(data?.findings) ? data.findings : [];
+        const filtered = findings.filter((f) => matchesFindingFilters(f, clientFilter));
+        return {
+            ...raw,
+            data: { ...data, findings: filtered, clientFiltered: true },
+        };
+    }
+    async searchFindingsAll(opts = {}) {
+        const maxPages = opts.maxPages ?? 20;
+        const clientFilter = opts.severity?.length || opts.excludeTagPrefix || opts.findingAgeDays != null
+            ? {
+                severity: opts.severity,
+                excludeTagPrefix: opts.excludeTagPrefix,
+                findingAgeDays: opts.findingAgeDays,
+            }
+            : undefined;
+        const apiOpts = { ...opts };
+        delete apiOpts.maxPages;
+        if (clientFilter) {
+            apiOpts.severity = undefined;
+            apiOpts.excludeTagPrefix = undefined;
+            apiOpts.findingAgeDays = undefined;
+        }
+        const all = [];
+        let afterKey = opts.afterKey;
+        let pagesFetched = 0;
+        for (let page = 0; page < maxPages; page++) {
+            const raw = await this.searchFindings({ ...apiOpts, afterKey, size: opts.size ?? 100 });
+            const data = raw?.data;
+            const batch = Array.isArray(data?.findings) ? data.findings : [];
+            pagesFetched += 1;
+            if (!batch.length)
+                break;
+            all.push(...batch);
+            const next = data?.afterKey;
+            if (next == null || next === -1)
+                break;
+            afterKey = Number(next);
+        }
+        const findings = clientFilter ? all.filter((f) => matchesFindingFilters(f, clientFilter)) : all;
+        return { findings, pagesFetched, totalFetched: all.length, afterKey: afterKey ?? null };
+    }
+    async getFinding(findingId) {
+        return this.get(`/user/findings/${findingId}`);
+    }
+    async getFindingEvents(findingId) {
+        return this.get(`/user/findings/${findingId}/events`);
+    }
+    statusBody(reason = "", notes = "") {
+        const body = {};
+        if (reason)
+            body.reason = reason;
+        if (notes)
+            body.notes = notes;
+        return body;
+    }
+    async confirmFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/confirm/${findingId}`, this.statusBody(reason, notes));
+    }
+    async controlFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/controlled/${findingId}`, this.statusBody(reason, notes));
+    }
+    async acceptRiskFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/accept-risk/${findingId}`, this.statusBody(reason, notes));
+    }
+    async openFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/reopen/${findingId}`, this.statusBody(reason, notes));
+    }
+    async falsePositiveFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/false-positive/${findingId}`, this.statusBody(reason, notes));
+    }
+    async triageFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/triage/${findingId}`, this.statusBody(reason, notes));
+    }
+    async inProgressFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/inProgress/${findingId}`, this.statusBody(reason, notes));
+    }
+    async suppressFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/suppressed/${findingId}`, this.statusBody(reason, notes));
+    }
+    async mitigateFinding(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/mitigated/${findingId}`, this.statusBody(reason, notes));
+    }
+    async bulkConfirm(findingIds, reason = "", notes = "") {
+        return this.put("/user/findings/bulk/confirm", { ...this.statusBody(reason, notes), findingIds });
+    }
+    async bulkReopen(findingIds, reason = "", notes = "") {
+        return this.put("/user/findings/bulk/reopen", { ...this.statusBody(reason, notes), findingIds });
+    }
+    async bulkAcceptRisk(findingIds, reason = "", notes = "") {
+        return this.put("/user/findings/bulk/accept-risk", { ...this.statusBody(reason, notes), findingIds });
+    }
+    async bulkFalsePositive(findingIds, reason = "", notes = "") {
+        return this.put("/user/findings/bulk/false-positive", { ...this.statusBody(reason, notes), findingIds });
+    }
+    async addComment(findingId, note) {
+        return this.post(`/user/findings/${findingId}/comment`, {
+            note,
+            markdownText: note,
+            isManualComment: true,
+        });
+    }
+    async updateFindingTags(findingId, opts) {
+        const findingTags = this.buildFindingTagsPayload(opts);
+        return this.put("/user/findings/findingTags", {
+            findingTags,
+            findingIds: [findingId],
+        });
+    }
+    async bulkUpdateFindingTags(findingIds, opts) {
+        const findingTags = this.buildFindingTagsPayload(opts);
+        const results = [];
+        for (const findingId of findingIds) {
+            results.push(await this.put("/user/findings/findingTags", { findingTags, findingIds: [findingId] }));
+        }
+        return { findingIds, results };
+    }
+    /** ArmorCode PUT /user/findings/findingTags expects tags to set, not the full tag list. */
+    buildFindingTagsPayload(opts) {
+        const tags = [...(opts.added ?? [])];
+        for (const raw of opts.removed ?? []) {
+            const key = raw.includes(":") ? raw.slice(0, raw.indexOf(":")) : raw;
+            const clear = key ? `${key}:` : raw;
+            if (!tags.some((t) => t === raw || t.startsWith(clear)))
+                tags.push(clear);
+        }
+        return tags;
+    }
+    /** Comment first, then tag — ArmorCode triage order. */
+    async setProductExploitability(findingId, exploitable, reason) {
+        const label = exploitable ? "exploitable" : "notexploitable";
+        const comment = `${label}\nreason: ${reason}`;
+        const commentResult = await this.addComment(findingId, comment);
+        const tag = productExploitabilityTag(exploitable);
+        const tags = await this.updateFindingTags(findingId, { added: [tag] });
+        return { comment: commentResult, tags };
+    }
+    async updateSeverity(findingId, severity, reason = "", notes = "") {
+        const body = { severity: severity.toUpperCase() };
+        if (reason)
+            body.reason = reason;
+        if (notes)
+            body.notes = notes;
+        return this.put(`/user/findings/severity/${findingId}`, body);
+    }
+    async bulkUpdateSeverity(findingIds, severity, reason = "", notes = "") {
+        const body = { findingIds, approved: true, severity: severity.toUpperCase() };
+        if (reason)
+            body.reason = reason;
+        if (notes)
+            body.notes = notes;
+        return this.put("/api/approve-reject/severity", body);
+    }
+    async assignFindingToException(findingId, reason = "", notes = "") {
+        return this.put(`/user/findings/update-risk-register/${findingId}`, this.statusBody(reason, notes));
+    }
+    // --- Stats ---
+    async getFindingStats(opts) {
+        try {
+            const filters = {};
+            if (opts.productIds?.length)
+                filters.product = opts.productIds;
+            if (opts.subproductIds?.length)
+                filters.subProduct = opts.subproductIds;
+            if (opts.status?.length)
+                filters.status = normalizeStatusList(opts.status);
+            if (opts.sourceTools?.length)
+                filters.source = opts.sourceTools;
+            return await this.post("/api/businessunits/dashboard/findingStats", { filters, aggField: "severity" });
+        }
+        catch (err) {
+            const { findings } = await this.searchFindingsAll({
+                productIds: opts.productIds,
+                subproductIds: opts.subproductIds,
+                severity: opts.severity,
+                status: opts.status,
+                sourceTools: opts.sourceTools,
+                maxPages: 20,
+                size: 100,
+            });
+            return {
+                ...computeStats(findings),
+                fallback: true,
+                dashboardError: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async getSeverityStats(productIds, subproductIds) {
+        try {
+            const filters = {};
+            if (productIds?.length)
+                filters.product = productIds;
+            if (subproductIds?.length)
+                filters.subProduct = subproductIds;
+            return await this.post("/api/businessunits/dashboard/findingStats/severity-stats", { filters });
+        }
+        catch (err) {
+            const { findings } = await this.searchFindingsAll({
+                productIds,
+                subproductIds,
+                maxPages: 20,
+                size: 100,
+            });
+            return {
+                ...computeStats(findings),
+                fallback: true,
+                dashboardError: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // --- Products ---
+    async listProducts(search = "", pageSize = 100) {
+        const body = { pageSize, pageNumber: 0, calculateRisk: true };
+        if (search)
+            body.search = search;
+        return this.post("/api/product/short", body);
+    }
+    async listSubproducts(opts = {}) {
+        const body = {};
+        if (opts.productIds?.length)
+            body.productIds = opts.productIds;
+        if (opts.search)
+            body.search = opts.search;
+        return this.post("/api/sub-product/name-id", body);
+    }
+    async createSubproduct(productId, name, description = "") {
+        const body = { name, product: { id: productId } };
+        if (description)
+            body.description = description;
+        return this.post("/api/sub-product", body);
+    }
+    // --- Risk ---
+    async getAllProductRiskScores(environmentName = "") {
+        return this.get("/compliance/product-risks", environmentName ? { environmentName } : undefined);
+    }
+    async getProductRiskScore(productId, environmentName = "") {
+        return this.get(`/compliance/product-risk/${productId}`, environmentName ? { environmentName } : undefined);
+    }
+    async getSubproductRiskScore(subproductId, environmentName = "") {
+        return this.get(`/compliance/subproduct-risks/${subproductId}`, environmentName ? { environmentName } : undefined);
+    }
+    // --- Environments ---
+    async listEnvironments(subproductId) {
+        return this.get("/user/environment/elastic/short", { subProductId: subproductId });
+    }
+    // --- Scans ---
+    async listScans(opts = {}) {
+        return this.get("/v2/scans", {
+            page: opts.page ?? 0,
+            size: opts.size ?? 20,
+            sort: opts.sort ?? "createdAt,desc",
+            productIds: opts.productIds,
+            subProductIds: opts.subproductIds,
+            environmentNames: opts.environmentNames,
+            toolNames: opts.toolNames,
+            scanStatuses: opts.scanStatuses?.map((s) => s.toUpperCase()),
+            scanTypes: opts.scanTypes,
+            triggerBy: opts.triggerBy,
+        });
+    }
+    async getScan(scanId) {
+        return this.get(`/api/scans/${scanId}`);
+    }
+    async executeScan(subproductId, toolName, environmentName) {
+        const url = new URL(`/api/sub-product/${subproductId}/execute-scan`, this.config.url);
+        url.searchParams.set("toolName", toolName);
+        url.searchParams.set("environmentName", environmentName);
+        return this.request("POST", url.toString());
+    }
+    async executeScanForFinding(findingId) {
+        return this.post(`/user/findings/${findingId}/execute-scan`);
+    }
+    // --- Exceptions ---
+    async listOpenExceptions() {
+        return this.get("/api/risk-register/open");
+    }
+    async getException(exceptionId) {
+        return this.get(`/api/risk-register/${exceptionId}`);
+    }
+    async createException(opts) {
+        const scope = { productId: opts.productId };
+        if (opts.subproductIds?.length)
+            scope.subProductIds = opts.subproductIds;
+        if (opts.environmentName)
+            scope.environmentName = opts.environmentName;
+        if (opts.autoAddFindings)
+            scope.autoAddInScopeFinding = true;
+        const body = {
+            name: opts.name,
+            description: opts.description,
+            startDate: opts.startDate,
+            endDate: opts.endDate,
+            scope,
+        };
+        if (opts.reasons?.length)
+            body.reasons = opts.reasons;
+        return this.post("/api/risk-register", body);
+    }
+    // --- Schedulers ---
+    async listToolSchedulers(toolName) {
+        return this.get(`/user/tools/scheduler/${encodeURIComponent(toolName)}`);
+    }
+    async getDefaultToolScheduler(toolName) {
+        return this.get(`/user/tools/scheduler/default/${encodeURIComponent(toolName)}`);
+    }
+    async createToolScheduler(opts) {
+        const body = {
+            toolName: opts.toolName,
+            timezone: opts.timezone ?? "UTC",
+            interval: Math.max(opts.interval ?? 900000, 900000),
+            frequencyUnit: opts.frequencyUnit ?? "MINUTES",
+            markInactiveAfter: 1,
+            enabled: opts.enabled ?? true,
+        };
+        if (opts.productId)
+            body.product = opts.productId;
+        if (opts.subproductId)
+            body.subProduct = opts.subproductId;
+        if (opts.environmentId)
+            body.environment = opts.environmentId;
+        if (opts.startTime)
+            body.startTime = opts.startTime;
+        if (opts.fromDate)
+            body.fromDate = opts.fromDate;
+        return this.post("/user/tools/scheduler", body);
+    }
+    async deleteToolScheduler(configId) {
+        return this.delete(`/user/tools/scheduler/${configId}`);
+    }
+    // --- Release gate ---
+    async releaseGateStatus(opts) {
+        const body = JSON.stringify({
+            product: opts.product,
+            subProducts: opts.subProducts,
+            env: opts.env,
+            jobName: opts.jobName ?? "mcp-check",
+            buildNumber: opts.buildNumber ?? "1",
+            current: "1",
+            end: "1",
+            jobURL: "",
+        });
+        return this.request("POST", `${this.config.url}/client/build`, undefined, body);
+    }
+    // --- HTTP ---
+    path(p) {
+        if (p.startsWith("http"))
+            return new URL(p).pathname + new URL(p).search;
+        return p.startsWith("/") ? p : `/${p}`;
+    }
+    applyQuery(url, query) {
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    url.searchParams.append(key, String(item));
+            }
+            else {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.config.apiToken}`,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+    }
+    async request(method, url, body, rawBody) {
+        const init = { method, headers: this.headers() };
+        if (rawBody !== undefined)
+            init.body = rawBody;
+        else if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const resp = await fetch(url, init);
+        if (!resp.ok) {
+            const text = await resp.text();
+            throw new Error(`ArmorCode API ${resp.status}: ${text.slice(0, 500)}`);
+        }
+        const contentType = resp.headers.get("content-type") ?? "";
+        if (!resp.headers.get("content-length") && resp.status === 204) {
+            return { status: "ok", http_code: resp.status };
+        }
+        const text = await resp.text();
+        if (!text)
+            return { status: "ok", http_code: resp.status, message: "" };
+        if (contentType.includes("application/json"))
+            return JSON.parse(text);
+        return { status: "ok", message: text };
+    }
+}

package/dist/config.js

@@ -0,0 +1,23 @@
+function envFlag(name, defaultValue = false) {
+    const v = process.env[name];
+    if (v === undefined || v.trim() === "")
+        return defaultValue;
+    const n = v.trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(n))
+        return false;
+    return ["1", "true", "yes", "on"].includes(n);
+}
+export function loadConfig() {
+    const url = process.env.ARMORCODE_URL;
+    const apiToken = process.env.ARMORCODE_API_TOKEN ?? process.env.ARMORCODE_API_KEY;
+    if (!url)
+        throw new Error("Missing required environment variable: ARMORCODE_URL");
+    if (!apiToken) {
+        throw new Error("Missing required environment variable: ARMORCODE_API_TOKEN (or ARMORCODE_API_KEY)");
+    }
+    return {
+        url: url.replace(/\/+$/, ""),
+        apiToken,
+        writeEnabled: envFlag("ARMORCODE_WRITE_ENABLED", false),
+    };
+}

package/dist/findingDetail.js

@@ -0,0 +1,58 @@
+import { listContent } from "./utils.js";
+export { listContent };
+export function parseResourceInfo(description) {
+    const marker = ["##Resource Information", "## Resource Information"].find((m) => description.includes(m));
+    if (!marker)
+        return null;
+    const block = description.slice(description.indexOf(marker));
+    const info = {};
+    for (const line of block.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("**") && trimmed.includes("**:")) {
+            const idx = trimmed.indexOf("**:");
+            if (idx >= 0) {
+                const key = trimmed.slice(2, idx).trim();
+                info[key] = trimmed.slice(idx + 3).trim();
+            }
+        }
+    }
+    return Object.keys(info).length ? info : null;
+}
+export function buildFindingDetail(finding) {
+    const product = finding.product ?? {};
+    const subProduct = finding.subProduct ?? {};
+    const environment = finding.environment ?? {};
+    const source = finding.source ?? {};
+    const description = String(finding.description ?? "");
+    const mitigation = String(finding.mitigation ?? "");
+    const resource = parseResourceInfo(description);
+    const detail = {
+        id: finding.id,
+        title: finding.title,
+        severity: finding.severity,
+        status: finding.status,
+        product: product.name,
+        productId: product.id,
+        subProduct: subProduct.name,
+        subProductId: subProduct.id,
+        environment: environment.name,
+        source: source.name ?? source,
+        category: finding.armorcodeCategory ?? finding.category,
+        scanType: finding.scanType,
+        riskScore: finding.riskScore ?? finding.findingScore,
+        cve: finding.cve ?? [],
+        cwes: finding.cwes ?? finding.cwe ?? [],
+        component: finding.componentName,
+        componentVersion: finding.componentVersion,
+        foundOn: finding.foundOn ?? finding.foundOnDate,
+        lastSeenDate: finding.lastSeenDate,
+        toolFindingStatus: finding.toolFindingStatus,
+        toolSeverity: finding.toolSeverity,
+        tags: finding.tags ?? [],
+        description,
+        mitigation,
+    };
+    if (resource)
+        detail.resourceInformation = resource;
+    return detail;
+}

package/dist/findingFilters.js

@@ -0,0 +1,65 @@
+export function normalizeSeverityList(values) {
+    const out = new Set();
+    for (const raw of values) {
+        const s = raw.trim().toUpperCase();
+        if (!s)
+            continue;
+        if (s === "CRITICAL" || s === "CRIT")
+            out.add("CRITICAL");
+        else if (s === "HIGH")
+            out.add("HIGH");
+        else if (s === "MEDIUM" || s === "MED")
+            out.add("MEDIUM");
+        else if (s === "LOW")
+            out.add("LOW");
+        else if (s === "INFO" || s === "INFORMATIONAL")
+            out.add("INFO");
+        else
+            out.add(s);
+    }
+    return [...out];
+}
+export function normalizeStatusList(values) {
+    return values.map((s) => s.trim().toUpperCase()).filter(Boolean);
+}
+/** ArmorCode AQL FindingAge uses first-detected date, not last seen. */
+export function findingFoundTimestamp(f) {
+    return Number(f.foundOn ?? f.foundOnDate ?? 0);
+}
+export function findingLastSeenTimestamp(f) {
+    return Number(f.lastSeenDate ?? 0);
+}
+export function hasTagPrefix(tags, prefix) {
+    const p = prefix.toLowerCase();
+    return (Array.isArray(tags) ? tags : []).some((t) => String(t).toLowerCase().startsWith(p));
+}
+export function matchesFindingFilters(f, opts) {
+    if (opts.severity?.length) {
+        const allowed = new Set(normalizeSeverityList(opts.severity));
+        if (!allowed.has(String(f.severity ?? "").toUpperCase()))
+            return false;
+    }
+    if (opts.excludeTagPrefix && hasTagPrefix(f.tags, opts.excludeTagPrefix))
+        return false;
+    if (opts.findingAgeDays != null && opts.findingAgeDays > 0) {
+        const cutoff = (opts.nowMs ?? Date.now()) - opts.findingAgeDays * 24 * 60 * 60 * 1000;
+        const ts = findingFoundTimestamp(f);
+        if (ts > 0 && ts < cutoff)
+            return false;
+    }
+    return true;
+}
+export function productExploitabilityTag(exploitable) {
+    return exploitable ? "product_exploitability:exploitable" : "product_exploitability:not exploitable";
+}
+export function computeStats(findings) {
+    const bySeverity = {};
+    const byStatus = {};
+    for (const f of findings) {
+        const sev = String(f.severity ?? "UNKNOWN").toUpperCase();
+        const st = String(f.status ?? "UNKNOWN").toUpperCase();
+        bySeverity[sev] = (bySeverity[sev] ?? 0) + 1;
+        byStatus[st] = (byStatus[st] ?? 0) + 1;
+    }
+    return { total: findings.length, bySeverity, byStatus, source: "computed_from_search" };
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ArmorCodeClient } from "./client.js";
+import { loadConfig } from "./config.js";
+import { registerArmorCodeTools } from "./tools/registerTools.js";
+const config = loadConfig();
+const client = new ArmorCodeClient(config);
+const server = new McpServer({
+    name: "armorcode-mcp",
+    version: "1.0.0",
+});
+registerArmorCodeTools(server, client);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/resolve.js

@@ -0,0 +1,45 @@
+import { listContent } from "./utils.js";
+export async function resolveProductSubproduct(client, productName = "", subproductName = "") {
+    let productIds;
+    if (productName) {
+        const products = await client.listProducts(productName);
+        const content = listContent(products);
+        const match = content.find((p) => String(p.name).toLowerCase() === productName.toLowerCase());
+        if (match?.id != null)
+            productIds = [Number(match.id)];
+        else if (content[0]?.id != null)
+            productIds = [Number(content[0].id)];
+    }
+    let subproductIds;
+    if (subproductName) {
+        const subproducts = await client.listSubproducts({ productIds, search: subproductName });
+        const spList = listContent(subproducts);
+        const match = spList.find((sp) => String(sp.name).toLowerCase() === subproductName.toLowerCase());
+        if (match?.id != null)
+            subproductIds = [Number(match.id)];
+        else if (spList[0]?.id != null)
+            subproductIds = [Number(spList[0].id)];
+    }
+    return { productIds, subproductIds };
+}
+export async function resolveProductId(client, productName) {
+    const products = await client.listProducts(productName);
+    const content = listContent(products);
+    const match = content.find((p) => String(p.name).toLowerCase() === productName.toLowerCase());
+    if (match?.id != null)
+        return Number(match.id);
+    if (content[0]?.id != null)
+        return Number(content[0].id);
+    return null;
+}
+export async function resolveSubproductId(client, subproductName, productName = "") {
+    const { productIds } = productName ? await resolveProductSubproduct(client, productName) : {};
+    const subproducts = await client.listSubproducts({ productIds, search: subproductName });
+    const spList = listContent(subproducts);
+    const match = spList.find((sp) => String(sp.name).toLowerCase() === subproductName.toLowerCase());
+    if (match?.id != null)
+        return Number(match.id);
+    if (spList[0]?.id != null)
+        return Number(spList[0].id);
+    return null;
+}

package/dist/tools/common.js

@@ -0,0 +1,18 @@
+export function jsonResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+export function resolveWriteMode(requestedDryRun, writeEnabled) {
+    if (requestedDryRun !== false)
+        return { dryRun: true };
+    if (!writeEnabled) {
+        return {
+            dryRun: true,
+            notice: "Writes disabled (ARMORCODE_WRITE_ENABLED not set or false). Preview only.",
+        };
+    }
+    return { dryRun: false };
+}
+export function splitCsv(value) {
+    const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+    return items.length ? items : undefined;
+}

package/dist/tools/registerTools.js

@@ -0,0 +1,360 @@
+import { z } from "zod";
+import { buildFindingDetail, listContent } from "../findingDetail.js";
+import { resolveProductId, resolveProductSubproduct, resolveSubproductId } from "../resolve.js";
+import { jsonResult, resolveWriteMode, splitCsv } from "./common.js";
+import { hasTagPrefix, productExploitabilityTag } from "../findingFilters.js";
+function findingsFromSearch(data) {
+    if (data && typeof data === "object") {
+        const o = data;
+        const nested = o.data;
+        if (nested && Array.isArray(nested.findings))
+            return nested.findings;
+    }
+    return listContent(data);
+}
+function summarizeFinding(f) {
+    const product = f.product ?? {};
+    const subProduct = f.subProduct ?? {};
+    const source = f.source ?? {};
+    return {
+        id: f.id,
+        title: f.title,
+        severity: f.severity,
+        status: f.status,
+        product: product.name,
+        subProduct: subProduct.name,
+        source: source.name ?? source,
+        cve: f.cve,
+        tags: f.tags ?? [],
+        component: f.componentName,
+        componentVersion: f.componentVersion,
+    };
+}
+async function statusTransition(client, dryRun, findingId, action, apply, newStatus, extra = {}) {
+    if (dryRun) {
+        return jsonResult({ success: true, dry_run: true, finding_id: findingId, action, new_status: newStatus, ...extra });
+    }
+    const response = await apply();
+    return jsonResult({ success: true, finding_id: findingId, new_status: newStatus, response, ...extra });
+}
+export function registerArmorCodeTools(server, client) {
+    server.registerTool("armorcode_health", { title: "ArmorCode Health", description: "Verify ArmorCode API connectivity.", inputSchema: {} }, async () => jsonResult(await client.listProducts("", 1)));
+    server.registerTool("armorcode_search_findings", {
+        title: "Search Findings",
+        description: "Search/filter ArmorCode findings. Severity and excludeTagPrefix are applied client-side when server filters fail. Use fetchAll=true to paginate.",
+        inputSchema: {
+            productName: z.string().optional(),
+            subproductName: z.string().optional(),
+            severity: z.string().optional(),
+            status: z.string().optional(),
+            sourceTool: z.string().optional(),
+            tags: z.string().optional(),
+            cves: z.string().optional(),
+            pageSize: z.number().int().positive().max(100).optional(),
+            afterKey: z.number().int().optional(),
+            fetchAll: z.boolean().optional(),
+            maxPages: z.number().int().positive().max(50).optional(),
+            excludeTagPrefix: z.string().optional(),
+            findingAgeDays: z.number().int().positive().max(365).optional(),
+        },
+    }, async ({ productName, subproductName, severity, status, sourceTool, tags, cves, pageSize, afterKey, fetchAll, maxPages, excludeTagPrefix, findingAgeDays, }) => {
+        const { productIds, subproductIds } = await resolveProductSubproduct(client, productName ?? "", subproductName ?? "");
+        const searchOpts = {
+            productIds,
+            subproductIds,
+            severity: splitCsv(severity ?? ""),
+            status: splitCsv(status ?? ""),
+            sourceTools: sourceTool ? [sourceTool] : undefined,
+            tags: splitCsv(tags ?? ""),
+            cves: splitCsv(cves ?? ""),
+            size: pageSize ?? 50,
+            afterKey,
+            excludeTagPrefix: excludeTagPrefix ?? undefined,
+            findingAgeDays: findingAgeDays ?? undefined,
+        };
+        if (fetchAll) {
+            const result = await client.searchFindingsAll({ ...searchOpts, maxPages: maxPages ?? 20, size: pageSize ?? 100 });
+            const findings = result.findings.map(summarizeFinding);
+            return jsonResult({
+                returned: findings.length,
+                pagesFetched: result.pagesFetched,
+                totalFetched: result.totalFetched,
+                findings,
+            });
+        }
+        const data = await client.searchFindings(searchOpts);
+        const findings = findingsFromSearch(data).map(summarizeFinding);
+        const raw = data;
+        const meta = raw.data ?? {};
+        return jsonResult({
+            returned: findings.length,
+            findings,
+            afterKey: meta.afterKey,
+            clientFiltered: meta.clientFiltered ?? false,
+        });
+    });
+    server.registerTool("armorcode_get_finding", { title: "Get Finding", description: "Full finding details by ID.", inputSchema: { findingId: z.number().int().positive() } }, async ({ findingId }) => jsonResult(buildFindingDetail((await client.getFinding(findingId)))));
+    server.registerTool("armorcode_get_finding_events", { title: "Finding Events", description: "Audit events for a finding.", inputSchema: { findingId: z.number().int().positive() } }, async ({ findingId }) => jsonResult(await client.getFindingEvents(findingId)));
+    const statusTool = (name, title, newStatus, apply) => {
+        server.registerTool(name, { title, description: `${title}. dryRun defaults true.`, inputSchema: { findingId: z.number().int().positive(), reason: z.string().optional(), notes: z.string().optional(), dryRun: z.boolean().optional() } }, async ({ findingId, reason, notes, dryRun }) => {
+            const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+            const result = await statusTransition(client, dry, findingId, name, () => apply(findingId, reason ?? "", notes ?? ""), newStatus, { notice });
+            return result;
+        });
+    };
+    statusTool("armorcode_confirm_finding", "Confirm Finding", "CONFIRMED", (id, r, n) => client.confirmFinding(id, r, n));
+    statusTool("armorcode_control_finding", "Control Finding", "CONTROLLED", (id, r, n) => client.controlFinding(id, r, n));
+    statusTool("armorcode_accept_risk", "Accept Risk", "ACCEPTRISK", (id, r, n) => client.acceptRiskFinding(id, r, n));
+    statusTool("armorcode_mark_false_positive", "False Positive", "FALSEPOSITIVE", (id, r, n) => client.falsePositiveFinding(id, r, n));
+    statusTool("armorcode_reopen_finding", "Reopen Finding", "OPEN", (id, r, n) => client.openFinding(id, r, n));
+    statusTool("armorcode_triage_finding", "Triage Finding", "TRIAGE", (id, r, n) => client.triageFinding(id, r, n));
+    statusTool("armorcode_mitigate_finding", "Mitigate Finding", "MITIGATED", (id, r, n) => client.mitigateFinding(id, r, n));
+    statusTool("armorcode_suppress_finding", "Suppress Finding", "SUPPRESSED", (id, r, n) => client.suppressFinding(id, r, n));
+    server.registerTool("armorcode_block_finding", { title: "Block Finding", description: "Block via accept-risk (fix unavailable). dryRun defaults true.", inputSchema: { findingId: z.number().int().positive(), reason: z.string().optional(), notes: z.string().optional(), dryRun: z.boolean().optional() } }, async ({ findingId, reason, notes, dryRun }) => {
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        return statusTransition(client, dry, findingId, "block", () => client.acceptRiskFinding(findingId, reason ?? "Fix Unavailable", notes ?? ""), "BLOCKED", { notice, reason: reason ?? "Fix Unavailable" });
+    });
+    server.registerTool("armorcode_add_comment", { title: "Add Comment", description: "Add comment to finding. dryRun defaults true.", inputSchema: { findingId: z.number().int().positive(), note: z.string().min(1), dryRun: z.boolean().optional() } }, async ({ findingId, note, dryRun }) => {
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, finding_id: findingId, note });
+        return jsonResult({ success: true, finding_id: findingId, response: await client.addComment(findingId, note) });
+    });
+    server.registerTool("armorcode_add_exploitability_comment", { title: "Exploitability Comment", description: "Structured exploitable/notexploitable comment. dryRun defaults true.", inputSchema: { findingId: z.number().int().positive(), exploitable: z.boolean(), reason: z.string().min(1), dryRun: z.boolean().optional() } }, async ({ findingId, exploitable, reason, dryRun }) => {
+        const label = exploitable ? "exploitable" : "notexploitable";
+        const comment = `${label}\nreason: ${reason}`;
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, finding_id: findingId, comment });
+        return jsonResult({ success: true, finding_id: findingId, comment, response: await client.addComment(findingId, comment) });
+    });
+    server.registerTool("armorcode_add_finding_tags", {
+        title: "Add Finding Tags",
+        description: "Add/remove finding tags only (no comment). For exploitability triage use armorcode_set_product_exploitability. dryRun defaults true.",
+        inputSchema: {
+            findingId: z.number().int().positive(),
+            tags: z.string().min(1),
+            removeTags: z.string().optional(),
+            dryRun: z.boolean().optional(),
+        },
+    }, async ({ findingId, tags, removeTags, dryRun }) => {
+        const added = splitCsv(tags) ?? [];
+        const removed = splitCsv(removeTags ?? "") ?? [];
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        const payload = { finding_id: findingId, added, removed };
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, ...payload });
+        return jsonResult({ success: true, ...payload, response: await client.updateFindingTags(findingId, { added, removed }) });
+    });
+    server.registerTool("armorcode_set_product_exploitability", {
+        title: "Set Product Exploitability",
+        description: "Triage exploitability: adds comment first, then product_exploitability tag. dryRun defaults true.",
+        inputSchema: {
+            findingId: z.number().int().positive(),
+            exploitable: z.boolean(),
+            reason: z.string().min(1),
+            dryRun: z.boolean().optional(),
+        },
+    }, async ({ findingId, exploitable, reason, dryRun }) => {
+        const tag = productExploitabilityTag(exploitable);
+        const label = exploitable ? "exploitable" : "notexploitable";
+        const comment = `${label}\nreason: ${reason}`;
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        const payload = { finding_id: findingId, exploitable, tag, comment };
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, ...payload });
+        return jsonResult({ success: true, ...payload, response: await client.setProductExploitability(findingId, exploitable, reason) });
+    });
+    server.registerTool("armorcode_bulk_set_product_exploitability", {
+        title: "Bulk Set Product Exploitability",
+        description: "Triage multiple findings: comment first, then product_exploitability tag per finding. dryRun defaults true.",
+        inputSchema: {
+            productName: z.string().min(1),
+            subproductName: z.string().optional(),
+            severity: z.string().optional(),
+            status: z.string().optional().default("OPEN"),
+            findingAgeDays: z.number().int().positive().max(365).optional().default(30),
+            exploitable: z.boolean().optional().default(false),
+            reason: z.string().min(1),
+            maxFindings: z.number().int().positive().max(200).optional().default(50),
+            dryRun: z.boolean().optional(),
+        },
+    }, async ({ productName, subproductName, severity, status, findingAgeDays, exploitable, reason, maxFindings, dryRun }) => {
+        const { productIds, subproductIds } = await resolveProductSubproduct(client, productName, subproductName ?? "");
+        const { findings, pagesFetched, totalFetched } = await client.searchFindingsAll({
+            productIds,
+            subproductIds,
+            status: splitCsv(status ?? "OPEN"),
+            severity: splitCsv(severity ?? "CRITICAL,HIGH"),
+            excludeTagPrefix: "product_exploitability",
+            findingAgeDays: findingAgeDays ?? 30,
+            maxPages: 20,
+            size: 100,
+        });
+        const targets = findings.slice(0, maxFindings ?? 50);
+        const tag = productExploitabilityTag(exploitable ?? false);
+        const label = exploitable ? "exploitable" : "notexploitable";
+        const comment = `${label}\nreason: ${reason}`;
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        const planned = targets.map((f) => ({
+            id: f.id,
+            severity: f.severity,
+            title: String(f.title ?? "").slice(0, 100),
+            component: f.componentName,
+            alreadyTagged: hasTagPrefix(f.tags, "product_exploitability"),
+            tag,
+            comment,
+        }));
+        if (dry) {
+            return jsonResult({
+                success: true,
+                dry_run: true,
+                notice,
+                matched: findings.length,
+                pagesFetched,
+                totalFetched,
+                planned_count: planned.length,
+                planned,
+            });
+        }
+        const results = [];
+        for (const f of targets) {
+            try {
+                const response = await client.setProductExploitability(Number(f.id), exploitable ?? false, reason);
+                results.push({ id: f.id, success: true, response });
+            }
+            catch (err) {
+                results.push({ id: f.id, success: false, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        return jsonResult({ success: true, matched: findings.length, applied: results.length, results });
+    });
+    server.registerTool("armorcode_update_finding_severity", { title: "Update Severity", description: "Update finding severity. dryRun defaults true.", inputSchema: { findingId: z.number().int().positive(), severity: z.enum(["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"]), reason: z.string().optional(), notes: z.string().optional(), dryRun: z.boolean().optional() } }, async ({ findingId, severity, reason, notes, dryRun }) => {
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, finding_id: findingId, new_severity: severity });
+        return jsonResult({ success: true, finding_id: findingId, new_severity: severity, response: await client.updateSeverity(findingId, severity, reason ?? "", notes ?? "") });
+    });
+    server.registerTool("armorcode_get_findings_stats", { title: "Findings Stats", description: "Finding counts by severity/status.", inputSchema: { productName: z.string().optional(), subproductName: z.string().optional(), severity: z.string().optional(), status: z.string().optional(), sourceTool: z.string().optional() } }, async (args) => {
+        const { productIds, subproductIds } = await resolveProductSubproduct(client, args.productName ?? "", args.subproductName ?? "");
+        return jsonResult(await client.getFindingStats({ productIds, subproductIds, severity: splitCsv(args.severity ?? ""), status: splitCsv(args.status ?? ""), sourceTools: args.sourceTool ? [args.sourceTool] : undefined }));
+    });
+    server.registerTool("armorcode_get_severity_stats", { title: "Severity Stats", description: "Severity breakdown for product/subproduct.", inputSchema: { productName: z.string().optional(), subproductName: z.string().optional() } }, async ({ productName, subproductName }) => {
+        const { productIds, subproductIds } = await resolveProductSubproduct(client, productName ?? "", subproductName ?? "");
+        return jsonResult(await client.getSeverityStats(productIds, subproductIds));
+    });
+    server.registerTool("armorcode_list_products", { title: "List Products", description: "List ArmorCode products/groups.", inputSchema: { search: z.string().optional() } }, async ({ search }) => jsonResult(await client.listProducts(search ?? "")));
+    server.registerTool("armorcode_list_subproducts", { title: "List Subproducts", description: "List subproducts, optionally by product.", inputSchema: { productName: z.string().optional(), search: z.string().optional() } }, async ({ productName, search }) => {
+        const { productIds } = await resolveProductSubproduct(client, productName ?? "");
+        return jsonResult(await client.listSubproducts({ productIds, search: search ?? "" }));
+    });
+    server.registerTool("armorcode_get_product_risk_score", { title: "Product Risk Score", description: "Risk score for a product by name.", inputSchema: { productName: z.string().min(1), environment: z.string().optional() } }, async ({ productName, environment }) => {
+        const productId = await resolveProductId(client, productName);
+        if (!productId)
+            return jsonResult({ error: `Product '${productName}' not found` });
+        return jsonResult(await client.getProductRiskScore(productId, environment ?? ""));
+    });
+    server.registerTool("armorcode_get_subproduct_risk_score", { title: "Subproduct Risk Score", description: "Risk score for a subproduct.", inputSchema: { subproductName: z.string().min(1), productName: z.string().optional(), environment: z.string().optional() } }, async ({ subproductName, productName, environment }) => {
+        const subproductId = await resolveSubproductId(client, subproductName, productName ?? "");
+        if (!subproductId)
+            return jsonResult({ error: `Subproduct '${subproductName}' not found` });
+        return jsonResult(await client.getSubproductRiskScore(subproductId, environment ?? ""));
+    });
+    server.registerTool("armorcode_get_all_product_risk_scores", { title: "All Product Risk Scores", description: "Risk scores for all products.", inputSchema: { environment: z.string().optional() } }, async ({ environment }) => jsonResult(await client.getAllProductRiskScores(environment ?? "")));
+    server.registerTool("armorcode_list_scans", { title: "List Scans", description: "List security scans with filters.", inputSchema: { productName: z.string().optional(), subproductName: z.string().optional(), toolName: z.string().optional(), environment: z.string().optional(), scanStatus: z.string().optional(), pageSize: z.number().int().positive().max(100).optional() } }, async ({ productName, subproductName, toolName, environment, scanStatus, pageSize }) => {
+        const { productIds, subproductIds } = await resolveProductSubproduct(client, productName ?? "", subproductName ?? "");
+        return jsonResult(await client.listScans({
+            productIds,
+            subproductIds,
+            toolNames: toolName ? [toolName] : undefined,
+            environmentNames: environment ? [environment] : undefined,
+            scanStatuses: splitCsv(scanStatus ?? ""),
+            size: pageSize ?? 20,
+        }));
+    });
+    server.registerTool("armorcode_get_scan", { title: "Get Scan", description: "Scan details by ID.", inputSchema: { scanId: z.number().int().positive() } }, async ({ scanId }) => jsonResult(await client.getScan(scanId)));
+    server.registerTool("armorcode_execute_scan", { title: "Execute Scan", description: "Trigger scan for subproduct. dryRun defaults true.", inputSchema: { subproductName: z.string().min(1), toolName: z.string().min(1), environment: z.string().min(1), productName: z.string().optional(), dryRun: z.boolean().optional() } }, async ({ subproductName, toolName, environment, productName, dryRun }) => {
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        const subproductId = await resolveSubproductId(client, subproductName, productName ?? "");
+        if (!subproductId)
+            return jsonResult({ error: `Subproduct '${subproductName}' not found` });
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, subproduct_id: subproductId, tool: toolName, environment });
+        return jsonResult({ success: true, response: await client.executeScan(subproductId, toolName, environment) });
+    });
+    server.registerTool("armorcode_list_exceptions", { title: "List Exceptions", description: "Open risk register exceptions.", inputSchema: {} }, async () => {
+        const result = await client.listOpenExceptions();
+        const items = Array.isArray(result) ? result : listContent(result);
+        return jsonResult({ total: items.length, exceptions: items });
+    });
+    server.registerTool("armorcode_get_exception", { title: "Get Exception", description: "Exception details by ID.", inputSchema: { exceptionId: z.number().int().positive() } }, async ({ exceptionId }) => jsonResult(await client.getException(exceptionId)));
+    server.registerTool("armorcode_create_exception", { title: "Create Exception", description: "Create risk register exception. dryRun defaults true.", inputSchema: { name: z.string().min(1), description: z.string().min(1), startDate: z.string().min(1), endDate: z.string().min(1), productName: z.string().min(1), reasons: z.string().optional(), subproductName: z.string().optional(), environment: z.string().optional(), dryRun: z.boolean().optional() } }, async (args) => {
+        const { dryRun: dry, notice } = resolveWriteMode(args.dryRun, client.writeEnabled);
+        const productId = await resolveProductId(client, args.productName);
+        if (!productId)
+            return jsonResult({ error: `Product '${args.productName}' not found` });
+        let subproductIds;
+        if (args.subproductName) {
+            const spId = await resolveSubproductId(client, args.subproductName, args.productName);
+            if (spId)
+                subproductIds = [spId];
+        }
+        const payload = { name: args.name, description: args.description, startDate: args.startDate, endDate: args.endDate, productId, reasons: splitCsv(args.reasons ?? "Fix Unavailable"), subproductIds, environmentName: args.environment };
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, payload });
+        return jsonResult({ success: true, exception: await client.createException({ ...payload, reasons: payload.reasons ?? ["Fix Unavailable"] }) });
+    });
+    server.registerTool("armorcode_trigger_scan_pull", { title: "Trigger Scan Pull", description: "Create temporary scheduler for PULL tools (e.g. Black Duck). dryRun defaults true.", inputSchema: { toolName: z.string().min(1), productName: z.string().min(1), subproductName: z.string().min(1), environment: z.string().optional(), dryRun: z.boolean().optional() } }, async ({ toolName, productName, subproductName, environment, dryRun }) => {
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        const productId = await resolveProductId(client, productName);
+        if (!productId)
+            return jsonResult({ error: `Product '${productName}' not found` });
+        const subproductId = await resolveSubproductId(client, subproductName, productName);
+        if (!subproductId)
+            return jsonResult({ error: `Subproduct '${subproductName}' not found` });
+        const envs = (await client.listEnvironments(subproductId));
+        const envList = Array.isArray(envs) ? envs : listContent(envs);
+        const envName = environment ?? "Production";
+        const envMatch = envList.find((e) => String(e.name).toLowerCase() === envName.toLowerCase());
+        const envId = envMatch?.id != null ? Number(envMatch.id) : envList[0]?.id != null ? Number(envList[0].id) : undefined;
+        const startTime = new Date(Date.now() + 60_000).toLocaleTimeString("en-US", { hour: "2-digit", minute: "2-digit", hour12: true, timeZone: "UTC" });
+        if (dry) {
+            return jsonResult({ success: true, dry_run: true, notice, tool: toolName, product_id: productId, subproduct_id: subproductId, environment_id: envId, start_time_utc: startTime });
+        }
+        await client.createToolScheduler({ toolName, productId, subproductId, environmentId: envId, startTime, timezone: "UTC", fromDate: new Date().toISOString() });
+        const schedulers = await client.listToolSchedulers(toolName);
+        const list = listContent(schedulers);
+        const scheduler = list.find((s) => s.product === productId && s.subProduct === subproductId);
+        return jsonResult({ success: true, scheduler_id: scheduler?.id, message: "Scan pull scheduler created. Use armorcode_list_scan_schedulers and armorcode_delete_scan_scheduler to clean up." });
+    });
+    server.registerTool("armorcode_list_scan_schedulers", { title: "List Scan Schedulers", description: "Schedulers for a security tool.", inputSchema: { toolName: z.string().min(1) } }, async ({ toolName }) => {
+        const schedulers = await client.listToolSchedulers(toolName);
+        const defaultSchedule = await client.getDefaultToolScheduler(toolName);
+        return jsonResult({ custom_schedulers: listContent(schedulers), default_schedule: defaultSchedule });
+    });
+    server.registerTool("armorcode_delete_scan_scheduler", { title: "Delete Scan Scheduler", description: "Delete scheduler config. dryRun defaults true.", inputSchema: { schedulerId: z.number().int().positive(), dryRun: z.boolean().optional() } }, async ({ schedulerId, dryRun }) => {
+        const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+        if (dry)
+            return jsonResult({ success: true, dry_run: true, notice, scheduler_id: schedulerId });
+        return jsonResult({ success: true, scheduler_id: schedulerId, response: await client.deleteToolScheduler(schedulerId) });
+    });
+    server.registerTool("armorcode_release_gate_status", { title: "Release Gate Status", description: "Check ArmorCode release gate (/client/build).", inputSchema: { product: z.string().min(1), subProducts: z.array(z.string().min(1)).min(1), env: z.string().min(1) } }, async ({ product, subProducts, env }) => jsonResult(await client.releaseGateStatus({ product, subProducts, env })));
+    server.registerTool("armorcode_api", { title: "ArmorCode API", description: "Escape hatch for any ArmorCode REST path.", inputSchema: { method: z.enum(["GET", "POST", "PUT", "DELETE"]), path: z.string().min(1), body: z.record(z.unknown()).optional(), dryRun: z.boolean().optional() } }, async ({ method, path, body, dryRun }) => {
+        const readOnlyPost = method === "POST" && /^\/api\/findings\b/i.test(path);
+        if (method !== "GET" && !readOnlyPost) {
+            const { dryRun: dry, notice } = resolveWriteMode(dryRun, client.writeEnabled);
+            if (dry)
+                return jsonResult({ dry_run: true, notice, method, path, body });
+        }
+        switch (method) {
+            case "GET":
+                return jsonResult(await client.get(path));
+            case "POST":
+                return jsonResult(await client.post(path, body));
+            case "PUT":
+                return jsonResult(await client.put(path, body));
+            case "DELETE":
+                return jsonResult(await client.delete(path));
+        }
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -0,0 +1,15 @@
+export function listContent(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === "object") {
+        const o = data;
+        if (Array.isArray(o.content))
+            return o.content;
+        if (Array.isArray(o.data))
+            return o.data;
+        const nested = o.data;
+        if (nested && Array.isArray(nested.findings))
+            return nested.findings;
+    }
+    return [];
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@raviraj87/armorcode-mcp",
+  "version": "1.1.0",
+  "description": "Local MCP server for ArmorCode finding triage, scans, exceptions, and risk workflows",
+  "license": "MIT",
+  "author": "Ravi Raj",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raviraj-ntp/armorcode-mcp.git"
+  },
+  "homepage": "https://github.com/raviraj-ntp/armorcode-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/raviraj-ntp/armorcode-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "armorcode",
+    "aspm",
+    "security",
+    "cursor"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "armorcode-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:readonly": "node scripts/test-readonly.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "node-fetch": "^3.3.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}