@skilljack/mcp 0.7.0 → 0.7.1

package/dist/skill-config-tool.js

@@ -0,0 +1,495 @@
+/**
+ * MCP App tool registration for skill directory configuration.
+ *
+ * Registers:
+ * - skill-config: Opens the configuration UI
+ * - skill-config-add-directory: Adds a directory (UI-only)
+ * - skill-config-remove-directory: Removes a directory (UI-only)
+ */
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { getAllDirectoriesWithSources, getConfigState, addDirectoryToConfig, removeDirectoryFromConfig, getGitHubAllowedOrgs, getGitHubAllowedUsers, addGitHubAllowedOrg, removeGitHubAllowedOrg, getStaticModeFromConfig, setStaticModeInConfig, } from "./skill-config.js";
+import { isGitHubUrl, parseGitHubUrl } from "./github-config.js";
+/**
+ * Resource URI for the skill-config UI.
+ */
+const RESOURCE_URI = "ui://skill-config/mcp-app.html";
+/**
+ * Get the path to the bundled UI HTML file.
+ */
+function getUIPath() {
+    // In production (dist/), the UI is at dist/ui/mcp-app.html
+    // In development, check multiple locations
+    const possiblePaths = [
+        // From dist/skill-config-tool.js
+        path.join(import.meta.dirname, "ui", "mcp-app.html"),
+        // From src/ during development
+        path.join(import.meta.dirname, "..", "dist", "ui", "mcp-app.html"),
+    ];
+    for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    throw new Error(`UI file not found. Tried: ${possiblePaths.join(", ")}. ` +
+        "Run 'npm run build:ui' to build the UI.");
+}
+/**
+ * Schema shape for add-directory tool input.
+ */
+const AddDirectoryInputSchema = {
+    directory: z.string().describe("Absolute path to the skills directory to add"),
+};
+/**
+ * Schema shape for remove-directory tool input.
+ */
+const RemoveDirectoryInputSchema = {
+    directory: z.string().describe("Absolute path to the skills directory to remove"),
+};
+/**
+ * Register skill-config MCP App tools and resource.
+ *
+ * @param server - The MCP server instance
+ * @param skillState - Shared skill state for getting skill counts
+ * @param onDirectoriesChanged - Callback when directories are added/removed
+ */
+export function registerSkillConfigTool(server, skillState, onDirectoriesChanged) {
+    /**
+     * Get directory info with skill counts from skillState.
+     */
+    function getDirectoriesWithCounts() {
+        const dirs = getAllDirectoriesWithSources();
+        // Count skills per directory
+        for (const dir of dirs) {
+            let count = 0;
+            if (isGitHubUrl(dir.path)) {
+                // For GitHub directories, match by owner/repo from skill source
+                try {
+                    const spec = parseGitHubUrl(dir.path);
+                    for (const skill of skillState.skillMap.values()) {
+                        if (skill.source.type === "github" &&
+                            skill.source.owner?.toLowerCase() === spec.owner.toLowerCase() &&
+                            skill.source.repo?.toLowerCase() === spec.repo.toLowerCase()) {
+                            count++;
+                        }
+                    }
+                }
+                catch {
+                    // Invalid GitHub URL, count stays 0
+                }
+            }
+            else {
+                // For local directories, match by path prefix
+                for (const skill of skillState.skillMap.values()) {
+                    const skillDir = path.dirname(skill.path);
+                    if (skillDir.startsWith(dir.path)) {
+                        count++;
+                    }
+                }
+            }
+            dir.skillCount = count;
+        }
+        return dirs;
+    }
+    // Main config tool - opens UI
+    registerAppTool(server, "skill-config", {
+        title: "Configure Skills",
+        description: "Open the skills directory configuration UI. " +
+            "Use when user wants to configure, add, or remove skill directories.",
+        inputSchema: {},
+        outputSchema: {
+            directories: z.array(z.object({
+                path: z.string(),
+                source: z.string(),
+                type: z.string(),
+                valid: z.boolean(),
+                allowed: z.boolean(),
+                skillCount: z.number().optional(),
+            })),
+            activeSource: z.string(),
+            isOverridden: z.boolean(),
+            staticMode: z.boolean(),
+            allowedOrgs: z.array(z.string()),
+            allowedUsers: z.array(z.string()),
+        },
+        _meta: { ui: { resourceUri: RESOURCE_URI } },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const configState = getConfigState();
+        const directories = getDirectoriesWithCounts();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Skills configuration UI opened.",
+                },
+            ],
+            structuredContent: {
+                directories,
+                activeSource: configState.activeSource,
+                isOverridden: configState.isOverridden,
+                staticMode: getStaticModeFromConfig(),
+                allowedOrgs: getGitHubAllowedOrgs(),
+                allowedUsers: getGitHubAllowedUsers(),
+            },
+        };
+    });
+    // Add directory tool (UI-only, hidden from model)
+    registerAppTool(server, "skill-config-add-directory", {
+        title: "Add Skills Directory",
+        description: "Add a skills directory to the configuration.",
+        inputSchema: AddDirectoryInputSchema,
+        outputSchema: {
+            success: z.boolean(),
+            directories: z.array(z.object({
+                path: z.string(),
+                source: z.string(),
+                type: z.string(),
+                valid: z.boolean(),
+                allowed: z.boolean(),
+                skillCount: z.number().optional(),
+            })).optional(),
+            activeSource: z.string().optional(),
+            isOverridden: z.boolean().optional(),
+            error: z.string().optional(),
+        },
+        _meta: {
+            ui: {
+                resourceUri: RESOURCE_URI,
+                visibility: ["app"], // Hidden from model, UI can call it
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const { directory } = args;
+        try {
+            addDirectoryToConfig(directory);
+            onDirectoriesChanged();
+            const directories = getDirectoriesWithCounts();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Added directory: ${directory}`,
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    directories,
+                    activeSource: getConfigState().activeSource,
+                    isOverridden: getConfigState().isOverridden,
+                    staticMode: getStaticModeFromConfig(),
+                    allowedOrgs: getGitHubAllowedOrgs(),
+                    allowedUsers: getGitHubAllowedUsers(),
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to add directory: ${message}`,
+                    },
+                ],
+                structuredContent: {
+                    success: false,
+                    error: message,
+                },
+                isError: true,
+            };
+        }
+    });
+    // Remove directory tool (UI-only, hidden from model)
+    registerAppTool(server, "skill-config-remove-directory", {
+        title: "Remove Skills Directory",
+        description: "Remove a skills directory from the configuration.",
+        inputSchema: RemoveDirectoryInputSchema,
+        outputSchema: {
+            success: z.boolean(),
+            directories: z.array(z.object({
+                path: z.string(),
+                source: z.string(),
+                type: z.string(),
+                valid: z.boolean(),
+                allowed: z.boolean(),
+                skillCount: z.number().optional(),
+            })).optional(),
+            activeSource: z.string().optional(),
+            isOverridden: z.boolean().optional(),
+            error: z.string().optional(),
+        },
+        _meta: {
+            ui: {
+                resourceUri: RESOURCE_URI,
+                visibility: ["app"], // Hidden from model, UI can call it
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const { directory } = args;
+        try {
+            removeDirectoryFromConfig(directory);
+            onDirectoriesChanged();
+            const directories = getDirectoriesWithCounts();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Removed directory: ${directory}`,
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    directories,
+                    activeSource: getConfigState().activeSource,
+                    isOverridden: getConfigState().isOverridden,
+                    staticMode: getStaticModeFromConfig(),
+                    allowedOrgs: getGitHubAllowedOrgs(),
+                    allowedUsers: getGitHubAllowedUsers(),
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to remove directory: ${message}`,
+                    },
+                ],
+                structuredContent: {
+                    success: false,
+                    error: message,
+                },
+                isError: true,
+            };
+        }
+    });
+    // Add allowed org tool (UI-only)
+    registerAppTool(server, "skill-config-add-allowed-org", {
+        title: "Add Allowed GitHub Org",
+        description: "Add a GitHub organization to the allowed list for skill repos.",
+        inputSchema: {
+            org: z.string().describe("GitHub organization name to allow"),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            allowedOrgs: z.array(z.string()),
+            error: z.string().optional(),
+        },
+        _meta: {
+            ui: {
+                resourceUri: RESOURCE_URI,
+                visibility: ["app"],
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const { org } = args;
+        try {
+            addGitHubAllowedOrg(org);
+            onDirectoriesChanged(); // Trigger GitHub resync
+            // Return full state so UI can update directories' allowed status
+            const directories = getDirectoriesWithCounts();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Added allowed org: ${org}`,
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    directories,
+                    activeSource: getConfigState().activeSource,
+                    isOverridden: getConfigState().isOverridden,
+                    staticMode: getStaticModeFromConfig(),
+                    allowedOrgs: getGitHubAllowedOrgs(),
+                    allowedUsers: getGitHubAllowedUsers(),
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to add allowed org: ${message}`,
+                    },
+                ],
+                structuredContent: {
+                    success: false,
+                    allowedOrgs: getGitHubAllowedOrgs(),
+                    error: message,
+                },
+                isError: true,
+            };
+        }
+    });
+    // Remove allowed org tool (UI-only)
+    registerAppTool(server, "skill-config-remove-allowed-org", {
+        title: "Remove Allowed GitHub Org",
+        description: "Remove a GitHub organization from the allowed list.",
+        inputSchema: {
+            org: z.string().describe("GitHub organization name to remove"),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            allowedOrgs: z.array(z.string()),
+            error: z.string().optional(),
+        },
+        _meta: {
+            ui: {
+                resourceUri: RESOURCE_URI,
+                visibility: ["app"],
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const { org } = args;
+        try {
+            removeGitHubAllowedOrg(org);
+            onDirectoriesChanged(); // Trigger GitHub resync
+            // Return full state so UI can update directories' allowed status
+            const directories = getDirectoriesWithCounts();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Removed allowed org: ${org}`,
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    directories,
+                    activeSource: getConfigState().activeSource,
+                    isOverridden: getConfigState().isOverridden,
+                    staticMode: getStaticModeFromConfig(),
+                    allowedOrgs: getGitHubAllowedOrgs(),
+                    allowedUsers: getGitHubAllowedUsers(),
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to remove allowed org: ${message}`,
+                    },
+                ],
+                structuredContent: {
+                    success: false,
+                    allowedOrgs: getGitHubAllowedOrgs(),
+                    error: message,
+                },
+                isError: true,
+            };
+        }
+    });
+    // Set static mode tool (UI-only, hidden from model)
+    registerAppTool(server, "skill-config-set-static-mode", {
+        title: "Set Static Mode",
+        description: "Enable or disable static mode (freezes skills list at startup).",
+        inputSchema: {
+            enabled: z.boolean().describe("Whether to enable static mode"),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            staticMode: z.boolean().optional(),
+            error: z.string().optional(),
+        },
+        _meta: {
+            ui: {
+                resourceUri: RESOURCE_URI,
+                visibility: ["app"], // Hidden from model, UI can call it
+            },
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const { enabled } = args;
+        try {
+            setStaticModeInConfig(enabled);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Static mode ${enabled ? "enabled" : "disabled"}. Restart server for changes to take effect.`,
+                    },
+                ],
+                structuredContent: {
+                    success: true,
+                    staticMode: enabled,
+                },
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to set static mode: ${message}`,
+                    },
+                ],
+                structuredContent: {
+                    success: false,
+                    error: message,
+                },
+                isError: true,
+            };
+        }
+    });
+    // Register the HTML UI resource
+    registerAppResource(server, RESOURCE_URI, RESOURCE_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+        const uiPath = getUIPath();
+        const html = await fsPromises.readFile(uiPath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: RESOURCE_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                },
+            ],
+        };
+    });
+}

package/dist/skill-config.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Configuration management for skill directories.
+ *
+ * Handles loading/saving skill directory configuration from:
+ * 1. CLI args (highest priority)
+ * 2. SKILLS_DIR environment variable
+ * 3. Config file (~/.skilljack/config.json)
+ *
+ * Supports both local directories and GitHub repository URLs.
+ */
+/**
+ * Invocation settings that can be overridden per skill.
+ */
+export interface SkillInvocationOverrides {
+    assistant?: boolean;
+    user?: boolean;
+}
+/**
+ * Configuration file schema.
+ */
+export interface SkillConfig {
+    skillDirectories: string[];
+    staticMode?: boolean;
+    skillInvocationOverrides?: Record<string, SkillInvocationOverrides>;
+    githubAllowedOrgs?: string[];
+    githubAllowedUsers?: string[];
+}
+/**
+ * Source of a skill directory configuration.
+ */
+export type DirectorySource = "cli" | "env" | "config";
+/**
+ * Type of skill source (local directory or GitHub repo).
+ */
+export type SourceType = "local" | "github";
+/**
+ * A skill directory with its source information.
+ */
+export interface DirectoryInfo {
+    path: string;
+    source: DirectorySource;
+    type: SourceType;
+    skillCount: number;
+    valid: boolean;
+    allowed: boolean;
+}
+/**
+ * Configuration state tracking active directories and their sources.
+ */
+export interface ConfigState {
+    /** All active directories with source info */
+    directories: DirectoryInfo[];
+    /** Which source is currently providing directories (cli > env > config) */
+    activeSource: DirectorySource;
+    /** Whether directories are overridden by CLI or env (config file edits won't take effect) */
+    isOverridden: boolean;
+}
+/**
+ * Get the platform-appropriate config directory path.
+ * Returns ~/.skilljack on Unix, %USERPROFILE%\.skilljack on Windows.
+ */
+export declare function getConfigDir(): string;
+/**
+ * Get the full path to the config file.
+ */
+export declare function getConfigPath(): string;
+/**
+ * Load config from the config file.
+ * Returns empty config if file doesn't exist.
+ */
+export declare function loadConfigFile(): SkillConfig;
+/**
+ * Save config to the config file.
+ */
+export declare function saveConfigFile(config: SkillConfig): void;
+/**
+ * Parse CLI arguments for skill directories.
+ * Returns resolved absolute paths for local dirs, unchanged for GitHub URLs.
+ */
+export declare function parseCLIArgs(): string[];
+/**
+ * Parse SKILLS_DIR environment variable.
+ * Returns resolved absolute paths for local dirs, unchanged for GitHub URLs.
+ */
+export declare function parseEnvVar(): string[];
+/**
+ * Get all skill directories with their source information.
+ * Priority: CLI args > env var > config file
+ */
+export declare function getConfigState(): ConfigState;
+/**
+ * Get skill directories from all sources combined.
+ * Used for the UI to show all configured directories.
+ */
+export declare function getAllDirectoriesWithSources(): DirectoryInfo[];
+/**
+ * Add a directory or GitHub URL to the config file.
+ * Does not affect CLI or env var configurations.
+ */
+export declare function addDirectoryToConfig(directory: string): void;
+/**
+ * Remove a directory or GitHub URL from the config file.
+ * Only removes from config file, not CLI or env var.
+ */
+export declare function removeDirectoryFromConfig(directory: string): void;
+/**
+ * Get only the active skill directories (respecting priority).
+ * This is what the server should use for skill discovery.
+ */
+export declare function getActiveDirectories(): string[];
+/**
+ * Get static mode setting from config file.
+ */
+export declare function getStaticModeFromConfig(): boolean;
+/**
+ * Set static mode setting in config file.
+ */
+export declare function setStaticModeInConfig(enabled: boolean): void;
+/**
+ * Get all skill invocation overrides from the config file.
+ */
+export declare function getSkillInvocationOverrides(): Record<string, SkillInvocationOverrides>;
+/**
+ * Set an invocation override for a skill.
+ * @param skillName - The name of the skill
+ * @param setting - Which setting to override ("assistant" or "user")
+ * @param value - The new value for the setting
+ */
+export declare function setSkillInvocationOverride(skillName: string, setting: "assistant" | "user", value: boolean): void;
+/**
+ * Clear an invocation override for a skill (revert to frontmatter default).
+ * @param skillName - The name of the skill
+ * @param setting - Which setting to clear (omit to clear both)
+ */
+export declare function clearSkillInvocationOverride(skillName: string, setting?: "assistant" | "user"): void;
+/**
+ * Get the GitHub allowed orgs from config file.
+ */
+export declare function getGitHubAllowedOrgs(): string[];
+/**
+ * Get the GitHub allowed users from config file.
+ */
+export declare function getGitHubAllowedUsers(): string[];
+/**
+ * Add a GitHub org to the allowed list.
+ * @param org - The org name to allow
+ */
+export declare function addGitHubAllowedOrg(org: string): void;
+/**
+ * Remove a GitHub org from the allowed list.
+ * @param org - The org name to remove
+ */
+export declare function removeGitHubAllowedOrg(org: string): void;
+/**
+ * Add a GitHub user to the allowed list.
+ * @param user - The user name to allow
+ */
+export declare function addGitHubAllowedUser(user: string): void;
+/**
+ * Remove a GitHub user from the allowed list.
+ * @param user - The user name to remove
+ */
+export declare function removeGitHubAllowedUser(user: string): void;