@zivis/mcp 0.1.8 → 0.1.11

package/dist/tools/explain-signal-for-diff.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { requireApplicationId } from "../resolve-application-id.js";
+import { sanitizeResponse } from "../sanitize.js";
+export const EXPLAIN_SIGNAL_FOR_DIFF_NAME = "zivis_explain_signal_for_my_diff";
+export const EXPLAIN_SIGNAL_FOR_DIFF_DESCRIPTION = `Check whether your proposed change would affect a specific SIGNAL.
+
+You have a SIGNAL flagged in your application's threat model. You're about to make a code change that may or may not address it. Use this tool to see whether your diff touches the files that triggered the signal — and a heuristic verdict on impact.
+
+Returns:
+  - all_evidence_files — every file the signal cites
+  - evidence_files_in_diff — the subset that your proposed change touches
+  - verdict: "may_resolve" | "may_persist" | "no_impact"
+
+The verdict is a heuristic (file overlap), not a guarantee. Run zivis_review_change for the broader picture, or push and let the canonical extraction confirm.`;
+export const EXPLAIN_SIGNAL_FOR_DIFF_SCHEMA = {
+    application_id: z
+        .string()
+        .optional()
+        .describe("Application UUID. If omitted, uses applicationId from .zivis/project.json."),
+    signal_id: z.string().describe("Signal logical id (from zivis_list_signals)"),
+    changes: z
+        .array(z.object({
+        file_path: z.string(),
+        after_content: z.string().optional(),
+        before_content: z.string().optional(),
+    }))
+        .min(1)
+        .describe("Proposed changes"),
+};
+export function createExplainSignalForDiffHandler(apiClient) {
+    return async (params) => {
+        const req = requireApplicationId(params.application_id);
+        if (!req.ok) {
+            return {
+                content: [{ type: "text", text: `Error: ${req.message}` }],
+                isError: true,
+            };
+        }
+        const application_id = req.id;
+        try {
+            const data = await apiClient.post(`/api/apps/${application_id}/signals/${params.signal_id}/explain-for-diff`, {
+                changes: params.changes.map((c) => ({
+                    filePath: c.file_path,
+                    beforeContent: c.before_content,
+                    afterContent: c.after_content,
+                })),
+            });
+            const result = {
+                application_id: data.applicationId,
+                signal_id: data.signalLogicalId,
+                title: data.title,
+                severity: data.severity,
+                verdict: data.verdict,
+                evidence_files_in_diff: data.evidenceFilesInDiff,
+                all_evidence_files: data.allEvidenceFiles,
+                caveats: data.caveats,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(sanitizeResponse(result), null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Failed to explain signal for diff";
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    };
+}

package/dist/tools/generate-diagram.d.ts

@@ -1,9 +1,3 @@
-/**
- * MCP Tool: Generate Diagram from Infrastructure Source
- *
- * Reads a local docker-compose file and sends it to the ZIVIS API
- * for server-side parsing and canvas diagram generation.
- */
 import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 export declare const GENERATE_DIAGRAM_NAME = "zivis_generate_diagram";

package/dist/tools/generate-diagram.js

@@ -1,13 +1,15 @@
-/**
- * MCP Tool: Generate Diagram from Infrastructure Source
- *
- * Reads a local docker-compose file and sends it to the ZIVIS API
- * for server-side parsing and canvas diagram generation.
- */
 import { z } from "zod";
 import { readFile } from "fs/promises";
-import { join } from "path";
+import { join, relative, resolve } from "path";
 import { sanitizeResponse } from "../sanitize.js";
+function resolveWithinProjectDir(projectDir, candidate) {
+    const base = resolve(projectDir);
+    const target = resolve(base, candidate);
+    const rel = relative(base, target);
+    if (rel.startsWith(".."))
+        return null;
+    return target;
+}
 export const GENERATE_DIAGRAM_NAME = "zivis_generate_diagram";
 export const GENERATE_DIAGRAM_DESCRIPTION = `Generate a visual architecture diagram from a Docker Compose file.
 
@@ -52,13 +54,21 @@ export function createGenerateDiagramHandler(apiClient) {
     return async (params) => {
         const projectDir = params.project_dir || process.cwd();
         const sourceFormat = params.source_format || "docker-compose";
-        // Find and read the compose file
         let filePath = params.file_path;
         let content = null;
         if (filePath) {
-            const resolved = filePath.startsWith("/")
-                ? filePath
-                : join(projectDir, filePath);
+            const resolved = resolveWithinProjectDir(projectDir, filePath);
+            if (!resolved) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: file_path must resolve inside project_dir (got: ${filePath})`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
             try {
                 content = await readFile(resolved, "utf-8");
             }
@@ -82,7 +92,6 @@ export function createGenerateDiagramHandler(apiClient) {
                     break;
                 }
                 catch {
-                    /* continue */
                 }
             }
             if (!content) {
@@ -150,4 +159,3 @@ export function createGenerateDiagramHandler(apiClient) {
         }
     };
 }
-//# sourceMappingURL=generate-diagram.js.map

package/dist/tools/get-application-overview.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_get_application_overview — Rich application context with endpoints & threat model
- *
- * Maps to: GET /api/rt/applications/:id/overview
- */
 import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 export declare const GET_APPLICATION_OVERVIEW_NAME = "zivis_get_application_overview";

package/dist/tools/get-application-overview.js

@@ -1,8 +1,3 @@
-/**
- * zivis_get_application_overview — Rich application context with endpoints & threat model
- *
- * Maps to: GET /api/rt/applications/:id/overview
- */
 import { z } from "zod";
 import { requireApplicationId } from "../resolve-application-id.js";
 import { sanitizeResponse } from "../sanitize.js";
@@ -140,4 +135,3 @@ export function createGetApplicationOverviewHandler(apiClient) {
         }
     };
 }
-//# sourceMappingURL=get-application-overview.js.map

package/dist/tools/get-application.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_get_application — Get details of a specific application
- *
- * Maps to: GET /api/rt/applications/:id
- */
 import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 export declare const GET_APPLICATION_NAME = "zivis_get_application";

package/dist/tools/get-application.js

@@ -1,8 +1,3 @@
-/**
- * zivis_get_application — Get details of a specific application
- *
- * Maps to: GET /api/rt/applications/:id
- */
 import { z } from "zod";
 import { requireApplicationId } from "../resolve-application-id.js";
 import { sanitizeResponse } from "../sanitize.js";
@@ -80,4 +75,3 @@ export function createGetApplicationHandler(apiClient) {
         }
     };
 }
-//# sourceMappingURL=get-application.js.map

package/dist/tools/get-diagram.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_get_diagram — Get full diagram content
- *
- * Maps to: GET /api/diagrams/:id
- */
 import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 export declare const GET_DIAGRAM_NAME = "zivis_get_diagram";

package/dist/tools/get-diagram.js

@@ -1,8 +1,3 @@
-/**
- * zivis_get_diagram — Get full diagram content
- *
- * Maps to: GET /api/diagrams/:id
- */
 import { z } from "zod";
 import { sanitizeResponse } from "../sanitize.js";
 export const GET_DIAGRAM_NAME = "zivis_get_diagram";
@@ -23,7 +18,6 @@ export function createGetDiagramHandler(apiClient) {
         try {
             const data = await apiClient.get(`/api/diagrams/${params.diagram_id}`);
             const sanitized = sanitizeResponse(data);
-            // Format nodes with clear structure
             const nodes = Array.isArray(sanitized.nodes)
                 ? sanitized.nodes.map((n) => ({
                     node_id: n.id,
@@ -43,7 +37,6 @@ export function createGetDiagramHandler(apiClient) {
                     linked_evidence_ids: n.linkedEvidenceIds || [],
                 }))
                 : [];
-            // Format connections
             const connections = Array.isArray(sanitized.connections)
                 ? sanitized.connections.map((c) => ({
                     connection_id: c.id,
@@ -56,7 +49,6 @@ export function createGetDiagramHandler(apiClient) {
                     metadata: c.metadata || null,
                 }))
                 : [];
-            // Format boundaries
             const boundaries = Array.isArray(sanitized.boundaries)
                 ? sanitized.boundaries.map((b) => ({
                     boundary_id: b.id,
@@ -69,7 +61,6 @@ export function createGetDiagramHandler(apiClient) {
                     height: b.height,
                 }))
                 : [];
-            // Extract linked entity IDs
             const linkedThreatModelIds = Array.isArray(sanitized.threatModelLinks)
                 ? sanitized.threatModelLinks.map((l) => l.threatModelId)
                 : [];
@@ -79,7 +70,7 @@ export function createGetDiagramHandler(apiClient) {
                 description: sanitized.description || null,
                 diagram_type: sanitized.diagramType,
                 content_type: sanitized.contentType,
-                content: sanitized.content || null, // Mermaid source; null for canvas-type diagrams
+                content: sanitized.content || null,
                 source_type: sanitized.sourceType,
                 created_at: sanitized.createdAt,
                 updated_at: sanitized.updatedAt,
@@ -106,4 +97,3 @@ export function createGetDiagramHandler(apiClient) {
         }
     };
 }
-//# sourceMappingURL=get-diagram.js.map

package/dist/tools/get-document.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_get_document — Fetch a document by ID, including its full markdown content.
- *
- * Maps to: GET /api/documents/:id
- */
 import { z } from "zod";
 import type { ApiClient } from "../api-client.js";
 export declare const GET_DOCUMENT_NAME = "zivis_get_document";

package/dist/tools/get-document.js

@@ -1,8 +1,3 @@
-/**
- * zivis_get_document — Fetch a document by ID, including its full markdown content.
- *
- * Maps to: GET /api/documents/:id
- */
 import { z } from "zod";
 import { sanitizeResponse } from "../sanitize.js";
 export const GET_DOCUMENT_NAME = "zivis_get_document";
@@ -40,4 +35,3 @@ export function createGetDocumentHandler(apiClient) {
         }
     };
 }
-//# sourceMappingURL=get-document.js.map

package/dist/tools/get-oss-zat.d.ts

@@ -1,8 +1,3 @@
-/**
- * zivis_get_oss_zat — Get the signed attestation token (ZAT) for a GitHub repo
- *
- * Maps to: GET /api/oss-trust/repos/:owner/:repo/zat (public, no auth required)
- */
 import { z } from "zod";
 import type { ZivisConfig } from "../types.js";
 export declare const GET_OSS_ZAT_NAME = "zivis_get_oss_zat";

package/dist/tools/get-oss-zat.js

@@ -1,8 +1,3 @@
-/**
- * zivis_get_oss_zat — Get the signed attestation token (ZAT) for a GitHub repo
- *
- * Maps to: GET /api/oss-trust/repos/:owner/:repo/zat (public, no auth required)
- */
 import { z } from "zod";
 export const GET_OSS_ZAT_NAME = "zivis_get_oss_zat";
 export const GET_OSS_ZAT_DESCRIPTION = `Get the ZIVIS Attestation Token (ZAT) for a GitHub repository — a cryptographically signed, machine-verifiable supply chain credential.
@@ -32,7 +27,6 @@ export const GET_OSS_ZAT_SCHEMA = {
         .string()
         .describe("GitHub repo URL (https://github.com/owner/repo) or owner/repo string"),
 };
-/** Parse GitHub URL or owner/repo into components */
 function parseRepo(input) {
     const trimmed = input.trim();
     const urlMatch = trimmed.match(/^https?:\/\/(?:www\.)?github\.com\/([a-zA-Z0-9._-]+)\/([a-zA-Z0-9._-]+)/);
@@ -102,4 +96,3 @@ export function createGetOssZatHandler(config) {
         }
     };
 }
-//# sourceMappingURL=get-oss-zat.js.map

package/dist/tools/get-signal.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+export declare const GET_SIGNAL_NAME = "zivis_get_signal";
+export declare const GET_SIGNAL_DESCRIPTION = "Get full detail on a single Signal by its id.\n\nReturns the qualified narrative \u2014 description, mitigation, attack-chain context, taxonomy (STRIDE / ATPS layer / MITRE / OWASP / compliance mappings), detected safeguards and what breaks them, and the polymorphic source-artifact reference for drilling into the native subsystem.\n\nPass `signal_id` from a `zivis_list_signals` response.\n\nSECURITY: Display-shaped output only. No raw graph data.";
+export declare const GET_SIGNAL_SCHEMA: {
+    application_id: z.ZodOptional<z.ZodString>;
+    signal_id: z.ZodString;
+};
+export declare function createGetSignalHandler(apiClient: ApiClient): (params: {
+    application_id?: string;
+    signal_id: string;
+}) => Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/tools/get-signal.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { requireApplicationId } from "../resolve-application-id.js";
+import { sanitizeResponse } from "../sanitize.js";
+export const GET_SIGNAL_NAME = "zivis_get_signal";
+export const GET_SIGNAL_DESCRIPTION = `Get full detail on a single Signal by its id.
+
+Returns the qualified narrative — description, mitigation, attack-chain context, taxonomy (STRIDE / ATPS layer / MITRE / OWASP / compliance mappings), detected safeguards and what breaks them, and the polymorphic source-artifact reference for drilling into the native subsystem.
+
+Pass \`signal_id\` from a \`zivis_list_signals\` response.
+
+SECURITY: Display-shaped output only. No raw graph data.`;
+export const GET_SIGNAL_SCHEMA = {
+    application_id: z
+        .string()
+        .optional()
+        .describe("Application UUID. If omitted, uses applicationId from .zivis/project.json."),
+    signal_id: z
+        .string()
+        .describe("Opaque signal id (from zivis_list_signals)."),
+};
+export function createGetSignalHandler(apiClient) {
+    return async (params) => {
+        const req = requireApplicationId(params.application_id);
+        if (!req.ok) {
+            return {
+                content: [{ type: "text", text: `Error: ${req.message}` }],
+                isError: true,
+            };
+        }
+        if (!params.signal_id) {
+            return {
+                content: [{ type: "text", text: "Error: signal_id is required" }],
+                isError: true,
+            };
+        }
+        const path = `/api/apps/${req.id}/signals/${encodeURIComponent(params.signal_id)}`;
+        try {
+            const s = await apiClient.get(path);
+            const result = {
+                id: s.id,
+                source: s.source,
+                severity: s.severity,
+                status: s.status,
+                confidence: s.confidence,
+                title: s.title,
+                description: s.description,
+                category: s.category,
+                attack_chain: s.attackChain
+                    ? {
+                        name: s.attackChain.chainName,
+                        step: `${s.attackChain.stepIndex}/${s.attackChain.totalSteps}`,
+                    }
+                    : null,
+                taxonomy: s.taxonomy ?? null,
+                components: s.components?.map((c) => c.name) ?? [],
+                refs: s.refs,
+                recommended_action: s.recommendedAction,
+                safeguards: s.safeguards ?? null,
+                fingerprint: s.fingerprint,
+            };
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(sanitizeResponse(result), null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Failed to load signal";
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    };
+}

package/dist/tools/get-started.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ApiClient } from "../api-client.js";
+import type { ZivisConfig } from "../types.js";
+export declare const GET_STARTED_NAME = "zivis_get_started";
+export declare const GET_STARTED_DESCRIPTION = "Call this FIRST on any turn where the user asks about security, vulnerabilities, code review, deployment readiness, threat modeling, dependencies, or \"what should I do next.\" Idempotent and safe to call repeatedly \u2014 detects prior inspect runs and never re-inspects unnecessarily. Prefer this over calling zivis_inspect directly.\n\nUse this when the user says any of:\n- \"what should I do for security on this app\"\n- \"uhh, where do I start\"\n- \"is my app safe\" / \"is my chatbot safe\"\n- \"I need to do security stuff before launch\"\n- \"I have an audit / pen test / customer asking about security\"\n- \"check my dependencies / libraries / repos\"\n- \"how do I use ZIVIS\"\n- \"what can ZIVIS do for me\"\n\nThis tool inspects the current project state \u2014 binding, application, scans, findings \u2014\nAND if a recent 'zivis inspect' artifact exists for this repo, evaluates the local\nthreat library against it to surface architectural patterns ZIVIS thinks may apply\n(self-consistency without context isolation, late org filter, privilege separation, etc.).\nThe 'relevant_threats' field in the response is what makes this tool different from a\ngeneric security menu: ZIVIS is reading the user's actual codebase via the graph\nartifact and naming threats by their architectural shape.\n\nAlways speak to the user in threat-model language: components, flows, trust boundaries,\nattack scenarios. Even when they don't yet know those terms \u2014 that's how they learn.\n\nOutput is a structured JSON object. Present recommended_next_steps as a numbered list\nto the user, in order, and ask them to pick one. If relevant_threats is non-empty, lead\nwith that \u2014 it's the most concrete thing ZIVIS knows about their repo. Use the label\nand why fields verbatim; do not invent new steps. If the user is unsure which to pick,\nrecommend the item flagged in if_user_unsure.";
+export declare const GET_STARTED_SCHEMA: {
+    concern: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+};
+export declare function createGetStartedHandler(apiClient: ApiClient, _config: ZivisConfig): (params: {
+    concern?: string;
+    cwd?: string;
+}) => Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;