@skilljack/mcp 0.7.0 → 0.7.1

package/dist/index.js

@@ -6,58 +6,166 @@
  * Provides global skills with tools for progressive disclosure.
  *
  * Usage:
- *   skilljack-mcp /path/to/skills [/path2 ...]   # One or more directories
- *   SKILLS_DIR=/path/to/skills skilljack-mcp    # Single directory via env
- *   SKILLS_DIR=/path1,/path2 skilljack-mcp      # Multiple (comma-separated)
+ *   skilljack-mcp /path/to/skills [/path2 ...]           # Local directories
+ *   skilljack-mcp --static /path/to/skills               # Static mode (no file watching)
+ *   skilljack-mcp github.com/owner/repo                  # GitHub repository
+ *   skilljack-mcp /local github.com/owner/repo           # Mixed local + GitHub
+ *   SKILLS_DIR=/path,github.com/owner/repo skilljack-mcp # Via environment
+ *   SKILLJACK_STATIC=true skilljack-mcp                  # Static mode via env
+ *   (or configure local directories via the skill-config UI)
+ *
+ * Options:
+ *   --static  Freeze skills list at startup. Disables file watching and
+ *             tools/prompts listChanged notifications. Resource subscriptions
+ *             remain fully dynamic.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import chokidar from "chokidar";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { discoverSkills, createSkillMap } from "./skill-discovery.js";
+import { fileURLToPath } from "node:url";
+import { discoverSkills, createSkillMap, applyInvocationOverrides, DEFAULT_SKILL_SOURCE, BUNDLED_SKILL_SOURCE } from "./skill-discovery.js";
 import { registerSkillTool, getToolDescription } from "./skill-tool.js";
 import { registerSkillResources } from "./skill-resources.js";
+import { registerSkillPrompts, refreshPrompts } from "./skill-prompts.js";
 import { createSubscriptionManager, registerSubscriptionHandlers, refreshSubscriptions, } from "./subscriptions.js";
+import { getActiveDirectories, getSkillInvocationOverrides, getStaticModeFromConfig } from "./skill-config.js";
+import { registerSkillConfigTool } from "./skill-config-tool.js";
+import { registerSkillDisplayTool } from "./skill-display-tool.js";
+import { isGitHubUrl, parseGitHubUrl, isRepoAllowed, getGitHubConfig, getRepoCachePath, } from "./github-config.js";
+import { syncAllRepos } from "./github-sync.js";
+import { createPollingManager } from "./github-polling.js";
 /**
  * Subdirectories to check for skills within the configured directory.
  */
 const SKILL_SUBDIRS = [".claude/skills", "skills"];
 /**
- * Separator for multiple paths in SKILLS_DIR environment variable.
- * Comma works cross-platform (not valid in file paths on any OS).
+ * Get the path to bundled skills directory.
+ * Resolves relative to the compiled module location.
  */
-const PATH_LIST_SEPARATOR = ",";
+function getBundledSkillsDir() {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    // From dist/index.js, go up one level to package root, then into skills/
+    return path.resolve(currentDir, "..", "skills");
+}
 /**
- * Get the skills directories from command line args and/or environment.
- * Returns deduplicated, resolved paths.
+ * Build a directory-to-source map from current configuration.
+ * Maps both main directories and their standard subdirectories.
+ *
+ * @param localDirs - Local skill directories
+ * @param githubSpecs - GitHub repository specifications
+ * @param cacheDir - GitHub cache directory path
+ * @param bundledDir - Optional bundled skills directory
  */
-function getSkillsDirs() {
-    const dirs = [];
-    // Collect all non-flag command-line arguments (comma-separated supported)
-    const args = process.argv.slice(2);
-    for (const arg of args) {
-        if (!arg.startsWith("-")) {
-            const paths = arg
-                .split(PATH_LIST_SEPARATOR)
-                .map((p) => p.trim())
-                .filter((p) => p.length > 0)
-                .map((p) => path.resolve(p));
-            dirs.push(...paths);
+function buildDirectorySourceMap(localDirs, githubSpecs, cacheDir, bundledDir) {
+    const map = {};
+    // Map local directories
+    for (const dir of localDirs) {
+        const source = {
+            type: "local",
+            displayName: "Local",
+        };
+        map[dir] = source;
+        // Also map standard subdirectories
+        for (const subdir of SKILL_SUBDIRS) {
+            map[path.join(dir, subdir)] = source;
+        }
+    }
+    // Map GitHub cache directories
+    for (const spec of githubSpecs) {
+        const cachePath = getRepoCachePath(spec, cacheDir);
+        const source = {
+            type: "github",
+            displayName: `${spec.owner}/${spec.repo}`,
+            owner: spec.owner,
+            repo: spec.repo,
+        };
+        map[cachePath] = source;
+        // Also map standard subdirectories
+        for (const subdir of SKILL_SUBDIRS) {
+            map[path.join(cachePath, subdir)] = source;
         }
     }
-    // Also check environment variable (comma-separated supported)
-    const envDir = process.env.SKILLS_DIR;
-    if (envDir) {
-        const envPaths = envDir
-            .split(PATH_LIST_SEPARATOR)
-            .map((p) => p.trim())
-            .filter((p) => p.length > 0)
-            .map((p) => path.resolve(p));
-        dirs.push(...envPaths);
+    // Map bundled skills directory
+    if (bundledDir) {
+        map[bundledDir] = BUNDLED_SKILL_SOURCE;
+        // Also map standard subdirectories
+        for (const subdir of SKILL_SUBDIRS) {
+            map[path.join(bundledDir, subdir)] = BUNDLED_SKILL_SOURCE;
+        }
     }
-    // Deduplicate by resolved path
-    return [...new Set(dirs)];
+    return map;
+}
+/**
+ * Current skill directories (mutable to support UI-driven changes).
+ * This includes both local directories and GitHub cache directories.
+ */
+let currentSkillsDirs = [];
+/**
+ * GitHub specs that are currently being polled.
+ */
+let currentGithubSpecs = [];
+/**
+ * Current directory-to-source map for skill discovery.
+ * Maps directory paths to their source info (local or GitHub).
+ */
+let currentSourceMap = {};
+/**
+ * Check if static mode is enabled.
+ * Static mode freezes the skills list at startup - no file watching,
+ * no listChanged notifications for tools/prompts.
+ * Priority: CLI flag > env var > config file
+ */
+function getStaticMode() {
+    // Check CLI flag (highest priority)
+    const args = process.argv.slice(2);
+    if (args.includes("--static")) {
+        return true;
+    }
+    // Check environment variable
+    const envValue = process.env.SKILLJACK_STATIC?.toLowerCase();
+    if (envValue === "true" || envValue === "1" || envValue === "yes") {
+        return true;
+    }
+    // Check config file (lowest priority)
+    return getStaticModeFromConfig();
+}
+/**
+ * Classify paths as local directories or GitHub repositories.
+ * GitHub URLs are detected by checking for "github.com" in the path.
+ */
+function classifyPaths(paths) {
+    const localDirs = [];
+    const githubSpecs = [];
+    for (const p of paths) {
+        if (isGitHubUrl(p)) {
+            try {
+                const spec = parseGitHubUrl(p);
+                githubSpecs.push(spec);
+            }
+            catch (error) {
+                console.error(`Warning: Invalid GitHub URL "${p}": ${error}`);
+            }
+        }
+        else {
+            // Local directory - resolve the path
+            localDirs.push(path.resolve(p));
+        }
+    }
+    // Deduplicate local dirs
+    const uniqueLocalDirs = [...new Set(localDirs)];
+    // Deduplicate GitHub specs by owner/repo
+    const seenRepos = new Set();
+    const uniqueGithubSpecs = githubSpecs.filter((spec) => {
+        const key = `${spec.owner}/${spec.repo}`;
+        if (seenRepos.has(key)) {
+            return false;
+        }
+        seenRepos.add(key);
+        return true;
+    });
+    return { localDirs: uniqueLocalDirs, githubSpecs: uniqueGithubSpecs };
 }
 /**
  * Shared state for skill management.
@@ -70,8 +178,11 @@ const skillState = {
  * Discover skills from multiple configured directories.
  * Each directory is checked along with its standard subdirectories.
  * Handles duplicate skill names by keeping first occurrence.
+ *
+ * @param skillsDirs - The skill directories to scan
+ * @param sourceMap - Map from directory paths to source info
  */
-function discoverSkillsFromDirs(skillsDirs) {
+function discoverSkillsFromDirs(skillsDirs, sourceMap) {
     const allSkills = [];
     const seenNames = new Map(); // name -> source directory
     for (const skillsDir of skillsDirs) {
@@ -80,13 +191,17 @@ function discoverSkillsFromDirs(skillsDirs) {
             continue;
         }
         console.error(`Scanning skills directory: ${skillsDir}`);
+        // Get source info for this directory (default to local if not in map)
+        const dirSource = sourceMap[skillsDir] || DEFAULT_SKILL_SOURCE;
         // Check if the directory itself contains skills
-        const dirSkills = discoverSkills(skillsDir);
+        const dirSkills = discoverSkills(skillsDir, dirSource);
         // Also check standard subdirectories
         for (const subdir of SKILL_SUBDIRS) {
             const subPath = path.join(skillsDir, subdir);
             if (fs.existsSync(subPath)) {
-                dirSkills.push(...discoverSkills(subPath));
+                // Use subpath source if available, otherwise inherit from parent
+                const subSource = sourceMap[subPath] || dirSource;
+                dirSkills.push(...discoverSkills(subPath, subSource));
             }
         }
         // Add skills, checking for duplicates
@@ -114,13 +229,17 @@ const SKILL_REFRESH_DEBOUNCE_MS = 500;
  * @param skillsDirs - The configured skill directories
  * @param server - The MCP server instance
  * @param skillTool - The registered skill tool to update
+ * @param promptRegistry - For refreshing skill prompts
  * @param subscriptionManager - For refreshing resource subscriptions
  */
-function refreshSkills(skillsDirs, server, skillTool, subscriptionManager) {
+function refreshSkills(skillsDirs, server, skillTool, promptRegistry, subscriptionManager) {
     console.error("Refreshing skills...");
-    // Re-discover all skills
-    const skills = discoverSkillsFromDirs(skillsDirs);
+    // Re-discover all skills using current source map
+    let skills = discoverSkillsFromDirs(skillsDirs, currentSourceMap);
     const oldCount = skillState.skillMap.size;
+    // Apply invocation overrides from config
+    const overrides = getSkillInvocationOverrides();
+    skills = applyInvocationOverrides(skills, overrides);
     // Update shared state
     skillState.skillMap = createSkillMap(skills);
     console.error(`Skills refreshed: ${oldCount} -> ${skills.length} skill(s)`);
@@ -128,6 +247,8 @@ function refreshSkills(skillsDirs, server, skillTool, subscriptionManager) {
     skillTool.update({
         description: getToolDescription(skillState),
     });
+    // Refresh prompts to match new skill state
+    refreshPrompts(server, skillState, promptRegistry);
     // Refresh resource subscriptions to match new skill state
     refreshSubscriptions(subscriptionManager, skillState, (uri) => {
         server.server.notification({
@@ -148,9 +269,10 @@ function refreshSkills(skillsDirs, server, skillTool, subscriptionManager) {
  * @param skillsDirs - The configured skill directories
  * @param server - The MCP server instance
  * @param skillTool - The registered skill tool to update
+ * @param promptRegistry - For refreshing skill prompts
  * @param subscriptionManager - For refreshing subscriptions
  */
-function watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManager) {
+function watchSkillDirectories(skillsDirs, server, skillTool, promptRegistry, subscriptionManager) {
     let refreshTimeout = null;
     const debouncedRefresh = () => {
         if (refreshTimeout) {
@@ -158,7 +280,7 @@ function watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManage
         }
         refreshTimeout = setTimeout(() => {
             refreshTimeout = null;
-            refreshSkills(skillsDirs, server, skillTool, subscriptionManager);
+            refreshSkills(skillsDirs, server, skillTool, promptRegistry, subscriptionManager);
         }, SKILL_REFRESH_DEBOUNCE_MS);
     };
     // Build list of paths to watch
@@ -230,36 +352,170 @@ function watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManage
  */
 const subscriptionManager = createSubscriptionManager();
 async function main() {
-    const skillsDirs = getSkillsDirs();
-    if (skillsDirs.length === 0) {
-        console.error("No skills directory configured.");
-        console.error("Usage: skilljack-mcp /path/to/skills [/path/to/more/skills ...]");
-        console.error("   or: SKILLS_DIR=/path/to/skills skilljack-mcp");
-        console.error("   or: SKILLS_DIR=/path1,/path2 skilljack-mcp");
-        process.exit(1);
+    // Check if static mode is enabled
+    const isStatic = getStaticMode();
+    // Get skill directories from CLI args, env var, or config file
+    // This returns paths that may include GitHub URLs
+    const allPaths = getActiveDirectories();
+    // Classify paths as local or GitHub
+    const { localDirs, githubSpecs } = classifyPaths(allPaths);
+    // Get GitHub configuration
+    const githubConfig = getGitHubConfig();
+    // Sync GitHub repositories
+    let githubDirs = [];
+    if (githubSpecs.length > 0) {
+        console.error(`GitHub repos: ${githubSpecs.map((s) => `${s.owner}/${s.repo}`).join(", ")}`);
+        // Filter by allowlist
+        for (const spec of githubSpecs) {
+            if (!isRepoAllowed(spec, githubConfig)) {
+                console.error(`Blocked: ${spec.owner}/${spec.repo} not in allowed orgs/users. ` +
+                    `Set GITHUB_ALLOWED_ORGS or GITHUB_ALLOWED_USERS to permit.`);
+                continue;
+            }
+            currentGithubSpecs.push(spec);
+        }
+        if (currentGithubSpecs.length > 0) {
+            console.error(`Syncing ${currentGithubSpecs.length} GitHub repo(s)...`);
+            const syncOptions = {
+                cacheDir: githubConfig.cacheDir,
+                token: githubConfig.token,
+                shallowClone: true,
+            };
+            const results = await syncAllRepos(currentGithubSpecs, syncOptions);
+            // Collect successful sync paths
+            for (const result of results) {
+                if (!result.error) {
+                    githubDirs.push(result.localPath);
+                }
+            }
+            console.error(`Successfully synced ${githubDirs.length}/${currentGithubSpecs.length} repo(s)`);
+        }
+    }
+    // Get bundled skills directory (ships with the package)
+    const bundledSkillsDir = getBundledSkillsDir();
+    const hasBundledSkills = fs.existsSync(bundledSkillsDir);
+    // Combine all skill directories
+    // User directories come first so they can override bundled skills (first-wins deduplication)
+    currentSkillsDirs = [...localDirs, ...githubDirs, ...(hasBundledSkills ? [bundledSkillsDir] : [])];
+    // Build source map for skill discovery
+    currentSourceMap = buildDirectorySourceMap(localDirs, currentGithubSpecs, githubConfig.cacheDir, hasBundledSkills ? bundledSkillsDir : undefined);
+    // Log configured directories
+    if (localDirs.length > 0) {
+        console.error(`Local directories: ${localDirs.join(", ")}`);
+    }
+    if (githubDirs.length > 0) {
+        console.error(`GitHub cache directories: ${githubDirs.join(", ")}`);
+    }
+    if (hasBundledSkills) {
+        console.error(`Bundled skills: ${bundledSkillsDir}`);
+    }
+    if (isStatic) {
+        console.error("Static mode enabled - skills list frozen at startup");
     }
-    console.error(`Skills directories: ${skillsDirs.join(", ")}`);
     // Discover skills at startup
-    const skills = discoverSkillsFromDirs(skillsDirs);
+    let skills = discoverSkillsFromDirs(currentSkillsDirs, currentSourceMap);
+    // Apply invocation overrides from config
+    const overrides = getSkillInvocationOverrides();
+    skills = applyInvocationOverrides(skills, overrides);
     skillState.skillMap = createSkillMap(skills);
     console.error(`Discovered ${skills.length} skill(s)`);
     // Create the MCP server
+    // In static mode, disable listChanged for tools/prompts (skills list is frozen)
+    // Resource subscriptions remain dynamic for individual skill file watching
     const server = new McpServer({
         name: "skilljack-mcp",
         version: "1.0.0",
     }, {
         capabilities: {
-            tools: { listChanged: true },
+            tools: { listChanged: !isStatic },
             resources: { subscribe: true, listChanged: true },
+            prompts: { listChanged: !isStatic },
         },
     });
-    // Register tools and resources
+    // Register tools, resources, and prompts
     const skillTool = registerSkillTool(server, skillState);
     registerSkillResources(server, skillState);
+    const promptRegistry = registerSkillPrompts(server, skillState);
     // Register subscription handlers for resource file watching
     registerSubscriptionHandlers(server, skillState, subscriptionManager);
-    // Set up file watchers for skill directory changes
-    watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManager);
+    // Register skill-config tool for UI-based directory configuration
+    // Skip in static mode since skills list is frozen
+    if (!isStatic) {
+        registerSkillConfigTool(server, skillState, async () => {
+            // Callback when directories or GitHub settings change via UI
+            // Reload directories from config and refresh skills
+            const newPaths = getActiveDirectories();
+            const { localDirs: newLocalDirs, githubSpecs: newGithubSpecs } = classifyPaths(newPaths);
+            // Get fresh GitHub config (in case allowed orgs/users changed)
+            const freshGithubConfig = getGitHubConfig();
+            // Filter GitHub specs by allowlist and sync
+            const allowedGithubSpecs = [];
+            for (const spec of newGithubSpecs) {
+                if (isRepoAllowed(spec, freshGithubConfig)) {
+                    allowedGithubSpecs.push(spec);
+                }
+                else {
+                    console.error(`Blocked: ${spec.owner}/${spec.repo} not in allowed orgs/users.`);
+                }
+            }
+            // Sync any GitHub repos
+            let newGithubDirs = [];
+            if (allowedGithubSpecs.length > 0) {
+                console.error(`Syncing ${allowedGithubSpecs.length} GitHub repo(s)...`);
+                const syncOptions = {
+                    cacheDir: freshGithubConfig.cacheDir,
+                    token: freshGithubConfig.token,
+                    shallowClone: true,
+                };
+                const results = await syncAllRepos(allowedGithubSpecs, syncOptions);
+                for (const result of results) {
+                    if (!result.error) {
+                        newGithubDirs.push(result.localPath);
+                    }
+                }
+                console.error(`Successfully synced ${newGithubDirs.length}/${allowedGithubSpecs.length} repo(s)`);
+            }
+            // Update current state
+            currentGithubSpecs = allowedGithubSpecs;
+            githubDirs = newGithubDirs;
+            // Include bundled skills (last, so user skills take precedence)
+            currentSkillsDirs = [...newLocalDirs, ...newGithubDirs, ...(hasBundledSkills ? [bundledSkillsDir] : [])];
+            currentSourceMap = buildDirectorySourceMap(newLocalDirs, allowedGithubSpecs, freshGithubConfig.cacheDir, hasBundledSkills ? bundledSkillsDir : undefined);
+            console.error(`Config changed via UI. Directories: ${currentSkillsDirs.join(", ") || "(none)"}`);
+            refreshSkills(currentSkillsDirs, server, skillTool, promptRegistry, subscriptionManager);
+        });
+        // Register skill-display tool for UI-based invocation settings
+        registerSkillDisplayTool(server, skillState, () => {
+            // Callback when invocation settings change via UI
+            // Refresh skills to apply new overrides
+            console.error("Invocation settings changed via UI. Refreshing skills...");
+            refreshSkills(currentSkillsDirs, server, skillTool, promptRegistry, subscriptionManager);
+        });
+    }
+    // Set up file watchers for skill directory changes (skip in static mode)
+    if (!isStatic && currentSkillsDirs.length > 0) {
+        watchSkillDirectories(currentSkillsDirs, server, skillTool, promptRegistry, subscriptionManager);
+    }
+    // Set up GitHub polling for updates (skip in static mode)
+    let pollingManager = null;
+    if (!isStatic && currentGithubSpecs.length > 0 && githubConfig.pollIntervalMs > 0) {
+        const syncOptions = {
+            cacheDir: githubConfig.cacheDir,
+            token: githubConfig.token,
+            shallowClone: true,
+        };
+        pollingManager = createPollingManager(currentGithubSpecs, syncOptions, {
+            intervalMs: githubConfig.pollIntervalMs,
+            onUpdate: (spec, result) => {
+                console.error(`GitHub update detected for ${spec.owner}/${spec.repo}`);
+                refreshSkills(currentSkillsDirs, server, skillTool, promptRegistry, subscriptionManager);
+            },
+            onError: (spec, error) => {
+                console.error(`GitHub polling error for ${spec.owner}/${spec.repo}: ${error.message}`);
+            },
+        });
+        pollingManager.start();
+    }
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/skill-config-tool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SkillState } from "./skill-tool.js";
+/**
+ * Callback type for when directories or GitHub settings change.
+ */
+export type OnDirectoriesChangedCallback = () => void | Promise<void>;
+/**
+ * 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 declare function registerSkillConfigTool(server: McpServer, skillState: SkillState, onDirectoriesChanged: OnDirectoriesChangedCallback): void;