synapse-mcp 1.0.0

package/dist/utils/help.js

@@ -0,0 +1,259 @@
+/**
+ * Help Handler - Auto-generate documentation from Zod discriminated union schemas
+ *
+ * Provides schema introspection to generate help text for MCP tools.
+ * Supports schemas wrapped in z.preprocess() for backward compatibility
+ * with composite discriminator patterns.
+ *
+ * NOTE: This module accesses Zod internal implementation details (_def, options, etc.)
+ * which are not part of the public API. When upgrading Zod:
+ * 1. Run full test suite to verify help generation still works
+ * 2. Check Zod changelog for changes to internal structure
+ * 3. Update this module if internal structure changes
+ */
+/**
+ * Safely access _def from a Zod schema
+ */
+function getDef(schema) {
+    return schema._def ?? {};
+}
+/**
+ * Unwrap z.preprocess wrapper to access inner discriminated union schema
+ *
+ * In Zod 4.x, z.preprocess() creates a pipe with:
+ * - _def.type === 'pipe'
+ * - _def.out containing the inner schema
+ */
+function unwrapSchema(schema) {
+    const def = getDef(schema);
+    // Check if schema is wrapped in z.preprocess (Zod 4.x uses pipe internally)
+    if (def.type === "pipe" && def.out) {
+        return def.out;
+    }
+    // Zod 3.x compatibility: check for innerType
+    if (def.innerType) {
+        return def.innerType;
+    }
+    return schema;
+}
+/**
+ * Get the base type name from a potentially wrapped Zod schema
+ *
+ * Handles default(), optional(), nullable() wrapping to get the underlying type.
+ */
+function getBaseTypeName(schema) {
+    const def = getDef(schema);
+    // Handle wrapped types: default, optional, nullable, etc.
+    if (def.innerType) {
+        return getBaseTypeName(def.innerType);
+    }
+    // Handle union type
+    if (def.type === "union" && def.options) {
+        const types = def.options.map((opt) => getBaseTypeName(opt));
+        return types.join(" | ");
+    }
+    // Handle enum type
+    if (def.type === "enum" && def.values) {
+        return def.values.map((v) => `"${v}"`).join(" | ");
+    }
+    // Handle native enum
+    if (def.type === "enum" || def.type === "nativeEnum") {
+        return "enum";
+    }
+    // Return the base type
+    return def.type ?? "unknown";
+}
+/**
+ * Get default value from a schema if present
+ */
+function getDefaultValue(schema) {
+    const def = getDef(schema);
+    if (def.type === "default" && def.defaultValue !== undefined) {
+        try {
+            // defaultValue is a getter function in Zod 4.x
+            return typeof def.defaultValue === "function" ? def.defaultValue() : def.defaultValue;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get options from a discriminated union schema
+ */
+function getOptions(schema) {
+    // Try direct access (Zod 4.x)
+    const directOptions = schema.options;
+    if (directOptions) {
+        return directOptions;
+    }
+    // Try via _def
+    const def = getDef(schema);
+    return def.options;
+}
+/**
+ * Check if a schema is a nested discriminated union (has options but no shape)
+ */
+function isNestedDiscriminatedUnion(schema) {
+    const def = getDef(schema);
+    const hasOptions = !!getOptions(schema);
+    const hasShape = !!schema.shape;
+    return hasOptions && !hasShape && (def.type === 'discriminatedUnion' || def.type === 'union');
+}
+/**
+ * Extract help entries from a single ZodObject schema
+ */
+function extractObjectHelpEntry(option, prefix) {
+    // Access shape from ZodObject
+    const shape = option.shape;
+    if (!shape) {
+        return null;
+    }
+    // Find literal fields for discriminator
+    const literals = [];
+    for (const key of Object.keys(shape)) {
+        const fieldSchema = shape[key];
+        const fieldDef = getDef(fieldSchema);
+        // In Zod 4.x, literals use _def.values array
+        if (fieldDef.type === "literal" && fieldDef.values) {
+            literals.push({ key, value: fieldDef.values[0] });
+        }
+    }
+    if (literals.length === 0) {
+        return null;
+    }
+    // Build discriminator value: action or action:subaction
+    let discriminatorValue;
+    const actionLiteral = literals.find(l => l.key === 'action');
+    const subactionLiteral = literals.find(l => l.key === 'subaction');
+    if (subactionLiteral && actionLiteral) {
+        // Nested pattern: action:subaction (e.g., "zfs:pools")
+        discriminatorValue = `${actionLiteral.value}:${subactionLiteral.value}`;
+    }
+    else if (actionLiteral) {
+        discriminatorValue = actionLiteral.value;
+    }
+    else if (subactionLiteral) {
+        discriminatorValue = prefix ? `${prefix}:${subactionLiteral.value}` : subactionLiteral.value;
+    }
+    else {
+        discriminatorValue = literals[0].value;
+    }
+    // Extract parameters (excluding discriminator fields)
+    const parameters = Object.entries(shape)
+        .filter(([key]) => 
+    // Skip discriminator-related fields
+    key !== "action_subaction" && key !== "action" && key !== "subaction")
+        .map(([name, fieldSchema]) => {
+        return {
+            name,
+            type: getBaseTypeName(fieldSchema),
+            description: fieldSchema.description,
+            required: !fieldSchema.isOptional(),
+            default: getDefaultValue(fieldSchema)
+        };
+    });
+    return {
+        discriminator: discriminatorValue,
+        description: option.description ?? "",
+        parameters
+    };
+}
+/**
+ * Generate help documentation from discriminated union or union schema
+ *
+ * Handles:
+ * - Schemas wrapped in z.preprocess()
+ * - z.discriminatedUnion with composite discriminator (Flux)
+ * - z.union with nested z.discriminatedUnion (Scout)
+ *
+ * @param schema - A Zod discriminated union or union schema
+ * @param topic - Optional discriminator value to filter results
+ * @returns Array of help entries for matching actions
+ */
+export function generateHelp(schema, topic) {
+    // Unwrap z.preprocess if present
+    const actualSchema = unwrapSchema(schema);
+    // Access options from discriminated union or union
+    const options = getOptions(actualSchema);
+    if (!options || !Array.isArray(options)) {
+        throw new Error("Schema is not a discriminated union or union");
+    }
+    const entries = [];
+    for (const option of options) {
+        // Check if this option is a nested discriminated union (like zfs or logs in Scout)
+        if (isNestedDiscriminatedUnion(option)) {
+            const nestedOptions = getOptions(option);
+            if (nestedOptions) {
+                for (const nestedOption of nestedOptions) {
+                    const entry = extractObjectHelpEntry(nestedOption);
+                    if (entry) {
+                        entries.push(entry);
+                    }
+                }
+            }
+        }
+        else {
+            // Regular ZodObject option
+            const entry = extractObjectHelpEntry(option);
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+    }
+    // Filter by topic if provided
+    if (topic) {
+        return entries.filter((e) => e.discriminator === topic || e.discriminator.startsWith(topic + ':'));
+    }
+    return entries;
+}
+/**
+ * Format help entries as markdown
+ *
+ * @param entries - Array of help entries from generateHelp
+ * @returns Formatted markdown string
+ */
+export function formatHelpMarkdown(entries) {
+    if (entries.length === 0) {
+        return "No help available for the specified topic.";
+    }
+    return entries
+        .map((entry) => {
+        let md = `## ${entry.discriminator}\n\n`;
+        if (entry.description) {
+            md += `${entry.description}\n\n`;
+        }
+        if (entry.parameters.length > 0) {
+            md += "**Parameters:**\n\n";
+            entry.parameters.forEach((param) => {
+                const required = param.required ? " (required)" : " (optional)";
+                const defaultVal = param.default !== undefined ? `, default: ${JSON.stringify(param.default)}` : "";
+                md += `- **${param.name}** (${param.type}${required}${defaultVal})`;
+                if (param.description) {
+                    md += ` - ${param.description}`;
+                }
+                md += "\n";
+            });
+        }
+        return md;
+    })
+        .join("\n---\n\n");
+}
+/**
+ * Format help entries as JSON
+ *
+ * Uses 'action' as the key name in output for consistency with tool parameters.
+ *
+ * @param entries - Array of help entries from generateHelp
+ * @returns JSON string
+ */
+export function formatHelpJson(entries) {
+    const jsonEntries = entries.map((entry) => ({
+        action: entry.discriminator,
+        description: entry.description,
+        parameters: entry.parameters
+    }));
+    return JSON.stringify(jsonEntries, null, 2);
+}
+//# sourceMappingURL=help.js.map

package/dist/utils/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/utils/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4CH;;GAEG;AACH,SAAS,MAAM,CAAC,MAAoB;IAClC,OAAQ,MAA8C,CAAC,IAAI,IAAI,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,MAAoB;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAE3B,4EAA4E;IAC5E,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;QACnC,OAAO,GAAG,CAAC,GAAG,CAAC;IACjB,CAAC;IACD,6CAA6C;IAC7C,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,OAAO,GAAG,CAAC,SAAS,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,MAAoB;IAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAE3B,0DAA0D;IAC1D,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QAClB,OAAO,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACxC,CAAC;IAED,oBAAoB;IACpB,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7D,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,mBAAmB;IACnB,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACtC,OAAQ,GAAG,CAAC,MAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,CAAC;IAED,qBAAqB;IACrB,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QACrD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,uBAAuB;IACvB,OAAO,GAAG,CAAC,IAAI,IAAI,SAAS,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,MAAoB;IAC3C,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAE3B,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAC7D,IAAI,CAAC;YACH,+CAA+C;YAC/C,OAAO,OAAO,GAAG,CAAC,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC;QACxF,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,MAAoB;IACtC,8BAA8B;IAC9B,MAAM,aAAa,GAAI,MAAkD,CAAC,OAAO,CAAC;IAClF,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,eAAe;IACf,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,SAAS,0BAA0B,CAAC,MAAoB;IACtD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,CAAC,CAAE,MAAyC,CAAC,KAAK,CAAC;IACpE,OAAO,UAAU,IAAI,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,oBAAoB,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;AAChG,CAAC;AAED;;GAEG;AACH,SAAS,sBAAsB,CAAC,MAAoB,EAAE,MAAe;IACnE,8BAA8B;IAC9B,MAAM,KAAK,GAAI,MAA6D,CAAC,KAAK,CAAC;IAEnF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wCAAwC;IACxC,MAAM,QAAQ,GAAqC,EAAE,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,6CAA6C;QAC7C,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAW,EAAE,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wDAAwD;IACxD,IAAI,kBAA0B,CAAC;IAC/B,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC;IAC7D,MAAM,gBAAgB,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,WAAW,CAAC,CAAC;IAEnE,IAAI,gBAAgB,IAAI,aAAa,EAAE,CAAC;QACtC,uDAAuD;QACvD,kBAAkB,GAAG,GAAG,aAAa,CAAC,KAAK,IAAI,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAC1E,CAAC;SAAM,IAAI,aAAa,EAAE,CAAC;QACzB,kBAAkB,GAAG,aAAa,CAAC,KAAK,CAAC;IAC3C,CAAC;SAAM,IAAI,gBAAgB,EAAE,CAAC;QAC5B,kBAAkB,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,gBAAgB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC;IAC/F,CAAC;SAAM,CAAC;QACN,kBAAkB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACzC,CAAC;IAED,sDAAsD;IACtD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACrC,MAAM,CACL,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE;IACR,oCAAoC;IACpC,GAAG,KAAK,kBAAkB,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,WAAW,CACxE;SACA,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,EAAE;QAC3B,OAAO;YACL,IAAI;YACJ,IAAI,EAAE,eAAe,CAAC,WAAW,CAAC;YAClC,WAAW,EAAE,WAAW,CAAC,WAAW;YACpC,QAAQ,EAAE,CAAC,WAAW,CAAC,UAAU,EAAE;YACnC,OAAO,EAAE,eAAe,CAAC,WAAW,CAAC;SACtC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEL,OAAO;QACL,aAAa,EAAE,kBAAkB;QACjC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;QACrC,UAAU;KACX,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,MAAoB,EAAE,KAAc;IAC/D,iCAAiC;IACjC,MAAM,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAE1C,mDAAmD;IACnD,MAAM,OAAO,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IAEzC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,OAAO,GAAgB,EAAE,CAAC;IAEhC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,mFAAmF;QACnF,IAAI,0BAA0B,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,MAAM,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;YACzC,IAAI,aAAa,EAAE,CAAC;gBAClB,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;oBACzC,MAAM,KAAK,GAAG,sBAAsB,CAAC,YAAY,CAAC,CAAC;oBACnD,IAAI,KAAK,EAAE,CAAC;wBACV,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACtB,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,2BAA2B;YAC3B,MAAM,KAAK,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,KAAK,IAAI,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC;IACrG,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAoB;IACrD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,4CAA4C,CAAC;IACtD,CAAC;IAED,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,aAAa,MAAM,CAAC;QAEzC,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;YACtB,EAAE,IAAI,GAAG,KAAK,CAAC,WAAW,MAAM,CAAC;QACnC,CAAC;QAED,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,EAAE,IAAI,qBAAqB,CAAC;YAC5B,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;gBACjC,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC;gBAChE,MAAM,UAAU,GACd,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnF,EAAE,IAAI,OAAO,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,GAAG,QAAQ,GAAG,UAAU,GAAG,CAAC;gBACpE,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;oBACtB,EAAE,IAAI,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC;gBAClC,CAAC;gBACD,EAAE,IAAI,IAAI,CAAC;YACb,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;SACD,IAAI,CAAC,WAAW,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,OAAoB;IACjD,MAAM,WAAW,GAAoB,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,EAAE,KAAK,CAAC,aAAa;QAC3B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;KAC7B,CAAC,CAAC,CAAC;IAEJ,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC9C,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { validateSecurePath, HostSecurityError, validateHostFormat, escapeShellArg, isSystemPath } from "./path-security.js";
+export { generateHelp, formatHelpMarkdown, formatHelpJson } from "./help.js";
+export type { HelpEntry, HelpJsonEntry } from "./help.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+// Explicit named exports for better IDE support and tree-shaking
+export { validateSecurePath, HostSecurityError, validateHostFormat, escapeShellArg, isSystemPath } from "./path-security.js";
+export { generateHelp, formatHelpMarkdown, formatHelpJson } from "./help.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/utils/path-security.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Path Security Utilities
+ *
+ * SECURITY: Path Traversal Protection (CWE-22) & Command Injection Prevention (CWE-78)
+ *
+ * This module provides utilities to prevent directory traversal attacks
+ * in file path parameters. Used by docker.ts buildImage() to validate
+ * build context and Dockerfile paths.
+ *
+ * Also provides host validation to prevent command injection attacks
+ * when hostnames are used in SSH commands.
+ *
+ * CVSS 7.4 (HIGH) - Prevents attackers from using paths like:
+ * - ../../../etc/passwd
+ * - /valid/../../../etc/passwd
+ * - /path/./to/../../sensitive
+ *
+ * @see https://cwe.mitre.org/data/definitions/22.html
+ * @see https://cwe.mitre.org/data/definitions/78.html
+ */
+/**
+ * Security error for invalid host format
+ */
+export declare class HostSecurityError extends Error {
+    readonly host: string;
+    constructor(message: string, host: string);
+}
+/**
+ * Validates hostname format to prevent command injection
+ *
+ * @param host - Hostname to validate
+ * @throws HostSecurityError if host contains dangerous characters
+ */
+export declare function validateHostFormat(host: string): void;
+/**
+ * Escapes a string for safe use as a shell argument.
+ * Uses single quotes with proper escaping for embedded single quotes.
+ *
+ * @param arg - String to escape
+ * @returns Safely quoted string
+ */
+export declare function escapeShellArg(arg: string): string;
+/**
+ * Checks if a path is a system path that should be protected
+ *
+ * @param path - Path to check
+ * @returns true if path is in a system directory
+ */
+export declare function isSystemPath(path: string): boolean;
+/**
+ * Validates that a file path is safe from directory traversal attacks
+ *
+ * Rules:
+ * 1. Must be absolute path (starts with /)
+ * 2. Cannot contain .. (parent directory)
+ * 3. Cannot contain . as a path component (except in filenames)
+ * 4. Must contain only allowed characters: a-zA-Z0-9._-/
+ *
+ * @param path - The file path to validate
+ * @param paramName - Name of the parameter (for error messages)
+ * @throws Error if path contains directory traversal or is invalid
+ */
+export declare function validateSecurePath(path: string, paramName: string): void;
+//# sourceMappingURL=path-security.d.ts.map

package/dist/utils/path-security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-security.d.ts","sourceRoot":"","sources":["../../src/utils/path-security.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAGxB,IAAI,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAK/B;AAQD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlD;AAiBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAyCxE"}

package/dist/utils/path-security.js

@@ -0,0 +1,138 @@
+/**
+ * Path Security Utilities
+ *
+ * SECURITY: Path Traversal Protection (CWE-22) & Command Injection Prevention (CWE-78)
+ *
+ * This module provides utilities to prevent directory traversal attacks
+ * in file path parameters. Used by docker.ts buildImage() to validate
+ * build context and Dockerfile paths.
+ *
+ * Also provides host validation to prevent command injection attacks
+ * when hostnames are used in SSH commands.
+ *
+ * CVSS 7.4 (HIGH) - Prevents attackers from using paths like:
+ * - ../../../etc/passwd
+ * - /valid/../../../etc/passwd
+ * - /path/./to/../../sensitive
+ *
+ * @see https://cwe.mitre.org/data/definitions/22.html
+ * @see https://cwe.mitre.org/data/definitions/78.html
+ */
+import { resolve } from "node:path";
+/**
+ * Security error for invalid host format
+ */
+export class HostSecurityError extends Error {
+    host;
+    constructor(message, host) {
+        super(message);
+        this.host = host;
+        this.name = "HostSecurityError";
+    }
+}
+// Pattern for valid hostnames: alphanumeric, dots, hyphens, underscores
+const VALID_HOST_PATTERN = /^[a-zA-Z0-9._-]+$/;
+// Dangerous shell characters that could enable command injection
+const DANGEROUS_HOST_CHARS = /[;|$`&<>(){}[\]'"\\!#*?]/;
+/**
+ * Validates hostname format to prevent command injection
+ *
+ * @param host - Hostname to validate
+ * @throws HostSecurityError if host contains dangerous characters
+ */
+export function validateHostFormat(host) {
+    if (!host || host.length === 0) {
+        throw new HostSecurityError("Host cannot be empty", host);
+    }
+    if (DANGEROUS_HOST_CHARS.test(host)) {
+        throw new HostSecurityError(`Invalid characters in hostname: ${host.substring(0, 50)}`, host);
+    }
+    if (!VALID_HOST_PATTERN.test(host)) {
+        throw new HostSecurityError(`Invalid hostname format: ${host.substring(0, 50)}`, host);
+    }
+}
+/**
+ * Escapes a string for safe use as a shell argument.
+ * Uses single quotes with proper escaping for embedded single quotes.
+ *
+ * @param arg - String to escape
+ * @returns Safely quoted string
+ */
+export function escapeShellArg(arg) {
+    // Single quote the entire string, escaping any embedded single quotes
+    // by ending the quote, adding an escaped single quote, and starting a new quote
+    return "'" + arg.replace(/'/g, "'\\''") + "'";
+}
+/**
+ * System paths that should trigger warnings when used as transfer targets
+ */
+const SYSTEM_PATH_PREFIXES = [
+    "/etc",
+    "/bin",
+    "/sbin",
+    "/usr/bin",
+    "/usr/sbin",
+    "/lib",
+    "/lib64",
+    "/boot",
+    "/root"
+];
+/**
+ * Checks if a path is a system path that should be protected
+ *
+ * @param path - Path to check
+ * @returns true if path is in a system directory
+ */
+export function isSystemPath(path) {
+    return SYSTEM_PATH_PREFIXES.some((prefix) => path === prefix || path.startsWith(prefix + "/"));
+}
+/**
+ * Validates that a file path is safe from directory traversal attacks
+ *
+ * Rules:
+ * 1. Must be absolute path (starts with /)
+ * 2. Cannot contain .. (parent directory)
+ * 3. Cannot contain . as a path component (except in filenames)
+ * 4. Must contain only allowed characters: a-zA-Z0-9._-/
+ *
+ * @param path - The file path to validate
+ * @param paramName - Name of the parameter (for error messages)
+ * @throws Error if path contains directory traversal or is invalid
+ */
+export function validateSecurePath(path, paramName) {
+    // 1. Check for empty path
+    if (!path || path.length === 0) {
+        throw new Error(`${paramName}: Path cannot be empty`);
+    }
+    // 2. Character validation - only allow alphanumeric, dots, hyphens, underscores, forward slashes
+    if (!/^[a-zA-Z0-9._\-/]+$/.test(path)) {
+        throw new Error(`${paramName}: Invalid characters in path: ${path}`);
+    }
+    // 3. Split path into components and check for ".." traversal first
+    const components = path.split("/").filter((c) => c.length > 0);
+    for (const component of components) {
+        // Reject ".." (parent directory traversal) - check this first
+        if (component === "..") {
+            throw new Error(`${paramName}: directory traversal (..) not allowed in path: ${path}`);
+        }
+    }
+    // 4. Must be absolute path (starts with /) - checked after .. but before .
+    if (!path.startsWith("/")) {
+        throw new Error(`${paramName}: absolute path required, got: ${path}`);
+    }
+    // 5. Check for "." as standalone component (only in absolute paths)
+    for (const component of components) {
+        // Reject "." as standalone component (current directory)
+        // BUT allow dots in filenames like "file.txt" or "config.prod"
+        if (component === ".") {
+            throw new Error(`${paramName}: directory traversal (.) not allowed in path: ${path}`);
+        }
+    }
+    // 5. Additional safety check: resolve path and verify it doesn't traverse
+    // This catches cases like /valid/path/../../etc that might slip through
+    const resolved = resolve(path);
+    if (!resolved.startsWith(path.split("/")[1] ? `/${path.split("/")[1]}` : "/")) {
+        throw new Error(`${paramName}: Path resolution resulted in directory traversal: ${path}`);
+    }
+}
+//# sourceMappingURL=path-security.js.map

package/dist/utils/path-security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-security.js","sourceRoot":"","sources":["../../src/utils/path-security.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "synapse-mcp",
+  "version": "1.0.0",
+  "description": "MCP server providing Flux (Docker management) and Scout (SSH operations) tools for homelab infrastructure",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "synapse-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run \"**/*.integration.test.ts\"",
+    "test:bench": "vitest run src/schemas/unified.bench.test.ts",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": [
+    "mcp",
+    "synapse",
+    "flux",
+    "scout",
+    "homelab",
+    "docker",
+    "ssh",
+    "infrastructure",
+    "zfs",
+    "remote-management"
+  ],
+  "author": "Jacob Magar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jmagar/synapse-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jmagar/synapse-mcp/issues"
+  },
+  "homepage": "https://github.com/jmagar/synapse-mcp#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "dockerode": "^4.0.9",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
+    "node-ssh": "^13.2.1",
+    "zod": "^4.2.1",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/dockerode": "^3.3.47",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@types/ssh2": "^1.15.5",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.7.4",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.51.0",
+    "vitest": "^4.0.16"
+  }
+}