musonda 1.0.0

package/dist/plugins/mcp/mcpConfig.js

@@ -0,0 +1,326 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { MCP_SCHEMA_V1, } from './types.js';
+import { logger } from '../../utils/logger.js';
+export class McpConfigValidator {
+    /**
+     * Expands ${PLUGIN_ROOT} and ${PLUGIN_DATA} in a string value.
+     * Single-pass, non-recursive textual replacement.
+     */
+    static expandVariables(value, pluginRoot, pluginData) {
+        return value
+            .replaceAll('${PLUGIN_ROOT}', pluginRoot)
+            .replaceAll('${PLUGIN_DATA}', pluginData);
+    }
+    /**
+     * Validates top-level mcp.json document structure.
+     */
+    static validateTopLevel(data) {
+        const errors = [];
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            return { valid: false, errors: ['mcp.json must be a JSON object.'] };
+        }
+        const obj = data;
+        const allowedKeys = new Set(['$schema', 'mcpServers']);
+        // Check unknown top-level keys
+        for (const key of Object.keys(obj)) {
+            if (!allowedKeys.has(key)) {
+                errors.push(`Unknown top-level field "${key}" in mcp.json is not permitted.`);
+            }
+        }
+        // Required $schema
+        if (!obj.$schema || typeof obj.$schema !== 'string') {
+            errors.push('mcp.json missing required string property "$schema".');
+        }
+        else if (obj.$schema !== MCP_SCHEMA_V1) {
+            errors.push(`Unsupported $schema in mcp.json: "${obj.$schema}". Expected "${MCP_SCHEMA_V1}".`);
+        }
+        // Required mcpServers
+        if (obj.mcpServers === undefined || obj.mcpServers === null) {
+            errors.push('mcp.json missing required property "mcpServers".');
+        }
+        else if (typeof obj.mcpServers !== 'object' || Array.isArray(obj.mcpServers)) {
+            errors.push('"mcpServers" must be an object.');
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors };
+        }
+        return { valid: true, doc: obj, errors: [] };
+    }
+    /**
+     * Validates and resolves an individual server entry from mcpServers.
+     */
+    static validateServer(serverName, rawConfig, pluginName, pluginRoot, pluginData) {
+        const errors = [];
+        if (!rawConfig || typeof rawConfig !== 'object' || Array.isArray(rawConfig)) {
+            return { valid: false, errors: [`Server "${serverName}" configuration must be an object.`] };
+        }
+        const type = rawConfig.type;
+        if (type !== 'stdio' && type !== 'streamable-http' && type !== 'sse') {
+            return {
+                valid: false,
+                errors: [`Server "${serverName}" has unknown or missing type "${type}". Allowed: stdio, streamable-http, sse.`],
+            };
+        }
+        const resolvedRoot = path.resolve(pluginRoot);
+        const resolvedData = path.resolve(pluginData);
+        if (type === 'stdio') {
+            const allowedStdioFields = new Set(['type', 'command', 'args', 'env', 'cwd']);
+            for (const k of Object.keys(rawConfig)) {
+                if (!allowedStdioFields.has(k)) {
+                    errors.push(`Server "${serverName}" of type stdio contains disallowed property "${k}".`);
+                }
+            }
+            const command = rawConfig.command;
+            if (!command || typeof command !== 'string') {
+                errors.push(`Server "${serverName}" missing required string property "command".`);
+            }
+            else {
+                // Must be single token, bare executable or plugin-relative ./
+                if (command.includes(' ') && !command.startsWith('./')) {
+                    errors.push(`Server "${serverName}" command must be a single executable token, not a shell string.`);
+                }
+            }
+            // Check containment if plugin-relative
+            let resolvedCommand = command;
+            if (typeof command === 'string' && command.startsWith('./')) {
+                const cmdPath = path.resolve(resolvedRoot, command);
+                if (!cmdPath.startsWith(resolvedRoot)) {
+                    errors.push(`Server "${serverName}" command "${command}" escapes plugin root.`);
+                }
+                else {
+                    resolvedCommand = cmdPath;
+                }
+            }
+            // Validate env
+            let resolvedEnv = undefined;
+            if (rawConfig.env !== undefined) {
+                if (typeof rawConfig.env !== 'object' || rawConfig.env === null || Array.isArray(rawConfig.env)) {
+                    errors.push(`Server "${serverName}" "env" must be an object of strings.`);
+                }
+                else {
+                    resolvedEnv = {};
+                    for (const [k, v] of Object.entries(rawConfig.env)) {
+                        if (k.toUpperCase() === 'PLUGIN_ROOT' || k.toUpperCase() === 'PLUGIN_DATA') {
+                            errors.push(`Server "${serverName}" "env" must not contain reserved key "${k}".`);
+                        }
+                        else if (typeof v !== 'string') {
+                            errors.push(`Server "${serverName}" env["${k}"] must be a string.`);
+                        }
+                        else {
+                            resolvedEnv[k] = this.expandVariables(v, resolvedRoot, resolvedData);
+                        }
+                    }
+                }
+            }
+            // Validate args
+            let resolvedArgs = undefined;
+            if (rawConfig.args !== undefined) {
+                if (!Array.isArray(rawConfig.args) || rawConfig.args.some((a) => typeof a !== 'string')) {
+                    errors.push(`Server "${serverName}" "args" must be an array of strings.`);
+                }
+                else {
+                    resolvedArgs = rawConfig.args.map((a) => this.expandVariables(a, resolvedRoot, resolvedData));
+                }
+            }
+            // Validate cwd
+            let resolvedCwd = resolvedRoot;
+            if (rawConfig.cwd !== undefined) {
+                if (typeof rawConfig.cwd !== 'string') {
+                    errors.push(`Server "${serverName}" "cwd" must be a string.`);
+                }
+                else {
+                    const expandedCwd = this.expandVariables(rawConfig.cwd, resolvedRoot, resolvedData);
+                    if (rawConfig.cwd.startsWith('./')) {
+                        const cwdPath = path.resolve(resolvedRoot, rawConfig.cwd);
+                        if (!cwdPath.startsWith(resolvedRoot)) {
+                            errors.push(`Server "${serverName}" cwd "${rawConfig.cwd}" escapes plugin root.`);
+                        }
+                        resolvedCwd = cwdPath;
+                    }
+                    else if (rawConfig.cwd === '${PLUGIN_ROOT}' ||
+                        rawConfig.cwd.startsWith('${PLUGIN_ROOT}/') ||
+                        rawConfig.cwd.startsWith('${PLUGIN_ROOT}\\')) {
+                        const cwdPath = path.resolve(expandedCwd);
+                        if (!cwdPath.startsWith(resolvedRoot)) {
+                            errors.push(`Server "${serverName}" cwd escapes plugin root.`);
+                        }
+                        resolvedCwd = cwdPath;
+                    }
+                    else if (rawConfig.cwd === '${PLUGIN_DATA}' ||
+                        rawConfig.cwd.startsWith('${PLUGIN_DATA}/') ||
+                        rawConfig.cwd.startsWith('${PLUGIN_DATA}\\')) {
+                        const cwdPath = path.resolve(expandedCwd);
+                        if (!cwdPath.startsWith(resolvedData)) {
+                            errors.push(`Server "${serverName}" cwd escapes plugin data directory.`);
+                        }
+                        resolvedCwd = cwdPath;
+                    }
+                    else {
+                        errors.push(`Server "${serverName}" cwd must start with "./", "\${PLUGIN_ROOT}", or "\${PLUGIN_DATA}".`);
+                    }
+                }
+            }
+            if (errors.length > 0) {
+                return { valid: false, errors };
+            }
+            return {
+                valid: true,
+                server: {
+                    name: serverName,
+                    pluginName,
+                    config: rawConfig,
+                    resolvedCommand,
+                    resolvedArgs,
+                    resolvedEnv,
+                    resolvedCwd,
+                },
+                errors: [],
+            };
+        }
+        // Remote HTTP / SSE transports
+        const allowedHttpFields = new Set(['type', 'url', 'headers']);
+        for (const k of Object.keys(rawConfig)) {
+            if (!allowedHttpFields.has(k)) {
+                errors.push(`Server "${serverName}" of type ${type} contains disallowed property "${k}".`);
+            }
+        }
+        const urlStr = rawConfig.url;
+        if (!urlStr || typeof urlStr !== 'string') {
+            errors.push(`Server "${serverName}" missing required string property "url".`);
+        }
+        else {
+            try {
+                const parsedUrl = new URL(urlStr);
+                if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+                    errors.push(`Server "${serverName}" url protocol must be http: or https:.`);
+                }
+                if (parsedUrl.username || parsedUrl.password) {
+                    errors.push(`Server "${serverName}" url must not contain user information.`);
+                }
+                if (parsedUrl.hash) {
+                    errors.push(`Server "${serverName}" url must not contain a fragment.`);
+                }
+                const isLoopback = parsedUrl.hostname === 'localhost' ||
+                    parsedUrl.hostname === '127.0.0.1' ||
+                    parsedUrl.hostname === '::1';
+                if (parsedUrl.protocol === 'http:' && !isLoopback) {
+                    errors.push(`Server "${serverName}" non-loopback endpoints must use HTTPS.`);
+                }
+            }
+            catch (err) {
+                errors.push(`Server "${serverName}" has invalid URL: ${err.message}`);
+            }
+        }
+        // Validate headers
+        if (rawConfig.headers !== undefined) {
+            if (typeof rawConfig.headers !== 'object' ||
+                rawConfig.headers === null ||
+                Array.isArray(rawConfig.headers)) {
+                errors.push(`Server "${serverName}" "headers" must be an object of strings.`);
+            }
+            else {
+                const seenHeaders = new Set();
+                for (const [hk, hv] of Object.entries(rawConfig.headers)) {
+                    const lowerHk = hk.toLowerCase();
+                    if (seenHeaders.has(lowerHk)) {
+                        errors.push(`Server "${serverName}" contains duplicate header "${hk}".`);
+                    }
+                    seenHeaders.add(lowerHk);
+                    if (typeof hv !== 'string') {
+                        errors.push(`Server "${serverName}" header "${hk}" value must be a string.`);
+                    }
+                }
+            }
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors };
+        }
+        return {
+            valid: true,
+            server: {
+                name: serverName,
+                pluginName,
+                config: rawConfig,
+            },
+            errors: [],
+        };
+    }
+    /**
+     * Discovers and parses mcp.json from a plugin directory.
+     */
+    static loadFromDirectory(pluginRootDir, pluginName, pluginDataDir) {
+        const resolvedRoot = path.resolve(pluginRootDir);
+        const mcpPath = path.join(resolvedRoot, 'mcp.json');
+        const result = {
+            valid: true,
+            servers: [],
+            errors: [],
+            warnings: [],
+        };
+        if (!fs.existsSync(mcpPath)) {
+            // Optional component
+            return result;
+        }
+        // Check containment
+        const resolvedMcpPath = path.resolve(mcpPath);
+        if (!resolvedMcpPath.startsWith(resolvedRoot)) {
+            result.valid = false;
+            result.errors.push(`mcp.json path escapes plugin root.`);
+            return result;
+        }
+        let stat;
+        try {
+            stat = fs.statSync(resolvedMcpPath);
+        }
+        catch (err) {
+            result.valid = false;
+            result.errors.push(`Failed to stat mcp.json: ${err.message}`);
+            return result;
+        }
+        if (!stat.isFile()) {
+            result.valid = false;
+            result.errors.push(`Fixed component location "mcp.json" exists but is not a regular file.`);
+            return result;
+        }
+        let fileContent;
+        try {
+            fileContent = fs.readFileSync(resolvedMcpPath, 'utf8');
+        }
+        catch (err) {
+            result.valid = false;
+            result.errors.push(`Failed to read mcp.json: ${err.message}`);
+            return result;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(fileContent);
+        }
+        catch (err) {
+            result.valid = false;
+            result.errors.push(`mcp.json is not valid JSON: ${err.message}`);
+            return result;
+        }
+        // Top-level validation
+        const topLevelCheck = this.validateTopLevel(parsed);
+        if (!topLevelCheck.valid) {
+            result.valid = false;
+            result.errors.push(...topLevelCheck.errors);
+            return result;
+        }
+        const doc = topLevelCheck.doc;
+        // Validate each server entry independently (narrow failure boundary)
+        for (const [sName, sCfg] of Object.entries(doc.mcpServers)) {
+            const serverCheck = this.validateServer(sName, sCfg, pluginName, resolvedRoot, pluginDataDir);
+            if (!serverCheck.valid) {
+                logger.warn(`[Plugin: ${pluginName}] Invalid MCP server "${sName}": ${serverCheck.errors.join('; ')}`);
+                result.warnings.push(`MCP server "${sName}" is invalid: ${serverCheck.errors.join('; ')}`);
+            }
+            else {
+                result.servers.push(serverCheck.server);
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=mcpConfig.js.map

package/dist/plugins/mcp/mcpConfig.js.map

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

package/dist/plugins/mcp/types.d.ts

@@ -0,0 +1,48 @@
+export declare const MCP_SCHEMA_V1 = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export interface McpStdioConfig {
+    type: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export interface McpHttpConfig {
+    type: 'streamable-http';
+    url: string;
+    headers?: Record<string, string>;
+}
+export interface McpSseConfig {
+    type: 'sse';
+    url: string;
+    headers?: Record<string, string>;
+}
+export type McpServerConfig = McpStdioConfig | McpHttpConfig | McpSseConfig;
+export interface McpDocument {
+    $schema: string;
+    mcpServers: Record<string, McpServerConfig>;
+    [key: string]: any;
+}
+export interface McpToolSchema {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, any>;
+        required?: string[];
+        [key: string]: any;
+    };
+}
+export interface McpValidationResult {
+    valid: boolean;
+    doc?: McpDocument;
+    errors: string[];
+}
+export interface ResolvedMcpServer {
+    name: string;
+    pluginName: string;
+    config: McpServerConfig;
+    resolvedCwd?: string;
+    resolvedCommand?: string;
+    resolvedArgs?: string[];
+    resolvedEnv?: Record<string, string>;
+}

package/dist/plugins/mcp/types.js

@@ -0,0 +1,2 @@
+export const MCP_SCHEMA_V1 = 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json';
+//# sourceMappingURL=types.js.map

package/dist/plugins/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/plugins/mcp/types.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,aAAa,GAAG,yDAAyD,CAAC"}

package/dist/plugins/pluginManager.d.ts

@@ -0,0 +1,164 @@
+import { MusondaConfig } from '../config/types.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { PluginPackage, PluginManifest } from './types.js';
+import { AgentSkill } from './skills/types.js';
+import { McpBridge } from './mcp/mcpBridge.js';
+export declare class PluginManager {
+    private config;
+    private plugins;
+    private skills;
+    private mcpBridge;
+    private isLoaded;
+    constructor(config: MusondaConfig);
+    getAllSkills(): AgentSkill[];
+    getAllPlugins(): PluginPackage[];
+    getMcpBridge(): McpBridge;
+    /**
+     * Discovers and loads all plugins from configured plugin directories.
+     * Registers skills and MCP tools into Musonda's ToolRegistry.
+     */
+    loadAll(toolRegistry: ToolRegistry): Promise<void>;
+    /**
+     * Loads a single plugin from a directory.
+     */
+    loadPluginFromDirectory(pluginDir: string, baseDataDir: string, disabledSet: Set<string>, toolRegistry: ToolRegistry): Promise<PluginPackage | null>;
+    /**
+     * Unloads a plugin from runtime: terminates its MCP servers, removes its bridged tools and skills.
+     */
+    unloadPlugin(pluginName: string, toolRegistry?: ToolRegistry): Promise<boolean>;
+    /**
+     * Reloads a specific plugin from disk into the live runtime.
+     */
+    reloadPlugin(pluginName: string, toolRegistry: ToolRegistry): Promise<PluginPackage | null>;
+    /**
+     * Reloads all plugins from configured directories without shutting down the gateway.
+     */
+    reloadAll(toolRegistry: ToolRegistry): Promise<{
+        loaded: number;
+        skills: number;
+        mcpServers: number;
+    }>;
+    /**
+     * Scaffolds a new plugin on disk with valid manifest, optional skills, and optional MCP servers,
+     * then immediately activates it in the live runtime.
+     */
+    createAndLoadPlugin(params: {
+        name: string;
+        description: string;
+        version?: string;
+        author?: {
+            name: string;
+            email?: string;
+        };
+        skills?: Array<{
+            name: string;
+            description: string;
+            content: string;
+            scripts?: Array<{
+                filename: string;
+                content: string;
+            }>;
+        }>;
+        mcp?: Record<string, any>;
+        targetDir?: string;
+    }, toolRegistry: ToolRegistry): Promise<{
+        success: boolean;
+        plugin?: PluginPackage;
+        error?: string;
+        skillsLoaded: number;
+        toolsRegistered: string[];
+    }>;
+    /**
+     * Installs an Agent Plugin from a local directory path, Git repository URL (e.g. GitHub), or npm package,
+     * validates its specification conformance (https://agent-plugins.org), installs any package dependencies,
+     * and immediately activates it in the live Musonda Gateway runtime without restarting the server.
+     */
+    installPlugin(params: {
+        source: string;
+        name?: string;
+        installDependencies?: boolean;
+        targetDir?: string;
+    }, toolRegistry: ToolRegistry): Promise<{
+        success: boolean;
+        plugin?: PluginPackage;
+        error?: string;
+        skillsLoaded: number;
+        toolsRegistered: string[];
+        installedPath?: string;
+    }>;
+    /**
+     * Unloads and uninstalls an Agent Plugin: stops its MCP servers, removes bridged tools and skills
+     * from runtime, optionally deletes its files from disk, and optionally purges its persistent data directory.
+     */
+    removePlugin(params: {
+        pluginName: string;
+        deleteFiles?: boolean;
+        purgeData?: boolean;
+    }, toolRegistry?: ToolRegistry): Promise<{
+        success: boolean;
+        error?: string;
+        pluginName: string;
+        unloaded: boolean;
+        deletedFiles: boolean;
+        purgedData: boolean;
+        skillsRemoved: string[];
+        toolsUnregistered: string[];
+    }>;
+    /**
+     * Discovers Agent Plugins locally on disk and across the ecosystem (official repositories, GitHub, npm).
+     */
+    findPlugins(params?: {
+        query?: string;
+        source?: 'all' | 'local' | 'remote';
+    }): Promise<{
+        query?: string;
+        totalFound: number;
+        local: Array<{
+            name: string;
+            version?: string;
+            description?: string;
+            isLoaded: boolean;
+            path: string;
+            skills: string[];
+            mcpServers: string[];
+        }>;
+        remote: Array<{
+            name: string;
+            description?: string;
+            repository: string;
+            url?: string;
+            author?: string;
+            keywords?: string[];
+            official?: boolean;
+            isInstalled: boolean;
+        }>;
+    }>;
+    /**
+     * Returns detailed inspection information for a specific plugin.
+     */
+    getPluginInfo(pluginNameOrPath: string): {
+        found: boolean;
+        isLoaded: boolean;
+        manifest?: PluginManifest;
+        rootDir?: string;
+        dataDir?: string;
+        skills: Array<{
+            name: string;
+            description: string;
+            instructionsSummary?: string;
+        }>;
+        mcpServers: Array<{
+            name: string;
+            type: string;
+            command?: string;
+            url?: string;
+            tools?: string[];
+        }>;
+        activeTools?: string[];
+        error?: string;
+    };
+    /**
+     * Shuts down all active plugin resources (MCP subprocesses).
+     */
+    shutdownAll(): Promise<void>;
+}